improve docs

Author: nikomatsakis

md/SUMMARY.md

@@ -30,6 +30,7 @@
     - [Daemon message bus](./design/daemon.md) <!-- 💡: Central message router implementation, client management, process lifecycle, and Unix socket server architecture -->
     - [MCP Tool interface](./design/mcp-tool-interface.md) <!-- 💡: API specification for AI assistants calling present_review tool with markdown content -->
 - [VSCode extension](./design/extension.md) <!-- 💡: Highlights of the VSCode Extension design and implementation: activation, establishing IPC protocol -->
+- [Dialect language](./design/dialect-language.md) <!-- 💡: JSON mini-language semantics for IDE operations - function composition, value types, and execution model -->
 
 # References
 
@@ -43,4 +44,5 @@
         - [Implementation Guide](./references/lsp-overview/implementation-guide.md) <!-- 💡: Practical LSP server/client implementation patterns covering process isolation, message ordering, state management, error handling with exponential backoff, transport configuration (--stdio, --pipe, --socket), three-tier testing strategy, and security considerations (input validation, process isolation, path sanitization). Relevant for: robust IPC implementation, testing strategy, security best practices -->
         - [Message Reference](./references/lsp-overview/message-reference.md) <!-- 💡: Complete LSP message catalog with request/response pairs, notifications, $/prefixed protocol messages, capabilities exchange during initialization, document synchronization (full/incremental), workspace/window features, and proper lifecycle management (initialize → initialized → shutdown → exit). Relevant for: protocol patterns, capability negotiation, document synchronization, future LSP integration -->
     - [Unix IPC Message Bus Implementation Guide](./references/unix-message-bus-architecture.md) <!-- 💡: Comprehensive research on Unix IPC message bus patterns covering Unix domain sockets vs other mechanisms, hub-and-spoke architecture with central broker, epoll-based event handling, process lifecycle management, performance optimization through hybrid approaches, security hardening, and real-world implementations (D-Bus, Redis, nanomsg). Validates Unix sockets as superior foundation for multi-client message buses with concrete implementation patterns. Relevant for: message bus daemon design, IPC architecture decisions, multi-process communication, performance considerations -->
+    - [VSCode PR Extension Research](./references/vscode-extensions-dev-pattern.md) <!-- 💡: This research report provides comprehensive technical documentation for building a VS Code extension that creates synthetic pull requests for LLM-generated code changes, covering all essential VS Code Extension APIs with detailed implementation examples. It includes the Comment Controller API for creating PR-like commenting experiences with pre-populated LLM explanations, the Tree View API for PR navigation interfaces in VS Code's sidebar, the Webview API for detailed PR panels with approve/request changes functionality, diff viewer integration for showing file changes, and file system watchers for detecting LLM modifications. The report contains practical code examples for comment thread management, tree data providers, webview panel creation, change tracking systems, command registration for review actions, and integration patterns for forwarding user feedback to LLMs and applying their suggested changes back to the codebase. Consult this report when implementing VS Code extensions that need to display code diffs, manage commenting workflows, create custom sidebar views, integrate with LLM APIs for code review scenarios, or replicate GitHub-style pull request interfaces within VS Code. -->
 - [Decision documents]()

md/design/ask-socratic-shell.md

@@ -1 +1,59 @@
 # Ask Socratic Shell
+
+How users can select code and route it to AI assistants running in terminals.
+
+## User Flow
+
+1. User selects code in VSCode editor
+2. Right-click → "Ask Socratic Shell" or use command palette
+3. Extension queries terminal registry for active AI assistants
+4. Routes to single terminal automatically, or shows picker for multiple
+5. Injects formatted context into chosen terminal
+
+## Message Flow
+
+```mermaid
+sequenceDiagram
+    participant User as User
+    participant Ext as VSCode Extension
+    participant Term as Terminal
+    participant AI as AI Assistant
+
+    User->>Ext: Select code + "Ask Socratic Shell"
+    Ext->>Ext: Query terminal registry
+    alt Single active terminal
+        Ext->>Term: Inject context message
+    else Multiple terminals
+        Ext->>User: Show terminal picker
+        User->>Ext: Select terminal
+        Ext->>Term: Inject context message
+    end
+    Term->>AI: Context available for next query
+```
+
+## Terminal Registry
+
+The extension tracks which terminals have active AI assistants by monitoring:
+- Shell PIDs from MCP server connections
+- VSCode terminal process IDs
+- Matching PIDs to route messages correctly
+
+**Multi-window support**: Each VSCode window maintains its own terminal registry.
+
+## Implementation Details
+
+**Context Formatting**:
+```
+<context>looking at this code from src/auth.ts:42:1-50</context>
+```
+
+**Terminal Detection** (`extension/src/extension.ts`):
+- Maintains `Set<number>` of active shell PIDs
+- Updates registry based on daemon messages
+- Matches VSCode terminals to shell processes
+
+## Key Files
+
+- `extension/src/extension.ts` - Terminal registry and routing logic
+- `extension/src/reviewWebview.ts` - Selection handling (if applicable)
+- Server components handle PID discovery and reporting

md/design/dialect-language.md

