amalfa 1.4.3 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,70 @@ All notable changes to AMALFA will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-01-26
+
+### Added
+- **LangExtract Sidecar**: Integrated Python-based entity extraction via MCP/Stdio bridge.
+  - New robust Node.js client (`src/services/LangExtractClient.ts`) with Zod validation and Pino logging.
+  - Automatically enriches documents >200 chars during `amalfa ember scan`.
+  - Handles API rate limits (429) gracefully.
+- **Reranker Integration**: Finalized BGE-M3 cross-encoder support.
+  - Added `--rerank` flag to `amalfa search` CLI command.
+  - Integrated `ContentHydrator` for retrieving document content for reranking.
+  - Verified end-to-end quality improvement.
+- **Example Config**: Added `amalfa.config.example.json` reference file.
+
+### Changed
+- **Service Naming**: Renamed `amalfa daemon` to `amalfa watcher` to align with internal naming and reduce confusion.
+  - `amalfa daemon` is now deprecated but still works (with warning).
+  - Updated `package.json` scripts to use `watcher`.
+- **Ember Hardening**: Fixed critical bug in tag parsing logic that caused garbage tags (single characters).
+  - Implemented strict array checking for tags.
+  - Added hygiene filters to remove numeric-only and short tags.
+  - Updated `EmberAnalyzer` to use project-relative paths for portable sidecars.
+
+### Fixed
+- **Tag Corruption**: Identified and fixed corrupted metadata in documentation files (`newbie-onboarding.md`, etc.) caused by previous buggy runs.
+- **Git Hygiene**: Added `*.ember.json` to `.gitignore` to treat sidecars as ephemeral artifacts.
+
+## [1.4.4] - 2026-01-17
+### Added
+- **Consistency Audit System**: Automated consistency checker for documentation/code alignment
+  - 6 check categories: CLI commands, file paths, service naming, config schema, cross-references, legacy commands
+  - Integrated into precommit hook with 80% threshold
+  - JSON output for dashboard integration
+  - Command: `bun run consistency-report`
+
+### Improved
+- **MCP Tool Descriptions**: Enhanced all 8 tool descriptions with strategic guidance
+  - When to use each tool (search_documents, explore_links, find_gaps, etc.)
+  - Value proposition and trigger scenarios
+  - Better agent understanding of tool purpose
+- **User Prompting Guide**: Added comprehensive section to README.md
+  - Effective prompts during and after work
+  - Building institutional memory patterns
+  - When NOT to prompt (novel problems, fresh thinking)
+- **Agent Developer Documentation**: New 113-line section in MCP-TOOLS.md
+  - Strategic tool usage patterns
+  - When to encourage debriefs and playbooks
+  - Proactive vs reactive search patterns
+  - TypeScript integration examples
+
+### Documentation
+- **Fixed Consistency Issues**: Improved from 76% to 98% consistency score
+  - Documented all CLI commands (validate, enhance, scripts, kill alias)
+  - Fixed daemon file path references in ARCHITECTURE.md
+  - Replaced legacy `rm -rf .amalfa/` with staged recovery approach
+  - Created `amalfa.config.example.json`
+  - Updated all legacy command references
+
+### Developer Experience
+- **Precommit Hook Enhancement**: Now includes 4 checks
+  - TypeScript compilation
+  - Biome lint/format
+  - **NEW:** Consistency audit (80% threshold)
+  - Changelog verification
+
 ## [1.4.3] - 2026-01-16
 ### Documentation
 - Bump to 1.4.3

package/README.md

@@ -2,181 +2,249 @@
 
 **A Memory Layer For Agents**
 
