diff --git a/docs/hooks/ARCHITECTURE.md b/docs/hooks/ARCHITECTURE.md
new file mode 100644
index 000000000..b190befae
--- /dev/null
+++ b/docs/hooks/ARCHITECTURE.md
@@ -0,0 +1,744 @@
+# RuVector Hooks Architecture
+
+Technical architecture documentation for the RuVector hooks system.
+
+## Table of Contents
+
+1. [System Overview](#system-overview)
+2. [Component Architecture](#component-architecture)
+3. [Intelligence Layer](#intelligence-layer)
+4. [Hook Execution Flow](#hook-execution-flow)
+5. [Data Storage](#data-storage)
+6. [Integration Points](#integration-points)
+7. [Security Model](#security-model)
+8. [Performance Optimization](#performance-optimization)
+
+---
+
+## System Overview
+
+### High-Level Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                         Claude Code Runtime                           │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                        │
+│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐             │
+│  │  PreToolUse │────►│  Tool Exec  │────►│ PostToolUse │             │
+│  │    Hooks    │     │             │     │    Hooks    │             │
+│  └──────┬──────┘     └─────────────┘     └──────┬──────┘             │
+│         │                                        │                    │
+│         ▼                                        ▼                    │
+│  ┌────────────────────────────────────────────────────────────┐      │
+│  │                    Hook Dispatcher                          │      │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │      │
+│  │  │ Matcher  │  │ Executor │  │ Response │  │ Timeout  │   │      │
+│  │  │  Engine  │  │  Engine  │  │ Handler  │  │ Manager  │   │      │
+│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │      │
+│  └────────────────────────────────────────────────────────────┘      │
+│                              │                                        │
+│                              ▼                                        │
+│  ┌────────────────────────────────────────────────────────────┐      │
+│  │                  RuVector CLI Layer                         │      │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │      │
+│  │  │ Command  │  │ Template │  │   Path   │  │ Config   │   │      │
+│  │  │ Parser   │  │  Engine  │  │ Resolver │  │ Manager  │   │      │
+│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │      │
+│  └────────────────────────────────────────────────────────────┘      │
+│                              │                                        │
+│                              ▼                                        │
+│  ┌────────────────────────────────────────────────────────────┐      │
+│  │                   Intelligence Layer                        │      │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │      │
+│  │  │Q-Learning│  │  Vector  │  │  Agent   │  │  Neural  │   │      │
+│  │  │  Engine  │  │  Memory  │  │  Router  │  │ Trainer  │   │      │
+│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │      │
+│  └────────────────────────────────────────────────────────────┘      │
+│                              │                                        │
+│                              ▼                                        │
+│  ┌────────────────────────────────────────────────────────────┐      │
+│  │                    Storage Layer                            │      │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐                 │      │
+│  │  │   JSON   │  │  RvLite  │  │  Global  │                 │      │
+│  │  │  Files   │  │   HNSW   │  │ Patterns │                 │      │
+│  │  └──────────┘  └──────────┘  └──────────┘                 │      │
+│  └────────────────────────────────────────────────────────────┘      │
+│                                                                        │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Design Principles
+
+1. **Portability**: No hardcoded paths; runtime resolution
+2. **Minimal Overhead**: <100ms total hook overhead
+3. **Graceful Degradation**: Hooks never block main flow
+4. **Learning by Default**: Automatic pattern improvement
+5. **Cross-Platform**: Linux, macOS, Windows support
+
+---
+
+## Component Architecture
+
+### CLI Layer (`crates/ruvector-cli`)
+
+The command-line interface for hook management.
+
+```
+crates/ruvector-cli/
+├── src/
+│   ├── cli/
+│   │   ├── commands.rs        # Command definitions
+│   │   ├── hooks/             # Hooks subcommands
+│   │   │   ├── mod.rs         # Module exports
+│   │   │   ├── init.rs        # hooks init
+│   │   │   ├── install.rs     # hooks install
+│   │   │   ├── migrate.rs     # hooks migrate
+│   │   │   ├── stats.rs       # hooks stats
+│   │   │   ├── export.rs      # hooks export
+│   │   │   └── import.rs      # hooks import
+│   │   └── ...
+│   └── main.rs
+├── templates/                  # Hook templates
+│   ├── hooks.json.j2          # Portable hooks template
+│   ├── config.toml.j2         # Configuration template
+│   └── gitignore.j2           # Gitignore template
+└── Cargo.toml
+```
+
+### Template Engine
+
+Uses Askama for type-safe template rendering:
+
+```rust
+#[derive(Template)]
+#[template(path = "hooks.json.j2")]
+struct HookTemplate {
+    shell: String,          // Platform shell wrapper
+    ruvector_cli: String,   // CLI invocation method
+    project_root: String,   // Project root path
+}
+
+fn render_hooks() -> Result<String> {
+    let template = HookTemplate {
+        shell: get_shell_wrapper(),
+        ruvector_cli: get_cli_invocation(),
+        project_root: env::current_dir()?.display().to_string(),
+    };
+    Ok(template.render()?)
+}
+```
+
+### Path Resolution
+
+Dynamic path resolution at runtime:
+
+```rust
+pub fn get_ruvector_home() -> Result<PathBuf> {
+    // Priority order:
+    // 1. RUVECTOR_HOME environment variable
+    // 2. ~/.ruvector (Unix) or %APPDATA%\ruvector (Windows)
+
+    if let Ok(home) = env::var("RUVECTOR_HOME") {
+        return Ok(PathBuf::from(shellexpand::tilde(&home).to_string()));
+    }
+
+    let home_dir = dirs::home_dir()
+        .ok_or_else(|| anyhow!("Could not determine home directory"))?;
+
+    Ok(home_dir.join(".ruvector"))
+}
+
+pub fn get_cli_path() -> Result<String> {
+    // Priority order:
+    // 1. Binary in PATH
+    // 2. npx ruvector
+    // 3. Current executable
+
+    if let Ok(path) = which::which("ruvector") {
+        return Ok(path.display().to_string());
+    }
+
+    Ok("npx ruvector".to_string())
+}
+```
+
+---
+
+## Intelligence Layer
+
+### Q-Learning Engine
+
+Implements temporal difference learning for action selection:
+
+```javascript
+// Q-value update equation
+// Q(s,a) ← Q(s,a) + α[r + γ max_a' Q(s',a') - Q(s,a)]
+
+class QLearning {
+    constructor(options = {}) {
+        this.alpha = options.learningRate || 0.1;   // Learning rate
+        this.gamma = options.discount || 0.95;      // Discount factor
+        this.qTable = new Map();                    // State-action values
+    }
+
+    update(state, action, reward, nextState) {
+        const currentQ = this.getQ(state, action);
+        const maxNextQ = this.getMaxQ(nextState);
+        const newQ = currentQ + this.alpha * (reward + this.gamma * maxNextQ - currentQ);
+        this.setQ(state, action, newQ);
+    }
+
+    selectAction(state) {
+        // Epsilon-greedy exploration
+        if (Math.random() < this.epsilon) {
+            return this.randomAction(state);
+        }
+        return this.bestAction(state);
+    }
+}
+```
+
+### State Representation
+
+States encode file context and action type:
+
+```javascript
+function encodeState(context) {
+    const { file, crate, tool, previousSuccess } = context;
+
+    return {
+        fileType: getFileExtension(file),           // 'rs', 'ts', 'py'
+        crateName: crate || 'unknown',              // 'ruvector-core'
+        toolCategory: categorize(tool),             // 'edit', 'bash', 'search'
+        historyHash: hashRecent(previousSuccess),   // Recent success pattern
+    };
+}
+
+// State key for Q-table lookup
+function stateKey(state) {
+    return `${state.toolCategory}_${state.fileType}_in_${state.crateName}`;
+}
+```
+
+### Vector Memory
+
+Semantic search using HNSW indexing:
+
+```javascript
+class VectorMemory {
+    constructor(dimensions = 128) {
+        this.dimensions = dimensions;
+        this.index = new HnswIndex({ dimensions, maxElements: 50000 });
+        this.metadata = new Map();
+    }
+
+    async store(key, text, metadata) {
+        const embedding = await this.embed(text);
+        const id = this.index.add(embedding);
+        this.metadata.set(id, { key, ...metadata });
+        return id;
+    }
+
+    async search(query, k = 5) {
+        const embedding = await this.embed(query);
+        const results = this.index.search(embedding, k);
+        return results.map(r => ({
+            ...this.metadata.get(r.id),
+            distance: r.distance
+        }));
+    }
+
+    async embed(text) {
+        // Simple embedding: TF-IDF + dimensionality reduction
+        // Production: Use sentence-transformers or similar
+        return textToEmbedding(text, this.dimensions);
+    }
+}
+```
+
+### Agent Router
+
+Intelligent agent assignment based on context:
+
+```javascript
+class AgentRouter {
+    constructor(qLearning, vectorMemory) {
+        this.q = qLearning;
+        this.memory = vectorMemory;
+        this.agentTypes = loadAgentTypes();
+    }
+
+    async route(context) {
+        const state = encodeState(context);
+
+        // 1. Check Q-learning suggestion
+        const qSuggestion = this.q.selectAction(state);
+        const qConfidence = this.q.getQ(state, qSuggestion);
+
+        // 2. Check similar past edits
+        const similar = await this.memory.search(context.file, 3);
+        const historyAgent = this.majorityVote(similar);
+
+        // 3. Apply file type heuristics
+        const heuristicAgent = this.fileTypeHeuristic(context.file);
+
+        // 4. Combine signals
+        return this.combine({
+            q: { agent: qSuggestion, confidence: qConfidence },
+            history: { agent: historyAgent, confidence: similar.length / 3 },
+            heuristic: { agent: heuristicAgent, confidence: 0.5 }
+        });
+    }
+
+    fileTypeHeuristic(file) {
+        const ext = path.extname(file);
+        const mapping = {
+            '.rs': 'rust-developer',
+            '.ts': 'typescript-developer',
+            '.tsx': 'react-developer',
+            '.py': 'python-developer',
+            '.go': 'go-developer',
+            '.sql': 'database-specialist',
+        };
+        return mapping[ext] || 'coder';
+    }
+}
+```
+
+---
+
+## Hook Execution Flow
+
+### PreToolUse Flow
+
+```
+┌─────────────────┐
+│  Claude Code    │
+│  Tool Request   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Match Hooks    │  ──► No match ──► Execute Tool
+│  (Regex/Type)   │
+└────────┬────────┘
+         │ Match
+         ▼
+┌─────────────────┐
+│  Execute Hook   │  timeout: 3000ms
+│  Command        │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Parse Result   │
+│  (JSON/stdout)  │
+└────────┬────────┘
+         │
+         ▼
+    ┌────┴────┐
+    │continue?│
+    └────┬────┘
+    │    │
+   Yes   No
+    │    │
+    ▼    ▼
+Execute  Block
+ Tool    Tool
+```
+
+### PostToolUse Flow
+
+```
+┌─────────────────┐
+│  Tool Completed │
+│  (Result Ready) │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Match Hooks    │
+│  (Regex/Type)   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Execute Hook   │  (async, non-blocking)
+│  Command        │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Intelligence   │
+│  Update         │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Q-value Train  │
+│  Memory Store   │
+│  Pattern Update │
+└─────────────────┘
+```
+
+### Session Hook Flow
+
+```
+Session Start                           Session End
+     │                                       │
+     ▼                                       ▼
+┌──────────┐                          ┌──────────┐
+│  Load    │                          │  Persist │
+│  Config  │                          │  State   │
+└────┬─────┘                          └────┬─────┘
+     │                                     │
+     ▼                                     ▼
+┌──────────┐                          ┌──────────┐
+│ Restore  │                          │  Export  │
+│ Memory   │                          │ Metrics  │
+└────┬─────┘                          └────┬─────┘
+     │                                     │
+     ▼                                     ▼
+┌──────────┐                          ┌──────────┐
+│ Display  │                          │ Generate │
+│ Status   │                          │ Summary  │
+└──────────┘                          └──────────┘
+```
+
+---
+
+## Data Storage
+
+### Directory Structure
+
+```
+Project Root
+├── .ruvector/                    # Project-local data
+│   ├── config.toml               # Configuration
+│   ├── intelligence/
+│   │   ├── memory.json           # Vector memory (JSON fallback)
+│   │   ├── patterns.json         # Q-learning patterns
+│   │   ├── trajectories.json     # Learning history
+│   │   ├── feedback.json         # User feedback
+│   │   └── memory.rvdb           # RvLite vector database
+│   ├── logs/
+│   │   └── hooks-YYYY-MM-DD.log  # Daily logs
+│   └── .gitignore
+│
+└── .claude/
+    └── settings.json             # Hook configurations
+
+Global (~/.ruvector/)
+├── global/
+│   ├── patterns.json             # Cross-project patterns
+│   ├── memory.rvdb               # Global vector memory
+│   └── sequences.json            # Common file sequences
+├── config.toml                   # Global configuration
+└── cache/
+    └── cli-path.txt              # Cached CLI location
+```
+
+### Data Formats
+
+#### patterns.json (Q-Learning)
+
+```json
+{
+  "edit_rs_in_ruvector-core": {
+    "rust-developer": {
+      "q_value": 0.823,
+      "update_count": 47,
+      "last_update": "2025-12-27T10:30:00Z"
+    },
+    "coder": {
+      "q_value": 0.312,
+      "update_count": 5,
+      "last_update": "2025-12-20T14:22:00Z"
+    }
+  }
+}
+```
+
+#### trajectories.json (Learning History)
+
+```json
+[
+  {
+    "id": "traj_001",
+    "state": "edit_rs_in_ruvector-core",
+    "action": "rust-developer",
+    "outcome": "success",
+    "reward": 1.0,
+    "timestamp": "2025-12-27T10:30:00Z",
+    "ab_group": "treatment",
+    "metadata": {
+      "file": "crates/ruvector-core/src/lib.rs",
+      "duration_ms": 1500
+    }
+  }
+]
+```
+
+#### memory.rvdb (Vector Database)
+
+RvLite database with HNSW indexing:
+
+```sql
+-- Schema (auto-created)
+CREATE TABLE memories (
+    id TEXT PRIMARY KEY,
+    embedding VECTOR(128),
+    content TEXT,
+    metadata JSON,
+    created_at TIMESTAMP
+);
+
+CREATE INDEX memories_hnsw ON memories USING hnsw (embedding);
+```
+
+---
+
+## Integration Points
+
+### Claude Code Integration
+
+Hook configuration in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "pattern",    // Regex for tool name
+      "hooks": [{
+        "type": "command",     // Shell command
+        "command": "...",      // Command to execute
+        "timeout": 3000        // Timeout in ms
+      }]
+    }],
+    "PostToolUse": [...],
+    "SessionStart": [...],
+    "Stop": [...]              // Session end
+  }
+}
+```
+
+### Claude-Flow Integration
+
+MCP tool coordination:
+
+```javascript
+// Pre-task hook with MCP
+async function preTask(description) {
+    // Store in coordination memory
+    await mcp__claude_flow__memory_usage({
+        action: "store",
+        key: "swarm/task/current",
+        namespace: "coordination",
+        value: JSON.stringify({ description, started: Date.now() })
+    });
+
+    // Spawn recommended agents
+    const agents = analyzeTaskNeeds(description);
+    for (const agent of agents) {
+        await mcp__claude_flow__agent_spawn({ type: agent });
+    }
+}
+```
+
+### Git Integration
+
+Pre-commit hook example:
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Run RuVector pre-edit on staged files
+FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+for FILE in $FILES; do
+    RESULT=$(npx ruvector hooks pre-edit --file "$FILE" --validate-syntax)
+    CONTINUE=$(echo "$RESULT" | jq -r '.continue')
+
+    if [ "$CONTINUE" = "false" ]; then
+        echo "Pre-edit hook blocked: $FILE"
+        echo "$RESULT" | jq -r '.reason'
+        exit 1
+    fi
+done
+```
+
+---
+
+## Security Model
+
+### Command Injection Prevention
+
+All user inputs are escaped:
+
+```rust
+use shell_escape::escape;
+
+fn generate_hook_command(file_path: &str) -> String {
+    let escaped = escape(file_path.into());
+    format!(
+        r#"/bin/bash -c 'npx ruvector hooks pre-edit --file {}'"#,
+        escaped
+    )
+}
+
+// Prevents: "; rm -rf /" attacks
+// file_path = "test.ts; rm -rf /"
+// escaped = "'test.ts; rm -rf /'"  (treated as literal string)
+```
+
+### Timeout Protection
+
+Hooks cannot hang indefinitely:
+
+```javascript
+async function executeHookSafely(hook, timeout = 3000) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+        const result = await executeHook(hook, { signal: controller.signal });
+        clearTimeout(timeoutId);
+        return result;
+    } catch (error) {
+        if (error.name === 'AbortError') {
+            console.warn('Hook timeout, continuing...');
+            return { continue: true, reason: 'timeout' };
+        }
+        throw error;
+    }
+}
+```
+
+### Graceful Failure
+
+Hooks never block tool execution:
+
+```javascript
+async function runPreHook(tool, context) {
+    try {
+        const result = await executeHookSafely(hook);
+        return result.continue !== false;
+    } catch (error) {
+        console.warn(`Hook failed: ${error.message}`);
+        return true;  // Continue on error
+    }
+}
+```
+
+---
+
+## Performance Optimization
+
+### Caching Strategy
+
+```javascript
+class IntelligenceCache {
+    constructor(maxAge = 300000) {  // 5 minutes
+        this.cache = new Map();
+        this.maxAge = maxAge;
+    }
+
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) return null;
+        if (Date.now() - entry.timestamp > this.maxAge) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+
+    set(key, value) {
+        this.cache.set(key, { value, timestamp: Date.now() });
+    }
+}
+
+// Cache agent routing decisions
+const routingCache = new IntelligenceCache();
+
+async function getAgent(file) {
+    const cached = routingCache.get(file);
+    if (cached) return cached;
+
+    const agent = await computeAgent(file);
+    routingCache.set(file, agent);
+    return agent;
+}
+```
+
+### Async Operations
+
+Non-blocking post-hooks:
+
+```javascript
+// Fire-and-forget for training
+function postEditHook(file, success) {
+    // Synchronous: quick response
+    const response = { continue: true, formatted: true };
+
+    // Async: training (non-blocking)
+    setImmediate(() => {
+        trainPatterns(file, success).catch(console.warn);
+        updateMemory(file).catch(console.warn);
+        recordTrajectory(file, success).catch(console.warn);
+    });
+
+    return response;
+}
+```
+
+### Batch Operations
+
+Reduce I/O with batching:
+
+```javascript
+class BatchWriter {
+    constructor(flushInterval = 5000) {
+        this.queue = [];
+        this.interval = setInterval(() => this.flush(), flushInterval);
+    }
+
+    add(item) {
+        this.queue.push(item);
+    }
+
+    async flush() {
+        if (this.queue.length === 0) return;
+
+        const batch = this.queue.splice(0);
+        await fs.appendFile(
+            'trajectories.json',
+            batch.map(JSON.stringify).join('\n') + '\n'
+        );
+    }
+}
+
+const trajectoryWriter = new BatchWriter();
+```
+
+### Performance Targets
+
+| Operation | Target | Typical |
+|-----------|--------|---------|
+| Pre-edit hook | <50ms | 30ms |
+| Post-edit hook | <100ms | 60ms |
+| Session start | <200ms | 150ms |
+| Memory search | <10ms | 5ms |
+| Q-value lookup | <1ms | 0.1ms |
+| Total overhead | <100ms | 70ms |
+
+---
+
+## See Also
+
+- [User Guide](USER_GUIDE.md) - Getting started
+- [CLI Reference](CLI_REFERENCE.md) - Command documentation
+- [Migration Guide](MIGRATION.md) - Upgrade from other systems
+- [Implementation Plan](IMPLEMENTATION_PLAN.md) - Development roadmap
diff --git a/docs/hooks/CLI_REFERENCE.md b/docs/hooks/CLI_REFERENCE.md
new file mode 100644
index 000000000..baa9c57e4
--- /dev/null
+++ b/docs/hooks/CLI_REFERENCE.md
@@ -0,0 +1,689 @@
+# RuVector Hooks CLI Reference
+
+Complete command-line reference for the RuVector hooks system.
+
+## Synopsis
+
+```bash
+npx ruvector hooks <command> [options]
+```
+
+Or with global installation:
+
+```bash
+ruvector hooks <command> [options]
+```
+
+---
+
+## Commands Overview
+
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize hooks system in current project |
+| `install` | Install hooks into Claude Code settings |
+| `migrate` | Migrate learning data from other sources |
+| `stats` | Display learning statistics |
+| `export` | Export learned patterns |
+| `import` | Import patterns from file |
+| `enable` | Enable hooks system |
+| `disable` | Disable hooks system |
+| `pre-edit` | Execute pre-edit hook |
+| `post-edit` | Execute post-edit hook |
+| `pre-command` | Execute pre-command hook |
+| `post-command` | Execute post-command hook |
+| `session-start` | Start a new session |
+| `session-end` | End current session |
+| `session-restore` | Restore a previous session |
+| `validate-config` | Validate hook configuration |
+
+---
+
+## Core Commands
+
+### `hooks init`
+
+Initialize the hooks system in the current project.
+
+**Syntax:**
+```bash
+npx ruvector hooks init [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--path` | `PATH` | `./.ruvector` | Custom directory location |
+| `--global` | flag | false | Initialize global patterns directory |
+| `--template` | `NAME` | `default` | Template: `default`, `minimal`, `advanced` |
+| `--force` | flag | false | Overwrite existing configuration |
+
+**Examples:**
+
+```bash
+# Basic initialization
+npx ruvector hooks init
+
+# Custom directory
+npx ruvector hooks init --path .config/ruvector
+
+# Minimal configuration
+npx ruvector hooks init --template minimal
+
+# Force reinitialize
+npx ruvector hooks init --force
+```
+
+**Output:**
+```
+Initialized ruvector hooks in ./.ruvector
+Created: .ruvector/config.toml
+Created: .ruvector/intelligence/
+Next: Run `npx ruvector hooks install` to add hooks to Claude Code
+```
+
+---
+
+### `hooks install`
+
+Install hooks into `.claude/settings.json`.
+
+**Syntax:**
+```bash
+npx ruvector hooks install [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--force` | flag | false | Overwrite existing hooks |
+| `--dry-run` | flag | false | Show changes without applying |
+| `--template` | `PATH` | built-in | Use custom hook template |
+| `--merge` | flag | true | Merge with existing settings |
+
+**Examples:**
+
+```bash
+# Standard installation
+npx ruvector hooks install
+
+# Preview changes
+npx ruvector hooks install --dry-run
+
+# Force overwrite
+npx ruvector hooks install --force
+
+# Custom template
+npx ruvector hooks install --template ./my-hooks.json
+```
+
+**Output:**
+```
+Hooks installed to .claude/settings.json
+Backup created: .claude/settings.json.backup
+Intelligence layer ready
+```
+
+---
+
+### `hooks migrate`
+
+Migrate learning data from other sources.
+
+**Syntax:**
+```bash
+npx ruvector hooks migrate --from <PATH> [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--from` | `PATH` | required | Source data path |
+| `--format` | `FORMAT` | auto-detect | Source format: `json`, `sqlite`, `csv` |
+| `--merge` | flag | false | Merge with existing patterns |
+| `--validate` | flag | false | Validate migration integrity |
+| `--dry-run` | flag | false | Show what would be migrated |
+
+**Examples:**
+
+```bash
+# Migrate from existing intelligence
+npx ruvector hooks migrate --from .claude/intelligence
+
+# Migrate from claude-flow memory
+npx ruvector hooks migrate --from ~/.swarm/memory.db --format sqlite
+
+# Merge with validation
+npx ruvector hooks migrate --from ./patterns.json --merge --validate
+
+# Preview migration
+npx ruvector hooks migrate --from ./old-data --dry-run
+```
+
+**Output:**
+```
+Migrating from JSON files...
+Imported 1,247 trajectories
+Imported 89 Q-learning patterns
+Converted 543 memories to vectors
+Validation passed (100% integrity)
+Completed in 3.2s
+```
+
+---
+
+### `hooks stats`
+
+Display learning statistics and system health.
+
+**Syntax:**
+```bash
+npx ruvector hooks stats [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--verbose` | flag | false | Show detailed breakdown |
+| `--json` | flag | false | Output as JSON |
+| `--compare-global` | flag | false | Compare local vs global patterns |
+
+**Examples:**
+
+```bash
+# Basic stats
+npx ruvector hooks stats
+
+# Detailed view
+npx ruvector hooks stats --verbose
+
+# JSON output for scripting
+npx ruvector hooks stats --json
+
+# Compare with global
+npx ruvector hooks stats --compare-global
+```
+
+**Output (verbose):**
+```
+RuVector Intelligence Statistics
+================================
+
+Learning Data:
+   Trajectories: 1,247
+   Patterns: 89 (Q-learning states)
+   Memories: 543 vectors
+   Total size: 2.4 MB
+
+Top Patterns:
+   1. edit_rs_in_ruvector-core → successful-edit (Q=0.823)
+   2. cargo_test → command-succeeded (Q=0.791)
+   3. npm_build → command-succeeded (Q=0.654)
+
+Recent Activity:
+   Last trajectory: 2 hours ago
+   A/B test group: treatment
+   Calibration error: 0.042
+```
+
+---
+
+### `hooks export`
+
+Export learned patterns for sharing or backup.
+
+**Syntax:**
+```bash
+npx ruvector hooks export --output <PATH> [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--output` | `PATH` | required | Output file path |
+| `--format` | `FORMAT` | `json` | Format: `json`, `csv`, `sqlite` |
+| `--include` | `TYPES` | `all` | Include: `patterns`, `memories`, `all` |
+| `--compress` | flag | false | Compress with gzip |
+
+**Examples:**
+
+```bash
+# Export all data
+npx ruvector hooks export --output backup.json
+
+# Export patterns only
+npx ruvector hooks export --output patterns.json --include patterns
+
+# Compressed export
+npx ruvector hooks export --output backup.json.gz --compress
+
+# CSV format
+npx ruvector hooks export --output data.csv --format csv
+```
+
+**Output:**
+```
+Exported 89 patterns to team-patterns.json
+Size: 45.2 KB
+SHA256: 8f3b4c2a...
+```
+
+---
+
+### `hooks import`
+
+Import learned patterns from file.
+
+**Syntax:**
+```bash
+npx ruvector hooks import --input <PATH> [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--input` | `PATH` | required | Input file path |
+| `--merge` | flag | false | Merge with existing patterns |
+| `--strategy` | `STRATEGY` | `prefer-local` | Merge strategy: `prefer-local`, `prefer-imported`, `average` |
+| `--validate` | flag | false | Validate before importing |
+
+**Examples:**
+
+```bash
+# Import patterns (replace)
+npx ruvector hooks import --input patterns.json
+
+# Merge with existing
+npx ruvector hooks import --input team-patterns.json --merge
+
+# Merge with strategy
+npx ruvector hooks import --input patterns.json --merge --strategy average
+
+# Validate first
+npx ruvector hooks import --input data.json --validate
+```
+
+**Output:**
+```
+Importing patterns...
+Imported 89 patterns
+Merged with 67 existing patterns
+New total: 123 patterns (33 updated, 56 unchanged)
+```
+
+---
+
+### `hooks enable` / `hooks disable`
+
+Enable or disable the hooks system.
+
+**Syntax:**
+```bash
+npx ruvector hooks enable
+npx ruvector hooks disable
+```
+
+**Examples:**
+
+```bash
+# Disable temporarily
+npx ruvector hooks disable
+# Output: Hooks disabled (set RUVECTOR_INTELLIGENCE_ENABLED=false)
+
+# Re-enable
+npx ruvector hooks enable
+# Output: Hooks enabled (set RUVECTOR_INTELLIGENCE_ENABLED=true)
+```
+
+---
+
+## Hook Execution Commands
+
+### `hooks pre-edit`
+
+Execute pre-edit validation and agent assignment.
+
+**Syntax:**
+```bash
+npx ruvector hooks pre-edit --file <PATH> [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--file`, `-f` | `PATH` | required | File path to be edited |
+| `--auto-assign-agent` | flag | true | Assign best agent |
+| `--validate-syntax` | flag | false | Validate syntax |
+| `--check-conflicts` | flag | false | Check for conflicts |
+| `--backup-file` | flag | false | Create backup |
+
+**Examples:**
+
+```bash
+# Basic pre-edit
+npx ruvector hooks pre-edit --file src/auth/login.ts
+
+# With validation
+npx ruvector hooks pre-edit -f src/api.ts --validate-syntax
+
+# Safe edit with backup
+npx ruvector hooks pre-edit -f config.json --backup-file
+```
+
+**Output (JSON):**
+```json
+{
+  "continue": true,
+  "file": "src/auth/login.ts",
+  "assignedAgent": "typescript-developer",
+  "confidence": 0.85,
+  "syntaxValid": true,
+  "warnings": []
+}
+```
+
+---
+
+### `hooks post-edit`
+
+Execute post-edit processing.
+
+**Syntax:**
+```bash
+npx ruvector hooks post-edit --file <PATH> [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--file`, `-f` | `PATH` | required | File that was edited |
+| `--success` | `BOOL` | true | Whether edit succeeded |
+| `--auto-format` | flag | true | Format code |
+| `--memory-key`, `-m` | `KEY` | auto | Memory storage key |
+| `--train-patterns` | flag | false | Train neural patterns |
+| `--validate-output` | flag | false | Validate result |
+
+**Examples:**
+
+```bash
+# Basic post-edit
+npx ruvector hooks post-edit --file src/app.ts
+
+# With memory key
+npx ruvector hooks post-edit -f src/auth.ts -m "auth/login-impl"
+
+# Full processing
+npx ruvector hooks post-edit -f src/utils.ts --train-patterns --validate-output
+```
+
+**Output (JSON):**
+```json
+{
+  "file": "src/app.ts",
+  "formatted": true,
+  "formatterUsed": "prettier",
+  "memorySaved": "edits/src/app.ts",
+  "patternsTrained": 3,
+  "success": true
+}
+```
+
+---
+
+### `hooks pre-command`
+
+Execute pre-command safety check.
+
+**Syntax:**
+```bash
+npx ruvector hooks pre-command <COMMAND> [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--check-safety` | flag | true | Verify command safety |
+| `--estimate-resources` | flag | false | Estimate resource usage |
+| `--require-confirmation` | flag | false | Require confirmation |
+
+**Examples:**
+
+```bash
+# Basic check
+npx ruvector hooks pre-command "npm install"
+
+# With resource estimation
+npx ruvector hooks pre-command "docker build ." --estimate-resources
+
+# Dangerous command
+npx ruvector hooks pre-command "rm -rf /tmp/*" --require-confirmation
+```
+
+---
+
+### `hooks post-command`
+
+Execute post-command logging.
+
+**Syntax:**
+```bash
+npx ruvector hooks post-command <COMMAND> <SUCCESS> [STDERR]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `COMMAND` | string | Command that was executed |
+| `SUCCESS` | boolean | Whether command succeeded |
+| `STDERR` | string | Error output (optional) |
+
+**Examples:**
+
+```bash
+# Successful command
+npx ruvector hooks post-command "npm test" true
+
+# Failed command
+npx ruvector hooks post-command "cargo build" false "error[E0308]"
+```
+
+---
+
+## Session Commands
+
+### `hooks session-start`
+
+Initialize a new session.
+
+**Syntax:**
+```bash
+npx ruvector hooks session-start [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--session-id`, `-s` | `ID` | auto-generated | Session identifier |
+| `--load-context` | flag | false | Load previous context |
+| `--init-agents` | flag | false | Initialize agents |
+
+**Examples:**
+
+```bash
+# Auto-generated session
+npx ruvector hooks session-start
+
+# Named session
+npx ruvector hooks session-start --session-id "feature-auth"
+
+# With context loading
+npx ruvector hooks session-start -s "debug-123" --load-context
+```
+
+**Output:**
+```
+RuVector Intelligence Layer Active
+
+Session: feature-auth
+Patterns: 131 state-action pairs
+Memories: 4,247 vectors
+Status: Ready
+```
+
+---
+
+### `hooks session-end`
+
+End and persist session state.
+
+**Syntax:**
+```bash
+npx ruvector hooks session-end [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--session-id`, `-s` | `ID` | current | Session to end |
+| `--save-state` | flag | true | Save session state |
+| `--export-metrics` | flag | false | Export metrics |
+| `--generate-summary` | flag | false | Generate summary |
+| `--cleanup-temp` | flag | false | Remove temp files |
+
+**Examples:**
+
+```bash
+# Basic end
+npx ruvector hooks session-end
+
+# With metrics and summary
+npx ruvector hooks session-end --export-metrics --generate-summary
+
+# Full cleanup
+npx ruvector hooks session-end -s "debug-session" --cleanup-temp
+```
+
+**Output (JSON):**
+```json
+{
+  "sessionId": "feature-auth",
+  "duration": 7200000,
+  "saved": true,
+  "metrics": {
+    "commandsRun": 145,
+    "filesModified": 23,
+    "tokensUsed": 85000
+  },
+  "summaryPath": "./sessions/feature-auth-summary.md"
+}
+```
+
+---
+
+### `hooks session-restore`
+
+Restore a previous session.
+
+**Syntax:**
+```bash
+npx ruvector hooks session-restore --session-id <ID> [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--session-id`, `-s` | `ID` | required | Session to restore |
+| `--restore-memory` | flag | true | Restore memory state |
+| `--restore-agents` | flag | false | Restore agent configs |
+
+**Examples:**
+
+```bash
+# Restore session
+npx ruvector hooks session-restore --session-id "feature-auth"
+
+# Full restore
+npx ruvector hooks session-restore -s "debug-123" --restore-agents
+```
+
+---
+
+## Utility Commands
+
+### `hooks validate-config`
+
+Validate hook configuration.
+
+**Syntax:**
+```bash
+npx ruvector hooks validate-config [OPTIONS]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--file` | `PATH` | `.claude/settings.json` | Config file to validate |
+| `--fix` | flag | false | Auto-fix issues |
+
+**Examples:**
+
+```bash
+# Validate default config
+npx ruvector hooks validate-config
+
+# Validate custom file
+npx ruvector hooks validate-config --file .claude/settings.json
+
+# Auto-fix issues
+npx ruvector hooks validate-config --fix
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Configuration error |
+| 3 | Migration error |
+| 4 | Validation failed |
+| 5 | Timeout |
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RUVECTOR_HOME` | `~/.ruvector` | Global patterns directory |
+| `RUVECTOR_DATA_DIR` | `./.ruvector` | Project-local data directory |
+| `RUVECTOR_CLI_PATH` | auto-detected | Path to CLI binary |
+| `RUVECTOR_INTELLIGENCE_ENABLED` | `true` | Enable/disable intelligence |
+| `RUVECTOR_LEARNING_RATE` | `0.1` | Q-learning alpha parameter |
+| `INTELLIGENCE_MODE` | `treatment` | A/B test group |
+| `CLAUDE_FLOW_DEBUG` | `false` | Enable debug output |
+
+---
+
+## See Also
+
+- [User Guide](USER_GUIDE.md) - Getting started guide
+- [Architecture](ARCHITECTURE.md) - Technical details
+- [Migration Guide](MIGRATION.md) - Upgrade from other systems
+- [Troubleshooting](TROUBLESHOOTING.md) - Common issues
diff --git a/docs/hooks/IMPLEMENTATION_PLAN.md b/docs/hooks/IMPLEMENTATION_PLAN.md
index cb8df1370..6fc7b0845 100644
--- a/docs/hooks/IMPLEMENTATION_PLAN.md
+++ b/docs/hooks/IMPLEMENTATION_PLAN.md
@@ -1,5 +1,7 @@
 # RuVector Generic Hooks System - Implementation Plan
 
+> **Related Documentation**: [README](README.md) | [User Guide](USER_GUIDE.md) | [CLI Reference](CLI_REFERENCE.md) | [Architecture](ARCHITECTURE.md)
+
 ## Executive Summary
 
 This document outlines a comprehensive SPARC-GOAP (Specification, Pseudocode, Architecture, Refinement, Completion + Goal-Oriented Action Planning) implementation plan for transforming the current repo-specific hooks system into a **generic, portable, CLI-integrated hooks system** for the ruvector project.
diff --git a/docs/hooks/MIGRATION.md b/docs/hooks/MIGRATION.md
new file mode 100644
index 000000000..111935851
--- /dev/null
+++ b/docs/hooks/MIGRATION.md
@@ -0,0 +1,581 @@
+# RuVector Hooks Migration Guide
+
+Guide for migrating to RuVector's portable hooks system from legacy setups or other tools.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Migration Paths](#migration-paths)
+3. [From Legacy Intelligence](#from-legacy-intelligence)
+4. [From Claude-Flow](#from-claude-flow)
+5. [From Manual Setup](#from-manual-setup)
+6. [Data Preservation](#data-preservation)
+7. [Verification](#verification)
+8. [Rollback](#rollback)
+
+---
+
+## Overview
+
+### Why Migrate?
+
+The new RuVector hooks system provides:
+
+| Feature | Legacy | New System |
+|---------|--------|------------|
+| Portability | Hardcoded paths | Dynamic resolution |
+| CLI Management | Manual JSON editing | Full CLI support |
+| Cross-platform | Linux/macOS only | Linux, macOS, Windows |
+| Global Patterns | Not available | Supported |
+| Binary Updates | Hooks break | Survive reinstalls |
+
+### Migration Safety
+
+All migrations include:
+- **Automatic backup** of existing data
+- **Validation** of migrated data
+- **Atomic operations** with rollback capability
+- **Zero data loss** guarantee
+
+---
+
+## Migration Paths
+
+### Quick Reference
+
+| Source | Command | Time |
+|--------|---------|------|
+| Legacy `.claude/intelligence/` | `hooks migrate --from .claude/intelligence` | <5s |
+| Claude-flow `memory.db` | `hooks migrate --from ~/.swarm/memory.db` | <10s |
+| Exported JSON | `hooks import --input patterns.json` | <2s |
+| Fresh start | `hooks init` | <1s |
+
+### Prerequisites
+
+Before migrating:
+
+```bash
+# 1. Backup existing data
+cp -r .claude/intelligence .claude/intelligence.backup
+cp -r ~/.swarm ~/.swarm.backup
+
+# 2. Install latest RuVector CLI
+npm install -g @ruvector/cli@latest
+
+# 3. Verify installation
+npx ruvector --version
+```
+
+---
+
+## From Legacy Intelligence
+
+Migrate from the repository-specific `.claude/intelligence/` system.
+
+### Current Legacy Structure
+
+```
+.claude/
+├── intelligence/
+│   ├── data/
+│   │   ├── memory.json       # Vector memories
+│   │   ├── trajectories.json # Learning history
+│   │   ├── patterns.json     # Q-learning patterns
+│   │   └── feedback.json     # User feedback
+│   ├── index.js              # Intelligence layer
+│   └── cli.js                # CLI commands
+└── settings.json             # Hardcoded hooks
+```
+
+### Migration Steps
+
+#### Step 1: Initialize New System
+
+```bash
+npx ruvector hooks init
+```
+
+This creates:
+```
+.ruvector/
+├── config.toml
+├── intelligence/
+│   └── (empty, ready for migration)
+└── .gitignore
+```
+
+#### Step 2: Migrate Data
+
+```bash
+# Migrate with validation
+npx ruvector hooks migrate \
+  --from .claude/intelligence \
+  --validate
+
+# Expected output:
+# Migrating from JSON files...
+# ✓ Imported 1,247 trajectories
+# ✓ Imported 89 Q-learning patterns
+# ✓ Converted 543 memories to vectors
+# ✓ Validation passed (100% integrity)
+# ⏱ Completed in 3.2s
+```
+
+#### Step 3: Install New Hooks
+
+```bash
+# Install portable hooks
+npx ruvector hooks install --force
+
+# This replaces hardcoded paths with dynamic resolution
+```
+
+#### Step 4: Verify Migration
+
+```bash
+# Check statistics
+npx ruvector hooks stats --verbose
+
+# Should show migrated data:
+# Patterns: 89
+# Memories: 543
+# Trajectories: 1,247
+```
+
+#### Step 5: Clean Up (Optional)
+
+After confirming migration success:
+
+```bash
+# Remove legacy intelligence directory
+rm -rf .claude/intelligence
+
+# Keep backup for safety
+# rm -rf .claude/intelligence.backup  # Only if confident
+```
+
+### Legacy Settings.json Update
+
+**Before (hardcoded):**
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "command": "/bin/bash -c 'cd /workspaces/ruvector/.claude/intelligence && node cli.js pre-command'"
+      }]
+    }]
+  }
+}
+```
+
+**After (portable):**
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "command": "/bin/bash -c 'RUVECTOR=$(which ruvector || echo npx ruvector); $RUVECTOR hooks pre-command \"$CMD\"'"
+      }]
+    }]
+  }
+}
+```
+
+---
+
+## From Claude-Flow
+
+Migrate from Claude-Flow's SQLite memory database.
+
+### Claude-Flow Structure
+
+```
+~/.swarm/
+├── memory.db          # SQLite database
+├── config.json        # Configuration
+└── sessions/          # Session data
+```
+
+### Migration Steps
+
+#### Step 1: Locate Memory Database
+
+```bash
+# Default location
+ls ~/.swarm/memory.db
+
+# Custom location (check config)
+cat ~/.swarm/config.json | jq '.memoryPath'
+```
+
+#### Step 2: Initialize RuVector
+
+```bash
+cd your-project
+npx ruvector hooks init
+```
+
+#### Step 3: Migrate SQLite Data
+
+```bash
+# Migrate from SQLite
+npx ruvector hooks migrate \
+  --from ~/.swarm/memory.db \
+  --format sqlite \
+  --validate
+
+# Output:
+# Migrating from SQLite database...
+# ✓ Extracted 2,500 trajectories
+# ✓ Converted 150 Q-learning patterns
+# ✓ Migrated 1,200 memories to vectors
+# ✓ Validation passed
+```
+
+**Note:** SQLite migration requires the `sqlite-migration` feature (v1.1+). For MVP, use JSON export:
+
+```bash
+# Alternative: Export from claude-flow first
+npx claude-flow memory export --output memory-export.json
+
+# Then import
+npx ruvector hooks import --input memory-export.json
+```
+
+#### Step 4: Merge with Existing Data
+
+If you have both legacy and claude-flow data:
+
+```bash
+# Merge with existing patterns
+npx ruvector hooks migrate \
+  --from ~/.swarm/memory.db \
+  --merge \
+  --strategy average
+```
+
+#### Step 5: Install Hooks
+
+```bash
+npx ruvector hooks install
+```
+
+---
+
+## From Manual Setup
+
+Migrate from manually configured hooks.
+
+### Current Manual Setup
+
+**`.claude/settings.json` (manual):**
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Write|Edit",
+      "hooks": [{
+        "type": "command",
+        "command": "echo 'Pre-edit hook'"
+      }]
+    }]
+  }
+}
+```
+
+### Migration Steps
+
+#### Step 1: Backup Existing Settings
+
+```bash
+cp .claude/settings.json .claude/settings.json.manual-backup
+```
+
+#### Step 2: Initialize RuVector
+
+```bash
+npx ruvector hooks init
+```
+
+#### Step 3: Install with Merge
+
+```bash
+# Merge RuVector hooks with existing
+npx ruvector hooks install --merge
+
+# This preserves your custom hooks and adds RuVector hooks
+```
+
+#### Step 4: Review Merged Settings
+
+```bash
+# View the merged settings
+cat .claude/settings.json
+
+# Verify your custom hooks are preserved
+```
+
+### Preserving Custom Hooks
+
+If you have custom hooks to preserve:
+
+**Before install:**
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "CustomTool",
+      "hooks": [{
+        "command": "my-custom-hook.sh"
+      }]
+    }]
+  }
+}
+```
+
+**After install (merged):**
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{
+          "command": "npx ruvector hooks pre-command"
+        }]
+      },
+      {
+        "matcher": "CustomTool",
+        "hooks": [{
+          "command": "my-custom-hook.sh"
+        }]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Data Preservation
+
+### What Gets Migrated
+
+| Data Type | Source | Destination |
+|-----------|--------|-------------|
+| Q-learning patterns | `patterns.json` | `.ruvector/intelligence/patterns.json` |
+| Trajectories | `trajectories.json` | `.ruvector/intelligence/trajectories.json` |
+| Vector memories | `memory.json` | `.ruvector/intelligence/memory.rvdb` |
+| Feedback data | `feedback.json` | `.ruvector/intelligence/feedback.json` |
+| Configuration | settings.json | `.ruvector/config.toml` |
+
+### Data Integrity Checks
+
+The migration process includes:
+
+1. **Checksum validation**: Verify data wasn't corrupted
+2. **Count verification**: Ensure all records migrated
+3. **Q-value preservation**: Maintain learned values
+4. **Vector accuracy**: Preserve embedding precision
+
+### Backup Locations
+
+Automatic backups are created:
+
+```
+.ruvector/
+├── intelligence/
+│   └── backup-YYYYMMDD-HHMMSS/
+│       ├── patterns.json
+│       ├── trajectories.json
+│       └── memory.json
+```
+
+---
+
+## Verification
+
+### Verify Migration Success
+
+```bash
+# 1. Check statistics
+npx ruvector hooks stats --verbose
+
+# 2. Compare counts
+echo "Legacy patterns: $(jq '.patterns | length' .claude/intelligence.backup/data/patterns.json 2>/dev/null || echo 0)"
+echo "Migrated patterns: $(npx ruvector hooks stats --json | jq '.patterns')"
+
+# 3. Test hook execution
+npx ruvector hooks pre-edit --file test.ts
+npx ruvector hooks post-edit --file test.ts --success true
+
+# 4. Verify session hooks
+npx ruvector hooks session-start --session-id "migration-test"
+npx ruvector hooks session-end --session-id "migration-test"
+```
+
+### Expected Verification Output
+
+```bash
+$ npx ruvector hooks stats --verbose
+
+RuVector Intelligence Statistics
+================================
+
+Data Migration Status: SUCCESS
+
+Learning Data:
+   Trajectories: 1,247 (migrated: 1,247)
+   Patterns: 89 (migrated: 89)
+   Memories: 543 vectors (migrated: 543)
+   Integrity: 100%
+
+Configuration:
+   Hooks installed: Yes
+   Portable paths: Yes
+   Intelligence enabled: Yes
+```
+
+### Test in Claude Code
+
+1. Open Claude Code in your project
+2. Verify session start message appears
+3. Make an edit to a file
+4. Confirm agent assignment message
+5. Check post-edit formatting
+
+---
+
+## Rollback
+
+### Automatic Rollback
+
+If migration fails, automatic rollback occurs:
+
+```bash
+$ npx ruvector hooks migrate --from .claude/intelligence
+
+Migrating from JSON files...
+✓ Imported 1,247 trajectories
+✗ Error during pattern migration: Invalid Q-value format
+⟲ Rolling back migration...
+✓ Restored from backup
+Migration failed, original data preserved
+```
+
+### Manual Rollback
+
+To manually rollback:
+
+#### Step 1: Restore Backup
+
+```bash
+# Restore intelligence data
+rm -rf .ruvector/intelligence
+cp -r .ruvector/intelligence/backup-YYYYMMDD-HHMMSS/* .ruvector/intelligence/
+
+# Or restore legacy location
+rm -rf .ruvector
+mv .claude/intelligence.backup .claude/intelligence
+```
+
+#### Step 2: Restore Settings
+
+```bash
+# Restore Claude settings
+cp .claude/settings.json.backup .claude/settings.json
+```
+
+#### Step 3: Verify Restoration
+
+```bash
+# For legacy
+node .claude/intelligence/cli.js stats
+
+# For new system
+npx ruvector hooks stats
+```
+
+### Complete Reset
+
+To completely reset and start fresh:
+
+```bash
+# Remove all RuVector data
+rm -rf .ruvector
+
+# Remove from Claude settings
+# Edit .claude/settings.json to remove hooks section
+
+# Reinitialize
+npx ruvector hooks init
+npx ruvector hooks install
+```
+
+---
+
+## Migration FAQ
+
+### Q: Will I lose my learned patterns?
+
+**A:** No. All migrations include automatic backup and validation. Q-values, trajectories, and memories are preserved with 100% integrity.
+
+### Q: Can I migrate incrementally?
+
+**A:** Yes. Use the `--merge` flag to add new data without replacing existing:
+
+```bash
+npx ruvector hooks migrate --from new-data.json --merge
+```
+
+### Q: What about Windows compatibility?
+
+**A:** The new system uses conditional shell detection:
+
+```bash
+# Windows
+cmd /c 'npx ruvector hooks ...'
+
+# Linux/macOS
+/bin/bash -c 'npx ruvector hooks ...'
+```
+
+### Q: How do I migrate a team project?
+
+**A:** Export and share patterns:
+
+```bash
+# Team member 1: Export
+npx ruvector hooks export --output team-patterns.json
+
+# Team member 2: Import and merge
+npx ruvector hooks import --input team-patterns.json --merge
+```
+
+### Q: Is the migration reversible?
+
+**A:** Yes. Backups are automatically created and manual rollback is always possible.
+
+---
+
+## Post-Migration Checklist
+
+- [ ] `npx ruvector hooks stats` shows expected counts
+- [ ] Session hooks trigger on Claude Code start
+- [ ] Pre-edit hooks assign agents correctly
+- [ ] Post-edit hooks format code
+- [ ] No hardcoded paths in `.claude/settings.json`
+- [ ] Backup data stored safely
+- [ ] Team notified of migration (if applicable)
+
+---
+
+## See Also
+
+- [User Guide](USER_GUIDE.md) - Getting started
+- [CLI Reference](CLI_REFERENCE.md) - Command documentation
+- [Architecture](ARCHITECTURE.md) - Technical details
+- [Troubleshooting](TROUBLESHOOTING.md) - Common issues
diff --git a/docs/hooks/MVP_CHECKLIST.md b/docs/hooks/MVP_CHECKLIST.md
index 4f2c43ce1..9cde3aa43 100644
--- a/docs/hooks/MVP_CHECKLIST.md
+++ b/docs/hooks/MVP_CHECKLIST.md
@@ -1,5 +1,7 @@
 # Hooks System MVP - Implementation Checklist
 
+> **Related Documentation**: [README](README.md) | [Implementation Plan](IMPLEMENTATION_PLAN.md) | [Architecture](ARCHITECTURE.md)
+
 **Target**: 3-4 weeks | **Status**: Ready for Development
 **Feature Branch**: `feature/portable-hooks-mvp`
 
diff --git a/docs/hooks/README.md b/docs/hooks/README.md
new file mode 100644
index 000000000..4d504042f
--- /dev/null
+++ b/docs/hooks/README.md
@@ -0,0 +1,241 @@
+# RuVector Hooks System Documentation
+
+Intelligent hooks for Claude Code that provide automatic agent assignment, code formatting, neural pattern training, and cross-session memory persistence.
+
+## Quick Navigation
+
+| Document | Description |
+|----------|-------------|
+| [User Guide](USER_GUIDE.md) | Getting started, setup, and basic usage |
+| [CLI Reference](CLI_REFERENCE.md) | Complete CLI command documentation |
+| [Architecture](ARCHITECTURE.md) | Technical design and system internals |
+| [Migration Guide](MIGRATION.md) | Upgrading from claude-flow or legacy systems |
+| [Troubleshooting](TROUBLESHOOTING.md) | Common issues and solutions |
+
+## Developer Documents
+
+| Document | Description |
+|----------|-------------|
+| [Implementation Plan](IMPLEMENTATION_PLAN.md) | SPARC-GOAP implementation roadmap |
+| [MVP Checklist](MVP_CHECKLIST.md) | Development checklist for MVP release |
+| [Review Report](REVIEW_REPORT.md) | Detailed code review and recommendations |
+| [Review Summary](REVIEW_SUMMARY.md) | Executive summary of review findings |
+
+---
+
+## What Are Hooks?
+
+Hooks are automated actions that execute before or after Claude Code tool operations. They enable:
+
+- **Intelligent Agent Assignment**: Automatically assign the best agent for each file type
+- **Code Quality**: Format, lint, and validate code automatically
+- **Memory Persistence**: Store decisions and context across sessions
+- **Neural Learning**: Continuously improve from successful patterns
+- **Swarm Coordination**: Synchronize knowledge across multi-agent workflows
+
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Claude Code Session                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐  │
+│  │ PreTool  │───►│  Tool    │───►│ PostTool │───►│  Result  │  │
+│  │   Hook   │    │ Execute  │    │   Hook   │    │          │  │
+│  └──────────┘    └──────────┘    └──────────┘    └──────────┘  │
+│       │                                │                         │
+│       ▼                                ▼                         │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │              Intelligence Layer                          │   │
+│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │   │
+│  │  │Q-Learn  │  │ Vector  │  │ Pattern │  │  Agent  │    │   │
+│  │  │ Table   │  │ Memory  │  │ Training│  │ Router  │    │   │
+│  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Quick Start
+
+### 1. Initialize Hooks
+
+```bash
+# Using npx (recommended)
+npx ruvector hooks init
+
+# Or using claude-flow
+npx claude-flow init --hooks
+```
+
+### 2. Install into Claude Code
+
+```bash
+npx ruvector hooks install
+```
+
+### 3. Verify Setup
+
+```bash
+npx ruvector hooks stats
+```
+
+## Hook Types
+
+### Pre-Operation Hooks
+
+Execute **before** Claude Code operations:
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `pre-edit` | Write, Edit, MultiEdit | Agent assignment, syntax validation |
+| `pre-bash` | Bash commands | Safety checks, resource estimation |
+| `pre-task` | Task spawning | Auto-spawn agents, load memory |
+| `pre-search` | Grep, Glob | Cache checking, query optimization |
+
+### Post-Operation Hooks
+
+Execute **after** Claude Code operations:
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `post-edit` | Write, Edit, MultiEdit | Formatting, memory storage, training |
+| `post-bash` | Bash commands | Logging, metrics, error detection |
+| `post-task` | Task completion | Performance analysis, learning export |
+| `post-search` | Grep, Glob | Caching, pattern improvement |
+
+### Session Hooks
+
+Manage session lifecycle:
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `session-start` | Session begins | Context loading, initialization |
+| `session-restore` | Manual restore | Restore previous session state |
+| `session-end` | Session ends | Persist state, export metrics |
+
+## Configuration
+
+Hooks are configured in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{
+          "type": "command",
+          "timeout": 3000,
+          "command": "npx ruvector hooks pre-command \"$CMD\""
+        }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [{
+          "type": "command",
+          "command": "npx ruvector hooks post-edit \"$FILE\""
+        }]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "npx ruvector hooks session-start"
+        }]
+      }
+    ]
+  }
+}
+```
+
+## Intelligence Layer
+
+The hooks system includes a self-learning intelligence layer:
+
+### Q-Learning Patterns
+
+Learns optimal actions from experience:
+
+- State-action pair tracking
+- Reward-based learning
+- Decay over time for relevance
+
+### Vector Memory
+
+Semantic search over past decisions:
+
+- 128-dimensional embeddings
+- HNSW indexing for fast retrieval
+- Persistent storage with rvlite
+
+### Agent Routing
+
+Intelligent agent assignment:
+
+- File type → agent type mapping
+- Confidence scoring
+- Fallback strategies
+
+## Directory Structure
+
+After initialization:
+
+```
+.ruvector/
+├── config.toml              # Project configuration
+├── intelligence/
+│   ├── memory.json          # Vector memory entries
+│   ├── patterns.json        # Q-learning patterns
+│   ├── trajectories.json    # Learning trajectories
+│   ├── feedback.json        # User feedback tracking
+│   └── memory.rvdb          # RvLite vector database
+└── .gitignore
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RUVECTOR_HOME` | `~/.ruvector` | Global patterns directory |
+| `RUVECTOR_DATA_DIR` | `./.ruvector` | Project-local data |
+| `RUVECTOR_INTELLIGENCE_ENABLED` | `true` | Enable/disable intelligence |
+| `INTELLIGENCE_MODE` | `treatment` | A/B test group |
+
+## Performance
+
+The hooks system is designed for minimal overhead:
+
+- **Hook execution**: <50ms typical
+- **Memory lookup**: <10ms with HNSW
+- **Pattern training**: Async, non-blocking
+- **Total overhead**: <100ms per operation
+
+## Integration
+
+Hooks integrate with:
+
+- **Claude Code**: Native tool hooks
+- **Claude Flow**: MCP swarm coordination
+- **Git**: Pre-commit and post-commit hooks
+- **RvLite**: Vector database storage
+- **Neural Training**: Pattern improvement
+
+## Next Steps
+
+1. Read the [User Guide](USER_GUIDE.md) for detailed setup
+2. Explore the [CLI Reference](CLI_REFERENCE.md) for all commands
+3. Check [Architecture](ARCHITECTURE.md) for internals
+4. See [Migration Guide](MIGRATION.md) if upgrading
+
+---
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/ruvnet/ruvector/issues)
+- **Documentation**: This directory
+- **Examples**: `.claude/commands/hooks/`
diff --git a/docs/hooks/REVIEW_REPORT.md b/docs/hooks/REVIEW_REPORT.md
index 088e62823..5f47813ad 100644
--- a/docs/hooks/REVIEW_REPORT.md
+++ b/docs/hooks/REVIEW_REPORT.md
@@ -1,5 +1,7 @@
 # Implementation Plan Code Review Report
 
+> **Related Documentation**: [README](README.md) | [Implementation Plan](IMPLEMENTATION_PLAN.md) | [MVP Checklist](MVP_CHECKLIST.md)
+
 **Document**: `/home/user/ruvector/docs/hooks/IMPLEMENTATION_PLAN.md`
 **Reviewer**: Code Review Agent
 **Date**: 2025-12-25
diff --git a/docs/hooks/REVIEW_SUMMARY.md b/docs/hooks/REVIEW_SUMMARY.md
index da6d2f4c9..be58a57be 100644
--- a/docs/hooks/REVIEW_SUMMARY.md
+++ b/docs/hooks/REVIEW_SUMMARY.md
@@ -1,5 +1,7 @@
 # Hooks Implementation Plan - Code Review Summary
 
+> **Related Documentation**: [README](README.md) | [Full Review](REVIEW_REPORT.md) | [Implementation Plan](IMPLEMENTATION_PLAN.md)
+
 **Status**: ✅ APPROVED WITH CRITICAL FIXES
 **Timeline**: Optimized from 6-8 weeks → **3-4 weeks for MVP**
 **Risk Level**: Low-Medium (major risks mitigated)
diff --git a/docs/hooks/TROUBLESHOOTING.md b/docs/hooks/TROUBLESHOOTING.md
new file mode 100644
index 000000000..3df9e63cc
--- /dev/null
+++ b/docs/hooks/TROUBLESHOOTING.md
@@ -0,0 +1,733 @@
+# RuVector Hooks Troubleshooting Guide
+
+Solutions for common issues with the RuVector hooks system.
+
+## Table of Contents
+
+1. [Quick Diagnostics](#quick-diagnostics)
+2. [Installation Issues](#installation-issues)
+3. [Hook Execution Issues](#hook-execution-issues)
+4. [Intelligence Layer Issues](#intelligence-layer-issues)
+5. [Performance Issues](#performance-issues)
+6. [Platform-Specific Issues](#platform-specific-issues)
+7. [Migration Issues](#migration-issues)
+8. [Debug Mode](#debug-mode)
+
+---
+
+## Quick Diagnostics
+
+### Run Full Diagnostic
+
+```bash
+# Check overall health
+npx ruvector hooks stats --verbose
+
+# Validate configuration
+npx ruvector hooks validate-config
+
+# Test hook execution
+npx ruvector hooks pre-edit --file test.ts
+npx ruvector hooks post-edit --file test.ts --success true
+```
+
+### Common Symptoms and Solutions
+
+| Symptom | Likely Cause | Solution |
+|---------|--------------|----------|
+| Hooks not running | Missing settings.json | Run `hooks install` |
+| "Command not found" | CLI not in PATH | Use `npx ruvector` |
+| No agent assignment | Intelligence disabled | Set `RUVECTOR_INTELLIGENCE_ENABLED=true` |
+| Slow hook execution | Large memory | Clean old trajectories |
+| Windows errors | Shell mismatch | Check shell wrapper |
+
+---
+
+## Installation Issues
+
+### Problem: `hooks init` fails
+
+**Symptoms:**
+```
+Error: Failed to create .ruvector directory
+Permission denied
+```
+
+**Solutions:**
+
+1. Check directory permissions:
+```bash
+ls -la .
+# Ensure you have write access
+```
+
+2. Create directory manually:
+```bash
+mkdir -p .ruvector/intelligence
+npx ruvector hooks init
+```
+
+3. Use sudo (last resort):
+```bash
+sudo npx ruvector hooks init
+sudo chown -R $USER:$USER .ruvector
+```
+
+---
+
+### Problem: `hooks install` doesn't update settings
+
+**Symptoms:**
+- `.claude/settings.json` unchanged
+- Old hooks still running
+
+**Solutions:**
+
+1. Use `--force` flag:
+```bash
+npx ruvector hooks install --force
+```
+
+2. Check backup and restore:
+```bash
+# View backup
+cat .claude/settings.json.backup
+
+# If needed, restore and try again
+cp .claude/settings.json.backup .claude/settings.json
+npx ruvector hooks install --force
+```
+
+3. Manually edit settings:
+```bash
+# Open and verify hook section
+code .claude/settings.json
+```
+
+---
+
+### Problem: "npx ruvector" command not found
+
+**Symptoms:**
+```
+npm ERR! could not determine executable to run
+```
+
+**Solutions:**
+
+1. Install globally:
+```bash
+npm install -g @ruvector/cli
+ruvector hooks init
+```
+
+2. Check npm configuration:
+```bash
+npm config get prefix
+# Ensure this is in your PATH
+```
+
+3. Use npx with package:
+```bash
+npx @ruvector/cli hooks init
+```
+
+---
+
+## Hook Execution Issues
+
+### Problem: Hooks not triggering
+
+**Symptoms:**
+- No output when editing files
+- Session start message missing
+- Intelligence not active
+
+**Diagnosis:**
+
+```bash
+# Check settings.json has hooks
+cat .claude/settings.json | jq '.hooks'
+
+# Should show PreToolUse, PostToolUse, etc.
+```
+
+**Solutions:**
+
+1. Reinstall hooks:
+```bash
+npx ruvector hooks install --force
+```
+
+2. Check matcher patterns:
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",  // Case-sensitive!
+      "hooks": [...]
+    }]
+  }
+}
+```
+
+3. Verify Claude Code is loading settings:
+```bash
+# Restart Claude Code to reload settings
+```
+
+---
+
+### Problem: Hook timeout
+
+**Symptoms:**
+```
+Warning: Hook timeout after 3000ms
+```
+
+**Solutions:**
+
+1. Increase timeout in settings:
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "timeout": 5000,  // Increase to 5 seconds
+        "command": "..."
+      }]
+    }]
+  }
+}
+```
+
+2. Check for slow operations:
+```bash
+# Time hook execution
+time npx ruvector hooks pre-edit --file test.ts
+```
+
+3. Reduce hook complexity:
+- Disable neural training in pre-hooks
+- Use async for heavy operations
+- Cache repeated lookups
+
+---
+
+### Problem: Hook blocks tool execution
+
+**Symptoms:**
+- Edit operations not completing
+- "continue: false" in output
+
+**Diagnosis:**
+
+```bash
+# Test hook directly
+npx ruvector hooks pre-edit --file problematic-file.ts
+
+# Check response
+# { "continue": false, "reason": "..." }
+```
+
+**Solutions:**
+
+1. Check protected files:
+```bash
+# If file is protected, you'll see:
+# { "continue": false, "reason": "Protected file" }
+
+# Add to exceptions in config.toml
+[hooks]
+protected_exceptions = [".env.local"]
+```
+
+2. Disable blocking:
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Write",
+      "hooks": [{
+        "command": "...",
+        "continueOnError": true  // Never block on error
+      }]
+    }]
+  }
+}
+```
+
+---
+
+## Intelligence Layer Issues
+
+### Problem: No agent suggestions
+
+**Symptoms:**
+- `assignedAgent` always null
+- No intelligence guidance
+
+**Diagnosis:**
+
+```bash
+# Check intelligence status
+npx ruvector hooks stats
+
+# Expected output:
+# Patterns: N
+# Memories: N
+# Status: Ready
+```
+
+**Solutions:**
+
+1. Enable intelligence:
+```bash
+export RUVECTOR_INTELLIGENCE_ENABLED=true
+```
+
+2. Check data files exist:
+```bash
+ls -la .ruvector/intelligence/
+# Should show patterns.json, memory.json, etc.
+```
+
+3. Initialize fresh data:
+```bash
+npx ruvector hooks init --force
+```
+
+---
+
+### Problem: Poor agent suggestions
+
+**Symptoms:**
+- Wrong agent assigned to file types
+- Low confidence scores
+
+**Diagnosis:**
+
+```bash
+# Check patterns
+npx ruvector hooks stats --verbose
+
+# Look for:
+# Top Patterns:
+#   1. edit_rs_in_xxx → rust-developer (Q=0.82)
+```
+
+**Solutions:**
+
+1. Reset learning data:
+```bash
+rm .ruvector/intelligence/patterns.json
+rm .ruvector/intelligence/trajectories.json
+# Will rebuild from scratch
+```
+
+2. Import team patterns:
+```bash
+npx ruvector hooks import --input team-patterns.json
+```
+
+3. Wait for learning:
+- Patterns improve with use
+- 50+ edits needed for good suggestions
+
+---
+
+### Problem: Memory search slow or failing
+
+**Symptoms:**
+- Memory search timeout
+- "Error: Failed to load memory"
+
+**Diagnosis:**
+
+```bash
+# Check memory size
+ls -la .ruvector/intelligence/memory.json
+
+# If >10MB, consider cleanup
+```
+
+**Solutions:**
+
+1. Clean old memories:
+```bash
+# Backup first
+cp .ruvector/intelligence/memory.json memory-backup.json
+
+# Keep only recent
+node -e "
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync('.ruvector/intelligence/memory.json'));
+const recent = data.slice(-1000);  // Keep last 1000
+fs.writeFileSync('.ruvector/intelligence/memory.json', JSON.stringify(recent));
+"
+```
+
+2. Rebuild HNSW index:
+```bash
+rm .ruvector/intelligence/memory.rvdb
+# Will rebuild on next use
+```
+
+---
+
+## Performance Issues
+
+### Problem: High hook overhead
+
+**Symptoms:**
+- Slow file operations
+- Noticeable delay on every edit
+
+**Diagnosis:**
+
+```bash
+# Time individual hooks
+time npx ruvector hooks pre-edit --file test.ts
+time npx ruvector hooks post-edit --file test.ts --success true
+
+# Target: <50ms each
+```
+
+**Solutions:**
+
+1. Disable neural training:
+```bash
+# In config.toml
+[intelligence]
+neural_training = false
+```
+
+2. Reduce memory operations:
+```toml
+[hooks]
+store_memory = false  # Disable memory storage
+```
+
+3. Use async post-hooks:
+```json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Write",
+      "hooks": [{
+        "command": "...",
+        "async": true  // Don't wait for completion
+      }]
+    }]
+  }
+}
+```
+
+---
+
+### Problem: Large intelligence data files
+
+**Symptoms:**
+- `.ruvector/intelligence/` >100MB
+- Slow startup
+
+**Solutions:**
+
+1. Set retention limits:
+```toml
+# In config.toml
+[intelligence]
+max_trajectories = 1000
+max_memories = 10000
+```
+
+2. Clean old data:
+```bash
+# Export current patterns
+npx ruvector hooks export --output patterns-backup.json --include patterns
+
+# Reset
+rm -rf .ruvector/intelligence/*
+
+# Re-import patterns
+npx ruvector hooks import --input patterns-backup.json
+```
+
+---
+
+## Platform-Specific Issues
+
+### Windows Issues
+
+#### Problem: "/bin/bash not found"
+
+**Symptoms:**
+```
+'/bin/bash' is not recognized as an internal or external command
+```
+
+**Solution:**
+
+Check that hooks use Windows-compatible shell:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "command": "cmd /c 'npx ruvector hooks pre-command'"
+      }]
+    }]
+  }
+}
+```
+
+Or reinstall hooks (auto-detects platform):
+```bash
+npx ruvector hooks install --force
+```
+
+#### Problem: Path separator issues
+
+**Symptoms:**
+- File paths not recognized
+- "File not found" errors
+
+**Solution:**
+
+Ensure paths use forward slashes or escaped backslashes:
+
+```bash
+# Good
+npx ruvector hooks pre-edit --file "src/app.ts"
+
+# Bad on Windows
+npx ruvector hooks pre-edit --file "src\app.ts"
+```
+
+#### Problem: jq not found
+
+**Symptoms:**
+```
+'jq' is not recognized as an internal or external command
+```
+
+**Solutions:**
+
+1. Install jq:
+```bash
+# Using chocolatey
+choco install jq
+
+# Using scoop
+scoop install jq
+```
+
+2. Or use jq-free hooks:
+```bash
+npx ruvector hooks install --template minimal
+```
+
+---
+
+### macOS Issues
+
+#### Problem: Permission denied
+
+**Symptoms:**
+```
+Error: EACCES: permission denied
+```
+
+**Solutions:**
+
+1. Fix npm permissions:
+```bash
+sudo chown -R $(whoami) ~/.npm
+```
+
+2. Use nvm:
+```bash
+# Install nvm and use it for npm
+nvm install node
+nvm use node
+```
+
+---
+
+### Linux Issues
+
+#### Problem: Node.js version too old
+
+**Symptoms:**
+```
+SyntaxError: Unexpected token '.'
+```
+
+**Solution:**
+
+Update Node.js:
+```bash
+# Using nvm
+nvm install 18
+nvm use 18
+
+# Or using package manager
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+```
+
+---
+
+## Migration Issues
+
+### Problem: Migration data loss
+
+**Symptoms:**
+- Fewer patterns after migration
+- Missing memories
+
+**Diagnosis:**
+
+```bash
+# Compare counts
+echo "Before: $(jq '.length' old-patterns.json)"
+echo "After: $(npx ruvector hooks stats --json | jq '.patterns')"
+```
+
+**Solutions:**
+
+1. Use validation:
+```bash
+npx ruvector hooks migrate --from old-data --validate
+```
+
+2. Merge instead of replace:
+```bash
+npx ruvector hooks migrate --from old-data --merge
+```
+
+3. Restore from backup:
+```bash
+cp .ruvector/intelligence/backup-*/* .ruvector/intelligence/
+```
+
+---
+
+### Problem: SQLite migration format error
+
+**Symptoms:**
+```
+Error: Unknown embedding format in memory.db
+```
+
+**Solution:**
+
+SQLite migration requires format detection. For MVP, use JSON export:
+
+```bash
+# Export from source as JSON first
+npx claude-flow memory export --output memory.json
+
+# Then import
+npx ruvector hooks import --input memory.json
+```
+
+---
+
+## Debug Mode
+
+### Enable Debug Output
+
+```bash
+# Set environment variable
+export CLAUDE_FLOW_DEBUG=true
+export RUVECTOR_DEBUG=true
+
+# Run with debug
+npx ruvector hooks pre-edit --file test.ts --debug
+```
+
+### Debug Output Interpretation
+
+```
+DEBUG: Loading config from .ruvector/config.toml
+DEBUG: Intelligence enabled: true
+DEBUG: Q-table loaded: 89 patterns
+DEBUG: Memory loaded: 543 vectors
+DEBUG: Encoding state for test.ts
+DEBUG: State key: edit_ts_in_project
+DEBUG: Q-values: { "typescript-developer": 0.82, "coder": 0.45 }
+DEBUG: Selected agent: typescript-developer (confidence: 0.82)
+```
+
+### View Hook Logs
+
+```bash
+# Today's logs
+cat .ruvector/logs/hooks-$(date +%Y-%m-%d).log
+
+# Tail logs
+tail -f .ruvector/logs/hooks-*.log
+```
+
+### Test Hooks Manually
+
+```bash
+# Test pre-edit
+echo '{"tool_input":{"file_path":"test.ts"}}' | npx ruvector hooks pre-edit --stdin
+
+# Test post-edit
+echo '{"tool_input":{"file_path":"test.ts"},"tool_result":{"success":true}}' | npx ruvector hooks post-edit --stdin
+```
+
+---
+
+## Getting Help
+
+### Gather Diagnostic Info
+
+```bash
+# Create diagnostic report
+{
+  echo "=== RuVector Version ==="
+  npx ruvector --version
+
+  echo -e "\n=== Node Version ==="
+  node --version
+
+  echo -e "\n=== Platform ==="
+  uname -a
+
+  echo -e "\n=== Hooks Stats ==="
+  npx ruvector hooks stats --json
+
+  echo -e "\n=== Config ==="
+  cat .ruvector/config.toml
+
+  echo -e "\n=== Settings ==="
+  cat .claude/settings.json | jq '.hooks'
+} > ruvector-diagnostic.txt
+
+echo "Diagnostic saved to ruvector-diagnostic.txt"
+```
+
+### Report Issues
+
+1. Create diagnostic report (above)
+2. Open issue: https://github.com/ruvnet/ruvector/issues
+3. Include:
+   - Diagnostic report
+   - Steps to reproduce
+   - Expected vs actual behavior
+
+---
+
+## See Also
+
+- [User Guide](USER_GUIDE.md) - Getting started
+- [CLI Reference](CLI_REFERENCE.md) - Command documentation
+- [Architecture](ARCHITECTURE.md) - Technical details
+- [Migration Guide](MIGRATION.md) - Upgrade from other systems
diff --git a/docs/hooks/USER_GUIDE.md b/docs/hooks/USER_GUIDE.md
new file mode 100644
index 000000000..3f771a8be
--- /dev/null
+++ b/docs/hooks/USER_GUIDE.md
@@ -0,0 +1,629 @@
+# RuVector Hooks User Guide
+
+A comprehensive guide to setting up and using the RuVector hooks system for intelligent Claude Code automation.
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Prerequisites](#prerequisites)
+3. [Installation](#installation)
+4. [Basic Usage](#basic-usage)
+5. [Configuration](#configuration)
+6. [Working with Hooks](#working-with-hooks)
+7. [Intelligence Features](#intelligence-features)
+8. [Best Practices](#best-practices)
+9. [Examples](#examples)
+
+---
+
+## Quick Start
+
+Get up and running in under 5 minutes:
+
+```bash
+# Step 1: Initialize hooks in your project
+npx ruvector hooks init
+
+# Step 2: Install hooks into Claude Code
+npx ruvector hooks install
+
+# Step 3: Verify installation
+npx ruvector hooks stats
+
+# Done! Hooks are now active
+```
+
+---
+
+## Prerequisites
+
+### Required
+
+- **Node.js 18+**: Required for hook execution
+- **Claude Code**: The hooks integrate with Claude Code's hook system
+- **npm or pnpm**: Package manager for installation
+
+### Optional
+
+- **jq**: JSON processing for hook data (auto-installed on most systems)
+- **Git**: For version control integration
+- **claude-flow CLI**: For advanced swarm coordination
+
+### Verify Prerequisites
+
+```bash
+# Check Node.js version
+node --version  # Should be 18.x or higher
+
+# Check npm
+npm --version
+
+# Check jq (optional)
+which jq || echo "jq not installed (optional)"
+```
+
+---
+
+## Installation
+
+### Method 1: npx (Recommended)
+
+The simplest way to install hooks:
+
+```bash
+# Initialize in any project
+cd your-project
+npx ruvector hooks init
+npx ruvector hooks install
+```
+
+### Method 2: Global Installation
+
+For frequent use across projects:
+
+```bash
+# Install globally
+npm install -g @ruvector/cli
+
+# Then use directly
+ruvector hooks init
+ruvector hooks install
+```
+
+### Method 3: With Claude Flow
+
+If using claude-flow for swarm coordination:
+
+```bash
+# Initialize with full hook support
+npx claude-flow init --hooks
+
+# Hooks are automatically configured
+```
+
+### Verify Installation
+
+```bash
+# Check hooks are installed
+npx ruvector hooks stats
+
+# Expected output:
+# RuVector Intelligence Statistics
+# --------------------------------
+# Patterns: 0 (new installation)
+# Memories: 0
+# Status: Ready
+```
+
+---
+
+## Basic Usage
+
+### How Hooks Work
+
+Hooks automatically execute when you use Claude Code:
+
+1. **Pre-hooks** run before tool execution
+2. **Post-hooks** run after tool execution
+3. **Session hooks** run at session boundaries
+
+### Automatic Behavior
+
+Once installed, hooks work automatically:
+
+```bash
+# When you edit a file in Claude Code:
+# 1. pre-edit hook checks file type, assigns agent
+# 2. Claude Code performs the edit
+# 3. post-edit hook formats code, stores in memory
+
+# When you run a command:
+# 1. pre-bash hook validates safety
+# 2. Command executes
+# 3. post-bash hook logs result, updates metrics
+```
+
+### Manual Hook Execution
+
+You can also run hooks manually:
+
+```bash
+# Test pre-edit hook
+npx ruvector hooks pre-edit --file "src/app.ts"
+
+# Test post-edit hook
+npx ruvector hooks post-edit --file "src/app.ts" --success true
+
+# Run session hooks
+npx ruvector hooks session-start
+npx ruvector hooks session-end --export-metrics
+```
+
+---
+
+## Configuration
+
+### Configuration File
+
+After `hooks init`, a configuration file is created:
+
+**`.ruvector/config.toml`**:
+
+```toml
+[intelligence]
+enabled = true
+learning_rate = 0.1
+ab_test_group = "treatment"
+use_hyperbolic_distance = true
+curvature = 1.0
+
+[memory]
+backend = "rvdb"
+max_memories = 50000
+dimensions = 128
+
+[patterns]
+decay_half_life_days = 7
+min_q_value = -0.5
+max_q_value = 0.8
+
+[hooks]
+pre_command_enabled = true
+post_command_enabled = true
+pre_edit_enabled = true
+post_edit_enabled = true
+session_start_enabled = true
+session_end_enabled = true
+timeout_ms = 3000
+```
+
+### Claude Code Settings
+
+Hooks are registered in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{
+          "type": "command",
+          "timeout": 3000,
+          "command": "npx ruvector hooks pre-command \"$CMD\""
+        }]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [{
+          "type": "command",
+          "timeout": 3000,
+          "command": "npx ruvector hooks pre-edit \"$FILE\""
+        }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [{
+          "type": "command",
+          "command": "npx ruvector hooks post-edit \"$FILE\" \"true\""
+        }]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [{
+          "type": "command",
+          "timeout": 5000,
+          "command": "npx ruvector hooks session-start"
+        }]
+      }
+    ]
+  }
+}
+```
+
+### Customizing Hooks
+
+#### Add Protected File Detection
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "npx ruvector hooks check-protected \"$FILE\""
+        }]
+      }
+    ]
+  }
+}
+```
+
+#### Add Auto-Testing
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [{
+          "type": "command",
+          "command": "test -f \"${FILE%.ts}.test.ts\" && npm test \"${FILE%.ts}.test.ts\"",
+          "continueOnError": true
+        }]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Working with Hooks
+
+### Pre-Edit Hook
+
+Runs before file modifications:
+
+```bash
+npx ruvector hooks pre-edit --file "src/auth/login.ts"
+```
+
+**What it does:**
+- Detects file type and language
+- Assigns appropriate agent (e.g., TypeScript files → typescript-developer)
+- Checks for existing patterns
+- Validates syntax if enabled
+- Creates backup if configured
+
+**Output example:**
+```json
+{
+  "continue": true,
+  "agent": "typescript-developer",
+  "confidence": 0.85,
+  "syntaxValid": true,
+  "warnings": []
+}
+```
+
+### Post-Edit Hook
+
+Runs after file modifications:
+
+```bash
+npx ruvector hooks post-edit --file "src/auth/login.ts" --success true
+```
+
+**What it does:**
+- Records successful edit in trajectory
+- Updates Q-learning patterns
+- Stores context in vector memory
+- Optionally formats code
+- Trains neural patterns
+
+### Session Hooks
+
+#### Starting a Session
+
+```bash
+npx ruvector hooks session-start --session-id "feature-dev"
+```
+
+**Output:**
+```
+RuVector Intelligence Layer Active
+
+Patterns: 131 state-action pairs
+Memories: 4,247 vectors
+Status: Ready
+```
+
+#### Ending a Session
+
+```bash
+npx ruvector hooks session-end --export-metrics --generate-summary
+```
+
+**What it does:**
+- Persists memory state
+- Exports session metrics
+- Generates work summary
+- Cleans up temporary files
+
+---
+
+## Intelligence Features
+
+### Q-Learning
+
+The hooks system learns from your actions:
+
+```bash
+# View learned patterns
+npx ruvector hooks stats --verbose
+
+# Output:
+# Top Patterns:
+# 1. edit_ts_in_src → typescript-developer (Q=0.82)
+# 2. edit_rs_in_crates → rust-developer (Q=0.79)
+# 3. cargo_test → success (Q=0.91)
+```
+
+### Agent Routing
+
+Automatically assigns the best agent for each file:
+
+| File Type | Assigned Agent | Confidence |
+|-----------|---------------|------------|
+| `*.ts`, `*.tsx` | typescript-developer | 85% |
+| `*.rs` | rust-developer | 80% |
+| `*.py` | python-developer | 78% |
+| `*.go` | go-developer | 75% |
+| `*.sql` | database-specialist | 70% |
+
+### Memory Persistence
+
+Decisions are stored for future reference:
+
+```bash
+# Check memory usage
+npx ruvector hooks stats
+
+# Output:
+# Memories: 4,247 vectors
+# Dimensions: 128
+# Storage: 2.4 MB
+```
+
+### A/B Testing
+
+Compare learning effectiveness:
+
+```bash
+# Treatment group (learning enabled)
+INTELLIGENCE_MODE=treatment npx ruvector hooks pre-edit --file "test.ts"
+
+# Control group (random baseline)
+INTELLIGENCE_MODE=control npx ruvector hooks pre-edit --file "test.ts"
+```
+
+---
+
+## Best Practices
+
+### 1. Initialize Early
+
+Set up hooks at the start of a project:
+
+```bash
+# After creating a new project
+npx ruvector hooks init
+npx ruvector hooks install
+```
+
+### 2. Use Meaningful Session IDs
+
+Track work with descriptive sessions:
+
+```bash
+# Good: Descriptive sessions
+npx ruvector hooks session-start --session-id "feature-auth-oauth2"
+npx ruvector hooks session-start --session-id "bugfix-memory-leak-123"
+
+# Avoid: Generic sessions
+npx ruvector hooks session-start --session-id "session1"
+```
+
+### 3. Export Metrics Regularly
+
+Capture performance data:
+
+```bash
+# At end of work session
+npx ruvector hooks session-end --export-metrics --generate-summary
+```
+
+### 4. Review Pattern Quality
+
+Check learning effectiveness:
+
+```bash
+# Weekly review
+npx ruvector hooks stats --verbose
+
+# Check calibration
+# Good: 0.04-0.06 calibration error
+# Bad: >0.15 calibration error
+```
+
+### 5. Keep Hooks Lightweight
+
+Follow performance guidelines:
+
+- Hook execution: <50ms
+- Total overhead: <100ms per operation
+- Async heavy operations
+- Cache repeated lookups
+
+### 6. Use Version Control
+
+Track hook configurations:
+
+```bash
+# Add to git
+git add .claude/settings.json
+git add .ruvector/config.toml
+
+# Ignore learning data (optional)
+echo ".ruvector/intelligence/" >> .gitignore
+```
+
+---
+
+## Examples
+
+### Example 1: Development Workflow
+
+```bash
+# Start development session
+npx ruvector hooks session-start --session-id "feature-user-profile"
+
+# Work on files (hooks run automatically via Claude Code)
+# - Pre-edit assigns agents
+# - Post-edit formats and stores
+
+# End session
+npx ruvector hooks session-end \
+  --session-id "feature-user-profile" \
+  --export-metrics \
+  --generate-summary
+```
+
+### Example 2: Debugging Session
+
+```bash
+# Start debug session
+npx ruvector hooks session-start --session-id "debug-api-timeout"
+
+# Load previous context
+npx ruvector hooks session-restore --session-id "debug-api-timeout"
+
+# Work on debugging...
+
+# Export findings
+npx ruvector hooks session-end \
+  --session-id "debug-api-timeout" \
+  --store-decisions \
+  --generate-report
+```
+
+### Example 3: Multi-Agent Task
+
+```bash
+# Pre-task with agent spawning
+npx claude-flow hook pre-task \
+  --description "Implement OAuth2 authentication" \
+  --auto-spawn-agents \
+  --load-memory
+
+# Agents work on files (hooks coordinate)
+
+# Post-task analysis
+npx claude-flow hook post-task \
+  --task-id "oauth2-impl" \
+  --analyze-performance \
+  --export-learnings
+```
+
+### Example 4: Custom Rust Workflow
+
+For Rust projects, specialized hooks are available:
+
+```bash
+# Pre-edit for Rust files
+.claude/hooks/rust-check.sh src/lib.rs
+
+# Post-edit with benchmarks
+.claude/hooks/post-rust-edit.sh src/lib.rs true
+```
+
+---
+
+## Environment Setup
+
+### Required Environment Variables
+
+```bash
+# Enable intelligence (default: true)
+export RUVECTOR_INTELLIGENCE_ENABLED=true
+
+# Set A/B test group
+export INTELLIGENCE_MODE=treatment
+
+# Optional: Custom data directory
+export RUVECTOR_DATA_DIR=.ruvector
+```
+
+### Recommended Shell Configuration
+
+Add to `~/.bashrc` or `~/.zshrc`:
+
+```bash
+# RuVector hooks
+export RUVECTOR_INTELLIGENCE_ENABLED=true
+export INTELLIGENCE_MODE=treatment
+
+# Alias for convenience
+alias rv='npx ruvector'
+alias rvhooks='npx ruvector hooks'
+```
+
+---
+
+## Getting Help
+
+### Check Status
+
+```bash
+npx ruvector hooks stats --verbose
+```
+
+### Debug Mode
+
+```bash
+# Enable debug output
+export CLAUDE_FLOW_DEBUG=true
+
+# Run with debug
+npx ruvector hooks pre-edit --file "test.ts" --debug
+```
+
+### View Logs
+
+```bash
+# Check hook execution logs
+cat .ruvector/logs/hooks-$(date +%Y-%m-%d).log
+```
+
+### Validate Configuration
+
+```bash
+# Check JSON syntax
+npx ruvector hooks validate-config
+```
+
+---
+
+## Next Steps
+
+- [CLI Reference](CLI_REFERENCE.md) - Full command documentation
+- [Architecture](ARCHITECTURE.md) - Technical details
+- [Migration Guide](MIGRATION.md) - Upgrade from other systems
+- [Troubleshooting](TROUBLESHOOTING.md) - Common issues