Clean up documentation structure and fix outdated content

- Reorganize SUMMARY.md to be user-focused rather than RFC-heavy
- Rewrite extension.md to match actual webview implementation (not fantasy tree view)
- Remove outdated subsections (terminal-registry.md, markdown-rendering.md)
- Convert tool interface docs to use mdbook includes with anchors to prevent staleness
- Add user-friendly pages for IDE capabilities and code walkthroughs
- Fix typos and improve cross-references in FAQ

The documentation now accurately reflects the current implementation and uses
patterns that prevent it from going stale.

Author: nikomatsakis

md/SUMMARY.md

@@ -8,9 +8,9 @@
 
 - [Installation](./installation.md) <!-- 💡: Step-by-step setup for both VSCode extension and MCP server components -->
 - [Quick start](./quick-start.md) <!-- 💡: Basic workflow example showing AI assistant → review display → navigation cycle -->
-- [Features]()
-    - [Presenting a walkthrough](./walkthrough-presentation.md) <!-- 💡: Explain how presentation works, from a user's perspective -->
-    - [Ask Socratic Shell](./ask-socratic-shell.md) <!-- 💡: Explain how Ask Socratic Shell works, from a user's perspective -->
+- [Features]() <!-- 💡: Explains how to use each feature -->
+    - [Code walkthroughs and Ask Socratic Shell](./present-review.md) <!-- 💡: Give examples of how to ask the agent to walk through code with you, what happens when you click links, and how you can use Ask Socratic Shell. -->
+    - [IDE Capabilities](./ide-capabilities.md) <!-- 💡: Natural language interface to VSCode/LSP features, current capabilities, and implementation details -->
     - [Review format](./review-format.md) <!-- 💡: Explains file:line syntax, reference-style links [file:line][], and markdown conventions AI assistants should follow -->
 - [Frequently asked questions](./faq.md) <!-- 💡: Anticipated user questions about common errors, expected workflow, purpose, comparisons with other tools, etc -->
 
@@ -19,24 +19,17 @@
 - [Building and testing](./design/build-and-test.md) <!-- 💡: Development environment setup, build process, and testing procedures -->
 - [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 -->
+    - [Codebase structure](./design/codebase-structure.md) <!-- 💡: Overview of project structure, key files, and how components connect for contributors -->
+- [How each feature works]() <!-- 💡: Walk through the flow of particular features -->
+    - [Present Review](./design/present-review.md) <!-- 💡: How AI assistants present code reviews, message flows, and implementation details -->
+    - [Ask Socratic Shell](./design/ask-socratic-shell.md) <!-- 💡: How Ask Socratic Shell works, message flows, and implementation details -->
+    - [IDE Capabilities](./design/ide-capabilities.md) <!-- 💡: Natural language interface to VSCode/LSP features, current capabilities, and implementation details -->
+- [MCP server](./design/mcp-server.md) <!-- 💡: Highlights of the MCP server  --> 
+    - [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 -->
-    - [Terminal registry](./design/terminal-registry.md) <!-- 💡: Implementation details for tracking active MCP servers, PID discovery, and capability-based routing -->
-    - [Markdown rendering](./design/markdown-rendering.md) <!-- 💡: markdown-it pipeline, custom renderer rules for file references, and HTML generation process -->
-
-# In-progress RFCs <!-- 💡: Design proposals under active development and discussion -->
-
-- [RFC: Exposing IDE capabilities](./rfcs/ide-capabilities/README.md) <!-- 💡: Proposal for natural language interface to VSCode and LSP features through composable JSON mini-language -->
-    - [RFC: Scripting language](./rfcs/ide-capabilities/scripting-language.md) <!-- 💡: JSON mini-language design with function composition and value types -->
-        - [RFC: Validation boundaries](./rfcs/ide-capabilities/scripting-language/validation-boundaries.md) <!-- 💡: Where should type checking happen - in the engine or in capability implementations? -->
-        - [RFC: Ambiguity resolution](./rfcs/ide-capabilities/scripting-language/ambiguity-resolution.md) <!-- 💡: How functions like {"symbol":{"name":"foo"}} handle multiple matches -->
-    - [RFC: Natural language interface](./rfcs/ide-capabilities/natural-language-interface.md) <!-- 💡: How natural language requests get converted to JSON programs -->
-    - [RFC: Capability registry](./rfcs/ide-capabilities/capability-registry.md) <!-- 💡: What IDE capabilities to expose initially and their function signatures -->
 
 # References
 

md/design/ask-socratic-shell.md

@@ -0,0 +1 @@
+# Ask Socratic Shell

md/design/codebase-structure.md

@@ -0,0 +1 @@
+# Codebase structure