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.

state/README.md

@@ -0,0 +1,81 @@
+# State Files
+
+Shared state for the multi-agent system. JSON format for machine readability.
+
+## Top-Level State
+
+| File | Purpose | Writer |
+|------|---------|--------|
+| `system-instructions.json` | Central process definitions | master-orchestrator |
+| `future-considerations.json` | Deferred features/decisions | master-orchestrator |
+| `model-policy.json` | Model selection rules | master-orchestrator |
+| `autonomy-levels.json` | Autonomy level definitions | master-orchestrator |
+| `component-registry.json` | Skills, commands, agents for routing | master-orchestrator |
+| `personal-assistant-preferences.json` | PA persistent config | personal-assistant |
+| `kb.json` | Shared knowledge base | personal-assistant |
+
+## Subdirectories
+
+### `personal-assistant/`
+
+| File | Purpose |
+|------|---------|
+| `general-instructions.json` | User memory (via `/pa --remember`) |
+| `session-context.json` | Session context override |
+| `kb.json` | PA-specific knowledge base |
+| `history/index.json` | Session history index |
+| `memory/decisions.json` | Recorded decisions |
+| `memory/preferences.json` | Learned preferences |
+| `memory/projects.json` | Project context |
+| `memory/facts.json` | Environment facts |
+
+### `sysadmin/`
+
+| File | Purpose |
+|------|---------|
+| `session-autonomy.json` | Per-session autonomy override |
+
+### `programmer/`
+
+| File | Purpose |
+|------|---------|
+| `projects/*.json` | Registered project configurations |
+
+### `usage/`
+
+| File | Purpose |
+|------|---------|
+| `config.json` | Usage tracking configuration |
+
+## File Format
+
+All state files use JSON:
+
+```json
+{
+  "version": "1.0",
+  "description": "What this file contains",
+  "data": {}
+}
+```
+
+## Reading State
+
+Agents read state at session start:
+
+```bash
+cat ~/.claude/state/system-instructions.json
+```
+
+## Writing State
+
+- **master-orchestrator**: Primary writer for top-level state
+- **personal-assistant**: Override authority, writes to PA state
+- **linux-sysadmin**: Writes to `sysadmin/` state
+
+## Principles
+
+1. **No duplication** - Each fact in one place only
+2. **JSON format** - Machine readable
+3. **Clear ownership** - Each file has one primary writer
+4. **Override authority** - PA can override master-orchestrator