@@ -0,0 +1,89 @@
+# Dialect language
+
+The "Dialect" language is a variation of the Lambda calculus that is used to express and compose IDE operations. It is written in JSON:
+## Quick Start
+
+Dialect programs are JSON expressions that compose IDE operations. Here are the most common patterns:
+
+**Find where a symbol is defined:**
+```json
+{"findDefinitions": "MyFunction"}
+```
+
+**Find all references to a symbol:**
+```json
+{"findReferences": "MyClass"}
+```
+
+**Get information about a symbol:**
+```json
+{"getSymbolInfo": "methodName"}
+```
+
+**Basic composition - find references to all definitions:**
+```json
+{"findReferences": {"findDefinitions": "MyFunction"}}
+```
+
+These expressions are passed to the `ide_operation` tool, which executes them and returns structured results with file locations and symbol information.
+
+## Grammar
+
+```
+Expr = ExprAtomic
+     | `{` Name `:` `{` Name `:` Expr ... `}` `}`
+     | `{` Name `:` ExprAtomic `}`
+
+ExprAtomic = number
+           | boolean
+           | `null`
+           | `undefined`
+           | string
+           | `[` Expr... `]`
+
+Name = string
+
+// Here: capitalized things are nonterminals.
+//
+// number, boolean, string are JSON terminals.
+//
+// `foo` indicates the text `foo`.
+//
+// And ... indicates a comma-separated list.
+```
+
+## Dynamic semantics
+
+A Dialect expression `E` evaluates to a JSON value:
+
+* If `E = [ Expr... ]` a list, then
+    * evaluate `Expr...` to values `V...`
+    * and `E` evaluates to `[ V... ]`
+* If `E = { Name_f: { Name_a: Expr ... }}`, then
+    * evaluate `Expr...` to values `V...`
+    * create an object `{ Name_a: V ... }` where each argument name is paired with the value of its expression
+    * lookup the function `Name_f` and call it with the given arguments
+* If `E = { Name_f: ExprAtomic }`, then
+    * lookup the function `Name_f` and check whether it defaults a default argument `Name_a`
+    * if so, evaluate `{ Name_f: { Name_a: ExprAtomic }}` instead
+* If `E = number | string | null | undefined`, evaluate to itself
+
+The interpreter is defined in `dialect.rs`.
+
+## Defining functions
+
+Functions are defined in Rust by implementing the `DialectFunction` trait:
+
+```rust
+{{#include ../../server/src/dialect.rs:dialect_function_trait}}
+```
+
+The `Output` will be serialized into JSON and passed along.
+
+Some functions evaluate to instances of themselves, these represent "values"
+(as in the lambda calculus). They can implement `DialectValue` instead:
+
+```rust
+{{#include ../../server/src/dialect.rs:dialect_value_trait}}
+```
+

md/design/ide-capabilities.md

@@ -1 +1,55 @@
 # IDE Capabilities
+
+How AI assistants access VSCode's Language Server Protocol (LSP) features through the `ide_operation` tool.
+
+## Dialect Mini-Language
+
+The `ide_operation` tool uses a composable [JSON mini-language called Dialect](./dialect-language.md) for IDE operations:
+
+```json
+{"findDefinitions": "MyFunction"}
+{"findReferences": "MyClass"}
+{"getSymbolInfo": "methodName"}
+```
+
+## Message Flow
+
+```mermaid
+sequenceDiagram
+    participant AI as AI Assistant
+    participant MCP as MCP Server
+    participant Ext as VSCode Extension
+    participant LSP as Language Server
+
+    AI->>MCP: ide_operation tool call
+    MCP->>Ext: Execute Dialect program
+    Ext->>LSP: LSP request (definitions/references/etc)
+    LSP->>Ext: Symbol locations/info
+    Ext->>MCP: Formatted results
+    MCP->>AI: Tool response with locations
+```
+
+## Implementation Details
+
+**MCP Server** (`server/src/server.rs`):
+- Receives Dialect program in `IdeOperationParams`
+- Forwards to extension via IPC for execution
+- Returns structured results to AI assistant
+
+**VSCode Extension**:
+- Interprets Dialect operations
+- Translates to appropriate VSCode/LSP API calls
+- Handles disambiguation when multiple matches found
+- Returns formatted location/symbol information
+
+**Supported Operations**:
+- `findDefinitions` - Where symbols are defined
+- `findReferences` - Where symbols are used
+- `getSymbolInfo` - Type signatures and documentation
+- Future: completion, hover info, workspace symbols
+
+## Key Files
+
+- `server/src/server.rs` - Tool handler and parameter validation
+- Extension components handle Dialect interpretation and LSP communication
+- `server/src/dialect/` - Dialect interpreter (if implemented)

md/design/present-review.md

@@ -1 +1,43 @@
 # Present Review
+
+How AI assistants display code reviews in VSCode through the MCP server and extension.
+
+## Message Flow
+
+```mermaid
+sequenceDiagram
+    participant AI as AI Assistant
+    participant MCP as MCP Server
+    participant Ext as VSCode Extension
+    participant UI as Webview Panel
+
+    AI->>MCP: present_review tool call
+    MCP->>Ext: PresentReview message (Unix socket)
+    Ext->>UI: Update webview content
+    UI->>Ext: Link click (postMessage)
+    Ext->>UI: Navigate to file/line
+```
+
+## Implementation Details
+
+**MCP Server** (`server/src/server.rs`):
+- Receives `present_review` tool call with markdown content
+- Validates parameters using `PresentReviewParams` struct
+- Forwards to VSCode extension via Unix socket IPC
+
+**VSCode Extension** (`extension/src/reviewWebview.ts`):
+- Receives message from MCP server
+- Processes markdown with custom link renderer
+- Updates webview panel with processed HTML
+
+**Link Processing**:
+- Converts `file.ts?searchTerm` → `dialectic:file.ts?regex=searchTerm`
+- Converts `file.ts#L42` → `dialectic:file.ts?line=42`
+- Handles disambiguation when search finds multiple matches
+
+## Key Files
+
+- `server/src/server.rs` - Tool handler and IPC forwarding
+- `server/src/types.rs` - Parameter definitions
+- `extension/src/reviewWebview.ts` - Webview management and link handling
+- `extension/src/extension.ts` - Message routing from daemon client