docs: add TUI user guide and keybindings reference

docs/guides/tui_keybindings.md

@@ -0,0 +1,327 @@
+# TUI Keybindings Reference
+
+This document provides a comprehensive reference of all keyboard shortcuts and keybindings
+available in the CleverAgents TUI.
+
+## Global Keybindings
+
+These keybindings are available from any screen or context:
+
+| Key | Action | Context |
+|-----|--------|---------|
+| `Ctrl+Q` | Quit the TUI immediately | Anywhere |
+| `F1` | Toggle context-sensitive help panel | Anywhere |
+| `Ctrl+T` | Cycle to next argument preset | Anywhere |
+| `Escape` | Close overlay / return to prompt | Overlays, modals |
+
+## Block Navigation (Conversation Area)
+
+Navigate message blocks in the conversation stream:
+
+| Key | Action |
+|-----|--------|
+| `alt+↑` | Move cursor to previous block |
+| `alt+↓` | Move cursor to next block |
+| `Enter` | Expand/collapse highlighted block |
+| `Space` | Expand/collapse highlighted block |
+
+## Prompt Input Keybindings
+
+### Basic Input
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Submit the prompt |
+| `Shift+Enter` | Add a newline (multi-line mode) |
+| `Ctrl+Enter` | Alternative newline (some terminals) |
+| `Escape` | Clear prompt / close overlay |
+
+### Text Editing
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+A` | Move to start of line |
+| `Ctrl+E` | Move to end of line |
+| `Ctrl+W` | Delete word backward |
+| `Ctrl+U` | Delete line |
+| `Ctrl+K` | Delete from cursor to end of line |
+| `Backspace` | Delete character backward |
+| `Delete` | Delete character forward |
+| `Ctrl+H` | Delete character backward (alternative) |
+| `Ctrl+D` | Delete character forward (alternative) |
+
+### Navigation in Multi-line Mode
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+Home` | Move to start of text |
+| `Ctrl+End` | Move to end of text |
+| `Page Up` | Scroll up |
+| `Page Down` | Scroll down |
+| `↑` | Move to previous line |
+| `↓` | Move to next line |
+| `←` | Move left |
+| `→` | Move right |
+
+## Input Mode Shortcuts
+
+### Normal Mode (Default)
+
+| Key | Action |
+|-----|--------|
+| `@` | Open Reference Picker overlay |
+| `/` | Open Slash Command overlay |
+| `Enter` | Submit message |
+
+### Shell Mode (`!` or `$`)
+
+| Key | Action |
+|-----|--------|
+| `!` | Trigger shell mode |
+| `$` | Trigger shell mode (alternative) |
+| `Enter` | Execute shell command |
+| `Escape` | Cancel shell command |
+
+### Command Mode (`/`)
+
+| Key | Action |
+|-----|--------|
+| `/` | Open Slash Command overlay |
+| `↑` / `↓` | Navigate command list |
+| `Enter` | Execute selected command |
+| `Escape` | Close overlay |
+| Type | Filter commands by name |
+
+### Reference Mode (`@`)
+
+| Key | Action |
+|-----|--------|
+| `@` | Open Reference Picker overlay |
+| `↑` / `↓` | Navigate suggestions |
+| `Enter` | Insert highlighted reference |
+| `Escape` | Close overlay |
+| Type | Filter suggestions by name |
+
+## Session Management
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+N` | Create a new session tab |
+| `Ctrl+W` | Close the current session tab |
+| `Ctrl+[` | Switch to previous session tab |
+| `Ctrl+]` | Switch to next session tab |
+| `Ctrl+S` | Open sessions screen |
+
+## Sidebar Navigation
+
+| Key | Action |
+|-----|--------|
+| `Shift+Tab` | Cycle sidebar state: hidden → visible → fullscreen |
+| `Escape` | Return to previous sidebar state |
+| `Ctrl+B` | Focus the sidebar (when visible) |
+| `Tab` | Move focus within sidebar |
+
+## Overlay Navigation
+
+### Slash Command Overlay
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Navigate command list |
+| `j` / `k` | Navigate command list (vim-style) |
+| `Enter` | Execute selected command |
+| `Escape` | Close overlay |
+| Type | Filter commands by name |
+| `/` | Clear filter |
+
+### Reference Picker Overlay
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Navigate suggestions |
+| `j` / `k` | Navigate suggestions (vim-style) |
+| `Enter` | Insert highlighted reference |
+| `Escape` | Close overlay |
+| Type | Filter suggestions by name |
+| `@` | Clear filter |
+
+### Help Panel (F1)
+
+| Key | Action |
+|-----|--------|
+| `F1` | Toggle help panel |
+| `Escape` | Close help panel |
+| `↑` / `↓` | Scroll help content |
+| `Page Up` / `Page Down` | Scroll help content |
+
+## Permission Request Keybindings
+
+### Single-File Permission Widget
+
+| Key | Action |
+|-----|--------|
+| `a` | Allow once |
+| `A` | Allow always (this session) |
+| `r` | Reject once |
+| `R` | Reject always (this session) |
+| `↑` / `↓` | Navigate options |
+| `Enter` | Confirm highlighted option |
+| `v` | Open full PermissionsScreen with diff view |
+
+### Multi-File PermissionsScreen
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Navigate file list |
+| `←` / `→` | Switch between panes |
+| `a` | Allow this request once |
+| `A` | Allow all requests from this tool (session) |
+| `r` | Reject this request once |
+| `R` | Reject all requests from this tool (session) |
+| `d` | Cycle diff mode: unified → side-by-side → context |
+| `Escape` | Close PermissionsScreen |
+
+## Actor Selection Overlay (First-Run)
+
+| Key | Action |
+|-----|--------|
+| `j` / `↓` | Move selection down |
+| `k` / `↑` | Move selection up |
+| `/` | Enter search mode |
+| `Enter` | Confirm highlighted actor |
+| `Escape` | Cancel selection |
+
+## Thought Block Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Space` | Expand/collapse thought block |
+| `Enter` | Expand/collapse thought block |
+
+## Vim-Style Navigation
+
+The TUI supports vim-style navigation in list contexts:
+
+| Key | Action |
+|-----|--------|
+| `j` | Move down |
+| `k` | Move up |
+| `h` | Move left |
+| `l` | Move right |
+| `g` | Go to top |
+| `G` | Go to bottom |
+| `/` | Search/filter |
+| `n` | Next search result |
+| `N` | Previous search result |
+
+## Emacs-Style Keybindings
+
+The TUI supports common Emacs-style keybindings in text input:
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+A` | Beginning of line |
+| `Ctrl+E` | End of line |
+| `Ctrl+F` | Forward character |
+| `Ctrl+B` | Backward character |
+| `Ctrl+N` | Next line |
+| `Ctrl+P` | Previous line |
+| `Ctrl+D` | Delete character forward |
+| `Ctrl+H` | Delete character backward |
+| `Ctrl+K` | Kill line (delete to end) |
+| `Ctrl+U` | Kill line (delete from start) |
+| `Ctrl+W` | Kill word backward |
+| `Alt+D` | Kill word forward |
+| `Alt+B` | Backward word |
+| `Alt+F` | Forward word |
+
+## Customizing Keybindings
+
+Keybindings can be customized through the TUI settings. Access settings with:
+
+```
+/settings
+```
+
+Or via the keyboard shortcut (if configured):
+
+| Key | Action |
+|-----|--------|
+| `F2` | Open settings (if configured) |
+| `Ctrl+,` | Open settings (if configured) |
+
+### Configuration File
+
+Keybindings are stored in `~/.config/cleveragents/tui-keybindings.yaml`. You can edit this
+file directly to customize keybindings:
+
+```yaml
+# Example custom keybindings
+global:
+  quit: "Ctrl+Q"
+  help: "F1"
+  preset_cycle: "Ctrl+T"
+
+prompt:
+  submit: "Enter"
+  newline: "Shift+Enter"
+  clear: "Escape"
+
+navigation:
+  block_up: "Alt+Up"
+  block_down: "Alt+Down"
+  expand: "Space"
+
+sessions:
+  new: "Ctrl+N"
+  close: "Ctrl+W"
+  prev: "Ctrl+["
+  next: "Ctrl+]"
+```
+
+## Context-Sensitive Help
+
+The help panel (F1) displays context-specific keybindings based on your current location:
+
+| Context | Triggered When |
+|---------|----------------|
+| **Main Screen** | Prompt is empty or contains normal text |
+| **Slash Commands** | Prompt starts with `/` |
+| **Reference Picker** | Prompt contains `@` |
+| **Shell Mode** | Prompt starts with `!` or `$` |
+| **Permissions** | Permission request is active |
+| **Settings** | Settings screen is open |
+
+## Accessibility
+
+The TUI is designed to be fully keyboard-accessible:
+
+- **No mouse required** — All operations can be performed with keyboard alone
+- **Discoverable shortcuts** — Press `F1` to see available keybindings for the current context
+- **Consistent navigation** — `Escape` always moves toward the main screen
+- **Tab order** — Focus follows logical navigation paths
+
+## Terminal Compatibility
+
+Some keybindings may not work in all terminal emulators:
+
+| Keybinding | Compatibility |
+|------------|----------------|
+| `Alt+↑` / `Alt+↓` | Most modern terminals (iTerm2, GNOME Terminal, Windows Terminal) |
+| `Shift+Enter` | Most modern terminals (may require configuration in some) |
+| `Ctrl+[` / `Ctrl+]` | All terminals |
+| `F1` - `F12` | Most terminals (may conflict with terminal shortcuts) |
+
+**Troubleshooting:**
+
+If a keybinding doesn't work in your terminal:
+
+1. Check your terminal's keybinding configuration
+2. Try an alternative keybinding (e.g., `Ctrl+Enter` instead of `Shift+Enter`)
+3. Configure custom keybindings in `~/.config/cleveragents/tui-keybindings.yaml`
+
+## Related Documentation
+
+- [TUI User Guide](tui_user_guide.md)
+- [TUI Reference](../reference/tui.md)
+- [ADR-044: TUI Architecture and Framework](../adr/ADR-044-tui-architecture-and-framework.md)

docs/guides/tui_user_guide.md

@@ -0,0 +1,766 @@
+# TUI User Guide
+
+The **CleverAgents Terminal User Interface (TUI)** is a full-screen, interactive application
+that provides real-time plan monitoring, multi-session management, persona switching, and rich
+conversation with actors in a single terminal window. This guide walks you through the TUI's
+core features and workflows.
+
+## Getting Started
+
+### Installation
+
+The TUI requires the optional `tui` extra:
+
+```bash
+pip install 'cleveragents[tui]'
+```
+
+### Launching the TUI
+
+```bash
+agents tui
+```
+
+### First-Run Experience
+
+On your first launch, the TUI displays an **actor selection overlay** in the center of the
+screen. This overlay guides you to select an LLM actor:
+
+- `anthropic/claude-4-sonnet` *(recommended)*
+- `anthropic/claude-4-opus`
+- `openai/gpt-4o`
+- `openai/o3`
+- `google/gemini-2`
+
+**Navigation:**
+
+| Key | Action |
+|-----|--------|
+| `j` / `↓` | Move selection down |
+| `k` / `↑` | Move selection up |
+| `/` | Enter search mode to filter actors |
+| `Enter` | Confirm the highlighted actor |
+
+After confirmation, a default **persona** is created and the overlay dismisses. Subsequent
+launches restore the last active persona from `~/.config/cleveragents/tui-state.yaml`.
+
+## TUI Interface Overview
+
+The TUI is organized into distinct regions:
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Header (clock)                                     │
+├─────────────────────────────────────────────────────┤
+│  Conversation area                                  │
+│  ┌─────────────────────────────────────────────┐   │
+│  │  Help Panel Overlay (F1, hidden by default) │   │
+│  └─────────────────────────────────────────────┘   │
+│  ┌─────────────────────────────────────────────┐   │
+│  │  Reference Picker Overlay (@)               │   │
+│  └─────────────────────────────────────────────┘   │
+│  ┌─────────────────────────────────────────────┐   │
+│  │  Slash Command Overlay (/)                  │   │
+│  └─────────────────────────────────────────────┘   │
+│  Prompt Input                                       │
+│  Persona Bar                                        │
+├─────────────────────────────────────────────────────┤
+│  Footer (key bindings)                              │
+└─────────────────────────────────────────────────────┘
+```
+
+### Conversation Area
+
+The conversation displays a chronological stream of message blocks:
+
+| Block Type | Description |
+|------------|-------------|
+| **Welcome** | ASCII art and first-run instructions (first message only) |
+| **UserInput** | Your prompts, rendered with left border and background tint |
+| **ActorResponse** | Actor responses with streaming Markdown and syntax highlighting |
+| **ActorThought** | Actor reasoning/thinking (expandable, if exposed) |
+| **ToolCall** | Tool invocations with status and collapsible details |
+| **PlanProgress** | Plan phase transitions and status updates |
+| **DiffView** | Code diffs with unified or side-by-side rendering |
+| **TerminalEmbed** | Shell command output in a bordered terminal widget |
+| **Note** | System notifications (info, warning, error) |
+
+**Block Navigation:**
+
+The conversation uses a 1-character-wide cursor column on the left. Navigate blocks with:
+
+| Key | Action |
+|-----|--------|
+| `alt+↑` | Move cursor to previous block |
+| `alt+↓` | Move cursor to next block |
+| `Enter` / `Space` | Expand/collapse the highlighted block |
+
+### Prompt Area
+
+The prompt is docked at the bottom of the conversation. It comprises:
+
+1. **Prompt input** — Type your message here
+2. **Overlays** — Reference picker (`@`) and slash commands (`/`) appear above the prompt
+3. **Persona bar** — Shows active persona, actor, preset, and scope information
+
+The prompt symbol changes based on input mode:
+
+| Symbol | Mode | Meaning |
+|--------|------|---------|
+| `❯` | Normal | Markdown message input |
+| `$` | Shell | Shell command execution |
+| `☰` | Multi-line | Input contains newlines |
+
+## Personas System
+
+A **persona** is a named identity that binds an actor, argument presets, and scope references.
+Personas are stored as YAML files in `~/.config/cleveragents/personas/` and allow you to
+quickly switch between different configurations.
+
+### Creating a Persona
+
+Use the `/persona:create` command:
+
+```
+/persona:create
+```
+
+You'll be prompted for:
+
+- **Name** — A unique identifier (no path separators or control characters)
+- **Actor** — The LLM actor to use (e.g., `openai/gpt-4o`)
+- **Description** — Optional description
+- **Base arguments** — Default arguments for every request
+- **Scoped projects** — Projects always in scope for this persona
+- **Scoped plans** — Plans always in scope for this persona
+
+### Switching Personas
+
+Use the `/persona:set` command to switch the active persona:
+
+```
+/persona:set
+```
+
+A filtered list appears. Type to search, then press `Enter` to select.
+
+### Persona Presets
+
+Each persona can have multiple **argument presets** — named override sets that modify the
+base arguments. The `default` preset is always present with no overrides.
+
+**Cycling presets:**
+
+Press `Ctrl+T` in the TUI to cycle through presets in the active persona. The persona bar
+displays the current preset name.
+
+**Example persona with presets:**
+
+```yaml
+name: my-persona
+actor: openai/gpt-4o
+base_arguments:
+  temperature: 0.7
+argument_presets:
+  - name: default
+    display: default
+    overrides: {}
+  - name: concise
+    display: Concise
+    overrides:
+      max_tokens: 256
+      temperature: 0.3
+  - name: creative
+    display: Creative
+    overrides:
+      temperature: 0.9
+      top_p: 0.95
+```
+
+### Managing Personas
+
+| Command | Action |
+|---------|--------|
+| `/persona:list` | List all personas |
+| `/persona:set` | Switch active persona |
+| `/persona:create` | Create a new persona |
+| `/persona:edit` | Edit an existing persona |
+| `/persona:delete` | Delete a persona |
+| `/persona:export` | Export persona YAML to a file |
+| `/persona:import` | Import persona YAML from a file |
+
+## Input Modes
+
+The TUI detects the input mode from the first character of your text:
+
+### Normal Mode (Default)
+
+Type a message and press `Enter` to submit. The message is sent as a Markdown prompt to the
+active actor.
+
+**Features:**
+
+- **Reference expansion** — Use `@` to insert file, resource, or plan references inline
+- **Markdown support** — Full Markdown syntax is supported
+- **Multi-line input** — Press `Shift+Enter` to add newlines
+
+**Example:**
+
+```
+Tell me about the architecture of @src/cleveragents/tui/app.py
+```
+
+### Command Mode (`/`)
+
+Type `/` to open the **Slash Command overlay**. A filtered list of matching commands appears
+as you type. Press `Enter` to dispatch the selected command.
+
+**Example:**
+
+```
+/plan:status
+```
+
+The TUI ships with **67 slash commands** across **14 groups** (session, persona, scope, plan,
+project, actor, resource, config, tool, skill, invariant, profile, context, and utility).
+
+See [Slash Commands Reference](#slash-commands-reference) for the complete catalog.
+
+### Shell Mode (`!` or `$`)
+
+Type `!` or `$` followed by a shell command to execute it in a subprocess. Output is captured
+and displayed in the conversation area.
+
+**Example:**
+
+```
+$ git status
+```
+
+**Safety:**
+
+Shell execution is gated by the `CLEVERAGENTS_ALLOW_DANGEROUS_SHELL` environment variable.
+Set it to `1` or `true` to permit shell commands. When unset, shell commands are blocked.
+
+Before execution, the command is scanned by the **shell danger detection** subsystem. If a
+dangerous pattern is matched (e.g., `rm -rf /`, fork bombs, pipe-to-shell), a warning overlay
+is shown with the danger level and a description of the risk. You can cancel or proceed.
+
+See [Shell Danger Detection](../reference/tui_shell_safety.md) for the full reference.
+
+### Reference Mode (`@`)
+
+Type `@` in the prompt to open the **Reference Picker overlay**. This allows you to insert
+file, resource, or plan references inline.
+
+**Navigation:**
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Navigate suggestions |
+| `Enter` | Insert the highlighted reference |
+| `Escape` | Close the overlay |
+| Type | Filter suggestions by name |
+
+**Example:**
+
+```
+Analyze the following file: @src/api/main.py
+```
+
+## Navigation and Keybindings
+
+### Global Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+Q` | Quit the TUI immediately |
+| `F1` | Toggle the context-sensitive help panel |
+| `Ctrl+T` | Cycle to the next argument preset for the active persona |
+| `Escape` | Close the current overlay and return to the prompt |
+
+### Block Navigation
+
+| Key | Action |
+|-----|--------|
+| `alt+↑` | Move cursor to previous block |
+| `alt+↓` | Move cursor to next block |
+| `Enter` / `Space` | Expand/collapse the highlighted block |
+
+### Prompt Navigation
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Submit the prompt |
+| `Shift+Enter` | Add a newline (multi-line mode) |
+| `Ctrl+A` | Move to start of line |
+| `Ctrl+E` | Move to end of line |
+| `Ctrl+W` | Delete word backward |
+| `Ctrl+U` | Delete line |
+
+### Session Management
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+N` | Create a new session tab |
+| `Ctrl+W` | Close the current session tab |
+| `Ctrl+[` | Switch to previous session tab |
+| `Ctrl+]` | Switch to next session tab |
+
+### Sidebar Navigation
+
+| Key | Action |
+|-----|--------|
+| `Shift+Tab` | Cycle sidebar state: hidden → visible → fullscreen |
+| `Escape` | Return to previous sidebar state |
+| `Ctrl+B` | Focus the sidebar (when visible) |
+
+## Shell Mode Usage
+
+Shell mode allows you to execute shell commands directly from the TUI. This is useful for
+running git commands, checking file status, or executing build scripts.
+
+### Enabling Shell Mode
+
+Set the environment variable before launching the TUI:
+
+```bash
+export CLEVERAGENTS_ALLOW_DANGEROUS_SHELL=1
+agents tui
+```
+
+### Executing Shell Commands
+
+Type `!` or `$` followed by the command:
+
+```
+$ git status
+$ npm run build
+! ls -la src/
+```
+
+### Shell Safety
+
+Before execution, the command is scanned for dangerous patterns:
+
+- **Destructive operations** — `rm -rf /`, `dd if=/dev/zero`, etc.
+- **Fork bombs** — `:(){ :|:& };:`
+- **Pipe-to-shell** — `| sh`, `| bash`
+- **Privilege escalation** — `sudo`, `su`
+
+If a dangerous pattern is detected, a warning overlay appears:
+
+```
+⚠️  Dangerous Command Detected
+
+Command: rm -rf /tmp/data
+Danger Level: HIGH
+
+This command will recursively delete files. Proceed with caution.
+
+[Cancel]  [Proceed]
+```
+
+Press `Enter` to proceed or `Escape` to cancel.
+
+See [Shell Danger Detection](../reference/tui_shell_safety.md) for the full pattern registry
+and how to add custom patterns.
+
+## Multi-line Input
+
+The TUI supports multi-line input via the **TextArea widget**. Press `Shift+Enter` to add a
+newline within the prompt:
+
+```
+Tell me about the following:
+
+1. The architecture of the TUI
+2. How personas work
+3. The shell safety system
+```
+
+The prompt symbol changes to `☰` when multi-line mode is active.
+
+**Multi-line Navigation:**
+
+| Key | Action |
+|-----|--------|
+| `Shift+Enter` | Add a newline |
+| `Ctrl+A` | Move to start of line |
+| `Ctrl+E` | Move to end of line |
+| `Ctrl+Home` | Move to start of text |
+| `Ctrl+End` | Move to end of text |
+| `Enter` | Submit the prompt (when not in multi-line mode) |
+
+## Permissions System
+
+When an actor requests a write operation on a resource, the TUI raises a **permissions
+request**. You review the proposed changes and decide whether to allow or reject the operation.
+
+### Single-File Permissions
+
+For single-file operations, an inline **PermissionQuestionWidget** appears in the conversation:
+
+```
+Permission Required
+
+The actor wants to write to:
+  src/api/main.py
+
+  ❯ a  Allow once
+    A  Allow always (this session)
+    r  Reject once
+    R  Reject always (this session)
+
+Press v to open full PermissionsScreen with diff view
+```
+
+**Navigation:**
+
+| Key | Action |
+|-----|--------|
+| `a` | Allow once |
+| `A` | Allow always (this session) |
+| `r` | Reject once |
+| `R` | Reject always (this session) |
+| `↑` / `↓` | Navigate options |
+| `Enter` | Confirm highlighted option |
+| `v` | Open full PermissionsScreen with diff view |
+
+### Multi-File Permissions
+
+For multi-file operations, the **PermissionsScreen** overlay is pushed. This provides a
+split-pane layout:
+
+- **Left pane** — List of files affected
+- **Right pane** — Diff view of the selected file
+
+**Navigation:**
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Navigate file list |
+| `←` / `→` | Switch between panes |
+| `a` | Allow this request once |
+| `A` | Allow all requests from this tool for the session |
+| `r` | Reject this request once |
+| `R` | Reject all requests from this tool for the session |
+| `d` | Cycle diff mode: unified → side-by-side → context |
+
+See [Permissions Reference](../reference/tui_permissions.md) for the full API reference.
+
+## Common Workflows
+
+### Workflow 1: Creating and Executing a Plan
+
+1. **Start a new plan:**
+   ```
+   /plan:use local/my-action my-project
+   ```
+
+2. **Execute the plan:**
+   ```
+   /plan:execute <PLAN_ID>
+   ```
+
+3. **Review the plan:**
+   ```
+   /plan:status
+   ```
+
+4. **Apply the changes:**
+   ```
+   /plan:apply <PLAN_ID>
+   ```
+
+### Workflow 2: Switching Between Personas
+
+1. **List available personas:**
+   ```
+   /persona:list
+   ```
+
+2. **Switch to a persona:**
+   ```
+   /persona:set
+   ```
+
+3. **Cycle through presets:**
+   Press `Ctrl+T` to cycle through argument presets.
+
+### Workflow 3: Managing Multiple Sessions
+
+1. **Create a new session:**
+   Press `Ctrl+N` to create a new session tab.
+
+2. **Switch between sessions:**
+   Press `Ctrl+[` / `Ctrl+]` to navigate tabs.
+
+3. **Close a session:**
+   Press `Ctrl+W` to close the current session.
+
+### Workflow 4: Reviewing Permissions
+
+1. **Wait for a permission request** — The actor will request permission for write operations.
+
+2. **Review the changes:**
+   - For single files, review inline in the conversation.
+   - For multiple files, press `v` to open the full PermissionsScreen.
+
+3. **Make a decision:**
+   - Press `a` to allow once.
+   - Press `A` to allow always (this session).
+   - Press `r` to reject once.
+   - Press `R` to reject always (this session).
+
+### Workflow 5: Executing Shell Commands
+
+1. **Enable shell mode:**
+   ```bash
+   export CLEVERAGENTS_ALLOW_DANGEROUS_SHELL=1
+   agents tui
+   ```
+
+2. **Execute a command:**
+   ```
+   $ git status
+   ```
+
+3. **Review the output** — The command output appears in the conversation.
+
+## Slash Commands Reference
+
+The TUI ships with **67 slash commands** across **14 groups**. Type `/` in the prompt to open
+the overlay and filter by name.
+
+### Session Commands
+
+| Command | Description |
+|---------|-------------|
+| `/session:create` | Create a new session tab |
+| `/session:list` | Display all sessions |
+| `/session:show` | Show session details |
+| `/session:switch` | Switch to a session |
+| `/session:close` | Close the current session |
+| `/session:delete` | Delete a saved session |
+| `/session:rename` | Rename current session |
+| `/session:export` | Export session to JSON |
+| `/session:import` | Import session from JSON |
+
+### Persona Commands
+
+| Command | Description |
+|---------|-------------|
+| `/persona:list` | Display all personas |
+| `/persona:set` | Switch active persona |
+| `/persona:create` | Create a persona |
+| `/persona:edit` | Edit a persona |
+| `/persona:delete` | Delete a persona |
+| `/persona:export` | Export persona YAML |
+| `/persona:import` | Import persona YAML |
+
+### Scope Commands
+
+| Command | Description |
+|---------|-------------|
+| `/scope:add` | Add scope reference |
+| `/scope:remove` | Remove scope reference |
+| `/scope:clear` | Clear session scope additions |
+| `/scope:show` | Show effective scope |
+
+### Plan Commands
+
+| Command | Description |
+|---------|-------------|
+| `/plan:use` | Start a new plan |
+| `/plan:list` | List plans |
+| `/plan:status` | Show plan status |
+| `/plan:tree` | Show decision tree |
+| `/plan:execute` | Execute a plan |
+| `/plan:apply` | Apply a completed plan |
+| `/plan:cancel` | Cancel a plan |
+| `/plan:diff` | Show plan diff |
+| `/plan:correct` | Correct a decision |
+| `/plan:resume` | Resume a plan |
+| `/plan:revert` | Revert plan state |
+| `/plan:rollback` | Rollback to checkpoint |
+| `/plan:explain` | Explain a decision |
+| `/plan:errors` | Show plan errors |
+| `/plan:artifacts` | Show plan artifacts |
+| `/plan:inspect` | Inspect plan details |
+
+### Project Commands
+
+| Command | Description |
+|---------|-------------|
+| `/project:list` | List projects |
+| `/project:create` | Create project |
+| `/project:show` | Show project details |
+| `/project:delete` | Delete project |
+| `/project:inspect` | Inspect project details |
+| `/project:context:show` | Show project context policy |
+
+### Actor Commands
+
+| Command | Description |
+|---------|-------------|
+| `/actor:list` | List actors |
+| `/actor:show` | Show actor details |
+| `/actor:set-default` | Set default actor |
+
+### Resource Commands
+
+| Command | Description |
+|---------|-------------|
+| `/resource:list` | List resources |
+| `/resource:show` | Show resource details |
+| `/resource:tree` | Show resource tree |
+| `/resource:inspect` | Inspect resource details |
+
+### Config Commands
+
+| Command | Description |
+|---------|-------------|
+| `/config:list` | List config entries |
+| `/config:get` | Get config value |
+| `/config:set` | Set config value |
+
+### Tool Commands
+
+| Command | Description |
+|---------|-------------|
+| `/tool:list` | List tools |
+| `/tool:show` | Show tool details |
+
+### Skill Commands
+
+| Command | Description |
+|---------|-------------|
+| `/skill:list` | List skills |
+| `/skill:show` | Show skill details |
+
+### Invariant Commands
+
+| Command | Description |
+|---------|-------------|
+| `/invariant:list` | List invariants |
+| `/invariant:add` | Add invariant |
+| `/invariant:remove` | Remove invariant |
+
+### Profile Commands
+
+| Command | Description |
+|---------|-------------|
+| `/profile:list` | List automation profiles |
+| `/profile:show` | Show automation profile |
+
+### Context Commands
+
+| Command | Description |
+|---------|-------------|
+| `/context:inspect` | Inspect context state |
+| `/context:set` | Set context policy |
+| `/context:simulate` | Simulate context assembly |
+
+### Utility Commands
+
+| Command | Description |
+|---------|-------------|
+| `/clear` | Clear conversation display |
+| `/theme` | Switch color theme |
+| `/settings` | Open settings |
+| `/help` | Show help |
+| `/about` | Show version information |
+| `/debug` | Toggle debug mode |
+
+## Help Panel (F1)
+
+Press `F1` at any time to toggle the context-sensitive help panel. The panel content adapts to
+your current context:
+
+| Context | Triggered when |
+|---------|---------------|
+| **Main Screen** | Prompt is empty or contains normal text |
+| **Slash Commands** | Prompt starts with `/` |
+| **Reference Picker** | Prompt contains `@` |
+| **Shell Mode** | Prompt starts with `!` or `$` |
+
+Each context shows global key bindings plus context-specific shortcuts.
+
+## Persona Bar
+
+The status bar at the bottom of the conversation displays:
+
+```
+<persona_name> | <actor_name> | <preset_name> | <N> scope refs
+```
+
+- **persona_name** — the active persona (e.g. `default`)
+- **actor_name** — the actor bound to the persona (e.g. `openai/gpt-4o`)
+- **preset_name** — the active argument preset (e.g. `default`)
+- **scope refs** — count of scoped projects and plans
+
+Use `Ctrl+T` to cycle through the argument presets defined in the active persona.
+
+## Troubleshooting
+
+### TUI won't start
+
+**Error:** `RuntimeError: Textual dependency missing`
+
+**Solution:** Install the TUI extra:
+```bash
+pip install 'cleveragents[tui]'
+```
+
+### Shell commands are blocked
+
+**Error:** `Shell execution is disabled`
+
+**Solution:** Enable shell mode by setting the environment variable:
+```bash
+export CLEVERAGENTS_ALLOW_DANGEROUS_SHELL=1
+agents tui
+```
+
+### Persona not found
+
+**Error:** `Persona 'my-persona' not found`
+
+**Solution:** List available personas with `/persona:list` and switch to an existing one with
+`/persona:set`.
+
+### Reference picker not working
+
+**Issue:** The `@` overlay doesn't appear when typing `@`
+
+**Solution:** Make sure you're in normal mode (not shell mode). The reference picker only
+works in normal mode.
+
+### Multi-line input not working
+
+**Issue:** `Shift+Enter` doesn't create a new line
+
+**Solution:** Some terminal emulators don't support `Shift+Enter`. Try using `Ctrl+Enter`
+instead, or check your terminal's key binding configuration.
+
+### Permission requests not appearing
+
+**Issue:** The actor requests permission but no overlay appears
+
+**Solution:** Check that the actor has permission to write to the target resource. If the
+permission request is for a non-file resource, it may appear as a question widget instead of
+an inline permission widget.
+
+## Related Documentation
+
+- [TUI Reference](../reference/tui.md)
+- [TUI Keybindings Reference](tui_keybindings.md)
+- [TUI Permissions Reference](../reference/tui_permissions.md)
+- [TUI Permission Question Widget](../reference/tui_permission_question.md)
+- [TUI Shell Danger Detection](../reference/tui_shell_safety.md)
+- [TUI Thought Blocks](../reference/tui_thought_block.md)
+- [Persona System Reference](../reference/persona.md)
+- [ADR-044: TUI Architecture and Framework](../adr/ADR-044-tui-architecture-and-framework.md)
+- [ADR-045: TUI Persona System](../adr/ADR-045-tui-persona-system.md)
+- [ADR-046: TUI Reference and Command System](../adr/ADR-046-tui-reference-and-command-system.md)

mkdocs.yml

@@ -44,6 +44,9 @@ nav:
     - Documentation Writer: development/docs-writer.md
   - Implementation Timeline: timeline.md
   - FAQ: faq.md
+  - Guides:
+    - TUI User Guide: guides/tui_user_guide.md
+    - TUI Keybindings Reference: guides/tui_keybindings.md
   - Reference: reference/
   - Architecture Decision Records (ADRs):
     - Overview: adr/index.md