feat: Add agent-tui and tui-explorer skills with comprehensive documentation and scripts

2026-09-04 20:03:30 +02:00 · 2026-09-04 20:03:30 +02:00 · 6a3e1e0d5a
commit 6a3e1e0d5a
parent d5a143ee36
24 changed files with 708 additions and 0 deletions
--- a/.agents/skills/agent-tui/SKILL.md
+++ b/.agents/skills/agent-tui/SKILL.md
@ -0,0 +1,74 @@
+---
+name: agent-tui
+description: >
+  Automate terminal UI (TUI) apps with agent-tui for testing, inspection, demos, and scripted interactions.
+  Use when automating CLI/TUI flows, regression testing terminal apps, verifying interactive behavior, or extracting structured text from terminal UIs.
+  Also use when asked what agent-tui is, how it works, or to demo it.
+  Do not use for web browsers, GUI apps, or non-terminal interfaces.
+---
+
+# agent-tui
+
+## Quick start
+- Verify install: `agent-tui --version`
+- Install with `npm i -g agent-tui` (or `pnpm add -g agent-tui`, `bun add -g agent-tui`).
+- Alternate install: `curl -fsSL https://raw.githubusercontent.com/pproenca/agent-tui/master/install.sh -o /tmp/agent-tui-install.sh && sh /tmp/agent-tui-install.sh` or `cargo install --git https://github.com/pproenca/agent-tui.git --path cli/crates/agent-tui`.
+- If you used the install script, ensure `~/.local/bin` is on your PATH.
+- Start a session: `agent-tui run --format json <command> -- <args...>`
+- Observe: `agent-tui screenshot --format json`
+- Act: `agent-tui press Enter`, `agent-tui type "text"`, or `agent-tui scroll down`
+- Wait or verify: `agent-tui wait "Expected text" --assert` or `agent-tui wait --stable`
+- Cleanup: `agent-tui kill --yes`
+
+## Core workflow
+Current automation loop: `run -> screenshot -> press/type/scroll -> wait -> kill --yes`.
+
+1. Run the app with `agent-tui run` and capture `session_id` from JSON output.
+2. Take a fresh snapshot with `agent-tui screenshot` or `agent-tui screenshot --format json`.
+3. Decide the next action based on the latest snapshot.
+4. Act with `press`, `type`, or `scroll`.
+5. Synchronize with `wait --assert` or `wait --stable`.
+6. Repeat from step 2 until the task finishes.
+7. Clean up with `agent-tui kill --yes`.
+
+## Reliability rules
+- Re-snapshot after every action that could change the UI.
+- Never act on a changing screen; wait for stability first.
+- Verify outcomes with `wait --assert` instead of assuming success.
+- Always end automation runs with `kill --yes` or `sessions cleanup --yes`.
+
+## Legacy migration
+Use current commands for new scripts. Legacy compatibility forms still parse for old scripts, but each one writes its deprecation notice to stderr, keeps JSON stdout parseable, and is covered by the next-major removal window.
+
+- `agent-tui input "text"` -> `agent-tui type "text"`.
+- `agent-tui action <selector> click` -> `agent-tui press Enter`.
+- `agent-tui action <selector> fill <text>` -> `agent-tui type "<text>"`.
+- `agent-tui screenshot -e` -> `agent-tui screenshot`.
+- `agent-tui screenshot -a` -> `agent-tui screenshot`.
+- `agent-tui wait -e <ref>` -> `agent-tui wait "<text>"`.
+- `agent-tui scroll-into-view <selector>` -> `agent-tui scroll <direction> [amount]` or `agent-tui press ...`; the compatibility command does not send terminal input.
+
+## Session handling
+- Use `--session <id>` for every command if more than one session exists.
+- If you lose the session id, run `agent-tui sessions` and `agent-tui sessions show <id>`.
+
+## Live preview (optional)
+- Ask whether a live preview is desired.
+- Start preview: `agent-tui live start --open`
+- Stop standalone preview state with `agent-tui live stop`; daemon-backed preview remains available until `agent-tui daemon stop --yes`.
+
+## Deep-dive references
+- Full CLI coverage and options: `references/command-atlas.md`
+- JSON output contract: `references/output-contract.md`
+- End-to-end command sequences: `references/flows.md`
+- Quick command selection: `references/decision-tree.md`
+- Session lifecycle and concurrency: `references/session-lifecycle.md`
+- Assertions and test oracles: `references/assertions.md`
+- Failure recovery playbook: `references/recovery.md`
+- Safety and confirmation prompts: `references/safety.md`
+- Clarification checklist: `references/clarifications.md`
+- Test plan template: `references/test-plan.md`
+- Demo script: `references/demo.md`
+- User prompt templates: `references/prompt-templates.md`
+- Minimal command sets by use case: `references/use-cases.md`
+- Explorer/replay automation skill: `../tui-explorer/SKILL.md`
--- a/.agents/skills/agent-tui/agents/openai.yaml
+++ b/.agents/skills/agent-tui/agents/openai.yaml
@ -0,0 +1,4 @@
+interface:
+  display_name: "Agent TUI"
+  short_description: "Automate terminal UIs with agent-tui workflows"
+  default_prompt: "Automate a TUI by running the app, taking fresh screenshots after each action, using press/type/scroll, waiting with --assert or --stable, and cleaning up with kill --yes. Ask for the command, expected UI text, inputs, and whether live preview is desired."
--- a/.agents/skills/agent-tui/references/assertions.md
+++ b/.agents/skills/agent-tui/references/assertions.md
@ -0,0 +1,21 @@
+# Assertions and Test Oracles
+
+Use this file when translating requirements into checks.
+
+## Turn Requirements into Assertions
+- Convert each requirement into observable UI state (text or stability).
+- Prefer `wait --assert` for pass/fail semantics.
+- Collect evidence with a final `screenshot` before cleanup.
+
+## Assertion Patterns
+- Text presence: `agent-tui wait "Expected" --assert`
+- Text gone: `agent-tui wait "Expected" --gone --assert`
+- Stability: `agent-tui wait --stable --assert`
+
+## Validation Strategy
+- For static UI: text snapshot + `wait` is enough.
+- For dynamic UI: insert `wait --stable` before each action.
+
+## Reporting
+- Report: scenario, actions taken, assertions run, and final evidence (screenshot output).
+- If an assertion fails, include the last screenshot and the expected condition.
--- a/.agents/skills/agent-tui/references/clarifications.md
+++ b/.agents/skills/agent-tui/references/clarifications.md
@ -0,0 +1,25 @@
+# Clarification Checklist
+
+Use this file when requirements are incomplete or ambiguous.
+
+## Ask Before Running
+- App command, args, and working directory (what to run, where).
+- Required environment variables or config files.
+- Expected UI outcomes (texts, states, or tree hints to assert).
+- Inputs and sequencing (keys, text, timing constraints).
+- Stop condition (what indicates the test is done).
+- Terminal size requirements (cols/rows) if layout-sensitive.
+- Output format preference: JSON for automation or text for readability.
+
+## Live Preview (always ask)
+- "Do you want a live preview while I run the test?"
+- If yes: run `agent-tui live start --open` before `agent-tui run ...` and stop it afterward.
+- `agent-tui live stop` clears standalone preview state; daemon-backed preview stays available until `agent-tui daemon stop --yes`.
+
+## Safety and Data Handling
+- Ask for credentials or test accounts if login is required; never guess secrets.
+- Confirm if it is safe to execute actions that modify data (delete, submit, confirm).
+- If the app can perform destructive actions, request a dry-run or a test environment.
+
+## Session Scope
+- Ask whether multiple sessions will be running; if yes, plan to use `--session <id>`.
--- a/.agents/skills/agent-tui/references/command-atlas.md
+++ b/.agents/skills/agent-tui/references/command-atlas.md
@ -0,0 +1,96 @@
+# Command Atlas (Full)
+
+Use this file when you need complete CLI coverage and exact options.
+
+## Global Flags
+- `--session <id>`: target a specific session (default: most recent).
+- `--format <text|json>`: output format.
+- `--json`: shorthand for `--format json`.
+- `--no-color`: disable color (also respects `NO_COLOR`).
+
+## Core Commands
+
+### Run
+- `agent-tui run <command> [-- args...]`
+- Options:
+  - `-d, --cwd <dir>`: working directory.
+  - `--cols <n>`: terminal columns (default 120).
+  - `--rows <n>`: terminal rows (default 40).
+
+### Screenshot
+- `agent-tui screenshot`
+- Options:
+  - `--region <name>`: reserved for named regions; currently rejected until region capture is supported.
+  - `--strip-ansi`: remove ANSI color codes.
+  - `--include-cursor`: include cursor position in JSON/text output.
+
+### Resize / Restart
+- `agent-tui resize --cols <n> --rows <n>`
+- `agent-tui restart`
+
+### Press / Type
+- `agent-tui press <key...> [--hold|--release]`
+- `agent-tui type "text"`
+  - Keys: Enter, Tab, Escape, Backspace, Delete, Arrow keys, Home, End, PageUp, PageDown, F1-F12
+  - Modifiers: Ctrl+<key>, Alt+<key>, Shift+<key>
+
+### Wait
+- `agent-tui wait <text>`
+- `agent-tui wait --stable`
+- Modifiers:
+  - `-g, --gone`: wait for text to disappear.
+  - `-t, --timeout <ms>`: timeout in milliseconds (default 30000).
+  - `--assert`: exit code 75 on timeout (0 on success).
+
+### Kill
+- `agent-tui kill [--yes|--dry-run]`
+- Use `agent-tui kill --yes` for no-input automation cleanup.
+
+### Sessions
+- `agent-tui sessions` (list)
+- `agent-tui sessions list`
+- `agent-tui sessions show <id>`
+- `agent-tui sessions switch <id>`
+- `agent-tui sessions attach` (use `-s <id>` to target)
+  - `-T, --no-tty`: stream only.
+  - `--detach-keys <keys>`: custom detach sequence (env: `AGENT_TUI_DETACH_KEYS`).
+- `agent-tui sessions cleanup [--all]`
+
+### Live Preview
+- `agent-tui live start [--open] [--browser <cmd>]`
+- `agent-tui live status`
+- `agent-tui live stop`
+- `live stop` clears standalone preview state. Daemon-backed preview remains served until `agent-tui daemon stop --yes`.
+- Options:
+  - `--open`: open UI in browser (uses `AGENT_TUI_UI_URL` if set).
+  - `--browser <cmd>`: override `$BROWSER`.
+
+### Daemon
+- `agent-tui daemon start`
+- `agent-tui daemon stop [--force] --yes`
+- `agent-tui daemon restart`
+
+### Utilities
+- `agent-tui env`
+- `agent-tui version`
+- `agent-tui help`
+
+### Shell Completions
+- `agent-tui completions <bash|zsh|fish|elvish>`
+
+## Environment Variables
+- `NO_COLOR`: disable colored output.
+- `AGENT_TUI_DETACH_KEYS`: default detach keys for `sessions attach`.
+- `AGENT_TUI_WS_LISTEN`: daemon WS bind address (default: `127.0.0.1:0`).
+- `AGENT_TUI_WS_ALLOW_REMOTE`: allow non-loopback bind (boolean).
+- `AGENT_TUI_WS_STATE`: state file path (default: `~/.agent-tui/api.json`).
+- `AGENT_TUI_WS_DISABLED`: disable daemon WS server (boolean).
+- `AGENT_TUI_WS_MAX_CONNECTIONS`: max live connections.
+- `AGENT_TUI_WS_QUEUE`: outbound WS queue size.
+- `AGENT_TUI_UI_URL`: base URL to open with `live start --open`.
+- `AGENT_TUI_SESSION_STORE`: session metadata log path (default: `~/.agent-tui/sessions.jsonl`).
+- `AGENT_TUI_LOG`: log file path (optional).
+- `AGENT_TUI_LOG_FORMAT`: log format (text or json; default: text).
+- `AGENT_TUI_LOG_STREAM`: log output stream (stderr or stdout; default: stderr).
+- `BROWSER`: browser command (overridden by `--browser`).
+- `PORT`: Bun web preview server port (`web/server.ts`), when using standalone web UI.
--- a/.agents/skills/agent-tui/references/decision-tree.md
+++ b/.agents/skills/agent-tui/references/decision-tree.md
@ -0,0 +1,21 @@
+# Decision Tree
+
+Use this file when you need a quick command choice based on intent.
+
+## Snapshot Strategy
+- Need raw text? Use `screenshot`.
+- Need machine-readable output? Use `screenshot --json`.
+
+## Waiting Strategy
+- Waiting for text to appear: `wait "text" --assert`.
+- Waiting for text to disappear: `wait "text" --gone --assert`.
+- Waiting for UI to settle: `wait --stable`.
+
+## Action Strategy
+- Navigate/confirm: `press` (keys or sequences).
+- Enter text: `type "text"`.
+
+## Reliability
+- Re-snapshot after any action that could change the UI.
+- Prefer `wait --stable` before acting on dynamic screens.
+- Verify outcomes with `wait ... --assert`.
--- a/.agents/skills/agent-tui/references/demo.md
+++ b/.agents/skills/agent-tui/references/demo.md
@ -0,0 +1,38 @@
+# Live Demo Script
+
+Goal: show a real terminal app launch, capture screenshots, send keystrokes, and verify outcomes in real-time.
+
+## Suggested Demo (htop)
+
+### Step 1: Launch
+```bash
+agent-tui run htop
+```
+
+### Step 2: Observe
+```bash
+agent-tui screenshot
+```
+Say: "Here is the current terminal screen. I'll keep re-snapshotting after each action."
+
+### Step 3: Interaction
+```bash
+agent-tui press F10
+```
+Say: "I'm sending a keypress to exit."
+
+### Step 4: Verify
+```bash
+agent-tui wait "Quit" --gone
+```
+Say: "I wait for the expected text to disappear to confirm the app closed."
+
+### Step 5: Cleanup
+```bash
+agent-tui kill --yes
+```
+
+## Narration Tips
+- Emphasize the observe/act/wait loop.
+- Call out that every action is followed by a fresh snapshot.
+- Highlight using `wait --stable` when the UI is changing.
--- a/.agents/skills/agent-tui/references/flows.md
+++ b/.agents/skills/agent-tui/references/flows.md
@ -0,0 +1,60 @@
+# Full Flows and Command Sequences
+
+Use this file when you need a complete, end-to-end command sequence.
+
+## Standard CLI Regression Test (human-like flow)
+1) Start the app under test:
+   - `agent-tui run <your-cli> -- <args>`
+2) Capture session id from JSON output (use `--session <id>` for the rest).
+3) First snapshot (text or structure):
+   - `agent-tui --session <id> screenshot --format json`
+4) Act based on the latest screen:
+   - `agent-tui --session <id> type "value"`
+   - `agent-tui --session <id> press Enter`
+5) Wait for expected state:
+   - `agent-tui --session <id> wait "Expected text" --assert`
+6) Repeat steps 3-5 until the flow finishes.
+7) Cleanup:
+   - `agent-tui --session <id> kill --yes`
+
+## Form Interaction Flow
+1) `agent-tui run <app>`
+2) `agent-tui --session <id> screenshot --format json`
+3) Focus the input (if needed): `agent-tui --session <id> press Tab`
+4) Type value: `agent-tui --session <id> type "my-value"`
+5) Submit: `agent-tui --session <id> press Enter`
+6) Wait for success: `agent-tui --session <id> wait "Success" --assert`
+7) Cleanup: `agent-tui --session <id> kill --yes`
+
+## Dynamic UI / Flaky Rendering Flow
+1) Start: `agent-tui run <app>`
+2) Stabilize: `agent-tui --session <id> wait --stable`
+3) Snapshot: `agent-tui --session <id> screenshot --format json`
+4) Act: `agent-tui --session <id> press Enter` or `agent-tui --session <id> type "text"`
+5) Re-stabilize: `agent-tui --session <id> wait --stable`
+6) Re-snapshot and continue.
+7) Cleanup: `agent-tui --session <id> kill --yes`
+
+## Live Preview Flow (optional)
+1) Ask user if they want live preview.
+2) If yes: `agent-tui live start --open`
+3) Run the app: `agent-tui run <app>`
+4) Continue normal flow (snapshot/act/wait).
+5) Stop standalone preview state when done: `agent-tui live stop`
+6) If preview is daemon-backed and the daemon should stop too: `agent-tui daemon stop --yes`
+7) Cleanup: `agent-tui kill --yes`
+
+## Debug/Attach Flow (existing session)
+1) List sessions: `agent-tui sessions`
+2) Switch active session if needed: `agent-tui sessions switch <id>`
+3) Attach to active session: `agent-tui sessions attach`
+4) Interact/observe, then detach (Ctrl-P Ctrl-B).
+5) Cleanup: `agent-tui kill --yes` or `agent-tui sessions cleanup --yes`
+
+## Smoke Test Example (htop)
+1) `agent-tui run htop`
+2) `agent-tui --session <id> screenshot`
+3) Verify UI text (e.g., "F1 Help").
+4) Quit: `agent-tui --session <id> press F10`
+5) Confirm quit: `agent-tui --session <id> wait "Quit" --gone`
+6) Cleanup: `agent-tui --session <id> kill --yes`
--- a/.agents/skills/agent-tui/references/output-contract.md
+++ b/.agents/skills/agent-tui/references/output-contract.md
@ -0,0 +1,63 @@
+# JSON Output Contract
+
+Use this file when parsing `--format json` output.
+
+## Spawn / Run
+- `agent-tui run ...` returns:
+  ```json
+  { "session_id": "<id>", "pid": 123 }
+  ```
+
+## Screenshot (text)
+- `agent-tui screenshot ...` returns:
+  ```json
+  {
+    "session_id": "<id>",
+    "screenshot": "<string>",
+    "rendered": "<optional>"
+  }
+  ```
+- `cursor` is only present when `--include-cursor` is passed:
+  ```json
+  { "cursor": { "row": 0, "col": 0, "visible": true } }
+  ```
+
+## Wait
+- `agent-tui wait ...` returns:
+  ```json
+  { "found": true, "elapsed_ms": 1200 }
+  ```
+
+## Resize
+- `agent-tui resize ...` returns:
+  ```json
+  { "success": true, "session_id": "<id>", "cols": 120, "rows": 40 }
+  ```
+
+## Restart / Kill
+- `restart` returns:
+  ```json
+  { "old_session_id": "<id>", "new_session_id": "<id>", "command": "<cmd>", "pid": 123 }
+  ```
+- `kill` returns:
+  ```json
+  { "success": true, "session_id": "<id>" }
+  ```
+
+## Sessions
+- `agent-tui sessions` returns:
+  ```json
+  {
+    "sessions": [
+      {
+        "id": "<id>",
+        "command": "<command>",
+        "pid": 123,
+        "running": true,
+        "created_at": "<timestamp>",
+        "size": { "cols": 120, "rows": 40 }
+      }
+    ],
+    "active_session": "<id>"
+  }
+  ```
--- a/.agents/skills/agent-tui/references/prompt-templates.md
+++ b/.agents/skills/agent-tui/references/prompt-templates.md
@ -0,0 +1,28 @@
+# Prompt Templates
+
+Use these verbatim when you need to ask the user for missing details.
+
+## Minimum Info Request
+- "Please share: (1) command + args to run, (2) expected UI text/state to assert, (3) inputs/steps, (4) any env vars, and (5) whether you want live preview while I run it."
+
+## Live Preview
+- "Do you want a live preview while I run the test? If yes, I'll start `agent-tui live start --open` before running the app."
+
+## Safety / Environment
+- "Is this a test environment, and is it safe to submit or modify data during this run?"
+
+## Credentials
+- "Does the flow require login? If so, please provide test credentials or a fixture account."
+
+## Clarify Assertions
+- "What exact text or UI state should I treat as success?"
+- "Are there any error states I should explicitly check for?"
+
+## Timeouts and Stability
+- "Should I use a longer timeout or wait for stability (`wait --stable`) before actions?"
+
+## Completion Check
+- "What should indicate the test is finished (specific screen, message, or exit state)?"
+
+## Results Summary Template
+- "I ran the flow, executed these actions: <actions>, and asserted: <assertions>. The last snapshot shows: <evidence>. Want me to extend coverage or add more assertions?"
--- a/.agents/skills/agent-tui/references/recovery.md
+++ b/.agents/skills/agent-tui/references/recovery.md
@ -0,0 +1,21 @@
+# Failure Recovery
+
+Use this file when runs are flaky, stalled, or inconsistent.
+
+## Common Failures and Fixes
+- Text not found: re-run `screenshot`, wait for stability, then re-check expected text.
+- Target not visible: use `press` navigation keys (for example `PageDown`, arrows), then re-snapshot.
+- Wait timeout: increase `--timeout`, use `wait --stable`, then re-snapshot.
+- No active session: `sessions` to list; re-run `run` if needed.
+- Daemon not running: `daemon start`.
+- Version mismatch: `daemon restart`.
+- Unresponsive session: `kill --yes`, then re-run.
+- Layout missing/overflow: `resize --cols --rows`, re-snapshot.
+
+## Retry Budget
+- Allow 3-5 retries for transient UI changes.
+- If still failing, stop and ask the user for guidance or updated expectations.
+
+## Escalation
+- Last resort: `daemon stop --force --yes` then `daemon start`.
+- Warn that `daemon restart` terminates all sessions.
--- a/.agents/skills/agent-tui/references/safety.md
+++ b/.agents/skills/agent-tui/references/safety.md
@ -0,0 +1,18 @@
+# Safety and Confirmation Prompts
+
+Use this file when actions can mutate data or require credentials.
+
+## Always Confirm
+- Destructive actions (delete, reset, overwrite, submit).
+- Actions against production or real user data.
+- Use of real credentials.
+
+## Prompt Examples
+- "Is this a test environment, and is it safe to submit or delete data?"
+- "Do you want me to use live preview while running the test?"
+- "Can you provide test credentials or a fixture account?"
+
+## Safe Defaults
+- Prefer dry-run or read-only flows when available.
+- Avoid submitting forms unless explicitly requested.
+- Avoid sharing secrets in logs or outputs.
--- a/.agents/skills/agent-tui/references/session-lifecycle.md
+++ b/.agents/skills/agent-tui/references/session-lifecycle.md
@ -0,0 +1,34 @@
+# Session Lifecycle and Concurrency
+
+Use this file when managing multiple sessions or debugging stuck runs.
+
+## Lifecycle Overview
+1) `run` creates a session and returns `session_id`.
+2) Commands without `--session` target the most recent session.
+3) Use `--session <id>` when multiple sessions exist.
+4) End automation sessions with `kill --yes` or `sessions cleanup --yes`.
+
+## Recommended Pattern
+- Capture `session_id` from `run` JSON output.
+- Pass `--session <id>` to every subsequent command in the flow.
+- When running multiple apps concurrently, never rely on the default session.
+
+## Inspect and Attach
+- `sessions`: list active sessions.
+- `sessions show <id>`: show session details.
+- `sessions switch <id>`: set the active session.
+- `sessions attach`: attach in TTY mode (detach with Ctrl-P Ctrl-B). Use `-s <id>` to target a specific session.
+- `-s <id> sessions attach -T`: stream output only (no TTY).
+
+## Cleanup and Recovery
+- `kill --yes`: terminate the current session without prompting.
+- `sessions cleanup --yes`: remove dead/orphaned sessions without prompting.
+- `sessions cleanup --all --yes`: remove all sessions (including active) without prompting.
+
+## Restart Behavior
+- `restart`: restart the current session command.
+- `daemon restart`: restarts daemon and terminates all sessions.
+
+## Utilities
+- `env`: show environment configuration affecting the CLI.
+- `version`: show CLI + daemon version info.
--- a/.agents/skills/agent-tui/references/test-plan.md
+++ b/.agents/skills/agent-tui/references/test-plan.md
@ -0,0 +1,25 @@
+# Test Plan Template
+
+Use this file when writing step-by-step tests.
+
+## Inputs to Collect
+- Command and args to run.
+- Terminal size (cols/rows) if layout-sensitive.
+- Expected text or stability checkpoints.
+- Credentials or fixtures (if needed).
+
+## Step Structure
+- Step 1: `screenshot` (or `screenshot --json`)
+- Step 2: Action (`press`, `type`)
+- Step 3: `wait --assert` for expected text or `wait --stable`
+- Step 4: Repeat until done
+- Step 5: Cleanup (`kill --yes`)
+
+## Example
+1) `agent-tui run <app>`
+2) `agent-tui --session <id> screenshot --format json`
+3) `agent-tui --session <id> press Tab`
+4) `agent-tui --session <id> type "value"`
+5) `agent-tui --session <id> press Enter`
+6) `agent-tui --session <id> wait "Success" --assert`
+7) `agent-tui --session <id> kill --yes`
--- a/.agents/skills/agent-tui/references/use-cases.md
+++ b/.agents/skills/agent-tui/references/use-cases.md
@ -0,0 +1,17 @@
+# Use Cases
+
+Use this file when selecting a minimal command set for a task.
+
+## Basic Automation Loop
+- Commands: `run` -> `screenshot` -> `press/type` -> `wait --assert` -> `kill --yes`.
+- Re-snapshot after each action.
+
+## Form Entry
+- Commands: `run`, `screenshot --json`, `press Tab`, `type "value"`, `press Enter`, `wait "Success" --assert`.
+
+## Stabilization Before Acting
+- Commands: `wait --stable`, `screenshot`, then `press/type`.
+
+## Live Preview Support
+- Commands: `live start --open` -> `run` -> normal flow -> `live stop`.
+- `live stop` clears standalone preview state. If the preview is served by the daemon and the daemon should stop too, run `daemon stop --yes`.
--- a/.agents/skills/tui-explorer/SKILL.md
+++ b/.agents/skills/tui-explorer/SKILL.md
@ -0,0 +1,46 @@
+---
+name: tui-explorer
+description: >
+  Discover and replay terminal UI paths using agent-tui.
+  Use when you need to launch a TUI app, explore navigation with bounded BFS,
+  generate markdown acceptance tests, and verify those tests repeatedly.
+  Do not use for web or desktop GUI automation.
+---
+
+# tui-explorer
+
+## Purpose
+Generate replayable acceptance tests from discovered TUI navigation paths.
+
+## Commands
+- Discover:
+  - `skills/tui-explorer/scripts/tui_explorer discover --command "<app command>"`
+- Verify:
+  - `skills/tui-explorer/scripts/tui_explorer verify --spec "<path-to-acceptance.md>"`
+
+## Defaults
+- Exploration strategy: bounded BFS.
+- Safe action set: `Enter`, `Tab`, `ArrowDown`, `ArrowUp`, `ArrowRight`, `ArrowLeft`, `Esc`, `Space`.
+- Risky actions are disabled unless `--allow-risky` is set.
+- Output directory defaults to `.agent-tui/discover/<timestamp>/`.
+- Replay fails on scenario failure and exits non-zero.
+
+## Workflow
+1. Start live preview over the HTTP endpoint with `agent-tui live start --open` before discovery so the user can watch exploration in the built-in web UI.
+2. Run `discover` for the target command.
+3. Inspect generated artifacts:
+   - `acceptance.md` (human-readable OpenSpec-style expectations + machine-executable steps)
+   - `trace.jsonl`
+   - `discover-report.json`
+4. Run `verify` against the generated `acceptance.md`.
+5. Stop live preview with `agent-tui live stop` after verification.
+
+Session handling for live preview:
+- Treat browser session selection as preview-local context only.
+- Do not use browser interactions to switch the daemon active session.
+6. On failure, inspect `verify-report.json` and files under `failures/`.
+
+## References
+- Schema details: `references/schema-v1.md`
+- Discovery mechanics: `references/discovery.md`
+- Replay semantics: `references/replay.md`
--- a/.agents/skills/tui-explorer/agents/openai.yaml
+++ b/.agents/skills/tui-explorer/agents/openai.yaml
@ -0,0 +1,4 @@
+interface:
+  display_name: "TUI Explorer"
+  short_description: "Discover and replay TUI acceptance paths"
+  default_prompt: "Use tui-explorer to discover bounded TUI navigation paths, generate schema v1 markdown acceptance tests, and verify them with fail-fast replay and artifacts. Start live preview over the HTTP endpoint with `agent-tui live start --open` before discovery so the user can watch exploration in the built-in web UI, and stop it with `agent-tui live stop` after verification. Treat browser session selection as preview-local and do not switch the daemon active session from UI navigation."
--- a/.agents/skills/tui-explorer/references/discovery.md
+++ b/.agents/skills/tui-explorer/references/discovery.md
@ -0,0 +1,33 @@
+# Discovery
+
+Run:
+- `skills/tui-explorer/scripts/tui_explorer discover --command "<app command>"`
+- Before running discover, start live preview so users can observe exploration in the web UI:
+  - `agent-tui live start --open`
+- After verification, stop preview:
+  - `agent-tui live stop`
+
+## Strategy
+- Bounded BFS over action paths.
+- Rebuild each node from a fresh session for deterministic state evaluation.
+- Deduplicate with:
+  - `sha256(normalized_screenshot + cursor + cols + rows)`
+
+## Normalization
+- Strip ANSI sequences.
+- Collapse whitespace.
+
+## Stop rules
+- `max_depth`
+- `max_states`
+- `branch_limit`
+- `time_budget_sec`
+
+## Artifacts
+- `acceptance.md` (includes OpenSpec-style `WHEN/THEN/SHOULD` expectation narrative plus executable step lines)
+- `trace.jsonl`
+- `discover-report.json`
+
+## Session isolation
+- Session changes made in the web UI are preview-local.
+- Discovery/verify commands must not rely on browser-driven active session switching.
--- a/.agents/skills/tui-explorer/references/replay.md
+++ b/.agents/skills/tui-explorer/references/replay.md
@ -0,0 +1,20 @@
+# Replay
+
+Run:
+- `skills/tui-explorer/scripts/tui_explorer verify --spec "<acceptance.md>"`
+
+## Execution model
+- Spawn a fresh session per scenario.
+- Execute each step in order.
+- Use `wait --assert` for `expect` steps.
+- Stop on first scenario failure (fail-fast).
+
+## Result contract
+- Exit `0`: all scenarios pass.
+- Exit `1`: scenario/assertion failure.
+- Exit `2`: spec validation error.
+- Exit `69`: agent-tui/daemon unavailable.
+
+## Failure artifacts
+- `verify-report.json`
+- `failures/<scenario>-step-<n>.txt`
--- a/.agents/skills/tui-explorer/references/schema-v1.md
+++ b/.agents/skills/tui-explorer/references/schema-v1.md
@ -0,0 +1,35 @@
+# Schema v1
+
+Acceptance files are markdown with YAML frontmatter.
+
+## Required frontmatter
+- `schema_version: "v1"`
+- `command`
+- `cols`
+- `rows`
+- `default_timeout_ms`
+- `generated_at`
+- `generator`
+
+Optional:
+- `cwd`
+
+## Scenario format
+Scenario header:
+- `## Scenario: <name>`
+
+Optional OpenSpec-style expectation narrative (human-readable):
+- `### Expectation` (or `### Expectations`)
+- `- **WHEN** ...`
+- `- **THEN** ...`
+- `- **AND** ...` (optional)
+- `- **SHOULD** ...`
+
+Supported steps:
+- `- expect: "<text>"`
+- `- press: "<key>"`
+- `- type: "<text>"`
+- `- wait_stable: true`
+
+OpenSpec narrative lines are ignored by the verifier parser; executable behavior is driven by the supported step lines.
+Any other non-empty line format is invalid.
--- a/.agents/skills/tui-explorer/scripts/tui_explorer
+++ b/.agents/skills/tui-explorer/scripts/tui_explorer
@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+
+exec cargo run -q --manifest-path "$ROOT/cli/Cargo.toml" -p xtask -- tui-explorer "$@"