-Local-first knowledge graph with semantic search for AI agents.
+[![npm](https://img.shields.io/npm/v/amalfa?logo=npm)](https://www.npmjs.com/package/amalfa)
+[![downloads](https://img.shields.io/npm/dm/amalfa)](https://www.npmjs.com/package/amalfa)
 
-**Core Design**: Your documents are the source of truth. The database is a disposable runtime artifact.
+Give your AI agents persistent memory and semantic search across sessions.
 
 ---
 
+## What It Does
 
-[![npm](https://img.shields.io/npm/v/amalfa?logo=npm)](https://www.npmjs.com/package/amalfa)
-[![downloads](https://img.shields.io/npm/dm/amalfa)](https://www.npmjs.com/package/amalfa)
+**Without Amalfa:**
+- Agents forget context between conversations
+- Same research repeated every session  
+- No institutional memory
+- Knowledge resets constantly
+
+**With Amalfa:**
+- Agents query past work: "What did we learn about auth?"  
+- Semantic search across all documentation
+- Persistent memory through structured reflection (briefs → debriefs → playbooks)
+- Knowledge compounds over time
+
+**How it works:** You write markdown. Amalfa indexes it into a searchable knowledge graph. AI agents access it via Model Context Protocol (MCP).
 
 ---
 
-## What is Amalfa?
+## What Agents Can Do
 
-Amalfa is a **Model Context Protocol (MCP) server** that provides AI agents with:
+Via MCP, agents get 8 tools:
 
-- 🔍 **Semantic search** over markdown documentation
-- 📊 **Graph traversal** of relationships between documents
-- 🧠 **Agent continuity** across sessions via persistent memory
-- ⚡ **Auto-augmentation** of metadata (tags, links, clusters)
-- 🏷️ **Latent space tagging** for emergent organization
+- **search_documents(query)** - Semantic search across all markdown  
+- **read_node_content(id)** - Read full document content  
+- **explore_links(id)** - Traverse document relationships  
+- **find_gaps()** - Discover similar but unlinked documents  
+- **list_directory_structure()** - Show document organization  
+- **inject_tags(path, tags)** - Add metadata to documents  
+- **scratchpad_read/list()** - Cache management for large outputs
 
-Built with **Bun + SQLite + FastEmbed**.
+**Example Session:**
+```
+Agent: "What did we learn about database migrations?"
+→ search_documents("database migrations lessons")
+→ Returns ranked debriefs with past learnings
+→ Agent applies proven patterns to new work
+```
+
+**Performance:** Sub-second searches across 1000+ documents. 4.6x faster than grep. 95% search precision.
 
-**Core distinguisher**: Database is a **disposable runtime artifact**. Documents are the source of truth.
+👉 **Full Tool Reference:** [MCP Tools Documentation](docs/MCP-TOOLS.md)
 
 ---
 
-## The Problem
+## CLI Mode: Direct Command Line Access
 
-**Current state:** AI agents lose context between sessions. Knowledge resets. Same problems get re-solved.
+**Amalfa doesn't require running as an MCP server.** All core search capabilities are available directly from the command line:
 
-**Amalfa solves this:** Agents write structured reflections (Write Brief → Do Work → Write Debrief → Update Playbooks). Amalfa indexes this as a queryable knowledge graph with semantic search.
+### Search Commands
 
-👉 **Deep Dive:** [Why Structured Reflection Beats Infinite Context](docs/WHY-STRUCTURED-REFLECTION.md)
+```bash
+# Semantic search across knowledge graph
+amalfa search "oauth patterns" --limit 10
 
-**Result:** Agents can query "What did we learn about authentication?" and get ranked, relevant past work—even across different agents and sessions.
+# Read full document content
+amalfa read docs/auth-guide.md
 
----
+# Explore document relationships
+amalfa explore docs/auth-guide.md --relation references
 
-## Core Architecture: Disposable Database
+# List configured source directories
+amalfa list-sources
 
-**The Foundation**: AMALFA treats your filesystem as the single source of truth and the database as an ephemeral cache.
+# Discover similar but unlinked documents (requires Sonar)
+amalfa find-gaps --limit 5 --threshold 0.7
 
-### The Philosophy
+# Add metadata tags to documents
+amalfa inject-tags docs/auth.md "authentication" "security"
+```
 
-**Documents = Truth, Database = Cache**
+### JSON Output for Scripting
 
-```
-Markdown Files (filesystem)
-    ↓
-  [Ingestion Pipeline]
-    ↓
-SQLite Database (.amalfa/)
-    ↓
-  [Vector Search]
-    ↓
-MCP Server (AI agents)
+All commands support `--json` for programmatic use:
+
+```bash
+# Machine-readable output
+amalfa search "database migrations" --json | jq '.[0].id'
+
+# Chain commands
+amalfa search "auth" --json | jq '.[0].id' | xargs amalfa read
+
+# Integrate with CI/CD
+amalfa find-gaps --json | jq 'length' # Count unlinked documents
 ```
 
-**Key Insight**: The database can be deleted and regenerated at any time without data loss.
+### When to Use CLI vs MCP
 
-- **Source of Truth**: Your markdown documents (immutable filesystem)
-- **Runtime Artifact**: SQLite database with embeddings and metadata
-- **Regeneration**: `rm -rf .amalfa/ && bun run scripts/cli/ingest.ts`
+**Use CLI when:**
+- Testing queries without MCP overhead
+- Scripting and automation (CI/CD, shell scripts)
+- Human power users who prefer terminal
+- Agents that execute shell commands (vs MCP protocol)
+- One-shot queries (no server needed)
 
-### Why This Matters
+**Use MCP when:**
+- Integrated with Claude Desktop or other MCP clients
+- Multi-turn agent conversations
+- Need scratchpad caching (MCP-only feature)
+- Prefer agent-native tool calling
 
-**Benefits**:
-- ✅ **No Migration Hell**: Upgrading? Just re-ingest. No migration scripts.
-- ✅ **Deterministic Rebuilds**: Same documents → same database state
-- ✅ **Version Freedom**: Switch between AMALFA versions without fear
-- ✅ **Corruption Immunity**: Database corrupt? Delete and rebuild in seconds
-- ✅ **Model Flexibility**: Change embedding models by re-ingesting
+---
 
-**Distinguisher**: Unlike traditional systems where the database *is* the truth, AMALFA inverts this. Your prose is permanent, the index is disposable.
+## Prompting Your Agent to Use Amalfa
 
-### Troubleshooting & Maintenance
+**Amalfa works best when you establish a knowledge-building habit with your agent.**
 
-Amalfa employs a tiered maintenance strategy. For standard issues, run `amalfa doctor`. For data updates, run `amalfa init`.
+### Effective Prompts
 
-👉 **Full Guide:** [User Manual - Maintenance & Troubleshooting](docs/USER-MANUAL.md#6-maintenance--troubleshooting)
+**During work:**
+- "What have we learned about [topic]?" → Triggers `search_documents`
+- "Check if we've solved this before" → Searches past solutions
+- "What patterns did we discover?" → Queries playbooks
 
+**After work:**
+- "Write a debrief of what we learned" → Encourages documentation
+- "Update the playbook with this pattern" → Codifies knowledge
+- "What related work should be linked?" → Triggers `find_gaps`
 
-### Write Brief → Do Work → Write Debrief → Update Playbooks Pattern
+### Building Institutional Memory
 
+**Session start:**
 ```
-Brief (task spec)
-   ↓
-Work (implementation)
-   ↓
-Debrief (what we learned)
-   ↓
-Playbook (codified patterns)
-   ↓
-Future briefs (informed by playbooks)
+You: "Before we start, search for any past work on [topic]"
+Agent: [Uses search_documents to query knowledge graph]
+Agent: "Found 3 relevant debriefs from previous sessions..."
 ```
 
-**Debriefs** capture:
-- What worked (successes)
-- What failed (dead ends)
-- Lessons learned (abstractions)
-
-**Playbooks** codify:
-- Principles (how we do things)
-- Patterns (reusable solutions)
-- Anti-patterns (what to avoid)
-- Decision records (why we chose X over Y)
+**During problem-solving:**
+```
+You: "Have we encountered this error before?"
+Agent: [Searches past debugging sessions]
+Agent: "Yes, in debrief-auth-safari we learned..."
+```
 
-### Auto-Augmentation
+**Session end:**
+```
+You: "Write a debrief capturing what we learned"
+Agent: [Creates debrief in markdown]
+You: "Now ingest it: amalfa init"
+```
 
-Amalfa **automatically** adds:
+### When NOT to Prompt
 
-- **Tags:** Extracted from content + latent space clustering
-- **Links:** Wiki-style links between related documents
-- **Clusters:** Documents organized by embedding similarity
-- **Suggested reading:** Context for new sessions
+**Let agents decide when:**
+- They're working on completely novel problems
+- Quick one-off tasks that won't recur
+- You explicitly want fresh thinking without past bias
 
-**Agents don't maintain metadata manually.** Amalfa handles it via git-audited auto-augmentation.
+**The goal:** Build compounding knowledge, not create busywork.
 
 ---
 
-## Sub-Agents & Discovery
+## The Problem
 
-Amalfa orchestrates specialized sub-agents (Vector, Reranker, Sonar) to provide intelligence.
+**Scenario:** You're debugging authentication for the 3rd time.
 
-*   **Vector Daemon**: Handles embeddings.
-*   **Reranker Daemon**: Re-scores search results for precision.
-*   **Sonar Agent**: Performs reasoning and deep research using local LLMs (Ollama) or Cloud APIs.
+**Without Amalfa:**
+- Agent searches codebase from scratch  
+- Rediscovers same issues  
+- Repeats same solutions  
+- Context resets every conversation
+
+**With Amalfa:**
+```
+Agent queries: "past auth debugging sessions"
+→ Finds debrief from 2 weeks ago
+→ "We learned the token refresh fails in Safari due to cookie scope"
+→ Applies fix immediately
+```
 
-👉 **Full Guide:** [User Manual - Services & Sub-Agents](docs/USER-MANUAL.md#5-services--sub-agents)
+**Result:** 10-minute fix instead of 2-hour investigation.
 
+👉 **Deep Dive:** [Why Structured Reflection Beats Infinite Context](docs/WHY-STRUCTURED-REFLECTION.md)
 
 ---
 
-## Architecture
+## Core Philosophy: Markdown as Source of Truth
+
+**The Inversion:** Traditional systems treat databases as truth and files as exports. Amalfa inverts this.
+
+```
+Markdown Files (filesystem)     ← Source of truth
+    ↓
+Ingestion Pipeline
+    ↓
+SQLite Database (.amalfa/)      ← Disposable cache
+    ↓
+MCP Server → AI Agents
+```
+
+**Key principle:** The database can be deleted and regenerated anytime without data loss.
 
-### Technology Stack
+### Why This Matters
+
+✅ **Zero migration hell** - Upgrade by re-ingesting. No migration scripts.  
+✅ **Model flexibility** - Change embedding models without data loss.  
+✅ **Corruption immunity** - `rm .amalfa/resonance.db* && amalfa init` fixes everything.
+✅ **Git-native** - Version control your knowledge, not your indexes.  
+✅ **Deterministic** - Same markdown → same database state.
+
+### Maintenance
 
-- **Runtime:** Bun (fast, TypeScript-native)
-- **Database:** SQLite with WAL mode (local-first, portable)
-- **Embeddings:** FastEmbed (`bge-small-en-v1.5`, 384 dims)
-- **Reranking:** Xenova Transformers (`bge-reranker-base`)
-- **Protocol:** Model Context Protocol (MCP)
+**Two commands:**
+- `amalfa init` - Regenerate database from markdown (safe, fast)
+- `amalfa doctor` - Health check (rarely needed)
 
-### Project Structure
+**No migrations. No backups. No complex maintenance.**
 
+When something breaks: delete `.amalfa/` and re-ingest. Takes seconds, not hours.
+
+
+---
+
+## Architecture
+
+**Technology Stack:**
+- Bun (TypeScript runtime)
+- SQLite (local-first database)
+- FastEmbed (bge-small-en-v1.5, 384-dim vectors)
+- Model Context Protocol (MCP)
+
+**Data Flow:**
 ```
-amalfa/
-├── src/
-│   ├── mcp/           # MCP server implementation
-│   ├── resonance/     # Database layer (SQLite wrapper)
-│   ├── core/          # Graph processing (EdgeWeaver, VectorEngine)
-│   └── utils/         # Logging, validation, lifecycle
-├── scripts/
-│   ├── cli/           # Command-line tools
-│   └── pipeline/      # Data ingestion pipeline
-├── docs/
-│   ├── VISION-AGENT-LEARNING.md        # Core vision
-│   ├── AGENT-METADATA-PATTERNS.md      # Auto-augmentation design
-│   └── SETUP.md                        # NPM publishing guide
-├── briefs/            # Task specifications
-├── debriefs/          # Reflective documents
-└── playbooks/         # Codified patterns
+Markdown → Parser → [Nodes + Edges] → SQLite
+                  ↓
+              Vector Embeddings (FAFCAS normalized)
+                  ↓
+              Semantic Search → MCP Tools → Agents
 ```
 
-### Key Patterns
+**Key Designs:**
+- **Hollow Nodes:** Metadata in SQLite, content on filesystem (git-friendly)
+- **FAFCAS Protocol:** Normalized vectors enable 10x faster similarity search
+- **Service Daemons:** Background file watching, vector generation, reranking
 
-1.  **Hollow Nodes:** Node metadata in SQLite, content on filesystem
-2.  **FAFCAS Protocol:** Embedding normalization that enables scalar product searches (10x faster than cosine similarity)
-3.  **Micro-Daemon Mesh:**
-    *   **Vector Daemon (3010)**: Embeddings
-    *   **Reranker Daemon (3011)**: Relevance Scoring
-    *   **Sonar Agent (3012)**: Reasoning loop
-4.  **ServiceLifecycle:** Unified daemon management pattern
+👉 **Deep Dive:** [Architecture Documentation](docs/ARCHITECTURE.md)
 
 ## Quick Start
 
@@ -188,18 +256,83 @@ amalfa/
 bun install -g amalfa
 ```
 
+**IMPORTANT**: Amalfa must be installed via **Bun only**. Do not use npm or other package managers.
+
 **Why Bun?**
 - ⚡ **Fast startup** - Critical for stdio-based MCP servers that spawn on every request
 - 🔄 **Built-in daemon management** - Runs background processes for file watching and vector embeddings
 - 📦 **Native TypeScript** - No compilation step, direct execution from source
 - 🎯 **SQLite performance** - Optimized native bindings for database operations
 
+### Uninstalling
+
+```bash
+bun remove -g amalfa
+```
+
+**Note**: Bun and npm maintain separate package registries. If you accidentally tried `npm install -g amalfa`, it won't work. Always use Bun for Amalfa installation and removal.
+
 **From source** (for development):
 ```bash
 git clone https://github.com/pjsvis/amalfa.git
 cd amalfa
-bun install
+bun install  # Must use bun, not npm
+```
+
+### Common Gotchas
+
+#### "I can't uninstall amalfa"
+
+**Problem**: `npm uninstall -g amalfa` does nothing.
+
+**Cause**: Bun and npm are **separate package managers** with separate:
+- Installation directories (`~/.bun/bin/` vs `/usr/local/lib/node_modules/`)
+- Package databases
+- Binary locations
+
+Think of them as **crossed porpoises**—two systems swimming in opposite directions, each functional in its own ecosystem, but never coordinating.
+
+**Solution**: Use the same package manager you installed with:
+```bash
+# If installed with Bun (correct)
+bun remove -g amalfa
+
+# If you somehow have a stale npm install
+npm uninstall -g amalfa
+```
+
+**Check which is active**:
+```bash
+which amalfa
+# ~/.bun/bin/amalfa = Bun install ✓
+# /usr/local/bin/amalfa = npm install (wrong)
+```
+
+#### "amalfa command not found after install"
+
+**Problem**: Shell can't find the `amalfa` binary.
+
+**Cause**: `~/.bun/bin` not in your `$PATH`.
+
+**Solution**: Add to your shell profile (`~/.zshrc` or `~/.bashrc`):
+```bash
+export PATH="$HOME/.bun/bin:$PATH"
 ```
+Then reload: `source ~/.zshrc`
+
+#### "Why can't I use npm? It's on npmjs.org"
+
+**Answer**: Amalfa is **published** to npm (for discoverability) but **requires Bun to run**. This is because:
+- Bun's native TypeScript execution (no build step)
+- Optimized SQLite bindings
+- Daemon lifecycle management
+- Faster stdio transport for MCP
+
+Think of it like a Rust crate that's listed but requires `cargo` to build. npm and Bun are crossed porpoises—both legitimate package managers, but trying to use one to manage the other's installations leads nowhere.
+
+#### "trustedDependencies in package.json?"
+
+These packages (`onnxruntime-node`, `protobufjs`) run native build scripts during `bun install`. Bun blocks untrusted scripts by default. This whitelist lets them compile native bindings for ML operations.
 
 ### Setup MCP Server
 
@@ -213,7 +346,7 @@ bun install
 
 2. **Ingest your markdown**:
    ```bash
-   bun run scripts/cli/ingest.ts
+   amalfa init
    ```
 
 3. **Generate MCP config**:
@@ -255,7 +388,7 @@ bun install
 - [ ] Auto-linking (wiki-style [[links]])
 - [ ] Tag extraction and indexing
 - [ ] Git-based auditing for augmentations
-- [ ] Automated file watcher updates
+- [x] Automated file watcher updates
 
 ### 🚧 Phase 2: Ember Service (Automated Enrichment)
 - ✅ **Analyzer** - Louvain community detection & heuristics
@@ -293,10 +426,11 @@ bun install
 
 ### Prerequisites
 
-- **Bun:** v1.0+ (required)
-- **Node:** v22.x (for compatibility)
+- **Bun:** v1.0+ (required - cannot use npm/yarn/pnpm)
 - **Git:** For version control
 
+**Note**: Node.js is NOT required. Bun replaces Node entirely.
+
 ### Setup
 
 ```bash
@@ -309,26 +443,38 @@ bun install
 
 # Run tests
 bun test
-
-# Start development server
-bun run dev
 ```
 
 ### Commands
 
 ```bash
-# CLI commands (after global install: bun install -g amalfa)
-amalfa init              # Initialize database from markdown
-amalfa serve             # Start MCP server (stdio)
-amalfa stats             # Show database statistics
-amalfa doctor            # Health check
-amalfa servers           # Show all service status (with commands!)
+# Core commands (after global install: bun install -g amalfa)
+amalfa init                      # Initialize database from markdown
+amalfa serve                     # Start MCP server (stdio)
+amalfa stats                     # Show database statistics
+amalfa doctor                    # Health check
+amalfa setup-mcp                 # Generate MCP config
+amalfa --help                    # Show help
+
+# Search commands (CLI mode)
+amalfa search <query>            # Semantic search [--limit N] [--json]
+amalfa read <node-id>            # Read document content [--json]
+amalfa explore <node-id>         # Show related documents [--relation type] [--json]
+amalfa list-sources              # Show configured source directories
+amalfa find-gaps                 # Discover unlinked documents [--limit N] [--threshold T] [--json]
+amalfa inject-tags <path> <tags> # Add metadata to markdown [--json]
+
+# Service management
+amalfa servers           # Show all service status
 amalfa servers --dot     # Generate DOT diagram
-amalfa daemon start      # Start file watcher daemon
-amalfa daemon stop       # Stop file watcher daemon
-amalfa daemon status     # Check daemon status
-amalfa setup-mcp         # Generate MCP config
-amalfa --help            # Show help
+amalfa stop-all          # Stop all running services (alias: kill)
+
+# Individual services (start|stop|status|restart)
+amalfa daemon <action>   # File watcher daemon
+amalfa vector <action>   # Vector embedding daemon
+amalfa reranker <action> # Reranking daemon
+amalfa sonar <action>    # Sonar AI agent
+amalfa ember <action>    # Ember enrichment (scan|squash)
 
 # Local development scripts (bun run <script>)
 bun run servers          # Test servers command
@@ -347,15 +493,16 @@ bun run format           # Biome format
 
 ## Documentation
 
-- **[VISION-AGENT-LEARNING.md](docs/VISION-AGENT-LEARNING.md)** - Why agent-generated knowledge works
-- **[AGENT-METADATA-PATTERNS.md](docs/AGENT-METADATA-PATTERNS.md)** - Auto-augmentation design
-- **[SETUP.md](docs/SETUP.md)** - NPM publishing setup
-
-### Playbooks
+**Core Docs:**
+- [MCP Tools Reference](docs/MCP-TOOLS.md) - Complete guide to agent tools
+- [Architecture Deep Dive](docs/ARCHITECTURE.md) - Technical implementation details
+- [Vision & Philosophy](docs/VISION-AGENT-LEARNING.md) - Why structured reflection works
+- [User Manual](docs/USER-MANUAL.md) - Setup, maintenance, troubleshooting
 
-- **[embeddings-and-fafcas-protocol-playbook.md](playbooks/embeddings-and-fafcas-protocol-playbook.md)** - Vector search patterns
-- **[local-first-vector-db-playbook.md](playbooks/local-first-vector-db-playbook.md)** - Database architecture
-- **[problem-solving-playbook.md](playbooks/problem-solving-playbook.md)** - Debugging strategies
+**Playbooks:**
+- [FAFCAS Protocol](playbooks/embeddings-and-fafcas-protocol-playbook.md) - Vector search optimization
+- [Local-First Architecture](playbooks/local-first-vector-db-playbook.md) - Database patterns
+- [Problem Solving](playbooks/problem-solving-playbook.md) - Debugging strategies
 
 ---