# TUI Workflows

The TUI is the primary Omnius control surface for interactive use.

## Core Commands

```text
/help
/model
/endpoint
/realtime
/broker
/sponsor
/cohere
/telegram
/skills
/pause
/stop
/resume
```

## Input Behavior

Shift+Enter inserts a newline in the prompt box and expands the input area. Enter submits the prompt.

The input box should preserve Unicode line boundaries and avoid overwriting previous lower entries.

Page Up/Page Down and the mouse wheel browse conversation history. End returns
to the live response when the prompt is empty; while editing, it moves to the
end of the prompt. New output does not pull a scrolled viewport back to live.

## Terminal Compatibility

The interactive terminal uses OpenTUI, the native rendering engine used by
OpenCode. Omnius keeps its Earth palette, transparent terminal background,
header, conversation/tool cards, tasks panel, prompt box, and metrics row.
The package includes the Bun runtime used by the renderer; the agent and CLI
launcher continue to run on Node. Noninteractive commands do not start a
terminal renderer.

The renderer owns terminal painting in a separate process and receives only
changed, styled rows. Component formatting is composed into a retained screen
before rendering, so cursor controls and scroll regions never compete on the
physical terminal. Frames coalesce during input bursts, and a slow terminal
can hold only one unacknowledged frame. Menus share protocol-filtered input;
inherited terminal commands wait for the renderer to suspend before starting.

Header controls use background-filled square padding by default. Run `/color frill on` to enable ornamental Unicode ends when the terminal font includes Symbols for Legacy Computing glyphs.

Box-border color animation and gradient flow are disabled by default. Run `/color flow on` to enable them. `/color`, `/color status`, `/color frill status`, and `/color flow status` expose the current state. Both preferences persist in project/global Omnius settings, and `--local` stores only the current project override.

## Shell Output

Shell command output is rendered inside bounded Unicode cards. Dynamic installer output should update inside the shell block with a mini-scroll effect instead of corrupting adjacent UI.

## Status Row

The bottom data row reports:

- local system stats
- remote sponsor stats when applicable
- tokens in
- tokens out
- token production rate as `t/s`
- model/endpoint state
- Ollama pressure where available

Sponsor consumer mode can alternate local and remote peer telemetry.

## Renderer Validation

After building the workspace, run the terminal fixture with:

```bash
node scripts/test-tui-native-live.mjs --report /tmp/omnius-tui-live.json
node scripts/benchmark-tui-history.mjs --help
```

The live fixture opens a real PTY and independently checks its screen with
xterm. It exercises 20,000 history lines, mouse bursts, tool expansion, editing,
menus, streaming, cancellation, resizing, terminal handoff, and worker cleanup.
It uses synthetic agent events by default and sends no model requests.

An optional real-model check requires `OMNIUS_TUI_LIVE_PREFLIGHT` to point to a
placement receipt containing `endpoint`, `model`, `gpu`, and `processes` with
runner `pid` and `gpu`. Set the matching `OMNIUS_TUI_LIVE_ENDPOINT` and
`OMNIUS_TUI_LIVE_MODEL` only after completing the live inference hardware gate
in AGENTS.md. The harness rechecks runner placement before requesting tokens.

## Mid-Task Steering

Added context and steering should pass through an intake layer that interprets the new requirement relative to the active task. It should not duplicate "Context added" text as prompt content or rely on hardcoded acknowledgements.
