# Documentation Index

[Top](../Readme.md)

---

## Guides

| Guide | Contents |
|---|---|
| [Architecture](guide_architecture.md) | Thread domains, cross-thread data structures, event system, application lifetime, task pipeline (producer-consumer), Execution Clutch (HITL), AI client multi-provider architecture, Anthropic/Gemini caching strategies, context refresh, comms logging, state machines |
| [Tools & IPC](guide_tools.md) | MCP Bridge 3-layer security model, all 26 native tool signatures, Hook API GET/POST endpoints with request/response formats, ApiHookClient method reference, `/api/ask` synchronous HITL protocol, session logging, shell runner |
| [MMA Orchestration](guide_mma.md) | Ticket/Track/WorkerContext data structures, DAG engine (cycle detection, topological sort), ConductorEngine execution loop, Tier 2 ticket generation, Tier 3 worker lifecycle with context amnesia, Tier 4 QA integration, token firewalling, track state persistence |
| [Simulations](guide_simulations.md) | `live_gui` pytest fixture lifecycle, `VerificationLogger`, process cleanup, Puppeteer pattern (8-stage MMA simulation), approval automation, mock provider (`mock_gemini_cli.py`) with JSON-L protocol, visual verification patterns, ASTParser (tree-sitter) vs summarizer (stdlib `ast`) |

---

## GUI Panels

### Projects Panel

Configuration and context management. Specifies the Git Directory (for commit tracking) and tracked file paths. Project switching swaps the active file list, discussion history, and settings via `<project>.toml` profiles.

- **Word-Wrap Toggle**: Dynamically swaps text rendering in large read-only panels (Responses, Comms Log) between unwrapped (code formatting) and wrapped (prose).

### Discussion History

Manages conversational branches to prevent context poisoning across tasks.

- **Discussions Sub-Menu**: Create separate timelines for different tasks (e.g., "Refactoring Auth" vs. "Adding API Endpoints").
- **Git Commit Tracking**: "Update Commit" reads HEAD from the project's git directory and stamps the discussion.
- **Entry Management**: Each turn has a Role (User, AI, System). Toggle between Read/Edit modes, collapse entries, or open in the Global Text Viewer via `[+ Max]`.
- **Auto-Add**: When toggled, Message panel sends and Response panel returns are automatically appended to the current discussion.

### Files & Screenshots

Controls what is fed into the context compiler.

- **Base Dir**: Defines the root for path resolution and MCP tool constraints.
- **Paths**: Explicit files or wildcard globs (`src/**/*.rs`).
- Full file contents are inlined by default. The AI can call `get_file_summary` for compact structural views.

### Provider

Switches between API backends (Gemini, Anthropic, DeepSeek, Gemini CLI). "Fetch Models" queries the active provider for the latest model list.

### Message & Response

- **Message**: User input field.
- **Gen + Send**: Compiles markdown context and dispatches to the AI via `AsyncEventQueue`.
- **MD Only**: Dry-runs the compiler for context inspection without API cost.
- **Response**: Read-only output; flashes green on new response.

### Global Text Viewer & Script Outputs

- **Last Script Output**: Pops up (flashing blue) whenever the AI executes a script. Shows both the executed script and stdout/stderr. `[+ Maximize]` reads from stored instance variables, not DPG widget tags, so it works regardless of word-wrap state.
- **Text Viewer**: Large resizable popup invoked by `[+]` / `[+ Maximize]` buttons. For deep-reading long logs, discussion entries, or script bodies.
- **Confirm Dialog**: The `[+ Maximize]` button in the script approval modal passes script text as `user_data` at button-creation time — safe to click even after the dialog is dismissed.

### Tool Calls & Comms History

Real-time display of MCP tool invocations and raw API traffic. Each comms entry: timestamp, direction (OUT/IN), kind, provider, model, payload.

### MMA Dashboard

Displays the 4-tier orchestration state: active track, ticket DAG with status indicators, per-tier token usage, output streams. Approval buttons for spawn/step/tool gates.

### System Prompts

Two text inputs for instruction overrides:
1. **Global**: Applied across every project.
2. **Project**: Specific to the active workspace.

Concatenated onto the base tool-usage guidelines.