# Track Specification: Deep Architectural Documentation Refresh

## Overview
This track implements a high-density, expert-level documentation suite for the Manual Slop project, focusing on the complex asynchronous orchestration, the 4-Tier MMA (Hierarchical Multi-Model Architecture), and the robust visual simulation framework. The documentation style adheres to the "USA Graphics Company" values of high information density, tactile interaction, and deep technical transparency, inspired by the architectural guides of `VEFontCache-Odin` and `gencpp`.

## Goals
1.  **Architectural Deep Dive:** Document the core engine, focusing on state management, asynchronous event loops, and the decoupling of the GUI from the AI client.
2.  **Hook System Technical Reference:** Provide a low-level guide to the `HookServer`, `HookHandler`, and the IPC mechanism used for automated verification.
3.  **Simulation & Testing Framework:** Detail the live GUI simulation strategy, including the use of `pytest` fixtures, `ApiHookClient`, and mock providers.
4.  **MMA Orchestration Logic:** Document the 4-Tier hierarchy (Orchestrator, Tech Lead, Worker, QA), token firewalling, and the DAG-based task execution engine.
5.  **Event Handling System:** Explain the dual event architecture using both synchronous `EventEmitter` and asynchronous `AsyncEventQueue`.

## Functional Requirements (Documentation Areas)

### 1. Core Architecture (`docs/guide_architecture.md`)
-   **Lifetime & Execution Loop:** Detailed breakdown of the application startup, the interaction between the main thread and daemon threads, and the event-driven updates.
-   **Asynchronous Orchestration:** Documentation of the `AsyncEventQueue` and how it prevents GUI blocking during long-running AI operations.
-   **State Synchronization:** How the `_pending_gui_tasks` queue and `threading.Lock` are used to safely bridge the Hook Server thread and the Main GUI thread.
-   **Linear Execution Clutch:** Explanation of the deterministic debugging mode and the step-through execution logic.

### 2. Tooling & Hooks (`docs/guide_tools.md`)
-   **IPC & Hook API:** A complete reference for all `/api/` endpoints, including data structures for `mma_status`, `diagnostics`, and `ask/respond`.
-   **ApiHookClient:** Usage guide for the requests-based client, detailing polling strategies and retry logic.
-   **MCP Toolset:** Updated documentation for the native MCP-like tools (file I/O, search, web fetch) and their security allowlist.

### 3. Verification & Simulation (`docs/guide_simulations.md` - NEW)
-   **Live GUI Verification:** How to run the app with `--enable-test-hooks` and use the `live_gui` fixture for end-to-end testing.
-   **Visual Simulation Lifecycle:** Detailed breakdown of `tests/visual_sim_mma_v2.py`, explaining how it simulates user interaction and verifies rendered state (e.g., DAG nodes, stream output).
-   **Mocking AI Providers:** How to use `tests/mock_gemini_cli.py` to test the full orchestration loop without incurring API costs.

### 4. README & Vision (`Readme.md`)
-   **Setup & Telemetry:** Updated instructions for `uv` and `credentials.toml`.
-   **Feature Roadmap:** Highlighting the MMA Dashboard, DAG engine, and the 4-Tier delegation model.

## Non-Functional Requirements
-   **Indentation & Formatting:** Follow the project's AI-optimized compact style (1-space indentation for code snippets).
-   **High Information Density:** Avoid conversational filler; focus on state transitions, data flow, and architectural constraints.
-   **Accurate Code Linkage:** Documentation must include specific file names and symbol references (e.g., `AsyncEventQueue`, `_cb_accept_tracks`).

## Acceptance Criteria
-   [ ] `docs/guide_architecture.md` updated with "Odin-style" depth.
-   [ ] `docs/guide_tools.md` contains a full API reference for the Hook system.
-   [ ] `docs/guide_simulations.md` created, detailing the visual verification suite.
-   [ ] `Readme.md` reflects the current high-density product vision.
-   [ ] `MainContext.md` decommissioned and references removed.

## Out of Scope
-   Documenting legacy `gui_legacy.py` code beyond its role as a fallback.
-   Visual diagram generation (focusing on high-quality text-based architectural mapping).