From cec62dad1c31223e7240a4f4f61a7df7f83e0da3 Mon Sep 17 00:00:00 2001
From: dave <futurechimp@users.noreply.github.com>
Date: Sun, 12 Apr 2026 13:11:23 +0000
Subject: [PATCH] huskies: merge
 542_refactor_add_doc_comments_to_all_undocumented_source_files_and_generate_source_map_in_readme

---
 README.md                                     | 278 ++++++++++++++++++
 server/src/agent_log.rs                       |   1 +
 server/src/agent_mode.rs                      |   1 +
 server/src/agents/gates.rs                    |   1 +
 server/src/agents/lifecycle.rs                |   1 +
 server/src/agents/merge.rs                    |   1 +
 server/src/agents/mod.rs                      |   1 +
 server/src/agents/pool/mod.rs                 |   1 +
 server/src/agents/pool/pipeline/advance.rs    |   1 +
 server/src/agents/pool/pipeline/completion.rs |   1 +
 server/src/agents/pool/pipeline/merge.rs      |   1 +
 server/src/agents/pool/pipeline/mod.rs        |   1 +
 server/src/agents/pool/process.rs             |   1 +
 server/src/agents/pool/query.rs               |   1 +
 server/src/agents/pool/start.rs               |   1 +
 server/src/agents/pool/stop.rs                |   1 +
 server/src/agents/pool/test_helpers.rs        |   1 +
 server/src/agents/pool/types.rs               |   1 +
 server/src/agents/pool/wait.rs                |   1 +
 server/src/agents/pool/worktree.rs            |   1 +
 server/src/agents/pty.rs                      |   1 +
 server/src/agents/runtime/claude_code.rs      |   1 +
 server/src/agents/runtime/gemini.rs           |   1 +
 server/src/agents/runtime/mod.rs              |   1 +
 server/src/agents/runtime/openai.rs           |   1 +
 server/src/agents/token_usage.rs              |   1 +
 .../src/chat/transport/matrix/bot/context.rs  |   1 +
 .../src/chat/transport/matrix/bot/format.rs   |   1 +
 .../src/chat/transport/matrix/bot/history.rs  |   1 +
 .../src/chat/transport/matrix/bot/mentions.rs |   1 +
 .../src/chat/transport/matrix/bot/messages.rs |   1 +
 server/src/chat/transport/matrix/bot/mod.rs   |   1 +
 server/src/chat/transport/matrix/bot/run.rs   |   1 +
 .../chat/transport/matrix/bot/verification.rs |   1 +
 server/src/chat/transport/matrix/config.rs    |   1 +
 server/src/chat/transport/mod.rs              |   1 +
 .../src/chat/transport/whatsapp/commands.rs   |   1 +
 server/src/chat/transport/whatsapp/format.rs  |   1 +
 server/src/chat/transport/whatsapp/history.rs |   1 +
 server/src/chat/transport/whatsapp/meta.rs    |   1 +
 server/src/chat/transport/whatsapp/twilio.rs  |   1 +
 server/src/config.rs                          |   1 +
 server/src/crdt_state.rs                      |   1 +
 server/src/crdt_sync.rs                       |   1 +
 server/src/crdt_wire.rs                       |   1 +
 server/src/db/mod.rs                          |   1 +
 server/src/http/agents.rs                     |   1 +
 server/src/http/agents_sse.rs                 |   1 +
 server/src/http/anthropic.rs                  |   1 +
 server/src/http/assets.rs                     |   1 +
 server/src/http/chat.rs                       |   1 +
 server/src/http/context.rs                    |   1 +
 server/src/http/health.rs                     |   1 +
 server/src/http/io.rs                         |   1 +
 server/src/http/mcp/agent_tools.rs            |   1 +
 server/src/http/mcp/diagnostics.rs            |   1 +
 server/src/http/mcp/git_tools.rs              |   1 +
 server/src/http/mcp/merge_tools.rs            |   1 +
 server/src/http/mcp/mod.rs                    |   1 +
 server/src/http/mcp/qa_tools.rs               |   1 +
 server/src/http/mcp/shell_tools.rs            |   1 +
 server/src/http/mcp/status_tools.rs           |   1 +
 server/src/http/mcp/story_tools.rs            |   1 +
 server/src/http/mod.rs                        |   1 +
 server/src/http/model.rs                      |   1 +
 server/src/http/oauth.rs                      |   1 +
 server/src/http/project.rs                    |   1 +
 server/src/http/settings.rs                   |   1 +
 server/src/http/wizard.rs                     |   1 +
 server/src/http/workflow/bug_ops.rs           |   1 +
 server/src/http/workflow/mod.rs               |   1 +
 server/src/http/workflow/story_ops.rs         |   1 +
 server/src/http/workflow/test_results.rs      |   1 +
 server/src/http/ws.rs                         |   1 +
 server/src/io/fs/files.rs                     |   1 +
 server/src/io/fs/mod.rs                       |   1 +
 server/src/io/fs/paths.rs                     |   1 +
 server/src/io/fs/preferences.rs               |   1 +
 server/src/io/fs/project.rs                   |   1 +
 server/src/io/fs/scaffold.rs                  |   1 +
 server/src/io/mod.rs                          |   1 +
 server/src/io/onboarding.rs                   |   1 +
 server/src/io/search.rs                       |   1 +
 server/src/io/shell.rs                        |   1 +
 server/src/io/story_metadata.rs               |   1 +
 server/src/io/wizard.rs                       |   1 +
 server/src/llm/chat.rs                        |   1 +
 server/src/llm/mod.rs                         |   1 +
 server/src/llm/oauth.rs                       |   1 +
 server/src/llm/prompts.rs                     |   1 +
 server/src/llm/providers/anthropic.rs         |   1 +
 server/src/llm/providers/claude_code.rs       |   1 +
 server/src/llm/providers/mod.rs               |   1 +
 server/src/llm/providers/ollama.rs            |   1 +
 server/src/llm/types.rs                       |   1 +
 server/src/main.rs                            |   2 +
 server/src/state.rs                           |   1 +
 server/src/store.rs                           |   1 +
 server/src/worktree.rs                        |   1 +
 99 files changed, 377 insertions(+)

diff --git a/README.md b/README.md
index a65a7356..423229b5 100644
--- a/README.md
+++ b/README.md
@@ -218,6 +218,284 @@ Both return a JSON document with:
 
 > **This is a debug tool.** For normal pipeline introspection use `get_pipeline_status` or `GET /api/pipeline` instead.
 
