# Grid-agent operator TUI

The operator TUI is a pure-Rust, cross-platform view of the versioned control
plane. Embedded and split modes use the same reducer, snapshots, commands, and
authenticated control requests; the UI never reads private runtime state.

Run an embedded UI with a live-grid integrated configuration:

```sh
cargo run --locked -p metacrate-grid-agent --features live-grid -- \
  --config config/grid-agent.integrated.example.yml --tui
```

Run a separate UI against a loopback split service:

```sh
cargo run --locked -p metacrate-grid-agent -- \
  --config config/grid-agent.split.example.yml --tui-client
```

The split client reads its operator capability from the ACL-restricted
`config.yml`. It never displays or copies that value. Remote
TLS clients must embed `TuiTransport` with their explicitly configured trust
roots; the command-line client intentionally accepts loopback TCP only.

Open preferences before a service is configured with
`metacrate-grid-agent --preferences`; the same panel is available from the live
TUI. It edits the endpoint, optional model, grid identity, hidden credentials,
mode, and privileged UUID list while preserving advanced YAML settings. Use
Up/Down to select, Enter to edit/commit, `w` to save, and Esc to cancel. Changes
to connection or authorization settings apply after restart. A one-time
`--import-env /path/to/.env` migrates legacy `GRID_*` and `OPENAPI_*` values.

Use Tab/arrow keys to change panels and scroll. `r` refreshes; `p`/`u` pause or
resume; `f` reconnects the grid; `a`/`d` approve or deny the first pending
approval; `x` cancels the newest visible action; `e` expires the first visible
session; `t` toggles the first roaming schedule; `s` requests shutdown; and
`q` or Ctrl-C exits. Mutations other than pause/resume require confirmation,
with shutdown marked high risk. Exiting or crashing a split TUI does not stop
the service.

Rendering is terminal-independent, Unicode display-width aware, responsive to
resize events, and monochrome when `NO_COLOR` is set or `TERM=dumb`. Input uses
a bounded queue. Snapshot ticks coalesce while a request is slow, and timeline
storage is bounded. The terminal guard restores raw mode, cursor visibility,
and the alternate screen on success, error, Ctrl-C, or panic unwinding.

Diagnostic panels show only explicitly captured redacted envelopes. Prompt
and response content, API keys, grid passwords, operator tokens, capability
URLs, and model reasoning have no TUI representation.

Focused verification:

```sh
cargo test --locked -p metacrate-grid-agent --lib tui_tests
cargo test --locked -p metacrate-grid-agent --test dependency_policy
cargo clippy --locked -p metacrate-grid-agent --all-targets --features live-grid -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --locked -p metacrate-grid-agent --no-deps
```