docs: add READMEs for all 18 hanzo-tools-* packages

pkg/hanzo-tools-agent/README.md

@@ -0,0 +1,75 @@
+# hanzo-tools-agent
+
+Agent orchestration tools for Hanzo MCP.
+
+## Installation
+
+```bash
+pip install hanzo-tools-agent
+
+# Optional: API mode
+pip install hanzo-tools-agent[api]
+
+# Optional: High-performance
+pip install hanzo-tools-agent[perf]
+```
+
+## Tools
+
+### agent - Unified Agent Runner
+Run various AI CLI agents with auto-backgrounding.
+
+```python
+# Run with default agent
+agent(action="run", prompt="Explain this code")
+
+# Run specific agent
+agent(action="run", name="gemini", prompt="Review this PR")
+
+# List available agents
+agent(action="list")
+
+# Check agent status
+agent(action="status", name="claude")
+```
+
+**Available Agents:**
+- `claude` - Anthropic Claude Code CLI
+- `codex` - OpenAI Codex CLI
+- `gemini` - Google Gemini CLI
+- `grok` - xAI Grok CLI
+- `qwen` - Alibaba Qwen CLI
+- `vibe` - Vibe coding agent
+- `code` - Hanzo Code agent
+- `dev` - Hanzo Dev agent
+
+### Direct API Mode
+Configure agents for direct API calls without CLI:
+
+```json
+// ~/.hanzo/agents/custom.json
+{
+    "endpoint": "https://api.openai.com/v1/chat/completions",
+    "api_type": "openai",
+    "model": "gpt-4",
+    "env_key": "OPENAI_API_KEY"
+}
+```
+
+### iching - I Ching Wisdom
+```python
+iching(challenge="How should I approach this refactoring?")
+```
+
+### review - Code Review
+```python
+review(
+    focus="FUNCTIONALITY",
+    work_description="Implemented auto-import feature",
+    file_paths=["/path/to/file.py"]
+)
+```
+
+## License
+
+MIT

pkg/hanzo-tools-browser/README.md

@@ -0,0 +1,65 @@
+# hanzo-tools-browser
+
+Browser automation tools for Hanzo MCP using Playwright.
+
+## Installation
+
+```bash
+pip install hanzo-tools-browser
+```
+
+## Tools
+
+### browser - Complete Playwright API
+70+ browser actions for full automation.
+
+**Navigation:**
+```python
+browser(action="navigate", url="https://example.com")
+browser(action="go_back")
+browser(action="reload")
+```
+
+**Input:**
+```python
+browser(action="click", selector="button.submit")
+browser(action="fill", selector="input[name=email]", text="[email protected]")
+browser(action="type", selector="textarea", text="Hello")
+```
+
+**Touch/Mobile:**
+```python
+browser(action="tap", selector=".button")
+browser(action="swipe", selector=".carousel", direction="left")
+browser(action="emulate", device="mobile")  # or tablet, laptop
+```
+
+**Assertions:**
+```python
+browser(action="expect_visible", selector=".modal")
+browser(action="expect_text", selector="h1", expected="Welcome")
+browser(action="expect_url", expected="*/dashboard*")
+```
+
+**Content:**
+```python
+browser(action="get_text", selector=".content")
+browser(action="screenshot", full_page=True)
+browser(action="pdf")
+```
+
+**Parallel Agents:**
+```python
+# Each agent gets isolated session
+browser(action="new_context")  # Separate cookies/storage
+```
+
+**Device Presets:**
+- `mobile` - iPhone-like (390x844, touch)
+- `tablet` - iPad-like (1024x1366, touch)
+- `laptop` - MacBook-like (1440x900)
+- `iphone_14`, `pixel_7`, `ipad_pro`, etc.
+
+## License
+
+MIT

pkg/hanzo-tools-core/README.md

