Files

Ed_ 08e003a137 docs: Complete documentation rewrite at gencpp/VEFontCache reference quality

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>

2026-03-01 09:44:50 -05:00

4.2 KiB

Raw Blame History

Documentation Index

Top

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_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:

Global: Applied across every project.
Project: Specific to the active workspace.

Concatenated onto the base tool-usage guidelines.

4.2 KiB Raw Blame History