+## Source Map
+
+### Core
+
+| File | Description |
+|------|-------------|
+| `server/src/main.rs` | Entry point, CLI argument parsing, and server startup |
+| `server/src/config.rs` | Parses `project.toml` for agents, components, and server settings |
+| `server/src/state.rs` | Global mutable session state (project root, cancellation) |
+| `server/src/store.rs` | JSON-backed persistent key-value store for settings |
+
+### Agents
+
+| File | Description |
+|------|-------------|
+| `server/src/agents/mod.rs` | Types, configuration, and orchestration for coding agents |
+| `server/src/agents/gates.rs` | Runs test suites and validation scripts in agent worktrees |
+| `server/src/agents/lifecycle.rs` | File creation, archival, and stage transitions for pipeline items |
+| `server/src/agents/merge.rs` | Rebases agent work onto master and runs post-merge validation |
+| `server/src/agents/pty.rs` | Spawns agent processes in pseudo-terminals and streams output |
+| `server/src/agents/token_usage.rs` | Persists per-agent token consumption records to disk |
+| `server/src/agent_log.rs` | Reads and writes JSONL agent event logs to disk |
+| `server/src/agent_mode.rs` | Headless build-agent mode for distributed story processing |
+
+### Agent Pool
+
+| File | Description |
+|------|-------------|
+| `server/src/agents/pool/mod.rs` | Manages the set of active agents across all pipeline stages |
+| `server/src/agents/pool/types.rs` | `AgentPool`, `StoryAgent`, and related data structures |
+| `server/src/agents/pool/start.rs` | Spawns a new agent process in a worktree for a story |
+| `server/src/agents/pool/stop.rs` | Terminates a running agent while preserving its worktree |
+| `server/src/agents/pool/wait.rs` | Blocks until an agent reaches a terminal state |
+| `server/src/agents/pool/query.rs` | Lists available/active agents and info lookups |
+| `server/src/agents/pool/process.rs` | Kills orphaned PTY child processes on shutdown |
+| `server/src/agents/pool/worktree.rs` | Creates and configures git worktrees for agents |
+| `server/src/agents/pool/test_helpers.rs` | In-memory pool construction and test assertions |
+
+### Agent Pool — Auto-assign
+
+| File | Description |
+|------|-------------|
+| `server/src/agents/pool/auto_assign/mod.rs` | Wires sub-files and re-exports public items |
+| `server/src/agents/pool/auto_assign/auto_assign.rs` | Scans pipeline stages and dispatches agents to unassigned stories |
+| `server/src/agents/pool/auto_assign/reconcile.rs` | Startup reconciliation: detects committed work and advances pipeline |
+| `server/src/agents/pool/auto_assign/scan.rs` | Scans pipeline stages for work items and queries pool state |
+| `server/src/agents/pool/auto_assign/story_checks.rs` | Front-matter checks: review holds, blocked state, merge failures |
+| `server/src/agents/pool/auto_assign/watchdog.rs` | Detects orphaned agents and triggers auto-assign |
+
+### Agent Pool — Pipeline
+
+| File | Description |
+|------|-------------|
+| `server/src/agents/pool/pipeline/mod.rs` | Stage advancement, completion handling, and merge orchestration |
+| `server/src/agents/pool/pipeline/advance.rs` | Moves stories forward through pipeline stages |
+| `server/src/agents/pool/pipeline/completion.rs` | Processes exit results and triggers pipeline advancement |
+| `server/src/agents/pool/pipeline/merge.rs` | Orchestrates the merge-to-master flow for completed stories |
+
+### Agent Runtimes
+
+| File | Description |
+|------|-------------|
+| `server/src/agents/runtime/mod.rs` | Pluggable backends (Claude Code, Gemini, OpenAI) for running agents |
+| `server/src/agents/runtime/claude_code.rs` | Launches Claude Code CLI sessions as agent backends |
+| `server/src/agents/runtime/gemini.rs` | Drives Google Gemini API sessions as agent backends |
+| `server/src/agents/runtime/openai.rs` | Drives OpenAI API sessions as agent backends |
+
+### CRDT
+
+| File | Description |
+|------|-------------|
+| `server/src/crdt_state.rs` | Pipeline state as a conflict-free replicated document backed by SQLite |
+| `server/src/crdt_sync.rs` | WebSocket-based replication of pipeline state between nodes |
+| `server/src/crdt_wire.rs` | Serialization format for `SignedOp` sync messages |
+| `server/src/pipeline_state.rs` | Typed pipeline state machine |
+
+### Database
+
+| File | Description |
+|------|-------------|
+| `server/src/db/mod.rs` | Content store, shadow writes, and CRDT op persistence |
+
+### HTTP Server
+
+| File | Description |
+|------|-------------|
+| `server/src/http/mod.rs` | Module declarations for all REST, MCP, WebSocket, and SSE endpoints |
+| `server/src/http/context.rs` | Shared `AppContext` threaded through all HTTP handlers |
+| `server/src/http/agents.rs` | REST API for listing, starting, stopping, and inspecting agents |
+| `server/src/http/agents_sse.rs` | Server-Sent Events endpoint for real-time agent output |
+| `server/src/http/anthropic.rs` | Proxy for model listing and key-validation to Anthropic |
+| `server/src/http/assets.rs` | Serves the embedded React frontend via `rust-embed` |
+| `server/src/http/bot_command.rs` | Bot command HTTP endpoint |
+| `server/src/http/chat.rs` | REST API for the LLM-powered chat interface |
+| `server/src/http/health.rs` | Returns a static "ok" response |
+| `server/src/http/io.rs` | REST API for file and directory operations |
+| `server/src/http/model.rs` | REST API for model selection and LLM provider management |
+| `server/src/http/oauth.rs` | Anthropic OAuth callback and token exchange flow |
+| `server/src/http/project.rs` | REST API for project initialization and context management |
+| `server/src/http/settings.rs` | REST API for user preferences and editor configuration |
+| `server/src/http/wizard.rs` | REST API for the project setup wizard |
+| `server/src/http/ws.rs` | Real-time pipeline updates, chat, and permission prompts |
+| `server/src/http/test_helpers.rs` | Shared test utilities for HTTP handler tests |
+
+### HTTP — MCP Tools
+
+| File | Description |
+|------|-------------|
+| `server/src/http/mcp/mod.rs` | Model Context Protocol endpoint dispatching tool calls |
+| `server/src/http/mcp/agent_tools.rs` | Start, stop, wait, list, and inspect agents via MCP |
+| `server/src/http/mcp/diagnostics.rs` | Server logs, CRDT dump, and story movement helpers |
+| `server/src/http/mcp/git_tools.rs` | Status, diff, add, commit, and log on agent worktrees |
+| `server/src/http/mcp/merge_tools.rs` | Merge agent work to master and report failures |
+| `server/src/http/mcp/qa_tools.rs` | Request, approve, and reject QA reviews |
+| `server/src/http/mcp/shell_tools.rs` | Run commands, execute tests, and stream output |
+| `server/src/http/mcp/status_tools.rs` | Pipeline status, story triage, and AC inspection |
+| `server/src/http/mcp/story_tools.rs` | Create, update, move, and manage stories/bugs/refactors |
+| `server/src/http/mcp/wizard_tools.rs` | Interactive setup wizard tool implementations |
+
+### HTTP — Workflow
+
+| File | Description |
+|------|-------------|
+| `server/src/http/workflow/mod.rs` | Shared story/bug file operations for HTTP and MCP handlers |
+| `server/src/http/workflow/bug_ops.rs` | Creates bug, refactor, and spike files in the pipeline |
+| `server/src/http/workflow/story_ops.rs` | Creates, updates, and manages acceptance criteria in stories |
+| `server/src/http/workflow/test_results.rs` | Writes structured test results into story markdown |
+
+### I/O
+
+| File | Description |
+|------|-------------|
+| `server/src/io/mod.rs` | Filesystem, shell, search, onboarding, and story metadata operations |
+| `server/src/io/fs/mod.rs` | Module declarations and re-exports for file operations |
+| `server/src/io/fs/files.rs` | Read, write, list, and create files and directories |
+| `server/src/io/fs/paths.rs` | Resolves CLI and session-relative paths to absolute paths |
+| `server/src/io/fs/preferences.rs` | Reads and writes model selection and user settings |
+| `server/src/io/fs/project.rs` | Tracks known projects and resolves the active project root |
+| `server/src/io/fs/scaffold.rs` | Creates the `.huskies/` directory structure and default files |
+| `server/src/io/onboarding.rs` | Checks whether scaffold templates have been customized |
+| `server/src/io/search.rs` | Full-text search across project files |
+| `server/src/io/shell.rs` | Runs commands in the project directory and captures output |
+| `server/src/io/story_metadata.rs` | Parses and modifies YAML front matter in story markdown |
+| `server/src/io/watcher.rs` | Filesystem watcher for `.huskies/work/` and `project.toml` |
+| `server/src/io/wizard.rs` | Multi-step project onboarding flow with per-step status |
+| `server/src/io/test_helpers.rs` | Shared test utilities for I/O module tests |
+
+### Chat
+
+| File | Description |
+|------|-------------|
+| `server/src/chat/mod.rs` | Transport abstraction for chat platforms |
+| `server/src/chat/lookup.rs` | Shared story-lookup helper for chat commands |
+| `server/src/chat/timer.rs` | Deferred agent start via one-shot timers |
+| `server/src/chat/util.rs` | Shared text utilities used by all transports |
+| `server/src/chat/test_helpers.rs` | Shared test utilities for chat handler tests |
+
+### Chat — Commands
+
+| File | Description |
+|------|-------------|
+| `server/src/chat/commands/mod.rs` | Bot-level command registry shared by all transports |
+| `server/src/chat/commands/ambient.rs` | `ambient` command handler |
+| `server/src/chat/commands/assign.rs` | `assign` command handler |
+| `server/src/chat/commands/cost.rs` | `cost` command handler |
+| `server/src/chat/commands/coverage.rs` | `coverage` command — show or refresh test coverage |
+| `server/src/chat/commands/depends.rs` | `depends` command handler |
+| `server/src/chat/commands/git.rs` | `git` command handler |
+| `server/src/chat/commands/help.rs` | `help` command handler |
+| `server/src/chat/commands/loc.rs` | `loc` command — top source files by line count |
+| `server/src/chat/commands/move_story.rs` | `move` command handler |
+| `server/src/chat/commands/overview.rs` | `overview` command handler |
+| `server/src/chat/commands/run_tests.rs` | `test` command — run the project's test suite |
+| `server/src/chat/commands/setup.rs` | `setup` command handler |
+| `server/src/chat/commands/show.rs` | `show` command handler |
+| `server/src/chat/commands/status.rs` | `status` command and pipeline status helpers |
+| `server/src/chat/commands/timer.rs` | `timer` command handler |
+| `server/src/chat/commands/triage.rs` | Story triage dump subcommand of `status` |
+| `server/src/chat/commands/unblock.rs` | `unblock` command handler |
+| `server/src/chat/commands/unreleased.rs` | `unreleased` command handler |
+
+### Chat — Matrix Transport
+
+| File | Description |
+|------|-------------|
+| `server/src/chat/transport/matrix/mod.rs` | Matrix bot integration |
+| `server/src/chat/transport/matrix/config.rs` | Deserialization of `bot.toml` Matrix settings |
+| `server/src/chat/transport/matrix/commands.rs` | Re-exports from `crate::chat::commands` |
+| `server/src/chat/transport/matrix/transport_impl.rs` | Matrix `ChatTransport` implementation |
+| `server/src/chat/transport/matrix/assign.rs` | Assign/re-assign a coder model to a story |
+| `server/src/chat/transport/matrix/delete.rs` | Delete a story/bug/spike from the pipeline |
+| `server/src/chat/transport/matrix/htop.rs` | Live-updating system and agent process dashboard |
+| `server/src/chat/transport/matrix/notifications.rs` | Stage transition notifications for Matrix rooms |
+| `server/src/chat/transport/matrix/rebuild.rs` | Trigger a server rebuild and restart |
+| `server/src/chat/transport/matrix/reset.rs` | Clear the current Claude Code session for a room |
+| `server/src/chat/transport/matrix/rmtree.rs` | Delete the worktree for a story |
+| `server/src/chat/transport/matrix/start.rs` | Start a coder agent on a story |
+
+### Chat — Matrix Bot
+
+| File | Description |
+|------|-------------|
+| `server/src/chat/transport/matrix/bot/mod.rs` | Sub-modules for the Matrix chat bot |
+| `server/src/chat/transport/matrix/bot/context.rs` | Shared state (rooms, history, permissions) |
+| `server/src/chat/transport/matrix/bot/format.rs` | Markdown-to-HTML conversion and startup announcements |
+| `server/src/chat/transport/matrix/bot/history.rs` | Per-room message history for LLM context |
+| `server/src/chat/transport/matrix/bot/mentions.rs` | Checks whether a message mentions the bot |
+| `server/src/chat/transport/matrix/bot/messages.rs` | Processes incoming messages and dispatches commands |
+| `server/src/chat/transport/matrix/bot/run.rs` | Connects to homeserver and processes sync events |
+| `server/src/chat/transport/matrix/bot/verification.rs` | Interactive emoji verification flow for E2EE |
+
+### Chat — Slack Transport
+
+| File | Description |
+|------|-------------|
+| `server/src/chat/transport/slack/mod.rs` | Slack Bot API integration |
+| `server/src/chat/transport/slack/commands.rs` | Incoming message dispatch and slash command handling |
+| `server/src/chat/transport/slack/format.rs` | Markdown to Slack mrkdwn conversion |
+| `server/src/chat/transport/slack/history.rs` | Conversation history persistence |
+| `server/src/chat/transport/slack/meta.rs` | `ChatTransport` implementation for Slack |
+| `server/src/chat/transport/slack/verify.rs` | Request signature verification |
+
+### Chat — Discord Transport
+
+| File | Description |
+|------|-------------|
+| `server/src/chat/transport/discord/mod.rs` | Discord Bot integration |
+| `server/src/chat/transport/discord/commands.rs` | Incoming message dispatch and command handling |
+| `server/src/chat/transport/discord/format.rs` | Markdown to Discord format conversion |
+| `server/src/chat/transport/discord/gateway.rs` | Minimal Discord Gateway WebSocket client |
+| `server/src/chat/transport/discord/history.rs` | Conversation history persistence |
+| `server/src/chat/transport/discord/meta.rs` | `ChatTransport` implementation for Discord |
+
+### Chat — WhatsApp Transport
+
+| File | Description |
+|------|-------------|
+| `server/src/chat/transport/whatsapp/mod.rs` | WhatsApp Business API integration |
+| `server/src/chat/transport/whatsapp/commands.rs` | Processes incoming messages as bot commands |
+| `server/src/chat/transport/whatsapp/format.rs` | Markdown-to-WhatsApp conversion and message chunking |
+| `server/src/chat/transport/whatsapp/history.rs` | Per-number history and messaging window tracking |
+| `server/src/chat/transport/whatsapp/meta.rs` | Meta Cloud API transport via Graph API |
+| `server/src/chat/transport/whatsapp/twilio.rs` | Twilio transport for sending/receiving messages |
+
+### Chat — Transport Abstraction
+
+| File | Description |
+|------|-------------|
+| `server/src/chat/transport/mod.rs` | Pluggable backends (Matrix, Slack, WhatsApp, Discord) |
+
+### LLM
+
+| File | Description |
+|------|-------------|
+| `server/src/llm/mod.rs` | Chat orchestration, prompts, OAuth, and provider integrations |
+| `server/src/llm/chat.rs` | Multi-turn conversations with tool-calling LLM providers |
+| `server/src/llm/oauth.rs` | Token refresh and credential management for Claude API |
+| `server/src/llm/prompts.rs` | Static prompt templates for chat and onboarding |
+| `server/src/llm/types.rs` | `Message`, `Role`, `ToolCall`, `ModelProvider` types |
+
+### LLM — Providers
+
+| File | Description |
+|------|-------------|
+| `server/src/llm/providers/mod.rs` | Module declarations for Anthropic, Claude Code, and Ollama |
+| `server/src/llm/providers/anthropic.rs` | Streaming completion client for Claude Messages API |
+| `server/src/llm/providers/claude_code.rs` | Runs Claude Code CLI in a PTY and parses output |
+| `server/src/llm/providers/ollama.rs` | Streaming completion client for Ollama models |
+
+### Utilities
+
+| File | Description |
+|------|-------------|
+| `server/src/log_buffer.rs` | Bounded in-memory ring buffer for server log output |
+| `server/src/rebuild.rs` | Server rebuild and restart logic |
+| `server/src/workflow.rs` | Test result tracking and acceptance evaluation |
+| `server/src/worktree.rs` | Creates, lists, and removes git worktrees for agent isolation |
+
 ## License
 
 GPL-3.0. See [LICENSE](LICENSE).