@@ -0,0 +1,63 @@
+# hanzo-tools-core
+
+Core infrastructure for Hanzo MCP tools.
+
+## Installation
+
+```bash
+pip install hanzo-tools-core
+```
+
+## Components
+
+### BaseTool
+Base class for all Hanzo tools.
+
+```python
+from hanzo_tools.core import BaseTool
+
+class MyTool(BaseTool):
+    name = "my_tool"
+    
+    @property
+    def description(self) -> str:
+        return "My custom tool"
+    
+    async def call(self, ctx, **params) -> str:
+        return "result"
+```
+
+### ToolRegistry
+Manage tool registration and discovery.
+
+```python
+from hanzo_tools.core import ToolRegistry
+
+ToolRegistry.register_tools(mcp_server, [MyTool()])
+```
+
+### PermissionManager
+Access control for file and command operations.
+
+```python
+from hanzo_tools.core import PermissionManager
+
+pm = PermissionManager(allowed_paths=["/home/user/project"])
+if pm.can_access("/home/user/project/file.py"):
+    # proceed
+```
+
+### Decorators
+
+```python
+from hanzo_tools.core import auto_timeout
+
+@auto_timeout("my_tool")
+async def my_function():
+    # Auto-backgrounds after timeout
+    pass
+```
+
+## License
+
+MIT

pkg/hanzo-tools-database/README.md

@@ -0,0 +1,73 @@
+# hanzo-tools-database
+
+Database tools for Hanzo MCP.
+
+## Installation
+
+```bash
+pip install hanzo-tools-database
+```
+
+## Tools
+
+### SQL Tools
+
+**sql_query:**
+```python
+sql_query(query="SELECT * FROM users WHERE active = true")
+```
+
+**sql_search:**
+```python
+sql_search(table="users", pattern="john%")
+```
+
+**sql_stats:**
+```python
+sql_stats(table="users")  # Table statistics
+```
+
+### Graph Database Tools
+
+**graph_add:**
+```python
+graph_add(node_type="Person", properties={"name": "John", "age": 30})
+graph_add(
+    edge_type="KNOWS",
+    from_node="person_1",
+    to_node="person_2"
+)
+```
+
+**graph_remove:**
+```python
+graph_remove(node_id="person_1")
+```
+
+**graph_query:**
+```python
+graph_query(pattern="MATCH (p:Person) RETURN p")
+```
+
+**graph_search:**
+```python
+graph_search(node_type="Person", properties={"name": "John"})
+```
+
+**graph_stats:**
+```python
+graph_stats()  # Graph statistics
+```
+
+## Configuration
+
+Set database URLs via environment:
+
+```bash
+DATABASE_URL=postgresql://user:pass@localhost:5432/db
+GRAPH_DATABASE_URL=neo4j://localhost:7687
+```
+
+## License
+
+MIT

pkg/hanzo-tools-editor/README.md

@@ -0,0 +1,53 @@
+# hanzo-tools-editor
+
+Neovim integration tools for Hanzo MCP.
+
+## Installation
+
+```bash
+pip install hanzo-tools-editor
+```
+
+## Tools
+
+### neovim_edit - Edit Files in Neovim
+```python
+neovim_edit(file="/path/to/file.py", line=10)
+```
+
+### neovim_command - Run Neovim Commands
+```python
+neovim_command(command=":w")  # Save
+neovim_command(command=":q!")  # Quit without saving
+neovim_command(command=":%s/old/new/g")  # Search replace
+```
+
+### neovim_session - Manage Sessions
+```python
+neovim_session(action="list")  # List sessions
+neovim_session(action="connect", name="main")
+neovim_session(action="disconnect")
+```
+
+## Requirements
+
+- Neovim with remote plugin support
+- `pynvim` package (installed automatically)
+
+## Configuration
+
+Set Neovim socket path:
+
+```bash
+NVIM_LISTEN_ADDRESS=/tmp/nvim.sock nvim
+```
+
+Or connect to existing session:
+
+```python
+neovim_session(action="connect", socket="/tmp/nvim.sock")
+```
+
+## License
+
+MIT

pkg/hanzo-tools-fs/README.md

