docs: improve DX with navigation and cross-references

- Update docs/mcp/tools/ placeholders with quick refs and links
- Create docs/ref/tools/index.md with full package table
- Create docs/ref/agent/index.md with topic links
- Create docs/ref/mcp/index.md with tool categories
- Create docs/tools/index.md as main entry point
- Add consistent cross-references between sections

docs/ref/agent/index.md

@@ -1,2 +1,45 @@
-# index
-Documentation coming soon.
+# Agent Reference
+
+API reference for the hanzo-agent framework.
+
+## Overview
+
+hanzo-agent provides a multi-agent SDK with:
+
+- OpenAI-compatible API
+- Multi-agent orchestration
+- Tool use and guardrails
+- Streaming and tracing
+
+## Documentation
+
+| Topic | Description |
+|-------|-------------|
+| [Getting Started](../../agent/index.md) | Introduction to agents |
+| [Running Agents](../../agent/running_agents.md) | How to run agents |
+| [Agent Config](../../agent/config.md) | Configuration options |
+| [Tools](../../agent/tools.md) | Tool integration |
+| [Guardrails](../../agent/guardrails.md) | Safety constraints |
+| [Multi-Agent](../../agent/multi_agent.md) | Orchestrating multiple agents |
+| [Handoffs](../../agent/handoffs.md) | Agent handoff patterns |
+| [Streaming](../../agent/streaming.md) | Streaming responses |
+| [Tracing](../../agent/tracing.md) | Debugging and tracing |
+
+## Quick Start
+
+```python
+from hanzo_agent import Agent, Runner
+
+agent = Agent(
+    name="assistant",
+    instructions="You are a helpful assistant.",
+)
+
+result = await Runner.run(agent, "Hello!")
+print(result.final_output)
+```
+
+## See Also
+
+- [Agent Tools](../../tools/agent.md) - CLI agent integration
+- [Consensus Protocol](../../lib/consensus.md) - Multi-agent agreement

docs/ref/mcp/index.md

@@ -1,2 +1,65 @@
-# index
-Documentation coming soon.
+# MCP Reference
+
+API reference for hanzo-mcp (Model Context Protocol).
+
+## Overview
+
+hanzo-mcp provides:
+
+- 30+ tools for AI development
+- FastMCP-based server
+- Claude Code integration
+- Entry-point based tool discovery
+
+## Documentation
+
+| Topic | Description |
+|-------|-------------|
+| [Quickstart](../../mcp/quickstart.md) | Getting started |
+| [Configuration](../../mcp/configuration.md) | Server configuration |
+| [VS Code Setup](../../mcp/vscode.md) | IDE integration |
+| [Tool Parity](../../mcp/PARITY.md) | Feature comparison |
+
+## Tool Categories
+
+| Category | Docs |
+|----------|------|
+| [Shell](../../mcp/tools/shell.md) | Command execution |
+| [Filesystem](../../mcp/tools/filesystem.md) | File operations |
+| [Browser](../../mcp/tools/browser.md) | Web automation |
+| [Memory](../../mcp/tools/memory.md) | Persistent memory |
+| [Reasoning](../../mcp/tools/reasoning.md) | Thinking tools |
+| [Agent](../../mcp/tools/agent.md) | Multi-agent |
+| [LSP](../../mcp/tools/lsp.md) | Code intelligence |
+| [LLM](../../mcp/tools/llm-tools.md) | LLM interface |
+
+## Quick Start
+
+```bash
+# Install
+pip install hanzo-mcp[tools-all]
+
+# Run server
+hanzo-mcp
+
+# Or with specific tools
+hanzo-mcp --tools shell,browser,memory
+```
+
+## Claude Code Integration
+
+```json
+{
+  "mcpServers": {
+    "hanzo": {
+      "command": "hanzo-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+## See Also
+
+- [Tools Reference](../tools/index.md) - Full tool documentation
+- [Core Libraries](../../lib/index.md) - Supporting packages

docs/ref/tools/index.md

@@ -1,2 +1,58 @@
-# index
-Documentation coming soon.
+# Tools Reference
+
+Comprehensive API reference for all hanzo-tools-* packages.
+
+## Tool Packages
+
+| Package | Tools | Description |
+|---------|-------|-------------|
+| [Core](../../tools/core.md) | Base classes | Foundation for tool development |
+| [Filesystem](../../tools/fs.md) | 7 | File operations and AST analysis |
+| [Shell](../../tools/shell.md) | 12 | Command execution and process management |
+| [Browser](../../tools/browser.md) | 1 (70+ actions) | Playwright automation |
+| [Memory](../../tools/memory.md) | 9 | Persistent memory and knowledge bases |
+| [Reasoning](../../tools/reasoning.md) | 2 | Structured thinking and analysis |
+| [Agent](../../tools/agent.md) | 3 | Multi-agent orchestration |
+| [LSP](../../tools/lsp.md) | 1 | Language server protocol |
+| [Refactor](../../tools/refactor.md) | 1 | Code refactoring with AST/LSP |
+| [LLM](../../tools/llm-tools.md) | 2 | Unified LLM interface |
+| [Database](../../tools/database.md) | 8 | SQL and graph databases |
+| [Vector](../../tools/vector.md) | 3 | Semantic search |
+| [Jupyter](../../tools/jupyter.md) | 1 | Notebook operations |
+| [Editor](../../tools/editor.md) | 3 | Neovim integration |
+| [Todo](../../tools/todo.md) | 1 | Task management |
+| [Computer](../../tools/computer.md) | 1 | Mac automation |
+| [Config](../../tools/config.md) | 2 | Configuration management |
+| [MCP](../../tools/mcp-tools.md) | 4 | MCP server management |
+
+## Quick Install
+
+```bash
+# All tools
+pip install hanzo-mcp[tools-all]
+
+# Core + dev tools
+pip install hanzo-mcp[tools-dev]
+
+# Specific packages
+pip install hanzo-tools-shell hanzo-tools-browser
+```
+
+## Tool Discovery
+
+Tools are discovered via entry points:
+
+```python
+from importlib.metadata import entry_points
+
+# Get all tool entry points
+eps = entry_points(group="hanzo.tools")
+for name, ep in eps.items():
+    tools = ep.load()
+    print(f"{name}: {len(tools)} tools")
+```
+
+## See Also
+
+- [MCP Configuration](../../mcp/configuration.md)
+- [MCP Quickstart](../../mcp/quickstart.md)