diff --git a/server/src/agent_log.rs b/server/src/agent_log.rs
index 27a5fbef..9c54c351 100644
--- a/server/src/agent_log.rs
+++ b/server/src/agent_log.rs
@@ -1,3 +1,4 @@
+//! Agent log persistence — reads and writes JSONL agent event logs to disk.
 use crate::agents::AgentEvent;
 use chrono::Utc;
 use serde::{Deserialize, Serialize};
diff --git a/server/src/agent_mode.rs b/server/src/agent_mode.rs
index e4258d9e..81a99d17 100644
--- a/server/src/agent_mode.rs
+++ b/server/src/agent_mode.rs
@@ -1,3 +1,4 @@
+//! Headless build-agent mode for distributed, rendezvous-based story processing.
 /// Headless build agent mode.
 ///
 /// When invoked via `huskies agent --rendezvous ws://host:3001/crdt-sync`, this
diff --git a/server/src/agents/gates.rs b/server/src/agents/gates.rs
index 352c4a80..990cc52f 100644
--- a/server/src/agents/gates.rs
+++ b/server/src/agents/gates.rs
@@ -1,3 +1,4 @@
+//! Acceptance gates — runs test suites and validation scripts in agent worktrees.
 use std::path::Path;
 use std::process::Command;
 use std::time::Duration;
diff --git a/server/src/agents/lifecycle.rs b/server/src/agents/lifecycle.rs
index f8b618bf..5600d951 100644
--- a/server/src/agents/lifecycle.rs
+++ b/server/src/agents/lifecycle.rs
@@ -1,3 +1,4 @@
+//! Story lifecycle helpers — file creation, archival, and stage transitions for pipeline items.
 use std::path::Path;
 use std::process::Command;
 
diff --git a/server/src/agents/merge.rs b/server/src/agents/merge.rs
index 6124ea1d..fc4757ae 100644
--- a/server/src/agents/merge.rs
+++ b/server/src/agents/merge.rs
@@ -1,3 +1,4 @@
+//! Merge operations — rebases agent work onto master and runs post-merge validation.
 use std::path::Path;
 use std::process::Command;
 use std::sync::Mutex;