@@ -0,0 +1,55 @@
+# hanzo-tools-fs
+
+Filesystem tools for Hanzo MCP.
+
+## Installation
+
+```bash
+pip install hanzo-tools-fs
+```
+
+## Tools
+
+### read - Read Files
+```python
+read(file_path="/path/to/file.py")
+read(file_path="/path/to/file.py", offset=100, limit=50)
+```
+
+### write - Write Files
+```python
+write(file_path="/path/to/file.py", content="...")
+```
+
+### edit - Edit Files
+```python
+edit(
+    file_path="/path/to/file.py",
+    old_string="def old():",
+    new_string="def new():"
+)
+```
+
+### tree - Directory Structure
+```python
+tree(path="/project", depth=3)
+```
+
+### find - File Discovery
+```python
+find(pattern="*.py", path="/project")
+```
+
+### search - Content Search
+```python
+search(pattern="TODO|FIXME", path="./src")
+```
+
+### ast - Code Structure
+```python
+ast(pattern="class.*Service", path="/src")
+```
+
+## License
+
+MIT

pkg/hanzo-tools-jupyter/README.md

@@ -0,0 +1,65 @@
+# hanzo-tools-jupyter
+
+Jupyter notebook tools for Hanzo MCP.
+
+## Installation
+
+```bash
+pip install hanzo-tools-jupyter
+```
+
+## Tools
+
+### jupyter - Notebook Operations
+Read and edit Jupyter notebooks.
+
+**Read notebook:**
+```python
+jupyter(action="read", path="/path/to/notebook.ipynb")
+jupyter(action="read", path="/path/to/notebook.ipynb", cell=5)  # Specific cell
+```
+
+**Edit cell:**
+```python
+jupyter(
+    action="edit",
+    path="/path/to/notebook.ipynb",
+    cell=5,
+    content="print('Hello, World!')"
+)
+```
+
+**Insert cell:**
+```python
+jupyter(
+    action="insert",
+    path="/path/to/notebook.ipynb",
+    after_cell=5,
+    content="# New cell",
+    cell_type="markdown"
+)
+```
+
+**Delete cell:**
+```python
+jupyter(
+    action="delete",
+    path="/path/to/notebook.ipynb",
+    cell=5
+)
+```
+
+**List cells:**
+```python
+jupyter(action="list", path="/path/to/notebook.ipynb")
+```
+
+## Cell Types
+
+- `code` - Python code cell
+- `markdown` - Markdown text cell
+- `raw` - Raw text cell
+
+## License
+
+MIT

pkg/hanzo-tools-lsp/README.md

@@ -0,0 +1,66 @@
+# hanzo-tools-lsp
+
+Language Server Protocol tools for Hanzo MCP.
+
+## Installation
+
+```bash
+pip install hanzo-tools-lsp
+```
+
+## Tools
+
+### lsp - Language Server Protocol
+Code intelligence via LSP servers.
+
+**Go to definition:**
+```python
+lsp(action="definition", file="/path/to/file.py", line=10, character=15)
+```
+
+**Find references:**
+```python
+lsp(action="references", file="/path/to/file.py", line=10, character=15)
+```
+
+**Hover information:**
+```python
+lsp(action="hover", file="/path/to/file.py", line=10, character=15)
+```
+
+**Code completion:**
+```python
+lsp(action="completion", file="/path/to/file.py", line=10, character=15)
+```
+
+**Diagnostics:**
+```python
+lsp(action="diagnostics", file="/path/to/file.py")
+```
+
+**Rename symbol:**
+```python
+lsp(action="rename", file="/path/to/file.py", line=10, character=15, new_name="newName")
+```
+
+**Check status:**
+```python
+lsp(action="status")  # Check LSP server status
+```
+
+## Supported Languages
+
+- Go (gopls)
+- Python (pyright)
+- TypeScript/JavaScript (typescript-language-server)
+- Rust (rust-analyzer)
+- Java (jdtls)
+- C/C++ (clangd)
+- Ruby (solargraph)
+- Lua (lua-language-server)
+
+Language servers are automatically installed as needed.
+
+## License
+
+MIT

pkg/hanzo-tools-memory/README.md

