Add README documentation for mcp and state directories

- mcp/README.md: Document Gmail setup, delegation helpers, MCP patterns
- state/README.md: Document state files, ownership, and subdirectories

Completes documentation coverage for all major directories.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

mcp/README.md

@@ -0,0 +1,88 @@
+# MCP Integrations
+
+Model Context Protocol servers and delegation helpers.
+
+## Directory Structure
+
+```
+mcp/
+├── gmail/              # Gmail OAuth setup and venv
+│   ├── venv/           # Python virtual environment
+│   └── ...
+└── delegation/         # Tiered delegation helpers
+    ├── gmail_delegate.py
+    └── gcal_delegate.py
+```
+
+## Gmail Integration
+
+### Setup
+
+The Gmail integration uses a Python virtual environment with `gmail-mcp`:
+
+```bash
+# Create venv (one time)
+cd ~/.claude/mcp/gmail
+python3 -m venv venv
+source venv/bin/activate
+pip install gmail-mcp
+
+# Credentials
+# OAuth credentials at: ~/.gmail-mcp/credentials.json
+# Token cached at: ~/.gmail-mcp/token.json
+```
+
+### Usage
+
+Skills reference the venv directly:
+
+```bash
+~/.claude/mcp/gmail/venv/bin/python script.py
+```
+
+## Delegation Helpers
+
+Helpers that implement tiered model delegation:
+
+| Helper | Purpose | Tiers |
+|--------|---------|-------|
+| `gmail_delegate.py` | Gmail operations | Haiku (list), Sonnet (summarize) |
+| `gcal_delegate.py` | Calendar operations | Haiku (list), Sonnet (analyze) |
+
+### Pattern
+
+```bash
+GMAIL_PY=~/.claude/mcp/gmail/venv/bin/python
+HELPER=~/.claude/mcp/delegation/gmail_delegate.py
+
+# Haiku tier - no LLM, just fetch
+$GMAIL_PY $HELPER check-unread --days 7
+
+# Sonnet tier - spawns claude --model sonnet
+$GMAIL_PY $HELPER summarize --query "from:github.com"
+```
+
+## Adding MCP Servers
+
+For proper MCP servers (vs. delegation helpers):
+
+1. Create server in `mcp/server-name/`
+2. Add to `.mcp.json` or `plugin.json`:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server-name/index.js"]
+    }
+  }
+}
+```
+
+## Note
+
+Current integrations use direct Python API calls rather than MCP protocol.
+This works but doesn't leverage MCP's tool registration and permissions.
+
+Future improvement: Convert to proper MCP servers.