diff --git a/.huskies/specs/tech/STACK.md b/.huskies/specs/tech/STACK.md
index c7927092..99d0b47b 100644
--- a/.huskies/specs/tech/STACK.md
+++ b/.huskies/specs/tech/STACK.md
@@ -30,6 +30,157 @@ docker/              — Dockerfile and docker-compose
 website/             — Static marketing/docs site
 ```
 
+## Source Map
+
+### Backend roots
+| Path | Purpose |
+|------|---------|
+| `server/src/main.rs` | Binary entry; CLI parsing; server startup |
+| `server/src/config/` | `project.toml` parsing |
+| `server/src/state.rs` | Global mutable session state |
+| `server/src/store.rs` | JSON-backed KV store for settings |
+| `server/src/gateway.rs` | Multi-project gateway mode (route builder, MCP proxy) |
+| `server/src/agent_mode.rs` | Headless build-agent mode |
+| `server/src/services.rs` | Top-level service registry / wiring |
+| `server/src/workflow.rs` | Cross-cutting workflow helpers |
+
+### Agents
+| Path | Purpose |
+|------|---------|
+| `server/src/agents/mod.rs` | Agent types and orchestration root |
+| `server/src/agents/pool/` | Coder/QA/mergemaster pool, auto-assign, lifecycle, retry |
+| `server/src/agents/pool/auto_assign/` | Auto-assigner: scans pipeline, spawns agents on free slots |
+| `server/src/agents/pool/pipeline/` | Stage transitions, completion, merge orchestration |
+| `server/src/agents/runtime/` | Per-provider runtimes: `claude_code.rs`, `gemini.rs`, `openai.rs` |
+| `server/src/agents/merge/` | Squash-merge mechanics, conflict detection |
+| `server/src/agents/pty.rs` | PTY pseudo-terminal spawning + output streaming |
+| `server/src/agents/lifecycle.rs` | Stage transitions and item movement |
+| `server/src/agents/gates.rs` | Quality-gate runner |
+| `server/src/agents/session_store.rs` | Per-agent session history |
+| `server/src/agents/token_usage.rs` | Per-agent token cost ledger |
+
+### CRDT + persistence
+| Path | Purpose |
+|------|---------|
+| `server/src/crdt_state/` | CRDT primitives — `lww_maps.rs`, `state.rs`, `read.rs`, `write.rs`, `ops.rs`, `types.rs`, `presence.rs`, `gateway_config.rs` |
+| `server/src/crdt_sync/` | WebSocket replication; `rpc.rs` holds the **read-RPC registry** |
+| `server/src/crdt_sync/server/` | Sync-server endpoint, keepalive |
+| `server/src/crdt_snapshot/` | Snapshot persistence |
+| `server/src/pipeline_state/` | Typed pipeline state machine + projections |
+| `server/src/db/mod.rs` | `content_store`, shadow writes, op persistence |
+
+### HTTP / WS routes
+| Path | Purpose |
+|------|---------|
+| `server/src/http/mod.rs` | Top-level route registration |
+| `server/src/http/ws.rs` | Top-level WebSocket dispatcher |
+| `server/src/http/events.rs` | Event push endpoint |
+| `server/src/http/agents/` | Agent REST + tests |
+| `server/src/http/gateway/` | Gateway routes — `rest.rs`, `websocket.rs`, `mcp.rs`, `jsonrpc.rs` |
+| `server/src/http/mcp/` | MCP tool handlers (agent_tools, story_tools, merge_tools, qa_tools, status_tools, git_tools, wizard_tools, dispatch.rs) |
+| `server/src/http/workflow/` | Story-creation workflow endpoints (`bug_ops.rs`, `test_results.rs`) |
+| `server/src/http/anthropic.rs` | Anthropic API proxy |
+| `server/src/http/oauth.rs` | OAuth flows |
+| `server/src/http/bot_command.rs` | Bot command dispatch |
+| `server/src/http/bot_config.rs` | Bot config save/get |
+| `server/src/http/wizard.rs` | Setup wizard endpoint |
+
+### Chat (bot)
+| Path | Purpose |
+|------|---------|
+| `server/src/chat/mod.rs` | Chat module root |
+| `server/src/chat/commands/` | Slash commands — `status.rs`, `backlog.rs`, `run_tests.rs`, `depends.rs`, `freeze.rs`, `unblock.rs`, `move_story.rs`, `assign.rs`, `loc.rs`, `cost.rs`, `help.rs`, etc. |
+| `server/src/chat/commands/mod.rs` | Command dispatch |
+| `server/src/chat/transport/matrix/` | Matrix bot |
+| `server/src/chat/transport/slack/` | Slack bot |
+| `server/src/chat/transport/whatsapp/` | WhatsApp Business API |
+| `server/src/chat/transport/discord/` | Discord bot |
+| `server/src/chat/test_helpers.rs` | `write_item_with_content` and other CRDT-seeding test helpers |
+
+### Domain services (one folder per concern)
+| Path | Purpose |
+|------|---------|
+| `server/src/service/agents/` | Agent listing + selection |
+| `server/src/service/events/` | Event store + buffer |
+| `server/src/service/gateway/` | Gateway business logic |
+| `server/src/service/git_ops/` | git status/diff/add/commit primitives |
+| `server/src/service/merge/` | Merge orchestration |
+| `server/src/service/notifications/` | Notification dispatch |
+| `server/src/service/qa/` | QA lifecycle |
+| `server/src/service/story/` | Story CRUD + front matter |
+| `server/src/service/timer/` | Timer schedule |
+| `server/src/service/wizard/` | Setup wizard state machine |
+| `server/src/service/ws/` | WebSocket message dispatch + inbound RPC routing |
+| `server/src/service/oauth/` | OAuth flow + PKCE |
+| `server/src/service/file_io/` | Filesystem read/write helpers |
+| `server/src/service/shell/` | Shell command execution + path-guard |
+| `server/src/service/anthropic/` | Anthropic API client |
+| `server/src/service/bot_command/` | Bot command core logic |
+| `server/src/service/diagnostics/` | Server diagnostics |
+| `server/src/service/pipeline/` | Pipeline-level service helpers |
+| `server/src/service/project/` | Project loading and selection |
+| `server/src/service/settings/` | Settings persistence + validation |
+| `server/src/service/status/` | Status text formatting |
+| `server/src/service/common/` | Cross-cutting service helpers |
+
+### LLM
+| Path | Purpose |
+|------|---------|
+| `server/src/llm/providers/` | `anthropic.rs`, `ollama.rs` |
+| `server/src/llm/chat/` | LLM chat session (`run.rs`, `tools.rs`) |
+| `server/src/llm/oauth.rs` | LLM OAuth flow |
+| `server/src/llm/prompts.rs` | Prompt templates |
+
+### IO, watcher, worktrees
+| Path | Purpose |
+|------|---------|
+| `server/src/io/fs/` | Project file paths + scaffold |
+| `server/src/io/watcher/` | Filesystem watcher for `.huskies/work/` and `project.toml` |
+| `server/src/io/story_metadata.rs` | Story front-matter parsing/writing — `parse_front_matter`, `set_front_matter_field`, `write_*_in_content` setters |
+| `server/src/io/onboarding.rs` | First-run onboarding |
+| `server/src/io/wizard.rs` | Wizard IO |
+| `server/src/io/search.rs` | Repo search |
+| `server/src/io/test_helpers.rs` | Generic IO test helpers |
+| `server/src/worktree/` | Git worktree create/remove + git ops |
+
+### Utilities
+| Path | Purpose |
+|------|---------|
+| `server/src/rebuild.rs` | Server rebuild + restart |
+| `server/src/agent_log.rs` | JSONL agent event logs |
+| `server/src/log_buffer.rs` | In-memory log buffer |
+| `server/src/mesh.rs` | Mesh networking |
+| `server/src/node_identity.rs` | Node identity |
+| `server/src/gateway_relay.rs` | Gateway relay |
+
+### Frontend
+| Path | Purpose |
+|------|---------|
+| `frontend/src/api/rpc.ts` | **Shared read-RPC client** over `/ws` — `rpcCall<T>(method, params)` |
+| `frontend/src/api/agents.ts` | Agent listing + streaming (uses `rpcCall`) |
+| `frontend/src/api/gateway.ts` | Multi-project gateway client |
+| `frontend/src/api/client.ts` | HTTP client base |
+| `frontend/src/components/` | React UI components (Chat, AgentPanel, WorkItemDetailPanel, etc.) |
+| `frontend/src/components/selection/` | Selection-related components |
+| `frontend/src/hooks/` | React hooks (`useChatWebSocket`, etc.) |
+| `frontend/src/utils/` | Utility helpers |
+
+### Crates
+| Path | Purpose |
+|------|---------|
+| `crates/bft-json-crdt/src/` | Core CRDT library — JSON CRDT, lists, maps, registers |
+| `crates/bft-json-crdt/bft-crdt-derive/src/` | Derive macros |
+
+### Canonical examples (when adding new things, copy these patterns)
+- **New CRDT collection (LWW-map):** see `server/src/crdt_state/lww_maps.rs`
+- **New read-RPC handler:** register in `server/src/crdt_sync/rpc.rs` (e.g. `handle_active_agents_list`); call from frontend with `rpcCall("method.name")`
+- **Migrate HTTP route → CRDT op:** delete the route from `gateway.rs` / `http/*`, add operation to `service/<area>/`, write through `crdt_state/`
+- **New front-matter field:** add to `StoryMetadata` and `FrontMatter` in `io/story_metadata.rs`, plus a `write_<name>_in_content` helper
+- **New service module:** copy structure of `server/src/service/agents/` (`mod.rs` + `io.rs` + `selection.rs`)
+- **New chat command:** add file under `server/src/chat/commands/` and register in `chat/commands/mod.rs::dispatch_command`
+- **New auto-assigner predicate:** add to `agents/pool/auto_assign/story_checks.rs`, wire in `auto_assign/auto_assign.rs`
+- **Test setup with CRDT seeding:** use `crate::db::write_item_with_content(story_id, stage, content)` — never `fs::write` to `.huskies/work/{stage}/`
+
 ## Quality Gates
 All enforced by `script/test`:
 1. Frontend build (`npm run build`)