@@ -0,0 +1,62 @@
+# hanzo-tools-memory
+
+Memory and knowledge management tools for Hanzo MCP.
+
+## Installation
+
+```bash
+pip install hanzo-tools-memory
+```
+
+## Tools
+
+### memory - Unified Memory Management
+Single tool with multiple actions for memory operations.
+
+**Recall memories:**
+```python
+memory(action="recall", query="project architecture")
+memory(action="recall", queries=["user preferences", "coding standards"])
+```
+
+**Create memories:**
+```python
+memory(action="create", data={"content": "User prefers dark mode"})
+memory(action="create", statements=["Fact 1", "Fact 2"])
+```
+
+**Update memories:**
+```python
+memory(action="update", id="mem_123", statement="Updated fact")
+```
+
+**Delete memories:**
+```python
+memory(action="delete", ids=["mem_123", "mem_456"])
+```
+
+**Knowledge bases:**
+```python
+memory(action="facts", query="API endpoints", kb_name="api_docs")
+memory(action="store", facts=["Rate limit: 100/hour"], kb_name="api_docs")
+memory(action="kb", action_type="list")  # List knowledge bases
+```
+
+**Summarize:**
+```python
+memory(
+    action="summarize",
+    content="Long discussion about API design...",
+    topic="API Design Decisions"
+)
+```
+
+## Scopes
+
+- `session` - Current session only
+- `project` - Project-specific (default)
+- `global` - Across all projects
+
+## License
+
+MIT

pkg/hanzo-tools-reasoning/README.md

@@ -0,0 +1,60 @@
+# hanzo-tools-reasoning
+
+Reasoning and analysis tools for Hanzo MCP.
+
+## Installation
+
+```bash
+pip install hanzo-tools-reasoning
+```
+
+## Tools
+
+### think - Structured Reasoning
+Record thoughts for complex reasoning or brainstorming.
+
+```python
+think(thought="Analyzing the architecture: The codebase uses...")
+```
+
+**Use cases:**
+- Bug exploration and fix brainstorming
+- Test failure analysis
+- Complex refactoring planning
+- Feature design decisions
+- Issue investigation
+
+### critic - Critical Analysis
+Play devil's advocate and ensure high standards.
+
+```python
+critic(analysis="Review this implementation for bugs and edge cases...")
+```
+
+**What it checks:**
+- Potential bugs and edge cases
+- Error handling gaps
+- Test coverage issues
+- Performance problems
+- Security vulnerabilities
+- Code quality and design
+
+**Example output:**
+```
+Code Review Analysis:
+- Implementation Issues:
+  * No error handling for network failures
+  * Race condition in concurrent updates
+  
+- Test Coverage Gaps:
+  * No tests for error scenarios
+  * Missing edge case: empty input
+  
+- Recommendations:
+  1. Add retry logic with exponential backoff
+  2. Use database transactions
+```
+
+## License
+
+MIT

pkg/hanzo-tools-refactor/README.md

@@ -0,0 +1,89 @@
+# hanzo-tools-refactor
+
+Advanced refactoring tools for Hanzo MCP.
+
+## Installation
+
+```bash
+pip install hanzo-tools-refactor
+```
+
+## Tools
+
+### refactor - Code Refactoring
+AST/LSP-based refactoring with parallel processing.
+
+**Rename symbol:**
+```python
+refactor(action="rename", file="/f.py", line=10, column=5, new_name="newName")
+```
+
+**Batch rename:**
+```python
+refactor(
+    action="rename_batch",
+    renames=[{"old": "foo", "new": "bar"}],
+    path="./src"
+)
+```
+
+**Extract function:**
+```python
+refactor(
+    action="extract_function",
+    file="/f.py",
+    start_line=10,
+    end_line=20,
+    new_name="extracted_function"
+)
+```
+
+**Extract variable:**
+```python
+refactor(
+    action="extract_variable",
+    file="/f.py",
+    line=10,
+    column=5,
+    new_name="extracted_var"
+)
+```
+
+**Inline:**
+```python
+refactor(action="inline", file="/f.py", line=10, column=5)
+```
+
+**Move:**
+```python
+refactor(action="move", file="/f.py", line=10, target_file="/new.py")
+```
+
+**Change signature:**
+```python
+refactor(
+    action="change_signature",
+    file="/f.py",
+    line=10,
+    add_parameter={"name": "x", "default": "None"}
+)
+```
+
+**Find references:**
+```python
+refactor(action="find_references", file="/f.py", line=10, column=5)
+```
+
+**Organize imports:**
+```python
+refactor(action="organize_imports", file="/f.py")
+```
+
+## Options
+
+- `preview=True` - Preview changes without applying
+- `parallel=True` - Process files in parallel (default)
+
+## License
+
+MIT

