manual_slop/conductor/tracks/documentation_refresh_20260224/plan.md

Implementation Plan: Deep Architectural Documentation Refresh

Phase 1: Context Cleanup & Research

• Task: Audit references to MainContext.md across the project.
• Task: Delete MainContext.md and update any identified references.
• Task: Execute py_get_skeleton and py_get_code_outline for events.py, api_hooks.py, api_hook_client.py, and gui_2.py to create a technical map for the guides.
• Task: Analyze the live_gui fixture in tests/conftest.py and the simulation loop in tests/visual_sim_mma_v2.py.

Phase 2: Core Architecture Deep Dive

Update docs/guide_architecture.md with expert-level detail.

• Task: Document the Dual-Threaded App Lifetime: Main GUI loop vs. Daemon execution threads.
• Task: Detail the AsyncEventQueue and EventEmitter roles in the decoupling strategy.
• Task: Explain the _pending_gui_tasks synchronization mechanism for bridging the Hook Server and GUI.
• Task: Document the "Linear Execution Clutch" and its deterministic state machine.
• Task: Verify the architectural descriptions against the actual implementation.
• Task: Conductor - User Manual Verification 'Phase 2: Core Architecture Deep Dive' (Protocol in workflow.md)

Phase 3: Hook System & Tooling Technical Reference

Update docs/guide_tools.md to include low-level API details.

• Task: Create a comprehensive API reference for all HookServer endpoints.
• Task: Document the ApiHookClient implementation, including retries and polling strategies.
• Task: Update the MCP toolset guide with current native tool implementations.
• Task: Document the ask/respond IPC flow for "Human-in-the-Loop" confirmations.
• Task: Conductor - User Manual Verification 'Phase 3: Hook System & Tooling Technical Reference' (Protocol in workflow.md)

Phase 4: Verification & Simulation Framework

Create the new docs/guide_simulations.md guide.

• Task: Detail the Live GUI testing infrastructure: --enable-test-hooks and the live_gui fixture.
• Task: Breakdown the Simulation Lifecycle: Startup, Polling, Interaction, and Assertion.
• Task: Document the mock provider strategy using tests/mock_gemini_cli.py.
• Task: Provide examples of visual verification tests (e.g., MMA lifecycle).
• Task: Conductor - User Manual Verification 'Phase 4: Verification & Simulation Framework' (Protocol in workflow.md)

Phase 5: README & Roadmap Update

• Task: Update Readme.md with current setup (uv, credentials.toml) and vision.
• Task: Perform a project-wide link validation of all Markdown files.
• Task: Verify the high-density information style across all documentation.
• Task: Conductor - User Manual Verification 'Phase 5: README & Roadmap Update' (Protocol in workflow.md)