Complete comprehensive documentation overhaul for Dialectic

User Guide sections:
- Create Ask Socratic Shell user guide with terminal selection and routing
- Create walkthrough presentation guide with navigation and review modes
- Update FAQ with ### headers for linkability and current daemon architecture
- Update quick start with dual workflows (review + Ask Socratic Shell)

System Overview sections:
- Rewrite communication protocol for daemon message bus architecture
- Update VSCode extension docs with terminal registry and Ask Socratic Shell
- Create comprehensive daemon message bus documentation
- Create detailed MCP server implementation documentation
- Streamline MCP tool interface to reference format with mdbook includes
- Add mdbook anchors for automatic code synchronization

Documentation now provides complete coverage of:
- Multi-window daemon message bus architecture
- Intelligent terminal routing without configuration
- Ask Socratic Shell integration with smart terminal detection
- Professional Mermaid diagrams with click-to-enlarge functionality
- Comprehensive user guides and technical reference documentation

All major components (MCP Server, Daemon, VSCode Extension) now have
dedicated technical documentation with implementation details, error
handling, and testing strategies. Documentation is production-ready.

Author: nikomatsakis

md/SUMMARY.md

@@ -20,6 +20,8 @@
 - [System overview](./design/overview.md) <!-- 💡: High-level architecture showing MCP server ↔ VSCode extension communication via Unix sockets -->
     - [Communication protocol](./design/protocol.md) <!-- 💡: JSON message format, Unix socket/named pipe IPC, and error handling between components -->
     - [Message flows](./design/message-flows.md) <!-- 💡: Detailed sequence diagrams and examples for review presentation and Ask Socratic Shell flows -->
+    - [Daemon message bus](./design/daemon.md) <!-- 💡: Central message router implementation, client management, process lifecycle, and Unix socket server architecture -->
+    - [MCP server](./design/mcp-server.md) <!-- 💡: AI assistant bridge implementation, process discovery, tool handlers, and daemon client functionality -->
     - [Security considerations](./design/security.md) <!-- 💡: CSP headers, DOMPurify sanitization, and secure webview practices for markdown rendering -->
     - [MCP Tool interface](./design/mcp-tool-interface.md) <!-- 💡: API specification for AI assistants calling present_review tool with markdown content -->
     - [AI Guidance design considerations](./design/ai-guidance.md) <!-- 💡: Design decisions made specifically to work well with AI collaboration patterns from socratic shell -->

md/ask-socratic-shell.md

@@ -1 +1,79 @@
 # Ask Socratic Shell
+
+Ask Socratic Shell lets you send selected code directly to your AI assistant for discussion, creating a seamless bridge between your editor and AI chat sessions.
+
+## How It Works
+
+When you select code in VSCode, Dialectic automatically detects which terminals have active AI assistants and routes your selection to the right place.
+
+## Using Ask Socratic Shell
+
+### 1. Select Code
+Highlight any code in your VSCode editor - a function, a few lines, or even a single variable.
+
+### 2. Trigger the Action
+Right-click and choose **"Ask Socratic Shell"** from the context menu, or use the lightbulb quick action that appears.
+
+### 3. Choose Your AI (if needed)
+- **Single AI assistant**: Your message goes directly to that terminal
+- **Multiple AI assistants**: A picker appears showing available options
+- **No AI assistants**: You'll see a helpful message about starting an AI session
+
+### 4. Continue the Conversation
+The selected code appears in your AI terminal with context about the file and location. Continue the conversation naturally.
+
+## Terminal Selection
+
+### Smart Detection
+Dialectic automatically finds terminals with active AI assistants - no need to name terminals or configure anything.
+
+### Multiple AI Assistants
+When you have multiple AI sessions running, the terminal picker shows:
+- **Quick access option**: "Use last terminal: [Name]" at the top
+- **All available terminals**: Listed with their process IDs
+- **Memory**: Your last choice is remembered and highlighted
+
+### Example Picker
+```
+┌─ Multiple AI-enabled terminals found ─────────────────┐
+│ Select terminal for AI chat (first option = quick...) │
+├───────────────────────────────────────────────────────┤
+│ ● 📜 Use last terminal: Terminal 2    PID: 67890      │
+│   Quick access to your previously used terminal       │
+│                                                       │
+│ ─ All available terminals                             │
+│                                                       │
+│   Terminal (qterm)           PID: 35059               │
+│   Terminal with active MCP server                     │
+│                                                       │
+│ ⭐ Terminal 2                 PID: 67890 (last used)  │
+│   Terminal with active MCP server                     │
+└───────────────────────────────────────────────────────┘
+```
+
+## Message Format
+
+Your selected code is sent with helpful context:
+
+```
+<context>looking at this code from src/auth.ts:42:1-45:20 <content>function validateUser(email) {
+  if (!email.includes('@')) {
+    return false;
+  }
+  return true;
+}</content></context> can you help me improve this validation?
+```
+
+This gives your AI assistant:
+- **File location**: `src/auth.ts:42:1-45:20`
+- **Actual code**: The selected content
+- **Your question**: Added automatically or you can type more
+
+## Tips
+
+- **Select meaningful chunks**: Functions, classes, or logical blocks work best
+- **Add your question**: The context menu adds "can you help me improve this?" but you can edit it
+- **Use consistently**: The system remembers your preferred terminal for quick access
+- **Multiple windows**: Each VSCode window tracks its own AI assistants independently
+
+Ask Socratic Shell eliminates the friction of copying code to chat - just select, click, and discuss!