pkg/hanzo-tools-shell/README.md

@@ -0,0 +1,98 @@
+# hanzo-tools-shell
+
+Shell execution tools for Hanzo MCP with DAG support and Shellflow DSL.
+
+## Installation
+
+```bash
+pip install hanzo-tools-shell
+```
+
+## Tools
+
+### dag - DAG Execution Engine
+Execute commands with directed acyclic graph semantics.
+
+```python
+# Serial execution (default)
+dag(["ls", "pwd", "git status"])
+
+# Parallel execution
+dag(["npm install", "cargo build"], parallel=True)
+
+# Mixed DAG with parallel blocks
+dag([
+    "mkdir -p dist",
+    {"parallel": ["cp a.txt dist/", "cp b.txt dist/"]},
+    "zip -r out.zip dist/"
+])
+
+# Tool invocations
+dag([{"tool": "search", "input": {"pattern": "TODO"}}])
+
+# Named nodes with dependencies
+dag([
+    {"id": "build", "run": "make build"},
+    {"id": "test", "run": "make test", "after": ["build"]},
+])
+```
+
+### zsh - Primary Shell with Shellflow DSL
+Execute shell commands with optional Shellflow syntax.
+
+```python
+# Simple command
+zsh("ls -la")
+
+# Shellflow DSL syntax
+zsh("mkdir dist ; { cp a dist/ & cp b dist/ } ; zip out")
+
+# With shell parameter
+zsh("echo $BASH_VERSION", shell="bash")
+```
+
+**Shellflow Syntax:**
+- `A ; B` - Sequential execution
+- `{ A & B }` - Parallel execution
+- `A ; { B & C } ; D` - Mixed DAG
+
+### ps - Process Management
+Monitor and control background processes.
+
+```python
+ps()                     # List all processes
+ps(id="abc123")          # Get specific process
+ps(kill="abc123")        # Kill process (SIGTERM)
+ps(logs="abc123", n=50)  # Last 50 lines of output
+```
+
+### Additional Tools
+- **shell** - Smart shell (zsh > bash fallback)
+- **bash** - Explicit bash execution
+- **npx** - Node package execution with auto-backgrounding
+- **uvx** - Python package execution with auto-backgrounding
+- **open** - Open files/URLs in system apps
+- **curl** - HTTP client without shell escaping issues
+- **jq** - JSON processor
+- **wget** - File/site downloads
+
+## Auto-Backgrounding
+
+Commands that exceed the timeout (default 60s) are automatically backgrounded:
+
+```python
+dag(["long-running-command"], timeout=30)
+# If command exceeds 30s, it continues in background
+# Use ps --logs <id> to view output
+```
+
+## Performance
+
+Shellflow DSL is optimized for high throughput:
+- Simple commands: ~7M ops/sec
+- Sequential: ~2.2M ops/sec  
+- Mixed DAG: ~100k ops/sec
+
+## License
+
+MIT

pkg/hanzo-tools-todo/README.md

@@ -0,0 +1,54 @@
+# hanzo-tools-todo
+
+Task management tools for Hanzo MCP.
+
+## Installation
+
+```bash
+pip install hanzo-tools-todo
+```
+
+## Tools
+
+### todo - Task Management
+Manage todo items with status tracking.
+
+**List todos:**
+```python
+todo()  # List all
+todo(filter="in_progress")  # Filter by status
+```
+
+**Add todo:**
+```python
+todo(action="add", content="Implement feature X")
+todo(action="add", content="Critical bug", priority="high")
+```
+
+**Update todo:**
+```python
+todo(action="update", id="abc123", status="completed")
+todo(action="update", id="abc123", content="Updated description")
+```
+
+**Remove todo:**
+```python
+todo(action="remove", id="abc123")
+todo(action="clear")  # Remove all
+```
+
+## Status Values
+
+- `pending` - Not started
+- `in_progress` - Currently working
+- `completed` - Done
+
+## Priority Values
+
+- `high` - Urgent
+- `medium` - Normal (default)
+- `low` - Can wait
+
+## License
+
+MIT