# Track Specification: Deep Architectural Documentation Refresh

## Overview
This track implements a high-density, expert-level documentation suite for the Manual Slop project. The documentation style is strictly modeled after the **pedagogical and narrative standards** of `gencpp` and `VEFontCache-Odin`. It moves beyond simple "User Guides" to provide a **"USA Graphics Company"** architectural reference: high information density, tactical technical transparency, and a narrative intent that guides a developer from high-level philosophy to low-level implementation.

## Pedagogical Goals
1.  **Narrative Intent:** Documentation must transition the reader through a logical learning journey: **Philosophy/Mental Model -> Architectural Boundaries -> Implementation Logic -> Verification/Simulation.**
2.  **High Information Density:** Eliminate conversational filler and "fluff." Every sentence must provide architectural signal (state transitions, data flows, constraints).
3.  **Technical Transparency:** Document the "How" and "Why" behind design decisions (e.g., *Why* the dual-threaded `Asyncio` loop? *How* does the "Execution Clutch" bridge the thread gap?).
4.  **Architectural Mapping:** Use precise symbol names (`AsyncEventQueue`, `_pending_gui_tasks`, `HookServer`) to map the documentation directly to the source code.
5.  **Multi-Layered Depth:** Each major component (Architecture, Tools, Simulations) must have its own dedicated, expert-level guide. No consolidation into single, shallow files.

## Functional Requirements (Documentation Areas)

### 1. Core Architecture (`docs/guide_architecture.md`)
-   **System Philosophy:** The "Decoupled State Machine" mental model.
-   **Application Lifetime:** The multi-threaded boot sequence and the "Dual-Flush" persistence model.
-   **The Task Pipeline:** Detailed producer-consumer synchronization between the GUI (Main) and AI (Daemon) threads.
-   **The Execution Clutch (HITL):** Detailed state machine for human-in-the-loop interception and payload mutation.

### 2. Tooling & IPC Reference (`docs/guide_tools.md`)
-   **MCP Bridge:** Low-level security constraints and filesystem sandboxing.
-   **Hook API:** A full technical reference for the REST/IPC interface (endpoints, payloads, diagnostics).
-   **IPC Flow:** The `ask/respond` sequence for synchronous human-in-the-loop requests.

### 3. Verification & Simulation Framework (`docs/guide_simulations.md`)
-   **Infrastructure:** The `--enable-test-hooks` flag and the `live_gui` pytest fixture.
-   **Lifecycle:** The "Puppeteer" pattern for driving the GUI via automated clients.
-   **Mocking Strategy:** Script-based AI provider mocking via `mock_gemini_cli.py`.
-   **Visual Assertion:** Examples of verifying the rendered state (DAG, Terminal streams) rather than just API returns.

### 4. Product Vision & Roadmap (`Readme.md`)
-   **Technological Identity:** High-density experimental tool for local AI orchestration.
-   **Pedagogical Landing:** Direct links to the deep-dive guides to establish the project's expert-level tone immediately.

## Acceptance Criteria for Expert Review (Claude Opus)
-   [ ] **Zero Filler:** No introductory "In this section..." or "Now we will..." conversational markers.
-   [ ] **Structural Parity:** Documentation follows the `gencpp` pattern (Philosophy -> Code Paths -> Interface).
-   [ ] **Expert-Level Detail:** Includes data structures, locking mechanisms, and thread-safety constraints.
-   [ ] **Narrative Cohesion:** The documents feel like a single, expert-authored manual for a complex graphics or systems engine.
-   [ ] **Tactile Interaction:** Explains the "Linear Execution Clutch" as a physical shift in the application's processing gears.

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