# Documentation Index

[Top](../README.md)

---

## Overview

This documentation suite provides comprehensive technical reference for the Manual Slop application — a GUI orchestrator for local LLM-driven coding sessions. The guides follow a strict old-school technical documentation style, emphasizing architectural depth, state management details, algorithmic breakdowns, and structural formats.

---

## Guides

| Guide | Contents |
|---|---|
| [Architecture](guide_architecture.md) | Thread domains (GUI Main, Asyncio Worker, HookServer, Ad-hoc), cross-thread data structures (AsyncEventQueue, Guarded Lists, Condition-Variable Dialogs), event system (EventEmitter, SyncEventQueue, UserRequestEvent), application lifetime (boot sequence, shutdown sequence), task pipeline (producer-consumer synchronization), Execution Clutch (HITL mechanism with ConfirmDialog, MMAApprovalDialog, MMASpawnApprovalDialog), AI client multi-provider architecture (Gemini SDK, Anthropic, DeepSeek, Gemini CLI, MiniMax), Anthropic/Gemini caching strategies (4-breakpoint system, server-side TTL), context refresh mechanism (mtime-based file re-reading, diff injection), comms logging (JSON-L format), state machines (ai_status, HITL dialog state) |
| [Meta-Boundary](guide_meta_boundary.md) | Explicit distinction between the Application's domain (Strict HITL — `gui_2.py`, `ai_client.py`, `multi_agent_conductor.py`, `dag_engine.py`) and the Meta-Tooling domain (`scripts/mma_exec.py`, `scripts/claude_mma_exec.py`, `scripts/tool_call.py`, `scripts/mcp_server.py`, `.gemini/`, `.claude/`), preventing feature bleed and safety bypasses via shared bridges like `mcp_client.py`. Documents the Inter-Domain Bridges (`cli_tool_bridge.py`, `claude_tool_bridge.py`) and the `GEMINI_CLI_HOOK_CONTEXT` environment variable. |
| [Tools & IPC](guide_tools.md) | MCP Bridge 3-layer security model (Allowlist Construction, Path Validation, Resolution Gate), all 26 native tool signatures with parameters and behavior (File I/O, AST-Based, Analysis, Network, Runtime), Hook API GET/POST endpoints with request/response formats, ApiHookClient method reference (Connection Methods, State Query Methods, GUI Manipulation Methods, Polling Methods, HITL Method), `/api/ask` synchronous HITL protocol (blocking request-response over HTTP), session logging (comms.log, toolcalls.log, apihooks.log, clicalls.log, scripts/generated/*.ps1), shell runner (mcp_env.toml configuration, run_powershell function with timeout handling and QA callback integration) |
| [MMA Orchestration](guide_mma.md) | Ticket/Track/WorkerContext data structures (from `models.py`), DAG engine (TrackDAG class with cycle detection, topological sort, cascade_blocks; ExecutionEngine class with tick-based state machine), ConductorEngine execution loop (run method, _push_state for state broadcast, parse_json_tickets for ingestion), Tier 2 ticket generation (generate_tickets, topological_sort), Tier 3 worker lifecycle (run_worker_lifecycle with Context Amnesia, AST skeleton injection, HITL clutch integration via confirm_spawn and confirm_execution), Tier 4 QA integration (run_tier4_analysis, run_tier4_patch_callback), token firewalling (tier_usage tracking, model escalation), track state persistence (TrackState, save_track_state, load_track_state, get_all_tracks) |
| [Simulations](guide_simulations.md) | Structural Testing Contract (Ban on Arbitrary Core Mocking, `live_gui` Standard, Artifact Isolation), `live_gui` pytest fixture lifecycle (spawning, readiness polling, failure path, teardown, session isolation via reset_ai_client), VerificationLogger for structured diagnostic logging, process cleanup (kill_process_tree for Windows/Unix), Puppeteer pattern (8-stage MMA simulation with mock provider setup, epic planning, track acceptance, ticket loading, status transitions, worker output verification), mock provider strategy (`tests/mock_gemini_cli.py` with JSON-L protocol, input mechanisms, response routing, output protocol), visual verification patterns (DAG integrity, stream telemetry, modal state, performance monitoring), supporting analysis modules (ASTParser with tree-sitter, summarize.py heuristic summaries, outline_tool.py hierarchical outlines) |

---

## GUI Panels

### Context Hub

The primary panel for project and file management.

- **Project Selector**: Switch between `<project>.toml` configurations. Changing projects swaps the active file list, discussion history, and settings.
- **Git Directory**: Path to the repository for commit tracking and git operations.
- **Main Context File**: Optional primary context document for the project.
- **Output Dir**: Directory where generated markdown files are written.
- **Word-Wrap Toggle**: Dynamically swaps text rendering in large read-only panels between unwrapped (code formatting) and wrapped (prose).
- **Summary Only**: When enabled, sends file structure summaries instead of full content to reduce token usage.
- **Auto-Scroll Comms/Tool History**: Automatically scrolls to the bottom when new entries arrive.

### Files & Media Panel

Controls what context is compiled and sent to the AI.

- **Base Dir**: Root directory for path resolution and MCP tool constraints.
- **Paths**: Explicit files or wildcard globs (`src/**/*.py`).
- **File Flags**:
  - **Auto-Aggregate**: Include in context compilation.
  - **Force Full**: Bypass summary-only mode for this file.
- **Cache Indicator**: Green dot (●) indicates file is in provider's context cache.

### Discussion Hub

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, Context, Tool, Vendor API). 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.
- **Truncate History**: Reduces history to N most recent User/AI pairs.

### AI Settings Panel

- **Provider**: Switch between API backends (Gemini, Anthropic, DeepSeek, Gemini CLI, MiniMax).
- **Model**: Select from available models for the current provider.
- **Fetch Models**: Queries the active provider for the latest model list.
- **Temperature / Max Tokens**: Generation parameters.
- **History Truncation Limit**: Character limit for truncating old tool outputs.

### Token Budget Panel

- **Current Usage**: Real-time token counts (input, output, cache read, cache creation).
- **Budget Percentage**: Visual indicator of context window utilization.
- **Provider-Specific Limits**: Anthropic (180K prompt), Gemini (900K input).

### Cache Panel

- **Gemini Cache Stats**: Count, total size, and list of cached files.
- **Clear Cache**: Forces cache invalidation on next send.

### Tool Analytics Panel

- **Per-Tool Statistics**: Call count, total time, failure count for each tool.
- **Session Insights**: Burn rate estimation, average latency.

### Message & Response Panels

- **Message**: User input field with auto-expanding height.
- **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.

### Operations Hub

- **Focus Agent Filter**: Show comms/tool history for specific tier (All, Tier 2, Tier 3, Tier 4).
- **Comms History**: Real-time display of raw API traffic (timestamp, direction, kind, provider, model, payload preview).
- **Tool Calls**: Sequential log of tool invocations with script/args and result preview.

### MMA Dashboard

The 4-tier orchestration control center.

- **Track Browser**: List of all tracks with status, progress, and actions (Load, Delete).
- **Active Track Summary**: Color-coded progress bar, ticket status breakdown (Completed, In Progress, Blocked, Todo), ETA estimation.
- **Visual Task DAG**: Node-based visualization using `imgui-node-editor` with color-coded states (Ready, Running, Blocked, Done).
- **Ticket Queue Management**: Bulk operations (Execute, Skip, Block), drag-and-drop reordering, priority assignment.
- **Tier Streams**: Real-time output from Tier 1/2/3/4 agents.

### Tier Stream Panels

Dedicated windows for each MMA tier:

- **Tier 1: Strategy**: Orchestrator output for epic planning and track initialization.
- **Tier 2: Tech Lead**: Architectural decisions and ticket generation.
- **Tier 3: Workers**: Individual worker output streams (one per active ticket).
- **Tier 4: QA**: Error analysis and diagnostic summaries.

### Log Management

- **Session Registry**: Table of all session logs with metadata (start time, message count, size, whitelist status).
- **Star/Unstar**: Mark sessions for preservation during pruning.
- **Force Prune**: Manually trigger aggressive log cleanup.

### Diagnostics Panel

- **Performance Telemetry**: FPS, Frame Time, CPU %, Input Lag with moving averages.
- **Detailed Component Timings**: Per-panel rendering times with threshold alerts.
- **Performance Graphs**: Historical plots for selected metrics.

---

## Configuration Files

### config.toml (Global)

```toml
[ai]
provider = "gemini"
model = "gemini-2.5-flash-lite"
temperature = 0.0
max_tokens = 8192
history_trunc_limit = 8000
system_prompt = ""

[projects]
active = "path/to/project.toml"
paths = ["path/to/project.toml"]

[gui]
separate_message_panel = false
separate_response_panel = false
separate_tool_calls_panel = false
show_windows = { "Context Hub": true, ... }

[paths]
logs_dir = "logs/sessions"
scripts_dir = "scripts/generated"
conductor_dir = "conductor"

[mma]
max_workers = 4
```

### <project>.toml (Per-Project)

```toml
[project]
name = "my_project"
git_dir = "./my_repo"
system_prompt = ""
main_context = ""

[files]
base_dir = "."
paths = ["src/**/*.py"]
tier_assignments = { "src/core.py" = 1 }

[screenshots]
base_dir = "."
paths = []

[output]
output_dir = "./md_gen"

[gemini_cli]
binary_path = "gemini"

[deepseek]
reasoning_effort = "medium"

[agent.tools]
run_powershell = true
read_file = true
list_directory = true
search_files = true
get_file_summary = true
web_search = true
fetch_url = true
py_get_skeleton = true
py_get_code_outline = true
get_file_slice = true
set_file_slice = false
edit_file = false
py_get_definition = true
py_update_definition = false
py_get_signature = true
py_set_signature = false
py_get_class_summary = true
py_get_var_declaration = true
py_set_var_declaration = false
get_git_diff = true
py_find_usages = true
py_get_imports = true
py_check_syntax = true
py_get_hierarchy = true
py_get_docstring = true
get_tree = true
get_ui_performance = true

[mma]
epic = ""
active_track_id = ""
tracks = []
```

### credentials.toml

```toml
[gemini]
api_key = "YOUR_KEY"

[anthropic]
api_key = "YOUR_KEY"

[deepseek]
api_key = "YOUR_KEY"

[minimax]
api_key = "YOUR_KEY"
```

### mcp_env.toml (Optional)

```toml
[path]
prepend = ["C:/custom/bin"]

[env]
MY_VAR = "some_value"
EXPANDED = "${HOME}/subdir"
```

---

## Environment Variables

| Variable | Purpose |
|---|---|
| `SLOP_CONFIG` | Override path to `config.toml` |
| `SLOP_CREDENTIALS` | Override path to `credentials.toml` |
| `SLOP_MCP_ENV` | Override path to `mcp_env.toml` |
| `SLOP_TEST_HOOKS` | Set to `"1"` to enable test hooks |
| `SLOP_LOGS_DIR` | Override logs directory |
| `SLOP_SCRIPTS_DIR` | Override generated scripts directory |
| `SLOP_CONDUCTOR_DIR` | Override conductor directory |
| `GEMINI_CLI_HOOK_CONTEXT` | Set by bridge scripts to bypass HITL for sub-agents |
| `CLAUDE_CLI_HOOK_CONTEXT` | Set by bridge scripts to bypass HITL for sub-agents |

---

## Exit Codes

| Code | Meaning |
|---|---|
| 0 | Normal exit |
| 1 | General error |
| 2 | Configuration error |
| 3 | API error |
| 4 | Test failure |

---

## File Layout

```
manual_slop/
├── conductor/              # Conductor system
│   ├── tracks/             # Track directories
│   │   └── <track_id>/     # Per-track files
│   │       ├── spec.md
│   │       ├── plan.md
│   │       ├── metadata.json
│   │       └── state.toml
│   ├── archive/            # Completed tracks
│   ├── product.md          # Product definition
│   ├── product-guidelines.md
│   ├── tech-stack.md
│   └── workflow.md
├── docs/                   # Deep-dive documentation
│   ├── guide_architecture.md
│   ├── guide_meta_boundary.md
│   ├── guide_mma.md
│   ├── guide_simulations.md
│   └── guide_tools.md
├── logs/                   # Runtime logs
│   ├── sessions/           # Session logs
│   │   └── <session_id>/   # Per-session files
│   │       ├── comms.log
│   │       ├── toolcalls.log
│   │       ├── apihooks.log
│   │       └── clicalls.log
│   ├── agents/             # Sub-agent logs
│   ├── errors/             # Error logs
│   └── test/               # Test logs
├── scripts/                # Utility scripts
│   ├── generated/          # AI-generated scripts
│   └── *.py                # Build/execution scripts
├── src/                    # Core implementation
│   ├── gui_2.py            # Primary ImGui interface
│   ├── app_controller.py   # Headless controller
│   ├── ai_client.py        # Multi-provider LLM abstraction
│   ├── mcp_client.py       # 26 MCP tools
│   ├── api_hooks.py        # HookServer REST API
│   ├── api_hook_client.py  # Hook API client
│   ├── multi_agent_conductor.py  # ConductorEngine
│   ├── conductor_tech_lead.py    # Tier 2 ticket generation
│   ├── dag_engine.py       # TrackDAG + ExecutionEngine
│   ├── models.py           # Ticket, Track, WorkerContext
│   ├── events.py           # EventEmitter, SyncEventQueue
│   ├── project_manager.py  # TOML persistence
│   ├── session_logger.py   # JSON-L logging
│   ├── shell_runner.py     # PowerShell execution
│   ├── file_cache.py       # ASTParser (tree-sitter)
│   ├── summarize.py        # Heuristic summaries
│   ├── outline_tool.py     # Code outlining
│   ├── performance_monitor.py  # FPS/CPU tracking
│   ├── log_registry.py     # Session metadata
│   ├── log_pruner.py       # Log cleanup
│   ├── paths.py            # Path resolution
│   ├── cost_tracker.py     # Token cost estimation
│   ├── gemini_cli_adapter.py  # CLI subprocess adapter
│   ├── mma_prompts.py      # Tier system prompts
│   └── theme*.py           # UI theming
├── simulation/             # Test simulations
│   ├── sim_base.py         # BaseSimulation class
│   ├── workflow_sim.py     # WorkflowSimulator
│   ├── user_agent.py       # UserSimAgent
│   └── sim_*.py            # Specific simulations
├── tests/                  # Test suite
│   ├── conftest.py         # Fixtures (live_gui)
│   ├── artifacts/          # Test outputs
│   └── test_*.py           # Test files
├── sloppy.py               # Main entry point
├── config.toml             # Global configuration
└── credentials.toml        # API keys
```