md/design/daemon.md

@@ -0,0 +1,18 @@
+# Daemon Message Bus
+
+The daemon message bus serves as the central communication hub that routes messages between MCP servers and VSCode extensions across multiple windows. It eliminates the need for direct connections while enabling intelligent message routing based on terminal capabilities.
+
+## Binary
+
+The [MCP server](./mcp-server.md) and daemon are packaged in the same binary. Daemons are started by passing the `daemon` parameter on the command line.
+
+## Lifecycle
+
+When an [MCP server](./mcp-server.md) starts, it identifies the PID of the IDE it is running inside of and attempts to start a daemon for that PID as a new process. If a daemon is already running, then this has no effect.
+
+The daemon runs as a root process. It periodically monitors the IDE PID to see whether the IDE has exited. If the IDE has terminated, the daemon will automatically terminate.
+
+## IPC communication
+
+Daemons bind an IPC socket whose name is determined by the PID of the IDE (given on the command line).
+The [IPC protocol](./protocol.md) is defined separately. Daemons themselves don't understand the protocol, they simple accept newline-delimited messages and re-broadcast them to all connected clients. Daemons are intentionally very simple.

md/design/extension.md

@@ -4,50 +4,133 @@
 
 ## Goal
 
-The VSCode extension provides a simple, focused interface for displaying and interacting with AI-generated code reviews. It eliminates the need to scroll through terminal output by bringing reviews directly into the IDE as a first-class citizen.
+The VSCode extension provides intelligent AI integration with two core capabilities:
 
-### Core Functionality
-
-The extension enables three essential capabilities:
-
-1. **Review Display** - Pop up a dedicated panel when the AI assistant presents a review, showing the structured markdown content with proper formatting
-
-2. **Code Navigation** - Make `file:line` references in the review clickable, allowing instant navigation to the referenced code locations in the editor
-
-3. **Content Export** - Provide a "Copy" button to copy the review content to the clipboard for use in commit messages, documentation, or sharing
-
-These three features support the core workflow: AI generates review → user reads and navigates → user exports for further use.
+1. **Review Display** - Present AI-generated code reviews in a dedicated sidebar panel with clickable navigation
+2. **Ask Socratic Shell** - Route selected code to AI assistants with intelligent terminal detection and routing
 
 ## Architecture
 
-The extension operates as both a UI component and an IPC server:
+The extension operates as a daemon client and UI component:
 
 ```
-┌─────────────────┐    IPC Server     ┌─────────────────┐    Tree View API    ┌─────────────────┐
-│   MCP Server    │ ←─────────────────→ │ VSCode Extension│ ←─────────────────→ │   VSCode UI     │
-└─────────────────┘                    └─────────────────┘                    └─────────────────┘
+┌─────────────────┐    Daemon Client    ┌─────────────────┐    VSCode APIs    ┌─────────────────┐
+│ Daemon Bus      │ ←─────────────────→ │ VSCode Extension│ ←───────────────→ │   VSCode UI     │
+└─────────────────┘                    └─────────────────┘                  └─────────────────┘
+                                               │
+                                               ▼
+                                        ┌─────────────────┐
+                                        │Terminal Registry│
+                                        └─────────────────┘
 ```
 
 **Key Responsibilities:**