diff --git a/server/src/agents/mod.rs b/server/src/agents/mod.rs
index 31ef12ab..7586ba76 100644
--- a/server/src/agents/mod.rs
+++ b/server/src/agents/mod.rs
@@ -1,3 +1,4 @@
+//! Agent subsystem — types, configuration, and orchestration for coding agents.
 pub mod gates;
 pub mod lifecycle;
 pub mod merge;
diff --git a/server/src/agents/pool/mod.rs b/server/src/agents/pool/mod.rs
index 79dce61f..e7d80c08 100644
--- a/server/src/agents/pool/mod.rs
+++ b/server/src/agents/pool/mod.rs
@@ -1,3 +1,4 @@
+//! Agent pool — manages the set of active agents across all pipeline stages.
 mod auto_assign;
 mod pipeline;
 mod start;
diff --git a/server/src/agents/pool/pipeline/advance.rs b/server/src/agents/pool/pipeline/advance.rs
index 812b9dde..06f36562 100644
--- a/server/src/agents/pool/pipeline/advance.rs
+++ b/server/src/agents/pool/pipeline/advance.rs
@@ -1,3 +1,4 @@
+//! Pipeline advance — moves stories forward through pipeline stages after agent completion.
 use crate::config::ProjectConfig;
 use crate::slog;
 use crate::slog_error;
diff --git a/server/src/agents/pool/pipeline/completion.rs b/server/src/agents/pool/pipeline/completion.rs
index d4b0c7b4..5dde2064 100644
--- a/server/src/agents/pool/pipeline/completion.rs
+++ b/server/src/agents/pool/pipeline/completion.rs
@@ -1,3 +1,4 @@
+//! Agent completion handling — processes exit results and triggers pipeline advancement.
 use crate::slog;
 use crate::io::watcher::WatcherEvent;
 use std::collections::HashMap;
diff --git a/server/src/agents/pool/pipeline/merge.rs b/server/src/agents/pool/pipeline/merge.rs
index 006b8916..85fa8353 100644
--- a/server/src/agents/pool/pipeline/merge.rs
+++ b/server/src/agents/pool/pipeline/merge.rs
@@ -1,3 +1,4 @@
+//! Pipeline merge step — orchestrates the merge-to-master flow for completed stories.
 use crate::slog;
 use crate::slog_error;
 use crate::slog_warn;
diff --git a/server/src/agents/pool/pipeline/mod.rs b/server/src/agents/pool/pipeline/mod.rs
index 14aa5390..b20ef5d5 100644
--- a/server/src/agents/pool/pipeline/mod.rs
+++ b/server/src/agents/pool/pipeline/mod.rs
@@ -1,3 +1,4 @@
+//! Pipeline operations — stage advancement, completion handling, and merge orchestration.
 mod advance;
 mod completion;
 mod merge;
diff --git a/server/src/agents/pool/process.rs b/server/src/agents/pool/process.rs
index 4ead32b5..cd8b4bf5 100644
--- a/server/src/agents/pool/process.rs
+++ b/server/src/agents/pool/process.rs
@@ -1,3 +1,4 @@
+//! Process management — kills orphaned PTY child processes on server shutdown.
 use crate::slog;
 
 use super::AgentPool;
diff --git a/server/src/agents/pool/query.rs b/server/src/agents/pool/query.rs
index 0b68e0d6..fed99d81 100644
--- a/server/src/agents/pool/query.rs
+++ b/server/src/agents/pool/query.rs
@@ -1,3 +1,4 @@
+//! Pool queries — lists available agents, active agents, and agent info lookups.
 use crate::config::ProjectConfig;
 use std::path::PathBuf;
 use tokio::sync::broadcast;
diff --git a/server/src/agents/pool/start.rs b/server/src/agents/pool/start.rs
index 83ca0ebd..284d7c1c 100644
--- a/server/src/agents/pool/start.rs
+++ b/server/src/agents/pool/start.rs
@@ -1,3 +1,4 @@
+//! Agent start — spawns a new agent process in a worktree for a given story.
 use crate::agent_log::AgentLogWriter;
 use crate::config::ProjectConfig;
 use crate::slog_error;
diff --git a/server/src/agents/pool/stop.rs b/server/src/agents/pool/stop.rs
index c1375f0b..564389b0 100644
--- a/server/src/agents/pool/stop.rs
+++ b/server/src/agents/pool/stop.rs
@@ -1,3 +1,4 @@
+//! Agent stop — terminates a running agent while preserving its worktree.
 use crate::slog;
 use crate::slog_error;
 use std::path::Path;
diff --git a/server/src/agents/pool/test_helpers.rs b/server/src/agents/pool/test_helpers.rs
index 0f04c384..6589d7ae 100644
--- a/server/src/agents/pool/test_helpers.rs
+++ b/server/src/agents/pool/test_helpers.rs
@@ -1,3 +1,4 @@
+//! Test helpers for the agent pool — in-memory pool construction and assertions.
 use crate::worktree::WorktreeInfo;
 use std::path::PathBuf;
 use std::sync::{Arc, Mutex};
diff --git a/server/src/agents/pool/types.rs b/server/src/agents/pool/types.rs
index c579956a..d168d4f3 100644
--- a/server/src/agents/pool/types.rs
+++ b/server/src/agents/pool/types.rs
@@ -1,3 +1,4 @@
+//! Agent pool types — `AgentPool`, `StoryAgent`, and related data structures.
 use crate::slog;
 use crate::worktree::WorktreeInfo;
 use std::collections::HashMap;
diff --git a/server/src/agents/pool/wait.rs b/server/src/agents/pool/wait.rs
index d20a572f..7a569f76 100644
--- a/server/src/agents/pool/wait.rs
+++ b/server/src/agents/pool/wait.rs
@@ -1,3 +1,4 @@
+//! Agent wait — blocks until an agent reaches a terminal state with optional timeout.
 use super::super::{AgentEvent, AgentInfo, AgentStatus};
 use super::types::{agent_info_from_entry, composite_key};
 use super::AgentPool;
diff --git a/server/src/agents/pool/worktree.rs b/server/src/agents/pool/worktree.rs
index 4e7fe1a9..ea4b24d4 100644
--- a/server/src/agents/pool/worktree.rs
+++ b/server/src/agents/pool/worktree.rs
@@ -1,3 +1,4 @@
+//! Agent worktree management — creates and configures git worktrees for agents.
 use crate::config::ProjectConfig;
 use std::path::{Path, PathBuf};
 
diff --git a/server/src/agents/pty.rs b/server/src/agents/pty.rs
index c8fe4ebb..43dcac69 100644
--- a/server/src/agents/pty.rs
+++ b/server/src/agents/pty.rs
@@ -1,3 +1,4 @@
+//! PTY runner — spawns agent processes in pseudo-terminals and streams their output.
 use std::collections::HashMap;
 use std::io::{BufRead, BufReader};
 use std::sync::{Arc, Mutex};
diff --git a/server/src/agents/runtime/claude_code.rs b/server/src/agents/runtime/claude_code.rs
index 25d519e3..8d696a97 100644
--- a/server/src/agents/runtime/claude_code.rs
+++ b/server/src/agents/runtime/claude_code.rs
@@ -1,3 +1,4 @@
+//! Claude Code runtime — launches Claude Code CLI sessions as agent backends.
 use std::collections::HashMap;
 use std::sync::{Arc, Mutex};
 
diff --git a/server/src/agents/runtime/gemini.rs b/server/src/agents/runtime/gemini.rs
index 4947ace3..b0f6c2a5 100644
--- a/server/src/agents/runtime/gemini.rs
+++ b/server/src/agents/runtime/gemini.rs
@@ -1,3 +1,4 @@
+//! Gemini runtime — drives Google Gemini API sessions as agent backends.
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
 
diff --git a/server/src/agents/runtime/mod.rs b/server/src/agents/runtime/mod.rs
index 265e6faa..d5f2b551 100644
--- a/server/src/agents/runtime/mod.rs
+++ b/server/src/agents/runtime/mod.rs
@@ -1,3 +1,4 @@
+//! Agent runtimes — pluggable backends (Claude Code, Gemini, OpenAI) for running agents.
 mod claude_code;
 mod gemini;
 mod openai;
diff --git a/server/src/agents/runtime/openai.rs b/server/src/agents/runtime/openai.rs
index 2160535a..4b6f3949 100644
--- a/server/src/agents/runtime/openai.rs
+++ b/server/src/agents/runtime/openai.rs
@@ -1,3 +1,4 @@
+//! OpenAI Codex runtime — drives OpenAI API sessions as agent backends.
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
 
