docs: add Claude Code hooks section to README and create HOOKS.md

- Added hooks feature summary near top of README.md
- Created comprehensive HOOKS.md documentation
- Links to detailed docs for pretrain, build-agents, verify, etc.

npm/packages/ruvector/HOOKS.md

@@ -0,0 +1,221 @@
+# RuVector Hooks for Claude Code
+
+Self-learning intelligence hooks that enhance Claude Code with Q-learning, vector memory, and automatic agent routing.
+
+## Quick Start
+
+```bash
+# Full setup: hooks + pretrain + optimized agents
+npx ruvector hooks init --pretrain --build-agents quality
+
+# Or step by step:
+npx ruvector hooks init          # Setup hooks
+npx ruvector hooks pretrain      # Analyze repository
+npx ruvector hooks build-agents  # Generate agent configs
+```
+
+## What It Does
+
+RuVector hooks integrate with Claude Code to provide:
+
+| Feature | Description |
+|---------|-------------|
+| **Agent Routing** | Suggests the best agent for each file type based on learned patterns |
+| **Co-edit Patterns** | Predicts "likely next files" from git history |
+| **Vector Memory** | Semantic recall of project context |
+| **Command Analysis** | Risk assessment for bash commands |
+| **Self-Learning** | Q-learning improves suggestions over time |
+
+## Commands
+
+### Initialization
+
+```bash
+# Full configuration
+npx ruvector hooks init
+
+# With pretrain and agent building
+npx ruvector hooks init --pretrain --build-agents security
+
+# Minimal (basic hooks only)
+npx ruvector hooks init --minimal
+
+# Options
+--force           # Overwrite existing settings
+--minimal         # Basic hooks only
+--pretrain        # Run pretrain after init
+--build-agents    # Generate optimized agents (quality|speed|security|testing|fullstack)
+--no-claude-md    # Skip CLAUDE.md creation
+--no-permissions  # Skip permissions config
+--no-env          # Skip environment variables
+--no-gitignore    # Skip .gitignore update
+--no-mcp          # Skip MCP server config
+--no-statusline   # Skip status line config
+```
+
+### Pretrain
+
+Analyze your repository to bootstrap intelligence:
+
+```bash
+npx ruvector hooks pretrain
+
+# Options
+--depth <n>     # Git history depth (default: 100)
+--verbose       # Show detailed progress
+--skip-git      # Skip git history analysis
+--skip-files    # Skip file structure analysis
+```
+
+**What it learns:**
+- File type → Agent mapping (`.rs` → rust-developer)
+- Co-edit patterns from git history
+- Directory → Agent mapping
+- Project context memories
+
+### Build Agents
+
+Generate optimized `.claude/agents/` configurations:
+
+```bash
+npx ruvector hooks build-agents --focus quality
+
+# Focus modes
+--focus quality   # Code quality, best practices (default)
+--focus speed     # Rapid development, prototyping
+--focus security  # OWASP, input validation, encryption
+--focus testing   # TDD, comprehensive coverage
+--focus fullstack # Balanced frontend/backend/database
+
+# Options
+--output <dir>    # Output directory (default: .claude/agents)
+--format <fmt>    # yaml, json, or md (default: yaml)
+--include-prompts # Include system prompts in agent configs
+```
+
+### Verification & Diagnostics
+
+```bash
+# Check if hooks are working
+npx ruvector hooks verify
+
+# Diagnose and fix issues
+npx ruvector hooks doctor
+npx ruvector hooks doctor --fix
+```
+
+### Data Management
+
+```bash
+# View statistics
+npx ruvector hooks stats
+
+# Export intelligence data
+npx ruvector hooks export -o backup.json
+npx ruvector hooks export --include-all
+
+# Import intelligence data
+npx ruvector hooks import backup.json
+npx ruvector hooks import backup.json --merge
+```
+
+### Memory Operations
+
+```bash
+# Store context in vector memory
+npx ruvector hooks remember "API uses JWT auth" -t project
+
+# Semantic search memory
+npx ruvector hooks recall "authentication"
+
+# Route a task to best agent
+npx ruvector hooks route "implement user login"
+```
+
+## Hook Events
+
+| Event | Trigger | RuVector Action |
+|-------|---------|-----------------|
+| **PreToolUse** | Before Edit/Write/Bash | Agent routing, file analysis, command risk |
+| **PostToolUse** | After Edit/Write/Bash | Q-learning update, pattern recording |
+| **SessionStart** | Conversation begins | Load intelligence, display stats |
+| **Stop** | Conversation ends | Save learning data |
+| **UserPromptSubmit** | User sends message | Context suggestions |
+| **PreCompact** | Before context compaction | Preserve important context |
+| **Notification** | Any notification | Track events for learning |
+
+## Generated Files
+
+After running `hooks init`:
+
+```
+your-project/
+├── .claude/
+│   ├── settings.json      # Hooks configuration
+│   ├── statusline.sh      # Status bar script
+│   └── agents/            # Generated agents (with --build-agents)
+│       ├── rust-specialist.yaml
+│       ├── typescript-specialist.yaml
+│       ├── test-architect.yaml
+│       └── project-coordinator.yaml
+├── .ruvector/
+│   └── intelligence.json  # Learning data
+├── CLAUDE.md              # Project documentation
+└── .gitignore             # Updated with .ruvector/
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RUVECTOR_INTELLIGENCE_ENABLED` | `true` | Enable/disable intelligence |
+| `RUVECTOR_LEARNING_RATE` | `0.1` | Q-learning rate (0.0-1.0) |
+| `RUVECTOR_MEMORY_BACKEND` | `rvlite` | Memory storage backend |
+| `INTELLIGENCE_MODE` | `treatment` | A/B testing mode |
+
+## Example Output
+
+### Agent Routing
+```
+🧠 Intelligence Analysis:
+   📁 src/api/routes.ts
+   🤖 Recommended: typescript-developer (85% confidence)
+      → learned from 127 .ts files in repo
+   📎 Likely next files:
+      - src/api/handlers.ts (12 co-edits)
+      - src/types/api.ts (8 co-edits)
+```
+
+### Command Analysis
+```
+🧠 Command Analysis:
+   📦 Category: rust
+   🏷️  Type: test
+   ✅ Risk: LOW
+```
+
+## Best Practices
+
+1. **Run pretrain on existing repos** — Bootstrap intelligence before starting work
+2. **Use focus modes** — Match agent generation to your current task
+3. **Export before major changes** — Backup learning data
+4. **Let it learn** — Intelligence improves with each edit
+
+## Troubleshooting
+
+```bash
+# Check setup
+npx ruvector hooks verify
+
+# Fix common issues
+npx ruvector hooks doctor --fix
+
+# Reset and reinitialize
+npx ruvector hooks init --force --pretrain
+```
+
+## Links
+
+- [RuVector GitHub](https://github.com/ruvnet/ruvector)
+- [npm Package](https://www.npmjs.com/package/ruvector)
+- [Claude Code Documentation](https://docs.anthropic.com/claude-code)

npm/packages/ruvector/README.md

@@ -20,6 +20,26 @@ Built by [rUv](https://ruv.io) with production-grade Rust performance and intell
 
 ---
 
+## 🧠 Claude Code Hooks (NEW)
+
+**Self-learning intelligence for Claude Code** — RuVector provides optimized hooks that learn from your development patterns.
+
+```bash
+# One-command setup with pretrain and agent generation
+npx ruvector hooks init --pretrain --build-agents quality
+```
+
+**Features:**
+- 🎯 **Smart Agent Routing** — Automatically suggests the best agent for each file type
+- 📚 **Repository Pretrain** — Analyzes your codebase to bootstrap intelligence
+- 🤖 **Agent Builder** — Generates optimized `.claude/agents/` configs for your stack
+- 🔗 **Co-edit Patterns** — Learns which files are edited together from git history
+- 💾 **Vector Memory** — Semantic recall of project context
+
+📖 **[Full Hooks Documentation →](https://github.com/ruvnet/ruvector/blob/main/npm/packages/ruvector/HOOKS.md)**
+
+---
+
 ## 🌟 Why Ruvector?
 
 ### The Problem with Existing Vector Databases

npm/packages/ruvector/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvector",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "High-performance vector database for Node.js with automatic native/WASM fallback",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",