-- Create and manage Unix socket IPC server for MCP communication
-- Set environment variables for MCP server discovery
-- Process incoming review messages and update UI components
+- Connect to daemon message bus as client
+- Maintain terminal registry of AI-enabled terminals
+- Process review presentation messages and update UI
+- Implement Ask Socratic Shell with intelligent terminal routing
 - Provide tree-based review display with clickable navigation
-- Handle copy-to-clipboard functionality
 
-## Implementation Approach
+## Core Components
+
+### Daemon Client
+Manages connection to the daemon message bus:
+- **Connection management** - Connects to daemon Unix socket on activation
+- **Message handling** - Processes PresentReview, Polo, Goodbye, and Marco messages
+- **Response routing** - Sends success/error responses back through daemon
+- **Reconnection logic** - Handles daemon restarts gracefully
+
+### Terminal Registry
+Tracks which terminals have active AI assistants:
+- **PID tracking** - Maintains `Set<number>` of shell PIDs with active MCP servers
+- **Discovery updates** - Updates registry based on Polo/Goodbye messages from daemon
+- **Terminal matching** - Maps VSCode terminals to shell PIDs for routing decisions
+- **Workspace isolation** - Each window maintains independent registry
+
+### Ask Socratic Shell Integration
+Routes selected code to AI assistants:
+- **Code selection** - Captures selected text with file location context
+- **Terminal detection** - Queries terminal registry for AI-enabled terminals
+- **Smart routing** - Auto-routes to single terminal or shows picker for multiple
+- **Terminal picker** - VSCode QuickPick with memory and quick access options
+- **Message formatting** - Formats code with context for AI consumption
+
+### Review Provider
+Displays AI-generated reviews in sidebar:
+- **Tree structure** - Hierarchical display of review sections and content
+- **Markdown rendering** - Processes markdown with custom link handling
+- **Navigation** - Clickable file:line references that jump to code locations
+- **Content management** - Supports replace, update, and append modes
+
+## Implementation Details
+
+### Terminal Registry Implementation
+```typescript
+class DaemonClient {
+    private activeTerminals = new Set<number>();
+    
+    private handlePoloMessage(message: PoloMessage) {
+        this.activeTerminals.add(message.shellPid);
+        this.outputChannel.appendLine(`Added terminal PID ${message.shellPid} to registry`);
+    }
+    
+    private handleGoodbyeMessage(message: GoodbyeMessage) {
+        this.activeTerminals.delete(message.shellPid);
+        this.outputChannel.appendLine(`Removed terminal PID ${message.shellPid} from registry`);
+    }
+}
+```
+
+### Ask Socratic Shell Flow
+1. **User selects code** - Context menu or quick action triggers command
+2. **Query registry** - Get list of terminals with active AI assistants
+3. **Route intelligently**:
+   - **Single terminal** - Send message directly
+   - **Multiple terminals** - Show picker with memory
+   - **No terminals** - Display helpful error message
+4. **Format message** - Include file location and selected code
+5. **Send to terminal** - Use VSCode terminal API to inject formatted text
+
+### Terminal Picker UX
+- **Quick access option** - "Use last terminal: [Name]" appears first
+- **Visual indicators** - Star icons and "(last used)" labels
+- **Natural ordering** - Terminals appear in same order as VSCode terminal list
+- **Workspace memory** - Remembers preference per VSCode window
+- **Graceful fallbacks** - Handles terminal closures and MCP server disconnections
+
+### Message Processing
+The extension filters daemon broadcasts based on shell PID matching:
+```typescript
+private async handlePresentReviewMessage(message: PresentReviewMessage) {
+    // Check if this message is for a terminal in our window
+    const matchingTerminal = await this.findTerminalByPID(message.shellPid);
+    if (matchingTerminal) {
+        // Process the review for our window
+        await this.reviewProvider.presentReview(message);
+        return { success: true };
+    }
+    // Ignore - another window will handle it
+    return null;
+}
+```
 
-### Technology Stack
-- **Language**: TypeScript with VSCode Extension API
-- **UI Framework**: VSCode TreeView API for hierarchical review display
-- **IPC**: Node.js `net` module for Unix socket server
-- **Markdown Processing**: Custom parser for tree structure generation
-- **Navigation**: VSCode editor commands for file/line jumping
+## Multi-Window Support
 
