# UI Guide

CleverAgents provides two interface options for monitoring plans, sessions,
diffs, and validation results: a **Textual-based TUI** for terminal use and a
**read-only Web UI** stub that serves JSON endpoints locally.

Both interfaces consume the same `UIDataProvider` protocol, so the data
displayed is identical regardless of which interface is used.

## TUI Dashboard

### Launching

```bash
agents ui tui
```

Optional flags:

| Flag | Description |
|------|-------------|
| `--project-id`, `-p` | Project ID to display (default: empty — show all) |
| `--refresh`, `-r` | Auto-refresh interval in seconds (overrides `tui_refresh_interval` setting) |

### Layout

The TUI is organized into four panes:

| Pane | Position | Content |
|------|----------|---------|
| **Plan List** | Top-left | Table of plans with ID, name, status, created date |
| **Plan Detail** | Top-right | Full detail of the selected plan including decisions and linked resources |
| **Diff Viewer** | Bottom-left | Changeset diffs for the selected plan |
| **Validation Summary** | Bottom-right | Pass/fail validation results |

### Keybindings

| Key | Action |
|-----|--------|
| `q` | Quit the TUI |
| `r` | Manual refresh all panes |
| `1` | Focus the plan list pane |
| `2` | Focus the plan detail pane |
| `3` | Focus the diff viewer pane |
| `4` | Focus the validation summary pane |

### Auto-Refresh

The TUI polls the data provider at a configurable interval.  The default is
**5 seconds**.  Override with:

- **CLI flag**: `--refresh 10`
- **Environment variable**: `CLEVERAGENTS_TUI_REFRESH_INTERVAL=10`
- **Configuration setting**: `tui_refresh_interval` in the settings file

## Web UI

### Enabling

The web UI is disabled by default.  Enable it with:

```bash
export CLEVERAGENTS_WEB_UI_ENABLED=true
```

### Launching

```bash
agents ui web
```

Optional flags:

| Flag | Description |
|------|-------------|
| `--host`, `-h` | Bind address (default: `127.0.0.1` — local only) |
| `--port` | Listen port (overrides `web_ui_port` setting, default: `8080`) |

### Endpoints

All endpoints are **read-only** (GET only).

| Route | Description |
|-------|-------------|
| `GET /ui/plans?project_id=...` | JSON array of plan summaries |
| `GET /ui/plans/{plan_id}` | Plan detail (404 if not found) |
| `GET /ui/sessions` | JSON array of sessions |
| `GET /ui/diffs/{plan_id}` | Changeset diffs for a plan |
| `GET /ui/validations/{plan_id}` | Validation results for a plan |
| `GET /ui/health` | Health check (`{"status": "ok"}`) |

### Security

The web UI binds to `127.0.0.1` by default.  **Do not expose it to the
network** — it is intended for local development only and has no
authentication or authorization.

## Configuration Reference

| Setting | Env Var | Default | Description |
|---------|---------|---------|-------------|
| `tui_refresh_interval` | `CLEVERAGENTS_TUI_REFRESH_INTERVAL` | `5` | Auto-refresh interval in seconds |
| `web_ui_enabled` | `CLEVERAGENTS_WEB_UI_ENABLED` | `false` | Enable the web UI server |
| `web_ui_port` | `CLEVERAGENTS_WEB_UI_PORT` | `8080` | Web UI listen port |

## Data Provider Architecture

Both the TUI and web UI consume the `UIDataProvider` protocol defined in
`cleveragents.ui.data_provider`.  The default implementation,
`LocalUIDataProvider`, resolves services from the DI container.

The protocol exposes these methods:

- `get_plans(project_id)` — plan summaries
- `get_plan_detail(plan_id)` — full plan detail
- `get_sessions()` — session list
- `get_validations(plan_id)` — validation results
- `get_diffs(plan_id)` — changeset diffs
- `get_logs(plan_id, level)` — log entries

Custom providers can be injected for testing or alternative data sources.