Ed_
08e003a137
Rewrites all docs from Gemini's 330-line executive summaries to 1874 lines of expert-level architectural reference matching the pedagogical depth of gencpp (Parser_Algo.md, AST_Types.md) and VEFontCache-Odin (guide_architecture.md). Changes: - guide_architecture.md: 73 -> 542 lines. Adds inline data structures for all dialog classes, cross-thread communication patterns, complete action type catalog, provider comparison table, 4-breakpoint Anthropic cache strategy, Gemini server-side cache lifecycle, context refresh algorithm. - guide_tools.md: 66 -> 385 lines. Full 26-tool inventory with parameters, 3-layer MCP security model walkthrough, all Hook API GET/POST endpoints with request/response formats, ApiHookClient method reference, /api/ask synchronous HITL protocol, shell runner with env config. - guide_mma.md: NEW (368 lines). Fills major documentation gap — complete Ticket/Track/WorkerContext data structures, DAG engine algorithms (cycle detection, topological sort), ConductorEngine execution loop, Tier 2 ticket generation, Tier 3 worker lifecycle with context amnesia, token firewalling. - guide_simulations.md: 64 -> 377 lines. 8-stage Puppeteer simulation lifecycle, mock_gemini_cli.py JSON-L protocol, approval automation pattern, ASTParser tree-sitter vs stdlib ast comparison, VerificationLogger. - Readme.md: Rewritten with module map, architecture summary, config examples. - docs/Readme.md: Proper index with guide contents table and GUI panel docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Documentation Index
Guides
| Guide | Contents |
|---|---|
| Architecture | 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 | 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 | 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 | 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_summaryfor 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 asuser_dataat 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:
- Global: Applied across every project.
- Project: Specific to the active workspace.
Concatenated onto the base tool-usage guidelines.