diff --git a/server/src/agents/token_usage.rs b/server/src/agents/token_usage.rs
index 18a50898..67ea1a24 100644
--- a/server/src/agents/token_usage.rs
+++ b/server/src/agents/token_usage.rs
@@ -1,3 +1,4 @@
+//! Token usage tracking — persists per-agent token consumption records to disk.
 use std::fs;
 use std::path::Path;
 
diff --git a/server/src/chat/transport/matrix/bot/context.rs b/server/src/chat/transport/matrix/bot/context.rs
index 6800da50..e3cc745c 100644
--- a/server/src/chat/transport/matrix/bot/context.rs
+++ b/server/src/chat/transport/matrix/bot/context.rs
@@ -1,3 +1,4 @@
+//! Matrix bot context — shared state for the Matrix bot (rooms, history, permissions).
 use crate::agents::AgentPool;
 use crate::chat::timer::TimerStore;
 use crate::chat::ChatTransport;
diff --git a/server/src/chat/transport/matrix/bot/format.rs b/server/src/chat/transport/matrix/bot/format.rs
index fa2c87e5..a48c6c59 100644
--- a/server/src/chat/transport/matrix/bot/format.rs
+++ b/server/src/chat/transport/matrix/bot/format.rs
@@ -1,3 +1,4 @@
+//! Matrix message formatting — Markdown-to-HTML conversion and startup announcements.
 use pulldown_cmark::{Options, Parser, html};
 
 /// Format the startup greeting the bot sends to each room when it comes online.
diff --git a/server/src/chat/transport/matrix/bot/history.rs b/server/src/chat/transport/matrix/bot/history.rs
index bddc9970..fa50de4a 100644
--- a/server/src/chat/transport/matrix/bot/history.rs
+++ b/server/src/chat/transport/matrix/bot/history.rs
@@ -1,3 +1,4 @@
+//! Matrix conversation history — per-room message history for LLM context.
 use crate::slog;
 use matrix_sdk::ruma::OwnedRoomId;
 use serde::{Deserialize, Serialize};
diff --git a/server/src/chat/transport/matrix/bot/mentions.rs b/server/src/chat/transport/matrix/bot/mentions.rs
index 97e28402..90db4704 100644
--- a/server/src/chat/transport/matrix/bot/mentions.rs
+++ b/server/src/chat/transport/matrix/bot/mentions.rs
@@ -1,3 +1,4 @@
+//! Matrix mention detection — checks whether a message mentions the bot.
 use matrix_sdk::ruma::events::room::message::{Relation, RoomMessageEventContentWithoutRelation};
 use matrix_sdk::ruma::{OwnedEventId, OwnedUserId};
 use std::collections::HashSet;
diff --git a/server/src/chat/transport/matrix/bot/messages.rs b/server/src/chat/transport/matrix/bot/messages.rs
index d908f4bc..f715ae67 100644
--- a/server/src/chat/transport/matrix/bot/messages.rs
+++ b/server/src/chat/transport/matrix/bot/messages.rs
@@ -1,3 +1,4 @@
+//! Matrix message handler — processes incoming room messages and dispatches commands.
 use crate::chat::util::{drain_complete_paragraphs, is_permission_approval};
 use crate::http::context::PermissionDecision;
 use crate::llm::providers::claude_code::{ClaudeCodeProvider, ClaudeCodeResult};
diff --git a/server/src/chat/transport/matrix/bot/mod.rs b/server/src/chat/transport/matrix/bot/mod.rs
index 7b14380b..cca76224 100644
--- a/server/src/chat/transport/matrix/bot/mod.rs
+++ b/server/src/chat/transport/matrix/bot/mod.rs
@@ -1,3 +1,4 @@
+//! Matrix bot — sub-modules for the Matrix chat bot implementation.
 pub mod context;
 pub mod format;
 pub mod history;
diff --git a/server/src/chat/transport/matrix/bot/run.rs b/server/src/chat/transport/matrix/bot/run.rs
index 54af521d..4de6711f 100644
--- a/server/src/chat/transport/matrix/bot/run.rs
+++ b/server/src/chat/transport/matrix/bot/run.rs
@@ -1,3 +1,4 @@
+//! Matrix bot run loop — connects to the homeserver and processes sync events.
 use crate::agents::AgentPool;
 use crate::slog;
 use matrix_sdk::{Client, LoopCtrl, config::SyncSettings};
diff --git a/server/src/chat/transport/matrix/bot/verification.rs b/server/src/chat/transport/matrix/bot/verification.rs
index 293823b3..aed7fcae 100644
--- a/server/src/chat/transport/matrix/bot/verification.rs
+++ b/server/src/chat/transport/matrix/bot/verification.rs
@@ -1,3 +1,4 @@
+//! Matrix device verification — interactive emoji verification flow for E2EE.
 use crate::slog;
 use futures::StreamExt;
 use matrix_sdk::Client;
diff --git a/server/src/chat/transport/matrix/config.rs b/server/src/chat/transport/matrix/config.rs
index b8591814..3210ac30 100644
--- a/server/src/chat/transport/matrix/config.rs
+++ b/server/src/chat/transport/matrix/config.rs
@@ -1,3 +1,4 @@
+//! Matrix transport configuration — deserialization of `bot.toml` Matrix settings.
 use serde::Deserialize;
 use std::path::Path;
 
diff --git a/server/src/chat/transport/mod.rs b/server/src/chat/transport/mod.rs
index c4c0eb6e..190f397f 100644
--- a/server/src/chat/transport/mod.rs
+++ b/server/src/chat/transport/mod.rs
@@ -1,3 +1,4 @@
+//! Chat transports — pluggable backends (Matrix, Slack, WhatsApp, Discord) for bot messaging.
 pub mod discord;
 pub mod matrix;
 pub mod slack;
diff --git a/server/src/chat/transport/whatsapp/commands.rs b/server/src/chat/transport/whatsapp/commands.rs
index adffd97a..ed5b6f93 100644
--- a/server/src/chat/transport/whatsapp/commands.rs
+++ b/server/src/chat/transport/whatsapp/commands.rs
@@ -1,3 +1,4 @@
+//! WhatsApp command handling — processes incoming WhatsApp messages as bot commands.
 use std::sync::Arc;
 
 use crate::chat::transport::matrix::{ConversationEntry, ConversationRole, RoomConversation};
diff --git a/server/src/chat/transport/whatsapp/format.rs b/server/src/chat/transport/whatsapp/format.rs
index 5989ded4..e1c93180 100644
--- a/server/src/chat/transport/whatsapp/format.rs
+++ b/server/src/chat/transport/whatsapp/format.rs
@@ -1,3 +1,4 @@
+//! WhatsApp message formatting — Markdown-to-WhatsApp conversion and message chunking.
 use regex::Regex;
 use std::sync::LazyLock;
 
diff --git a/server/src/chat/transport/whatsapp/history.rs b/server/src/chat/transport/whatsapp/history.rs
index 8035c3c2..1b07a313 100644
--- a/server/src/chat/transport/whatsapp/history.rs
+++ b/server/src/chat/transport/whatsapp/history.rs
@@ -1,3 +1,4 @@
+//! WhatsApp conversation history — per-number message history and messaging window tracking.
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::sync::Arc;
diff --git a/server/src/chat/transport/whatsapp/meta.rs b/server/src/chat/transport/whatsapp/meta.rs
index 60021fc2..18023147 100644
--- a/server/src/chat/transport/whatsapp/meta.rs
+++ b/server/src/chat/transport/whatsapp/meta.rs
@@ -1,3 +1,4 @@
+//! WhatsApp Meta (Cloud API) transport — sends and receives messages via the Meta Graph API.
 use async_trait::async_trait;
 use serde::{Deserialize, Serialize};
 
diff --git a/server/src/chat/transport/whatsapp/twilio.rs b/server/src/chat/transport/whatsapp/twilio.rs
index ff1c5c16..c7bbc111 100644
--- a/server/src/chat/transport/whatsapp/twilio.rs
+++ b/server/src/chat/transport/whatsapp/twilio.rs
@@ -1,3 +1,4 @@
+//! WhatsApp Twilio transport — sends and receives messages via the Twilio API.
 use async_trait::async_trait;
 use serde::Deserialize;
 
diff --git a/server/src/config.rs b/server/src/config.rs
index 5e2c180e..ed295740 100644
--- a/server/src/config.rs
+++ b/server/src/config.rs
@@ -1,3 +1,4 @@
+//! Project configuration — parses `project.toml` for agents, components, and server settings.
 use crate::slog;
 use serde::Deserialize;
 use std::collections::HashSet;