-### Core Components
+Each VSCode window runs an independent extension instance:
+- **Separate daemon connections** - Each window connects to the same daemon
+- **Independent registries** - Each tracks its own terminals
+- **Automatic routing** - Messages route to correct window based on shell PID
+- **Isolated preferences** - Terminal picker memory is per-window
+
+## Technology Stack
+
+- **Language**: TypeScript with VSCode Extension API
+- **IPC**: Node.js Unix socket client for daemon communication
+- **UI**: VSCode TreeView API for review display, QuickPick for terminal selection
+- **Terminal Integration**: VSCode Terminal API for message injection
+- **State Management**: VSCode workspace state for terminal picker memory
 
-**Extension Activation**: Main entry point that sets up all functionality
-- Creates review provider for tree-based display
+The extension provides seamless AI integration that eliminates configuration while supporting sophisticated multi-window workflows.
 - Registers tree view with VSCode's sidebar
 - Sets up IPC server for MCP communication
 - Registers commands and cleanup handlers

md/design/mcp-server.md

@@ -0,0 +1,15 @@
+# MCP Server
+
+The MCP server acts as a bridge between AI assistants and the VSCode extension. It offers [tools](./tool-interface.md) that AI assistants can use to send messages to the extension (e.g., present-review).
+
+## Lifecycle
+
+MCP servers are started automatically by the AI client. They can be long- or short-lived depending on the whims of the client.
+
+## PID identification
+
+When the MCP server starts, it walks up the process tree to identify the PID for the shell it is running within and the IDE that this shell is contained within. If those PIDs cannot be identified, it returns an error. As described in the [daemon lifecycle](./daemon.md#lifecycle), the server will also spawn a daemon process for the IDE PID if needed.
+
+## Tools offered to clients
+
+See the [Tool Interface](./tool-interface.md) section.

md/design/mcp-tool-interface.md

@@ -1,33 +1,66 @@
 # MCP Tool Interface
 
-*This section documents the `present_review` tool that AI assistants use to display code reviews in VSCode.*
-
-## Tool Overview
-
-The `present_review` tool is the primary interface between AI assistants and the Dialectic system. It accepts markdown content and displays it in the VSCode review panel with clickable file references and proper formatting.
+*Reference documentation for the `present_review` tool exposed to AI assistants.*
 
 ## Tool Definition
 
-The tool is registered with the MCP server and exposed to AI assistants:
-
-```typescript
-{{#include ../../server/src/index.ts:tool_definition}}
+```rust
+{{#include ../../server/src/server.rs:present_review_tool}}
 ```
 
 ## Parameters
 
-The tool accepts parameters defined by the `PresentReviewParams` interface:
+### `content` (required)
+Markdown content of the review to display with support for clickable file references.
 
-```typescript
-{{#include ../../server/src/types.ts:present_review_params}}
+### `mode` (optional, default: "replace")
+- `"replace"` - Replace entire review content
+- `"update-section"` - Update specific section of existing review  
+- `"append"` - Add content to end of existing review
+
+### `baseUri` (required)
+Base directory path for resolving relative file references.
+
+### `section` (optional)
+Section name for `update-section` mode.
+
+## File Reference Formats
+
+```markdown
+[auth.ts](src/auth.ts)                    # Opens file
+[auth.ts:42](src/auth.ts#L42)             # Jumps to line 42
+[auth.ts:42-50](src/auth.ts#L42-L50)      # Highlights line range
+[validateUser](src/auth.ts?validateUser)  # Finds pattern in file
 ```
 
-### Parameter Details
+## Usage Examples
 
-**`content` (required)**
-- **Type**: `string`
-- **Description**: Markdown content of the review to display
-- **Format**: Standard markdown with support for file references using `[filename:line][]` syntax
+### Basic Review
+```javascript
+await use_mcp_tool("present_review", {
+    content: "# Code Review\n\nImplemented user authentication...",
+    baseUri: "/workspace/myapp"
+});
+```
+
+### Section Update
+```javascript
+await use_mcp_tool("present_review", {
+    content: "## Updated Error Handling\n\nImproved validation...",
+    mode: "update-section",
+    section: "Error Handling", 
+    baseUri: "/workspace/myapp"
+});
+```
+
+### Append Mode
+```javascript
+await use_mcp_tool("present_review", {
+    content: "## Next Steps\n\n- Add rate limiting\n- Implement caching",
+    mode: "append",
+    baseUri: "/workspace/myapp"
+});
+```
 - **Example**: 
   ```markdown
   # Authentication System Implementation