diff --git a/server/src/crdt_state.rs b/server/src/crdt_state.rs
index 8d2e97f8..8f29b71a 100644
--- a/server/src/crdt_state.rs
+++ b/server/src/crdt_state.rs
@@ -1,3 +1,4 @@
+//! CRDT state layer — manages pipeline state as a conflict-free replicated document backed by SQLite.
 /// CRDT state layer for pipeline state, backed by SQLite.
 ///
 /// The CRDT document is the primary source of truth for pipeline item
diff --git a/server/src/crdt_sync.rs b/server/src/crdt_sync.rs
index 17ce32e1..5e7e3914 100644
--- a/server/src/crdt_sync.rs
+++ b/server/src/crdt_sync.rs
@@ -1,3 +1,4 @@
+//! CRDT sync — WebSocket-based replication of pipeline state between huskies nodes.
 /// WebSocket-based CRDT sync layer for replicating pipeline state between
 /// huskies nodes.
 ///
diff --git a/server/src/crdt_wire.rs b/server/src/crdt_wire.rs
index a375297a..377ae65b 100644
--- a/server/src/crdt_wire.rs
+++ b/server/src/crdt_wire.rs
@@ -1,3 +1,4 @@
+//! CRDT wire codec — serialization format for `SignedOp` sync messages between nodes.
 /// Wire codec for `SignedOp` CRDT sync between nodes.
 ///
 /// # Wire Format
diff --git a/server/src/db/mod.rs b/server/src/db/mod.rs
index 53a7664d..16ec4fbc 100644
--- a/server/src/db/mod.rs
+++ b/server/src/db/mod.rs
@@ -1,3 +1,4 @@
+//! SQLite storage layer — content store, shadow writes, and CRDT op persistence.
 /// SQLite storage layer for pipeline state and story content.
 ///
 /// The CRDT layer (`crdt_state`) is the primary source of truth for pipeline
diff --git a/server/src/http/agents.rs b/server/src/http/agents.rs
index 5f23c91a..a2e20476 100644
--- a/server/src/http/agents.rs
+++ b/server/src/http/agents.rs
@@ -1,3 +1,4 @@
+//! HTTP agent endpoints — REST API for listing, starting, stopping, and inspecting agents.
 use crate::config::ProjectConfig;
 use crate::http::context::{AppContext, OpenApiResult, bad_request, not_found};
 use crate::workflow::{StoryTestResults, TestCaseResult, TestStatus};
diff --git a/server/src/http/agents_sse.rs b/server/src/http/agents_sse.rs
index 16e435c7..135ac95f 100644
--- a/server/src/http/agents_sse.rs
+++ b/server/src/http/agents_sse.rs
@@ -1,3 +1,4 @@
+//! Agent SSE streaming — Server-Sent Events endpoint for real-time agent output.
 use crate::http::context::AppContext;
 use poem::handler;
 use poem::http::StatusCode;
diff --git a/server/src/http/anthropic.rs b/server/src/http/anthropic.rs
index 2630a356..b1648ff4 100644
--- a/server/src/http/anthropic.rs
+++ b/server/src/http/anthropic.rs
@@ -1,3 +1,4 @@
+//! Anthropic API proxy — forwards model listing and key-validation requests to Anthropic.
 use crate::http::context::{AppContext, OpenApiResult, bad_request};
 use crate::llm::chat;
 use crate::store::StoreOps;
diff --git a/server/src/http/assets.rs b/server/src/http/assets.rs
index 8bccee79..8bca8575 100644
--- a/server/src/http/assets.rs
+++ b/server/src/http/assets.rs
@@ -1,3 +1,4 @@
+//! Static asset serving — serves the embedded React frontend via `rust-embed`.
 use poem::{
     Response, handler,
     http::{StatusCode, header},
diff --git a/server/src/http/chat.rs b/server/src/http/chat.rs
index 137d589b..fccd099a 100644
--- a/server/src/http/chat.rs
+++ b/server/src/http/chat.rs
@@ -1,3 +1,4 @@
+//! HTTP chat endpoints — REST API for the LLM-powered chat interface.
 use crate::http::context::{AppContext, OpenApiResult, bad_request};
 use crate::llm::chat;
 use poem_openapi::{OpenApi, Tags, payload::Json};
diff --git a/server/src/http/context.rs b/server/src/http/context.rs
index f7fb72c8..d5149e90 100644
--- a/server/src/http/context.rs
+++ b/server/src/http/context.rs
@@ -1,3 +1,4 @@
+//! Application context — shared state (`AppContext`) threaded through all HTTP handlers.
 use crate::agents::{AgentPool, ReconciliationEvent};
 use crate::chat::timer::TimerStore;
 use crate::io::watcher::WatcherEvent;
diff --git a/server/src/http/health.rs b/server/src/http/health.rs
index 8340ac13..64c3120b 100644
--- a/server/src/http/health.rs
+++ b/server/src/http/health.rs
@@ -1,3 +1,4 @@
+//! Health check endpoint — returns a static "ok" response.
 use poem::handler;
 use poem_openapi::{Object, OpenApi, Tags, payload::Json};
 use serde::Serialize;
diff --git a/server/src/http/io.rs b/server/src/http/io.rs
index c40bca64..c3a46dff 100644
--- a/server/src/http/io.rs
+++ b/server/src/http/io.rs
@@ -1,3 +1,4 @@
+//! HTTP I/O endpoints — REST API for file and directory operations.
 use crate::http::context::{AppContext, OpenApiResult, bad_request};
 use crate::io::fs as io_fs;
 use poem_openapi::{Object, OpenApi, Tags, payload::Json};
diff --git a/server/src/http/mcp/agent_tools.rs b/server/src/http/mcp/agent_tools.rs
index f82f9513..8856f429 100644
--- a/server/src/http/mcp/agent_tools.rs
+++ b/server/src/http/mcp/agent_tools.rs
@@ -1,3 +1,4 @@
+//! MCP agent tools — start, stop, wait, list, and inspect agents via MCP.
 use crate::agents::PipelineStage;
 use crate::config::ProjectConfig;
 use crate::http::context::AppContext;
diff --git a/server/src/http/mcp/diagnostics.rs b/server/src/http/mcp/diagnostics.rs
index 307f3996..6c545056 100644
--- a/server/src/http/mcp/diagnostics.rs
+++ b/server/src/http/mcp/diagnostics.rs
@@ -1,3 +1,4 @@
+//! MCP diagnostic tools — server logs, CRDT dump, and story movement helpers.
 use crate::agents::move_story_to_stage;
 use crate::http::context::AppContext;
 use crate::log_buffer;
diff --git a/server/src/http/mcp/git_tools.rs b/server/src/http/mcp/git_tools.rs
index 0111c70d..23f0b903 100644
--- a/server/src/http/mcp/git_tools.rs
+++ b/server/src/http/mcp/git_tools.rs
@@ -1,3 +1,4 @@
+//! MCP git tools — status, diff, add, commit, and log operations on agent worktrees.
 use crate::http::context::AppContext;
 use serde_json::{json, Value};
 use std::path::PathBuf;
diff --git a/server/src/http/mcp/merge_tools.rs b/server/src/http/mcp/merge_tools.rs
index b2c55051..719ad856 100644
--- a/server/src/http/mcp/merge_tools.rs
+++ b/server/src/http/mcp/merge_tools.rs
@@ -1,3 +1,4 @@
+//! MCP merge tools — merge agent work to master and report merge failures.
 use crate::agents::move_story_to_merge;
 use crate::http::context::AppContext;
 use crate::io::story_metadata::write_merge_failure;
diff --git a/server/src/http/mcp/mod.rs b/server/src/http/mcp/mod.rs
index 960e300c..bfa1e126 100644
--- a/server/src/http/mcp/mod.rs
+++ b/server/src/http/mcp/mod.rs
@@ -1,3 +1,4 @@
+//! MCP server — Model Context Protocol endpoint dispatching tool calls to handlers.
 use crate::slog_warn;
 use crate::http::context::AppContext;
 use poem::handler;
diff --git a/server/src/http/mcp/qa_tools.rs b/server/src/http/mcp/qa_tools.rs
index 9533114f..d6d782f5 100644
--- a/server/src/http/mcp/qa_tools.rs
+++ b/server/src/http/mcp/qa_tools.rs
@@ -1,3 +1,4 @@
+//! MCP QA tools — request, approve, and reject QA reviews for stories.
 use crate::agents::{move_story_to_merge, move_story_to_qa, reject_story_from_qa};
 use crate::http::context::AppContext;
 use crate::slog;
diff --git a/server/src/http/mcp/shell_tools.rs b/server/src/http/mcp/shell_tools.rs
index 88e372fe..2e0805dd 100644
--- a/server/src/http/mcp/shell_tools.rs
+++ b/server/src/http/mcp/shell_tools.rs
@@ -1,3 +1,4 @@
+//! MCP shell tools — run commands, execute tests, and stream output via MCP.
 use crate::http::context::AppContext;
 use bytes::Bytes;
 use futures::StreamExt;
diff --git a/server/src/http/mcp/status_tools.rs b/server/src/http/mcp/status_tools.rs
index 44fad140..d83bde16 100644
--- a/server/src/http/mcp/status_tools.rs
+++ b/server/src/http/mcp/status_tools.rs
@@ -1,3 +1,4 @@
+//! MCP status tools — pipeline status, story triage, and acceptance criteria inspection.
 use crate::http::context::AppContext;
 use serde_json::{Value, json};
 use std::fs;
diff --git a/server/src/http/mcp/story_tools.rs b/server/src/http/mcp/story_tools.rs
index a7710a19..e4d31312 100644
--- a/server/src/http/mcp/story_tools.rs
+++ b/server/src/http/mcp/story_tools.rs
@@ -1,3 +1,4 @@
+//! MCP story tools — create, update, move, and manage stories, bugs, and refactors via MCP.
 use crate::agents::{
     close_bug_to_archive, feature_branch_has_unmerged_changes, move_story_to_done,
 };
diff --git a/server/src/http/mod.rs b/server/src/http/mod.rs
index e65c9d93..0bb92e42 100644
--- a/server/src/http/mod.rs
+++ b/server/src/http/mod.rs
@@ -1,3 +1,4 @@
+//! HTTP server — module declarations for all REST, MCP, WebSocket, and SSE endpoints.
 pub mod agents;
 pub mod agents_sse;
 pub mod anthropic;
diff --git a/server/src/http/model.rs b/server/src/http/model.rs
index 388f1d11..8059b729 100644
--- a/server/src/http/model.rs
+++ b/server/src/http/model.rs
@@ -1,3 +1,4 @@
+//! HTTP model endpoints — REST API for model selection and LLM provider management.
 use crate::http::context::{AppContext, OpenApiResult, bad_request};
 use crate::io::fs;
 use crate::llm::chat;
diff --git a/server/src/http/oauth.rs b/server/src/http/oauth.rs
index 502d45e1..fbdeec16 100644
--- a/server/src/http/oauth.rs
+++ b/server/src/http/oauth.rs
@@ -1,3 +1,4 @@
+//! OAuth endpoints — Anthropic OAuth callback and token exchange flow.
 use crate::llm::oauth;
 use crate::slog;
 use poem::handler;
diff --git a/server/src/http/project.rs b/server/src/http/project.rs
index b23bd030..ac5f8882 100644
--- a/server/src/http/project.rs
+++ b/server/src/http/project.rs
@@ -1,3 +1,4 @@
+//! HTTP project endpoints — REST API for project initialization and context management.
 use crate::http::context::{AppContext, OpenApiResult, bad_request};
 use crate::io::fs;
 use poem_openapi::{Object, OpenApi, Tags, payload::Json};
diff --git a/server/src/http/settings.rs b/server/src/http/settings.rs
index 242200da..fe3be876 100644
--- a/server/src/http/settings.rs
+++ b/server/src/http/settings.rs
@@ -1,3 +1,4 @@
+//! HTTP settings endpoints — REST API for user preferences and editor configuration.
 use crate::http::context::{AppContext, OpenApiResult, bad_request};
 use crate::store::StoreOps;
 use poem_openapi::{Object, OpenApi, Tags, param::Query, payload::Json};
diff --git a/server/src/http/wizard.rs b/server/src/http/wizard.rs
index 16ffc9ab..ab3bffb7 100644
--- a/server/src/http/wizard.rs
+++ b/server/src/http/wizard.rs
@@ -1,3 +1,4 @@
+//! HTTP wizard endpoints — REST API for the project setup wizard.
 use crate::http::context::{AppContext, OpenApiResult, bad_request, not_found};
 use crate::io::wizard::{StepStatus, WizardState, WizardStep};
 use poem_openapi::{Object, OpenApi, Tags, param::Path, payload::Json};
diff --git a/server/src/http/workflow/bug_ops.rs b/server/src/http/workflow/bug_ops.rs
index db21ddcc..2ed5bae2 100644
--- a/server/src/http/workflow/bug_ops.rs
+++ b/server/src/http/workflow/bug_ops.rs
@@ -1,3 +1,4 @@
+//! Bug operations — creates bug, refactor, and spike files in the pipeline.
 use crate::io::story_metadata::parse_front_matter;
 use std::path::Path;
 
diff --git a/server/src/http/workflow/mod.rs b/server/src/http/workflow/mod.rs
index 354c31cb..9796f3f2 100644
--- a/server/src/http/workflow/mod.rs
+++ b/server/src/http/workflow/mod.rs
@@ -1,3 +1,4 @@
+//! Workflow helpers — shared story/bug file operations used by HTTP and MCP handlers.
 mod bug_ops;
 mod story_ops;
 mod test_results;
diff --git a/server/src/http/workflow/story_ops.rs b/server/src/http/workflow/story_ops.rs
index c7b6eb54..c56a1011 100644
--- a/server/src/http/workflow/story_ops.rs
+++ b/server/src/http/workflow/story_ops.rs
@@ -1,3 +1,4 @@
+//! Story operations — creates, updates, and manages acceptance criteria in story files.
 use crate::io::story_metadata::set_front_matter_field;
 use serde_json::Value;
 use std::collections::HashMap;
diff --git a/server/src/http/workflow/test_results.rs b/server/src/http/workflow/test_results.rs
index b206a165..34acb03e 100644
--- a/server/src/http/workflow/test_results.rs
+++ b/server/src/http/workflow/test_results.rs
@@ -1,3 +1,4 @@
+//! Test result persistence — writes structured test results into story markdown files.
 use crate::io::story_metadata::set_front_matter_field;
 use crate::workflow::{StoryTestResults, TestCaseResult, TestStatus};
 use std::path::Path;
diff --git a/server/src/http/ws.rs b/server/src/http/ws.rs
index 1b5a8ea8..fb02f407 100644
--- a/server/src/http/ws.rs
+++ b/server/src/http/ws.rs
@@ -1,3 +1,4 @@
+//! WebSocket endpoint — real-time pipeline updates, chat, and permission prompts.
 use crate::http::context::{AppContext, PermissionDecision};
 use crate::http::workflow::{PipelineState, load_pipeline_state};
 use crate::io::onboarding;
diff --git a/server/src/io/fs/files.rs b/server/src/io/fs/files.rs
index 36b98f54..d717616c 100644
--- a/server/src/io/fs/files.rs
+++ b/server/src/io/fs/files.rs
@@ -1,3 +1,4 @@
+//! Filesystem file operations — read, write, list, and create files and directories.
 use crate::state::SessionState;
 use serde::Serialize;
 use std::fs;
diff --git a/server/src/io/fs/mod.rs b/server/src/io/fs/mod.rs
index b0117af0..a49d21ff 100644
--- a/server/src/io/fs/mod.rs
+++ b/server/src/io/fs/mod.rs
@@ -1,3 +1,4 @@
+//! Filesystem I/O — module declarations and re-exports for file operations.
 pub mod files;
 pub mod paths;
 pub mod preferences;
diff --git a/server/src/io/fs/paths.rs b/server/src/io/fs/paths.rs
index 865555f5..6964fed5 100644
--- a/server/src/io/fs/paths.rs
+++ b/server/src/io/fs/paths.rs
@@ -1,3 +1,4 @@
+//! Path resolution — resolves CLI and session-relative paths to absolute paths.
 use crate::state::SessionState;
 use std::path::{Path, PathBuf};
 
diff --git a/server/src/io/fs/preferences.rs b/server/src/io/fs/preferences.rs
index f8eb1d4d..811ac91a 100644
--- a/server/src/io/fs/preferences.rs
+++ b/server/src/io/fs/preferences.rs
@@ -1,3 +1,4 @@
+//! User preferences — reads and writes model selection and other user settings.
 use crate::store::StoreOps;
 use serde_json::json;
 
diff --git a/server/src/io/fs/project.rs b/server/src/io/fs/project.rs
index 42fcba8b..2b15f6cf 100644
--- a/server/src/io/fs/project.rs
+++ b/server/src/io/fs/project.rs
@@ -1,3 +1,4 @@
+//! Project management — tracks known projects and resolves the active project root.
 use crate::state::SessionState;
 use crate::store::StoreOps;
 use serde_json::json;
diff --git a/server/src/io/fs/scaffold.rs b/server/src/io/fs/scaffold.rs
index e3357487..aff7497e 100644
--- a/server/src/io/fs/scaffold.rs
+++ b/server/src/io/fs/scaffold.rs
@@ -1,3 +1,4 @@
+//! Project scaffolding — creates the `.huskies/` directory structure and default files.
 use std::fs;
 use std::path::Path;
 
diff --git a/server/src/io/mod.rs b/server/src/io/mod.rs
index 825f6888..1b502a1e 100644
--- a/server/src/io/mod.rs
+++ b/server/src/io/mod.rs
@@ -1,3 +1,4 @@
+//! I/O subsystem — filesystem, shell, search, onboarding, and story metadata operations.
 pub mod fs;
 pub mod onboarding;
 pub mod search;
diff --git a/server/src/io/onboarding.rs b/server/src/io/onboarding.rs
index 071ec2d7..d6d14d31 100644
--- a/server/src/io/onboarding.rs
+++ b/server/src/io/onboarding.rs
@@ -1,3 +1,4 @@
+//! Onboarding detection — checks whether scaffold templates have been customized.
 use std::path::Path;
 
 /// Sentinel comment injected as the first line of scaffold templates.
diff --git a/server/src/io/search.rs b/server/src/io/search.rs
index bdd68fa5..9673ccb8 100644
--- a/server/src/io/search.rs
+++ b/server/src/io/search.rs
@@ -1,3 +1,4 @@
+//! Code search — full-text search across project files using the `ignore` crate.
 use crate::slog;
 use crate::state::SessionState;
 use ignore::WalkBuilder;
diff --git a/server/src/io/shell.rs b/server/src/io/shell.rs
index a554382c..7a7efbe0 100644
--- a/server/src/io/shell.rs
+++ b/server/src/io/shell.rs
@@ -1,3 +1,4 @@
+//! Shell command execution — runs commands in the project directory and captures output.
 use crate::state::SessionState;
 use serde::Serialize;
 use std::path::PathBuf;
diff --git a/server/src/io/story_metadata.rs b/server/src/io/story_metadata.rs
index 55a6deda..f8f1d75e 100644
--- a/server/src/io/story_metadata.rs
+++ b/server/src/io/story_metadata.rs
@@ -1,3 +1,4 @@
+//! Story metadata — parses and modifies YAML front matter in story markdown files.
 use serde::Deserialize;
 use std::fs;
 use std::path::Path;
diff --git a/server/src/io/wizard.rs b/server/src/io/wizard.rs
index 2f0a0c95..a4cd0006 100644
--- a/server/src/io/wizard.rs
+++ b/server/src/io/wizard.rs
@@ -1,3 +1,4 @@
+//! Setup wizard — multi-step project onboarding flow with per-step status tracking.
 use serde::{Deserialize, Serialize};
 use serde_json;
 use std::fs;
diff --git a/server/src/llm/chat.rs b/server/src/llm/chat.rs
index 41ef6d84..0104675c 100644
--- a/server/src/llm/chat.rs
+++ b/server/src/llm/chat.rs
@@ -1,3 +1,4 @@
+//! LLM chat — orchestrates multi-turn conversations with tool-calling LLM providers.
 use crate::slog;
 use crate::io::onboarding;
 use crate::llm::prompts::{ONBOARDING_PROMPT, SYSTEM_PROMPT};
diff --git a/server/src/llm/mod.rs b/server/src/llm/mod.rs
index fb658d7b..f9bacdfe 100644
--- a/server/src/llm/mod.rs
+++ b/server/src/llm/mod.rs
@@ -1,3 +1,4 @@
+//! LLM subsystem — chat orchestration, prompts, OAuth, and provider integrations.
 pub mod chat;
 pub mod oauth;
 pub mod prompts;
diff --git a/server/src/llm/oauth.rs b/server/src/llm/oauth.rs
index ad039076..b2848bf7 100644
--- a/server/src/llm/oauth.rs
+++ b/server/src/llm/oauth.rs
@@ -1,3 +1,4 @@
+//! Anthropic OAuth — token refresh and credential management for Claude API access.
 use crate::slog;
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
diff --git a/server/src/llm/prompts.rs b/server/src/llm/prompts.rs
index ccaa62d8..f4d6d57e 100644
--- a/server/src/llm/prompts.rs
+++ b/server/src/llm/prompts.rs
@@ -1,3 +1,4 @@
+//! System prompts — static prompt templates for the LLM chat and onboarding flows.
 pub const SYSTEM_PROMPT: &str = r#"You are an AI Agent with direct access to the user's filesystem and development environment.
 
 CRITICAL INSTRUCTIONS:
diff --git a/server/src/llm/providers/anthropic.rs b/server/src/llm/providers/anthropic.rs
index 8179d49d..ab3408bb 100644
--- a/server/src/llm/providers/anthropic.rs
+++ b/server/src/llm/providers/anthropic.rs
@@ -1,3 +1,4 @@
+//! Anthropic provider — streaming completion client for the Claude Messages API.
 use crate::llm::types::{
     CompletionResponse, FunctionCall, Message, Role, ToolCall, ToolDefinition,
 };
diff --git a/server/src/llm/providers/claude_code.rs b/server/src/llm/providers/claude_code.rs
index bb2b8615..3a9b4ebb 100644
--- a/server/src/llm/providers/claude_code.rs
+++ b/server/src/llm/providers/claude_code.rs
@@ -1,3 +1,4 @@
+//! Claude Code provider — runs Claude Code CLI in a PTY and parses structured output.
 use crate::slog;
 use portable_pty::{CommandBuilder, PtySize, native_pty_system};
 use std::io::{BufRead, BufReader};
diff --git a/server/src/llm/providers/mod.rs b/server/src/llm/providers/mod.rs
index 96e3b37b..32c8336a 100644
--- a/server/src/llm/providers/mod.rs
+++ b/server/src/llm/providers/mod.rs
@@ -1,3 +1,4 @@
+//! LLM providers — module declarations for Anthropic, Claude Code, and Ollama backends.
 pub mod anthropic;
 pub mod claude_code;
 pub mod ollama;
diff --git a/server/src/llm/providers/ollama.rs b/server/src/llm/providers/ollama.rs
index c3b166a0..cc501d0d 100644
--- a/server/src/llm/providers/ollama.rs
+++ b/server/src/llm/providers/ollama.rs
@@ -1,3 +1,4 @@
+//! Ollama provider — streaming completion client for locally-hosted Ollama models.
 use crate::llm::types::{
     CompletionResponse, FunctionCall, Message, ModelProvider, Role, ToolCall, ToolDefinition,
 };
diff --git a/server/src/llm/types.rs b/server/src/llm/types.rs
index 0d6dec41..829a815d 100644
--- a/server/src/llm/types.rs
+++ b/server/src/llm/types.rs
@@ -1,3 +1,4 @@
+//! LLM types — `Message`, `Role`, `ToolCall`, `ModelProvider`, and related data structures.
 use async_trait::async_trait;
 use serde::{Deserialize, Serialize};
 use std::fmt::Debug;
diff --git a/server/src/main.rs b/server/src/main.rs
index 76ed4ca9..d1596ebe 100644
--- a/server/src/main.rs
+++ b/server/src/main.rs
@@ -1,3 +1,5 @@
+//! Huskies server — entry point, CLI argument parsing, and server startup.
+
 // matrix-sdk-crypto's deeply nested types require a higher recursion limit
 // when the `e2e-encryption` feature is enabled.
 #![recursion_limit = "256"]
diff --git a/server/src/state.rs b/server/src/state.rs
index 4522fd51..917e4f9f 100644
--- a/server/src/state.rs
+++ b/server/src/state.rs
@@ -1,3 +1,4 @@
+//! Session state — global mutable state shared across the server (project root, cancellation).
 use std::path::PathBuf;
 use std::sync::Mutex;
 use tokio::sync::watch;
diff --git a/server/src/store.rs b/server/src/store.rs
index 342499a7..fcb44a6c 100644
--- a/server/src/store.rs
+++ b/server/src/store.rs
@@ -1,3 +1,4 @@
+//! Key-value store — JSON-backed persistent storage for user settings and preferences.
 use serde_json::Value;
 use std::collections::HashMap;
 use std::fs;
diff --git a/server/src/worktree.rs b/server/src/worktree.rs
index e8082d21..0a2f7f35 100644
--- a/server/src/worktree.rs
+++ b/server/src/worktree.rs
@@ -1,3 +1,4 @@
+//! Git worktree management — creates, lists, and removes worktrees for agent isolation.
 use crate::config::ProjectConfig;
 use crate::slog;
 use std::path::{Path, PathBuf};