fix(plugins): pin ruflo-ruvector to ruvector@0.2.25 + expand verified CLI surface

The plugin's docs had drifted from the real ruvector CLI: many documented invocations (`embed "TEXT"`, `compare`, `cluster --namespace`, `hooks route --task`, `brain agi status`, `midstream status`, `index create/stats`, `embed --model poincare`) failed with "unknown command" or "unknown option" on the installed ruvector. Probed every subcommand against ruvector@0.2.25 and rewrote the plugin to match reality. Changes: - Pin every `npx ruvector` call to `npx -y ruvector@0.2.25` across README, agent, skills, and commands - Rewrite commands/vector.md with 80+ verified subcommands (embed, db lifecycle, RVF cognitive containers, GNN, attention mechanisms, hooks, native/workers, brain, SONA, LLM, identity, edge, server, decompile, demo) - Add vector-setup skill that installs onnx-embeddings-wasm + pi-brain + ruvllm and registers the MCP server with the pinned version - Add scripts/smoke.sh — 11-check contract test (version pin, top-level surface, positional-arg invariants, removed-surface-stays-removed) - Replace stale "Search Capabilities (v2.1+)" table claiming FlashAttention-3 / Graph RAG / DiskANN / ColBERT / Matryoshka / MLA / TurboQuant as CLI features with an "Attention Mechanisms" table mapped to real `attention compute|benchmark|hyperbolic` invocations - Document known 0.2.25 bugs: `optimize` not yet shipped, `hooks force-learn` TypeError, `hooks graph-mincut` undefined.length, `benchmark` dimension bug, top-level `cluster` "Coming Soon" - Add ADR-0001 documenting the pin policy, optional add-on packages, MCP registration, removed-surface contract, and smoke-test gate - Bump plugin version 0.2.0 → 0.2.1 Smoke: 11/11 passing against ruvector@0.2.25. Co-Authored-By: RuFlo <ruv@ruv.net>
2026-09-14 14:01:28 +08:00 · 2026-05-04 15:56:58 -04:00
parent 1f3b7c8c24
commit 6e1bdc211e
10 changed files with 761 additions and 206 deletions
@@ -1,7 +1,7 @@
 {
  "name": "ruflo-ruvector",
-  "description": "Self-learning vector database via npx ruvector — HNSW, FlashAttention-3, Graph RAG, hybrid search, DiskANN, 103 MCP tools, Brain AGI",
-  "version": "0.2.0",
+  "description": "Self-learning vector database via npx ruvector@0.2.25 — HNSW, adaptive LoRA embeddings, code-graph clustering, hooks routing, brain/SONA, 103 MCP tools",
+  "version": "0.2.1",
  "author": {
    "name": "ruvnet",
    "url": "https://github.com/ruvnet"
@@ -13,11 +13,11 @@
    "ruvector",
    "vector-database",
    "hnsw",
-    "flash-attention",
-    "graph-rag",
-    "hybrid-search",
-    "diskann",
-    "mcp",
-    "brain-agi"
+    "adaptive-lora",
+    "graph-cluster",
+    "hooks",
+    "sona",
+    "brain",
+    "mcp"
  ]
 }
@@ -1,15 +1,28 @@
 # ruflo-ruvector

-Self-learning vector database powered by [`ruvector`](https://www.npmjs.com/package/ruvector) — HNSW, FlashAttention-3, Graph RAG, hybrid search, DiskANN, 103 MCP tools, Brain AGI, and 50+ attention mechanisms.
+Self-learning vector database powered by [`ruvector@0.2.25`](https://www.npmjs.com/package/ruvector) — HNSW, Adaptive LoRA embeddings, hooks-based intelligence, SONA self-optimizing patterns, brain (collective knowledge), and 103 MCP tools.
+
+> **Pinned version:** this plugin targets `ruvector@0.2.25`. Earlier 0.1.x versions are missing several commands (`brain`, `route`, `sona`); some legacy docs referenced 2.x features that do not exist on npm. Always invoke with the pin.

 ## Overview

-Wraps the `ruvector` npm package as a Ruflo plugin, providing vector embedding, semantic search, clustering, hyperbolic space reasoning, self-learning hooks, and Brain AGI diagnostics. ruvector's Rust backend delivers sub-millisecond queries and 52,000+ inserts/sec.
+Wraps the `ruvector` npm package as a Ruflo plugin, providing vector embedding, semantic search, code-graph clustering, hyperbolic projection, self-learning hooks, and SONA / Brain diagnostics. ruvector's Rust backend delivers sub-millisecond queries and 52,000+ inserts/sec.

 ## Prerequisites

 ```bash
-npm install ruvector
+# Required
+npm install ruvector@0.2.25
+
+# Optional add-ons (install as needed)
+npm install ruvector-onnx-embeddings-wasm   # required for `embed text` to work
+npm install @ruvector/pi-brain              # required for `brain` subcommands
+npm install @ruvector/ruvllm                # required for `sona` subcommands (JS fallback)
+```
+
+Run a health check:
+```bash
+npx -y ruvector@0.2.25 doctor
 ```

 ## Installation
@@ -20,107 +33,223 @@ claude --plugin-dir plugins/ruflo-ruvector

 ## MCP Integration (103 Tools)

+Register with the pinned version:
 ```bash
-claude mcp add ruvector -- npx ruvector mcp start
+claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start
 ```

-Key tool categories: hooks routing, AST analysis, diff classification, coverage routing, graph clustering, security scanning, RAG context, brain knowledge, AGI diagnostics, midstream analytics.
+Key tool categories: hooks routing, AST analysis, diff classification, coverage routing, graph clustering, security scanning, RAG context, brain knowledge, SONA learning.

 ## Agents

 | Agent | Model | Role |
 |-------|-------|------|
-| `vector-engineer` | sonnet | Embedding, HNSW indexing, FlashAttention-3, Graph RAG, hybrid search, clustering, hyperbolic space, Brain AGI |
+| `vector-engineer` | sonnet | Embedding, HNSW indexing, code-graph clustering, hyperbolic projection, hooks routing, brain/SONA |

 ## Skills

 | Skill | Usage | Description |
 |-------|-------|-------------|
-| `vector-embed` | `/vector-embed <text-or-file>` | ONNX embeddings (384-dim), normalize, store in HNSW |
-| `vector-cluster` | `/vector-cluster <namespace> [--k N]` | k-means or density clustering with labeled summaries |
-| `vector-hyperbolic` | `/vector-hyperbolic <text>` | Poincare ball hierarchical embeddings |
+| `vector-setup` | `/vector-setup [--full]` | First-run installer: pins `ruvector@0.2.25`, adds ONNX/Brain/SONA/router add-ons, registers MCP, runs `doctor` |
+| `vector-embed` | `/vector-embed <text>` | ONNX embeddings (384-dim) via `embed text` |
+| `vector-cluster` | `/vector-cluster <files...>` | Spectral/Louvain code-graph clustering via `hooks graph-cluster` |
+| `vector-hyperbolic` | `/vector-hyperbolic <text>` | Standard ONNX embed + Poincare projection in user code |

-## Commands
+## Commands (`/vector` slash command)
+
+The full surface is documented in `commands/vector.md` (80+ subcommands). Quick reference:

 ```bash
 # Embedding
-vector embed <text>
-vector batch <glob-pattern>
-vector compare <text1> <text2>
+/vector embed <text>                 # ruvector embed text "<text>"
+/vector embed-adaptive <text>        # ruvector embed text "<text>" --adaptive --domain code
+/vector embed-file <path>            # read file, pass content as text
+/vector embed-benchmark              # ruvector embed benchmark

-# Search
-vector search <query> [--limit N] [--hybrid] [--graph-rag]
+# Database lifecycle
+/vector db create <path>             # ruvector create <path> -d 384 -m cosine
+/vector db stats <path>              # ruvector stats <path>
+/vector insert <db> <json>           # ruvector insert <db> <json>
+/vector search <db> <vector-json>    # ruvector search <db> -v <json> -k N
+/vector export <db>                  # ruvector export <db> -o backup.json
+/vector import <file>                # ruvector import <file> -d <database>

-# Clustering
-vector cluster <namespace> [--k N | --density]
+# RVF cognitive containers (45 example stores)
+/vector rvf create|ingest|query|status|segments|derive|compact|export|examples|download

-# Index management
-vector index create <name>
-vector index stats <name>
+# GNN + attention (real native bindings)
+/vector gnn info|layer|search|compress
+/vector attention list|compute|benchmark|hyperbolic|info

-# Hyperbolic
-vector hyperbolic embed <text>
+# Code intelligence (hooks)
+/vector ast <file>                   # ruvector hooks ast-analyze <file>
+/vector hooks ast-complexity <files...>
+/vector hooks coverage-route <file> | coverage-suggest <files...>
+/vector hooks rag-context <query>
+/vector hooks route|route-enhanced|suggest-context
+/vector cluster <files...>           # ruvector hooks graph-cluster <files>
+/vector hooks security-scan <files...>
+/vector hooks diff-analyze|diff-classify|diff-similar [commit]
+/vector hooks remember|recall <query>
+/vector hooks coedit-record|coedit-suggest|error-record|error-suggest
+/vector hooks trajectory-begin|trajectory-step|trajectory-end

-# Self-learning hooks
-vector hooks init
-vector hooks route <task>
-vector ast <file>
+# Native + workers
+/vector native list|run <type>|benchmark|compare
+/vector workers triggers|presets|phases|dispatch|status|...

-# Brain AGI
-vector brain status
-vector midstream status
+# Collective intelligence
+/vector brain status|search|share|list|drift|partition|transfer|sync|page  (needs @ruvector/pi-brain)
+/vector sona status|info|stats|patterns|train|export                       (needs @ruvector/ruvllm)
+/vector llm models|embed|benchmark|info                                    (needs @ruvector/ruvllm)
+
+# Identity + edge compute (pi network)
+/vector identity generate|show|export|import
+/vector edge status|balance|tasks|join|dashboard
+
+# Server / decompile / demo / system
+/vector server [-p 8080] [-g 50051]
+/vector decompile <npm-pkg-or-file-or-url>
+/vector demo --basic | --gnn | --graph
+/vector doctor | info | benchmark | install | setup
 ```

-## Search Capabilities (ruvector v2.1+)
+## End-to-End Example: store + search project files

-| Feature | Description | Improvement |
-|---------|-------------|-------------|
-| FlashAttention-3 | IO-aware tiled attention | O(N) memory vs O(N^2) |
-| Graph RAG | Knowledge graph + community detection | 30-60% better multi-hop |
-| Hybrid Search | Sparse + dense with RRF fusion | 20-49% better retrieval |
-| DiskANN / Vamana | SSD-friendly ANN with PQ compression | Large-scale search |
-| ColBERT | Per-token late interaction | Fine-grained matching |
-| Matryoshka | Adaptive-dimension with cascade | Flexible precision |
-| MLA | Multi-Head Latent Attention | ~93% KV-cache compression |
-| TurboQuant | 2-4 bit quantization | 6-8x memory reduction |
+```bash
+# 0. One-time setup
+/vector-setup
+
+# 1. Create a database
+npx -y ruvector@0.2.25 create project.db -d 384 -m cosine
+
+# 2. Embed every TypeScript source file (loop — no built-in --batch)
+mkdir -p .vec
+for f in $(find src -name '*.ts'); do
+  npx -y ruvector@0.2.25 embed text "$(cat "$f")" -o ".vec/${f//\//_}.json"
+done
+
+# 3. Insert all embeddings (assumes a JSON array of {id, vector, metadata})
+jq -s '[.[] | {id: input_filename, vector: .vector}]' .vec/*.json > corpus.json
+npx -y ruvector@0.2.25 insert project.db corpus.json
+
+# 4. Search by query embedding
+QV=$(npx -y ruvector@0.2.25 embed text "JWT refresh-token rotation" --output -)
+npx -y ruvector@0.2.25 search project.db -v "$QV" -k 5
+
+# 5. Inspect index health
+npx -y ruvector@0.2.25 stats project.db
+```
+
+For an alternative store format with lineage tracking, replace steps 1–3 with:
+```bash
+npx -y ruvector@0.2.25 rvf create project.rvf
+npx -y ruvector@0.2.25 rvf ingest project.rvf < corpus.json
+npx -y ruvector@0.2.25 rvf query project.rvf
+```
+
+## Capabilities (ruvector@0.2.25, verified)
+
+| Feature | CLI | Notes |
+|---------|-----|-------|
+| HNSW search | `search <db> -v ... -k N` | ~0.045ms latency |
+| Adaptive LoRA embeddings | `embed text "..." --adaptive --domain code` | LoRA-tuned |
+| Distance metrics | `create <path> -m cosine\|euclidean\|dot` | set at create time |
+| RVF cognitive containers | `rvf create|ingest|query|derive|compact` | 45 example stores via `rvf examples` |
+| Attention mechanisms | `attention list` | DotProduct, MultiHead, Flash, Hyperbolic, Linear, MoE, GraphRoPe, EdgeFeatured, DualSpace, LocalGlobal |
+| GNN ops | `gnn layer|search|compress` | multi-head attention layers, differentiable search, tensor compression |
+| Code-graph clustering | `hooks graph-cluster <files>` | spectral / Louvain |
+| Diff embeddings | `hooks diff-analyze|diff-classify|diff-similar` | git-aware |
+| Coverage-aware routing | `hooks coverage-route|coverage-suggest` | test-gap-aware |
+| RAG context | `hooks rag-context "query"` | works in CLI and MCP |
+| AST analysis | `hooks ast-analyze|ast-complexity` | symbols, complexity, parse time |
+| Self-learning loop | `hooks remember|recall|coedit-*|error-*|trajectory-*` | persistent intelligence |
+| Native workers | `native list|run <security|analysis|learning>` | no external deps |
+| Background workers | `workers dispatch|status|presets|phases` | first run installs `agentic-flow` |
+| Decompile npm/JS | `decompile <target>` | inspect upstream packages |
+| Server | `server -p 8080` | HTTP/gRPC mode |
+| Demo | `demo --basic|--gnn|--graph` | interactive tutorial |
+| Identity (pi key) | `identity generate|show|export|import` | for brain + edge |
+| Edge compute | `edge status|balance|tasks|join` | distributed, rUv currency |
+
+### Known limitations / bugs in 0.2.25
+
+| Issue | Detail | Workaround |
+|-------|--------|-----------|
+| ONNX runtime missing | `embed text` → `ONNX WASM files not bundled` | `npm i ruvector-onnx-embeddings-wasm` (see `/vector-setup`) |
+| `optimize` | Self-reports "not yet shipped in this release" | none — track upstream issue 401 |
+| `hooks force-learn` | TypeError `intel.tick is not a function` | run a real trajectory via `trajectory-begin/step/end` |
+| `hooks graph-mincut` | `Cannot read properties of undefined (reading 'length')` | use `hooks graph-cluster` |
+| `hooks git-churn` | Fails outside a git repo | run from inside the repo |
+| `benchmark` | Some installs fail with `Missing field 'dimensions'` | use `attention benchmark` or `gnn search` benchmarking |
+| `cluster` (top-level) | `Status: Coming Soon` | use `hooks graph-cluster` |
+| `compare`, top-level `index`, `midstream`, `embed --file/--batch/--glob/--model poincare` | Don't exist | see `commands/vector.md` for replacements |

 ## Self-Learning Hooks

 ```bash
-# Full 9-phase pretrain pipeline
-npx ruvector hooks init --pretrain --build-agents quality
+# Full pretrain pipeline + agent generation
+npx -y ruvector@0.2.25 hooks init --pretrain --build-agents quality

-# Smart agent routing
-npx ruvector hooks route --task "description"
+# Smart agent routing (positional task!)
+npx -y ruvector@0.2.25 hooks route "implement OAuth flow"
+npx -y ruvector@0.2.25 hooks route-enhanced "fix CVE-2025-1234"

-# Code analysis
-npx ruvector hooks ast-analyze --file src/module.ts
-npx ruvector hooks diff-analyze --file src/module.ts
-npx ruvector hooks coverage-route --task "description"
-npx ruvector hooks security-scan --path src/
+# Code analysis (positional file!)
+npx -y ruvector@0.2.25 hooks ast-analyze src/module.ts
+npx -y ruvector@0.2.25 hooks diff-analyze HEAD
+npx -y ruvector@0.2.25 hooks coverage-route src/module.ts
+npx -y ruvector@0.2.25 hooks security-scan src/
 ```

-## Brain AGI
-
-Access 8 AGI subsystems:
+## Brain (Collective Knowledge)

 ```bash
-npx ruvector brain agi status      # Combined diagnostics
-npx ruvector brain agi sona        # SONA patterns and trajectories
-npx ruvector brain agi temporal    # Knowledge evolution velocity
-npx ruvector brain agi explore     # Meta-learning curiosity & regret
-npx ruvector brain search "query"  # Shared brain knowledge search
+npm install @ruvector/pi-brain   # required dependency
+
+npx -y ruvector@0.2.25 brain status
+npx -y ruvector@0.2.25 brain search "authentication patterns"
+npx -y ruvector@0.2.25 brain list
+npx -y ruvector@0.2.25 brain drift code   # knowledge drift for a domain
+```
+
+## SONA (Self-Optimizing Neural Architecture)
+
+```bash
+npx -y ruvector@0.2.25 sona status
+npx -y ruvector@0.2.25 sona patterns "auth refactor"
+npx -y ruvector@0.2.25 sona stats
 ```

 ## Performance

 | Operation | Latency | Notes |
 |-----------|---------|-------|
-| HNSW search | ~0.045ms | 8,800x vs inference |
-| Memory cache | ~0.01ms | 40,000x vs inference |
-| Insert | 52,000+/sec | Rust backend |
+| HNSW search | ~0.045ms | 8,800x vs ONNX inference |
+| Memory cache | ~0.01ms | 40,000x vs ONNX inference |
+| Insert | 52,000+/sec | Rust backend (`@ruvector/core`) |
 | Memory per vector | ~50 bytes | Efficient storage |

+## Known Caveats
+
+- **ONNX runtime not bundled by default** — `embed text` will report `ONNX WASM files not bundled` until you install `ruvector-onnx-embeddings-wasm`.
+- **No `--file`, `--batch`, `--glob`, `--namespace`, `--k`, `--task`, `--model poincare` flags** — these were in older docs but never shipped in 0.2.25. See `agents/vector-engineer.md` for the replacement table.
+- **`brain` requires `@ruvector/pi-brain`** — install separately.
+- **`sona` requires `@ruvector/ruvllm`** — install separately (the native binding is not always present in the npm tarball).
+- **Top-level `cluster` is "Coming Soon"** — for actual clustering use `hooks graph-cluster <files>`.
+- **`compare`, `midstream`, top-level `index` subcommands do not exist.**
+
+## Architecture Decisions
+
+- [`ADR-0001` — Pin ruflo-ruvector to ruvector@0.2.25 with optional add-ons](./docs/adrs/0001-pin-ruvector-0.2.25.md)
+
+## Smoke test
+
+```bash
+bash plugins/ruflo-ruvector/scripts/smoke.sh
+# Expected: "11 passed, 0 failed"
+```
+
 ## Related Plugins

 - `ruflo-agentdb` — HNSW storage backend in AgentDB
@@ -1,47 +1,57 @@
 ---
 name: vector-engineer
-description: Vector operations specialist using npx ruvector — HNSW indexing, FlashAttention-3, Graph RAG, hybrid search, DiskANN, Brain AGI, 103 MCP tools
+description: Vector operations specialist using npx ruvector@0.2.25 — HNSW indexing, adaptive LoRA embeddings, code-graph clustering, hooks routing, brain/SONA, 103 MCP tools
 model: sonnet
 ---

 You are a vector engineer that orchestrates the `ruvector` npm package for embedding, indexing, search, clustering, and self-learning intelligence.

-### Core Tool: npx ruvector
+### Core Tool: npx ruvector@0.2.25 (PINNED)

-All vector operations go through the `ruvector` CLI. Install once, then invoke via npx:
+All vector operations go through the `ruvector` CLI, pinned to **0.2.25**. Install once, then always invoke with the version pin:

 ```bash
-# Ensure installed
-npm ls ruvector 2>/dev/null || npm install ruvector
+# Ensure pinned version installed
+npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install ruvector@0.2.25

-# MCP server (103 tools)
-npx ruvector mcp start
+# MCP server (register once with pinned version)
+claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start

-# Hooks system (self-learning)
-npx ruvector hooks init --pretrain --build-agents quality
-npx ruvector hooks route --task "description"
-npx ruvector hooks ast-analyze --file src/module.ts
-npx ruvector hooks diff-analyze --file src/module.ts
-npx ruvector hooks coverage-route --task "description"
+# Hooks system (self-learning) — note: positional args, NOT --task / --file
+npx -y ruvector@0.2.25 hooks init --pretrain --build-agents quality
+npx -y ruvector@0.2.25 hooks route "description"
+npx -y ruvector@0.2.25 hooks route-enhanced "description"
+npx -y ruvector@0.2.25 hooks ast-analyze src/module.ts
+npx -y ruvector@0.2.25 hooks diff-analyze HEAD
+npx -y ruvector@0.2.25 hooks diff-classify HEAD
+npx -y ruvector@0.2.25 hooks coverage-route src/module.ts
+npx -y ruvector@0.2.25 hooks security-scan src/

-# Brain AGI
-npx ruvector brain agi status
-npx ruvector brain agi sona
-npx ruvector brain agi temporal
-npx ruvector brain agi explore
+# Brain (collective knowledge — requires @ruvector/pi-brain)
+npm install @ruvector/pi-brain
+npx -y ruvector@0.2.25 brain status
+npx -y ruvector@0.2.25 brain search "query"
+npx -y ruvector@0.2.25 brain list

-# Midstream
-npx ruvector midstream status
-npx ruvector midstream benchmark
+# SONA (Self-Optimizing Neural Architecture)
+npx -y ruvector@0.2.25 sona status
+npx -y ruvector@0.2.25 sona patterns "query"
+npx -y ruvector@0.2.25 sona stats
+
+# System diagnostics
+npx -y ruvector@0.2.25 doctor
+npx -y ruvector@0.2.25 info
 ```

 ### MCP Integration

-ruvector exposes 103 MCP tools. Add as MCP server for direct tool access:
+ruvector@0.2.25 exposes 103 MCP tools. Register the MCP server with the pinned version:
 ```bash
-claude mcp add ruvector -- npx ruvector mcp start
+claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start
 ```

+Verify after registration: `claude mcp list | grep ruvector`.
+
 Key tool categories:
 - `hooks_route`, `hooks_route_enhanced` — smart agent routing
 - `hooks_ast_analyze`, `hooks_ast_complexity` — code structure analysis
@@ -50,21 +60,33 @@ Key tool categories:
 - `hooks_graph_mincut`, `hooks_graph_cluster` — code boundaries
 - `hooks_security_scan` — vulnerability detection
 - `hooks_rag_context` — semantic context retrieval
- `brain_search`, `brain_share`, `brain_status` — shared brain knowledge
- `brain_agi_status`, `brain_sona_stats` — AGI diagnostics
+- `brain_search`, `brain_share`, `brain_status` — shared brain knowledge (needs `@ruvector/pi-brain`)
+- `sona_status`, `sona_patterns`, `sona_stats` — SONA learning (needs `@ruvector/ruvllm`)
+- `attention_list`, `attention_compute` — attention mechanism dispatch
+- `gnn_info`, `gnn_layer`, `gnn_search` — graph neural net ops
+- `rvf_create`, `rvf_query`, `rvf_status` — cognitive container management

-### Search Capabilities (ruvector v2.1+)
+### Attention Mechanisms (verified via `attention list` on 0.2.25)

-| Feature | Description | Improvement |
-|---------|-------------|-------------|
-| FlashAttention-3 | IO-aware tiled attention, O(N) memory | Replaces O(N^2) |
-| Graph RAG | Knowledge graph + community detection | 30-60% better multi-hop |
-| Hybrid Search | Sparse + dense with RRF fusion | 20-49% better retrieval |
-| DiskANN / Vamana | SSD-friendly ANN with PQ compression | Large-scale search |
-| ColBERT | Per-token late interaction (MaxSim) | Fine-grained matching |
-| Matryoshka | Adaptive-dimension with cascade | Flexible precision |
-| MLA | Multi-Head Latent Attention | ~93% KV-cache compression |
-| TurboQuant | 2-4 bit KV-cache quantization | 6-8x memory reduction |
+```bash
+npx -y ruvector@0.2.25 attention list
+```
+Reports the available mechanisms. Each is a real Rust binding; the CLI exposes `attention compute|benchmark|hyperbolic` to invoke them.
+
+| Mechanism | Complexity | CLI surface |
+|---|---|---|
+| `DotProductAttention` | O(n²) | `attention compute` |
+| `MultiHeadAttention` | O(n²) | `attention compute` |
+| `FlashAttention` | O(n²) IO-optimized | `attention compute` / `attention benchmark` |
+| `HyperbolicAttention` | O(n²) | `attention hyperbolic` |
+| `LinearAttention` | O(n) | `attention compute` |
+| `MoEAttention` | O(n*k) | `attention compute` |
+| `GraphRoPeAttention` | O(n²) | `attention compute` |
+| `EdgeFeaturedAttention` | O(n²) | `attention compute` |
+| `DualSpaceAttention` | O(n²) | `attention compute` |
+| `LocalGlobalAttention` | O(n*k) | `attention compute` |
+
+> Earlier docs claimed ruvector exposed `Graph RAG`, `Hybrid Search`, `DiskANN`, `ColBERT`, `Matryoshka`, `MLA`, `TurboQuant` as standalone search modes. As of 0.2.25 the **CLI does not surface them as subcommands**. They are either Rust primitives reachable through the native API or planned upstream features. Use `hooks rag-context` for the closest CLI-level RAG capability.

 ### HNSW Parameters Guide

@@ -78,26 +100,49 @@ Key tool categories:

 ruvector's 9-phase pretrain pipeline:
 ```bash
-npx ruvector hooks init --pretrain --build-agents quality
+npx -y ruvector@0.2.25 hooks init --pretrain --build-agents quality
 ```
 Phases: AST analysis, diff embeddings, coverage routing, neural training, graph analysis, security scanning, co-edit pattern learning, agent building, RAG context indexing.

-### Embedding Operations
+### Embedding Operations (ruvector@0.2.25)

 ```bash
 # Single text embedding (ONNX all-MiniLM-L6-v2, 384-dim)
-npx ruvector embed "your text here"
+# NOTE: subcommand is `embed text`, text is positional. There is no `embed "TEXT"` form.
+npx -y ruvector@0.2.25 embed text "your text here"
+npx -y ruvector@0.2.25 embed text "your text" --adaptive --domain code -o vec.json

-# Batch embedding
-npx ruvector embed --batch --glob "src/**/*.ts"
+# Batch — no built-in glob; loop yourself:
+for f in src/**/*.ts; do
+  npx -y ruvector@0.2.25 embed text "$(cat "$f")" -o "${f}.vec.json"
+done

-# Similarity search
-npx ruvector search "query text" --limit 10
+# Similarity search — requires an existing database and a JSON-encoded query vector
+npx -y ruvector@0.2.25 create my.db -d 384 -m cosine
+npx -y ruvector@0.2.25 insert my.db vectors.json
+npx -y ruvector@0.2.25 search my.db -v '[0.1,0.2,...]' -k 10

-# Compare two texts
-npx ruvector compare "text1" "text2"
+# Compare two texts — no top-level `compare` subcommand exists in 0.2.25.
+# Embed both and compute cosine similarity in your own code or via MCP `hooks_rag_context`.
 ```

+### Removed / Renamed CLI Surface (was in older docs, NOT in 0.2.25)
+
+| Old form (broken) | Replacement |
+|-------------------|-------------|
+| `ruvector embed "TEXT"` | `ruvector embed text "TEXT"` |
+| `ruvector embed --file F` | Read F yourself, pass content as text arg |
+| `ruvector embed --batch --glob G` | Shell loop over glob |
+| `ruvector compare A B` | Embed both, compute cosine in user code |
+| `ruvector index create N` | `ruvector create <path> -d 384` |
+| `ruvector index stats N` | `ruvector stats <path>` |
+| `ruvector cluster --namespace N --k K` | `ruvector hooks graph-cluster <files>` |
+| `ruvector embed --model poincare T` | Embed normally, project to Poincare in user code |
+| `ruvector hooks route --task X` | `ruvector hooks route "X"` (positional) |
+| `ruvector hooks ast-analyze --file F` | `ruvector hooks ast-analyze F` (positional) |
+| `ruvector brain agi status` | `ruvector brain status` (needs `@ruvector/pi-brain`) |
+| `ruvector midstream status` | (no replacement — command not present) |
+
 ### Performance (ruvector benchmarks)

 | Operation | Latency | Throughput |
@@ -108,18 +153,23 @@ npx ruvector compare "text1" "text2"
 | Insert | - | 52,000+ vectors/sec |
 | Memory per vector | ~50 bytes | - |

-### Clustering
+### Clustering (code graph only in 0.2.25)

- **k-means**: `npx ruvector cluster --namespace patterns --k 5`
- **Density (DBSCAN)**: `npx ruvector cluster --namespace patterns --density`
+The top-level `cluster` subcommand is reserved for distributed cluster ops ("Coming Soon"). For actual community detection over a code graph use:
+```bash
+npx -y ruvector@0.2.25 hooks graph-cluster <files...>   # spectral / Louvain
+npx -y ruvector@0.2.25 hooks graph-mincut   <files...>  # min-cut boundaries
+```
+For namespaced k-means / DBSCAN over arbitrary embeddings, run the algorithm in your own code against vectors stored in AgentDB.

 ### Hyperbolic Embeddings (Poincare Ball)

-For hierarchical data (dependency trees, taxonomies, module structures):
+ruvector@0.2.25 has no `--model poincare` flag. For hierarchical data, embed normally and project to the Poincare ball in your own code:
 ```bash
-npx ruvector embed --model poincare "hierarchical concept"
-npx ruvector search --model poincare "query" --limit 10
+npx -y ruvector@0.2.25 embed text "hierarchical concept" -o concept.vec.json
+# then normalize to live inside the unit ball: x_i / (||x|| * (1 + epsilon))
 ```
+The experimental neural substrate (`embed neural --help`) may expose richer projections in future versions.

 ### Memory Persistence

@@ -1,67 +1,155 @@
 ---
 name: vector
-description: RuVector operations via npx ruvector — embedding, search, clustering, indexing, hyperbolic, hooks, brain AGI
+description: RuVector operations via npx ruvector@0.2.25 — embedding, search, RVF cognitive containers, GNN, attention, hooks, brain, sona, edge, identity
 ---

 $ARGUMENTS
-Vector operations via the `ruvector` npm package. Parse subcommand from $ARGUMENTS.
+Vector operations via the `ruvector` npm package (pinned to 0.2.25). Parse subcommand from $ARGUMENTS.
+
+Pinned version: `ruvector@0.2.25` — every command below uses `npx -y ruvector@0.2.25 ...`.

 Usage: /vector <subcommand> [options]

-Subcommands:
+## Embedding

-1. For **embed `<text>`**:
-   Run: `npx ruvector embed "TEXT"`
-   For files: `npx ruvector embed --file src/module.ts`
-   Return the 384-dim vector and confirm storage.
+1. **embed `<text>`** — `npx -y ruvector@0.2.25 embed text "TEXT"`
+   384-dim ONNX vector. If `ONNX WASM files not bundled`, run `/vector setup`.
+2. **embed-adaptive `<text>`** — `npx -y ruvector@0.2.25 embed text "TEXT" --adaptive --domain code`
+   LoRA-adapted embedding tuned to a domain.
+3. **embed-file `<path>`** — Read file, then `npx -y ruvector@0.2.25 embed text "$(cat <path>)" -o <path>.vec.json`
+4. **embed-benchmark** — `npx -y ruvector@0.2.25 embed benchmark` (compares base vs adaptive).

-2. For **batch `<glob-pattern>`**:
-   Run: `npx ruvector embed --batch --glob "PATTERN"`
-   Report count of vectors inserted and index size.
+## Database lifecycle

-3. For **search `<query>` [--limit N]**:
-   Run: `npx ruvector search "QUERY" --limit N`
-   Present results ranked by similarity score.
-   For hybrid search: `npx ruvector search "QUERY" --hybrid`
-   For Graph RAG: `npx ruvector search "QUERY" --graph-rag`
+5. **db create `<path>`** — `npx -y ruvector@0.2.25 create <path> -d 384 -m cosine`
+6. **db stats `<path>`** — `npx -y ruvector@0.2.25 stats <path>`
+7. **insert `<database>` `<json-file>`** — `npx -y ruvector@0.2.25 insert <database> <json-file>`
+8. **search `<database>` `<vector-json>` [-k N]** — `npx -y ruvector@0.2.25 search <database> -v '[0.1,...]' -k N`
+9. **export `<database>` [-o file] [-f json|binary|parquet] [--compress]** — `npx -y ruvector@0.2.25 export <database> -o backup.json`
+10. **import `<file>` [-d database]** — `npx -y ruvector@0.2.25 import <file> -d <database> [--merge|--replace]`

-4. For **compare `<text1>` `<text2>`**:
-   Run: `npx ruvector compare "TEXT1" "TEXT2"`
-   Report cosine similarity as decimal and percentage.
+## RVF (cognitive containers)

-5. For **cluster `<namespace>` [--k N]**:
-   Run: `npx ruvector cluster --namespace NAMESPACE --k N`
-   Without --k, uses density clustering: `npx ruvector cluster --namespace NAMESPACE --density`
-   Present cluster summaries with labels, counts, and cohesion.
+11. **rvf create `<path>`** — `npx -y ruvector@0.2.25 rvf create <path>`
+12. **rvf ingest `<path>`** — `npx -y ruvector@0.2.25 rvf ingest <path>`
+13. **rvf query `<path>`** — `npx -y ruvector@0.2.25 rvf query <path>` (nearest neighbors)
+14. **rvf status `<path>`** — `npx -y ruvector@0.2.25 rvf status <path>`
+15. **rvf segments `<path>`** — `npx -y ruvector@0.2.25 rvf segments <path>`
+16. **rvf derive `<parent>` `<child>`** — `npx -y ruvector@0.2.25 rvf derive <parent> <child>` (lineage tracking)
+17. **rvf compact `<path>`** — `npx -y ruvector@0.2.25 rvf compact <path>` (reclaim deleted space)
+18. **rvf examples** — `npx -y ruvector@0.2.25 rvf examples` (45 reference stores)
+19. **rvf download `<name>`** — `npx -y ruvector@0.2.25 rvf download <name>` (e.g. `agent_memory`, `swarm_knowledge`)

-6. For **index create `<name>`**:
-   Run: `npx ruvector index create NAME --M 16 --efConstruction 200`
-   Confirm creation with parameters.
+## GNN (Graph Neural Networks)

-7. For **index stats `<name>`**:
-   Run: `npx ruvector index stats NAME`
-   Report vector count, dimension, M, efConstruction, memory usage.
+20. **gnn info** — `npx -y ruvector@0.2.25 gnn info`
+21. **gnn layer** — `npx -y ruvector@0.2.25 gnn layer` (build/test a multi-head attention GNN layer)
+22. **gnn search** — `npx -y ruvector@0.2.25 gnn search` (differentiable soft-attention search)
+23. **gnn compress** — `npx -y ruvector@0.2.25 gnn compress` (5-level adaptive tensor compression)

-8. For **hyperbolic embed `<text>`**:
-   Run: `npx ruvector embed --model poincare "TEXT"`
-   Return Poincare ball coordinates.
+## Attention mechanisms

-9. For **hooks init**:
-   Run: `npx ruvector hooks init --pretrain --build-agents quality`
-   Initialize self-learning with 9-phase pretrain pipeline.
+24. **attention list** — `npx -y ruvector@0.2.25 attention list`
+    Lists ALL available mechanisms: DotProduct, MultiHead, Flash, Hyperbolic, Linear, MoE, GraphRoPe, EdgeFeatured, DualSpace, LocalGlobal.
+25. **attention compute** — `npx -y ruvector@0.2.25 attention compute`
+26. **attention benchmark** — `npx -y ruvector@0.2.25 attention benchmark`
+27. **attention hyperbolic** — `npx -y ruvector@0.2.25 attention hyperbolic` (Poincare-ball geometry ops; the real hyperbolic surface in 0.2.25)
+28. **attention info** — `npx -y ruvector@0.2.25 attention info`

-10. For **hooks route `<task>`**:
-    Run: `npx ruvector hooks route --task "DESCRIPTION"`
-    Return smart agent routing recommendation.
+## Code intelligence (hooks)

-11. For **ast `<file>`**:
-    Run: `npx ruvector hooks ast-analyze --file FILE`
-    Return AST analysis with symbols, complexity, imports.
+29. **hooks init** — `npx -y ruvector@0.2.25 hooks init --pretrain --build-agents quality`
+30. **hooks stats** — `npx -y ruvector@0.2.25 hooks stats` (Q-learning patterns, vector memories, trajectories)
+31. **hooks route `<task>`** — `npx -y ruvector@0.2.25 hooks route "DESCRIPTION"` (positional)
+32. **hooks route-enhanced `<task>`** — `npx -y ruvector@0.2.25 hooks route-enhanced "DESCRIPTION"`
+33. **hooks suggest-context** — `npx -y ruvector@0.2.25 hooks suggest-context`
+34. **hooks ast-analyze `<file>`** — `npx -y ruvector@0.2.25 hooks ast-analyze <file>` (positional)
+35. **hooks ast-complexity `<files...>`** — `npx -y ruvector@0.2.25 hooks ast-complexity <files...>`
+36. **hooks diff-analyze [commit]** — `npx -y ruvector@0.2.25 hooks diff-analyze HEAD`
+37. **hooks diff-classify [commit]** — `npx -y ruvector@0.2.25 hooks diff-classify HEAD`
+38. **hooks diff-similar** — `npx -y ruvector@0.2.25 hooks diff-similar`
+39. **hooks coverage-route `<file>`** — `npx -y ruvector@0.2.25 hooks coverage-route <file>`
+40. **hooks coverage-suggest `<files...>`** — `npx -y ruvector@0.2.25 hooks coverage-suggest <files...>`
+41. **hooks graph-cluster `<files...>`** — `npx -y ruvector@0.2.25 hooks graph-cluster <files...>` (spectral/Louvain)
+42. **hooks rag-context `<query>`** — `npx -y ruvector@0.2.25 hooks rag-context "QUERY"`
+43. **hooks security-scan `<files...>`** — `npx -y ruvector@0.2.25 hooks security-scan <files...>` (run `hooks init` first)
+44. **hooks remember `<content>`** — `npx -y ruvector@0.2.25 hooks remember "CONTENT"`
+45. **hooks recall `<query>`** — `npx -y ruvector@0.2.25 hooks recall "QUERY"`
+46. **hooks coedit-record / coedit-suggest** — record + retrieve files edited together.
+47. **hooks error-record / error-suggest** — learn error→fix pairs and retrieve.
+48. **hooks trajectory-begin / trajectory-step / trajectory-end** — record an execution trajectory.
+49. **hooks pre-edit / post-edit / pre-command / post-command / session-start / session-end** — Claude Code hook lifecycle.

-12. For **brain status**:
-    Run: `npx ruvector brain agi status`
-    Show AGI subsystem diagnostics.
+> **Known bugs in 0.2.25 hooks:** `force-learn` raises `intel.tick is not a function`; `graph-mincut` raises `Cannot read properties of undefined`; `git-churn` fails outside a git repo. Avoid these or run inside a git repo with seeded intelligence state.

-13. For **midstream status**:
-    Run: `npx ruvector midstream status`
-    Show streaming analysis platform overview.
+## Native + workers (background analysis)
+
+50. **native list** — `npx -y ruvector@0.2.25 native list` (worker types: security, analysis, learning)
+51. **native run `<type>`** — `npx -y ruvector@0.2.25 native run security` (or analysis|learning)
+52. **native benchmark** — `npx -y ruvector@0.2.25 native benchmark`
+53. **native compare** — `npx -y ruvector@0.2.25 native compare`
+54. **workers triggers / presets / phases / dispatch / status / stats / cleanup / cancel / run / create / init-config** — all available via `npx -y ruvector@0.2.25 workers <subcmd>`. First invocation auto-installs `agentic-flow` (slow).
+
+## Collective knowledge (brain) — needs `@ruvector/pi-brain`
+
+55. **brain status** — `npx -y ruvector@0.2.25 brain status`
+56. **brain search `<query>`** — `npx -y ruvector@0.2.25 brain search "QUERY"`
+57. **brain share `<title>`** — `npx -y ruvector@0.2.25 brain share "TITLE"`
+58. **brain list / get / vote / delete / drift / partition / transfer / sync / page** — full Brainpedia + LoRA-weight management.
+
+## SONA (Self-Optimizing Neural Architecture) — needs `@ruvector/ruvllm`
+
+59. **sona status / info / stats** — `npx -y ruvector@0.2.25 sona status`
+60. **sona patterns `<query>`** — `npx -y ruvector@0.2.25 sona patterns "QUERY"`
+61. **sona train `<data>`** — `npx -y ruvector@0.2.25 sona train <data>` (record a training trajectory)
+62. **sona export** — `npx -y ruvector@0.2.25 sona export` (export learned weights)
+
+## LLM orchestration — needs `@ruvector/ruvllm`
+
+63. **llm models** — `npx -y ruvector@0.2.25 llm models`
+64. **llm embed `<text>`** — `npx -y ruvector@0.2.25 llm embed "TEXT"` (RuvLLM-backed embeddings)
+65. **llm benchmark** — `npx -y ruvector@0.2.25 llm benchmark`
+66. **llm info** — `npx -y ruvector@0.2.25 llm info`
+
+## Identity (pi key for brain/edge/MCP)
+
+67. **identity generate** — `npx -y ruvector@0.2.25 identity generate` (creates a 64-hex-char pi key)
+68. **identity show** — `npx -y ruvector@0.2.25 identity show`
+69. **identity export `-o file`** — `npx -y ruvector@0.2.25 identity export -o key.enc` (encrypted backup)
+70. **identity import `<file>`** — `npx -y ruvector@0.2.25 identity import <file>`
+
+## Edge compute network
+
+71. **edge status** — `npx -y ruvector@0.2.25 edge status`
+72. **edge balance [nodeId]** — `npx -y ruvector@0.2.25 edge balance` (rUv balance)
+73. **edge tasks** — `npx -y ruvector@0.2.25 edge tasks`
+74. **edge join** — `npx -y ruvector@0.2.25 edge join` (join the network as a node)
+75. **edge dashboard** — `npx -y ruvector@0.2.25 edge dashboard` (opens in browser)
+
+## Server / Decompile / Demo
+
+76. **server [-p 8080] [-g 50051] [-d data-dir]** — `npx -y ruvector@0.2.25 server -p 8080`
+77. **decompile `<target>` [-o dir] [-f modules|single|json]** — `npx -y ruvector@0.2.25 decompile <npm-pkg-or-file-or-url>`
+78. **demo --basic | --gnn | --graph** — `npx -y ruvector@0.2.25 demo --basic` (interactive tutorial)
+
+## System
+
+79. **doctor** — `npx -y ruvector@0.2.25 doctor` (Node, npm, bindings, Rust)
+80. **info** — `npx -y ruvector@0.2.25 info`
+81. **benchmark** — `npx -y ruvector@0.2.25 benchmark` (known issue: fails with `Missing field 'dimensions'` on some installs; use `gnn search` or `attention benchmark` as alternatives)
+82. **install [pkg|--all]** — `npx -y ruvector@0.2.25 install --all` (lists/installs optional add-ons)
+83. **setup** — `npx -y ruvector@0.2.25 setup` (Setup Guide)
+
+## Setup helper
+
+For first-run users hitting `ONNX WASM files not bundled`, `Brain commands require @ruvector/pi-brain`, or `SONA not available`, invoke the `vector-setup` skill: `/vector-setup`.
+
+## MCP server (103 tools)
+
+- Register once: `claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start`
+- Verify: `claude mcp list | grep ruvector`
+- Then call MCP tools directly (e.g. `hooks_route`, `hooks_ast_analyze`, `hooks_rag_context`, `brain_search`, `attention_list`).
+
+## Not in 0.2.25 (do not invoke)
+
+`compare`, top-level `index`, `midstream`, `embed --file`, `embed --batch --glob`, `cluster --namespace --k` (top-level `cluster` is "Coming Soon"), `embed --model poincare`, `optimize` (per its own message: "not yet shipped in this release"), `brain agi *` (use `brain status` directly).
@@ -0,0 +1,122 @@
+---
+id: ADR-0001
+title: Pin ruflo-ruvector plugin to ruvector@0.2.25 with optional add-on packages
+status: Accepted
+date: 2026-05-04
+authors:
+  - reviewer (Claude Code)
+tags: [plugin, ruvector, versioning, mcp, dependencies]
+---
+
+## Context
+
+The `ruflo-ruvector` plugin wraps the `ruvector` npm package as a Claude Code plugin. The plugin's documentation (README, agent file, skills, command spec) drifted from the actual CLI surface in two ways:
+
+1. **Aspirational features.** Older docs referenced `FlashAttention-3`, `Graph RAG`, `Hybrid Search`, `DiskANN`, `ColBERT`, `Matryoshka`, `MLA`, `TurboQuant`, `Brain AGI`, and `Midstream` as if they were invokable CLI subcommands. The native Rust bindings expose primitives for most of these, but **no CLI subcommand wires them up** — only `attention list` enumerates the mechanisms.
+2. **Unspecified version.** The plugin invoked `npx ruvector ...` without a version pin, so a user with `ruvector@0.1.x` resolved would silently get a different surface (no `brain`, no `route`, no `sona`) than a user on `ruvector@0.2.x`.
+
+Concretely, this caused:
+
+- `npx ruvector embed "TEXT"` → `unknown command 'TEXT'` (real form is `embed text "TEXT"`)
+- `npx ruvector compare A B` → command does not exist
+- `npx ruvector cluster --namespace ... --k N` → `cluster` is for distributed cluster ops, not k-means
+- `npx ruvector hooks route --task X` → unknown option `--task` (positional)
+- `npx ruvector brain agi status` → no `agi` subgroup
+- `npx ruvector midstream status` → command does not exist
+- `npx ruvector index create N` → command does not exist (use `create <path>`)
+
+A live audit against `ruvector@0.2.25` confirmed which subcommands work, which require optional add-on packages, and which are upstream bugs.
+
+## Decision
+
+The plugin pins to `ruvector@0.2.25` and documents the optional add-on packages required for full functionality.
+
+### 1. Pin every CLI invocation
+
+All `npx` calls in the plugin (README, agent, skills, commands, scripts) MUST be of the form:
+
+```bash
+npx -y ruvector@0.2.25 <subcommand> [args]
+```
+
+Rationale: the `-y` flag suppresses the npm interactive prompt; the version pin prevents a future ruvector release from breaking the plugin's contract without our knowledge.
+
+### 2. Treat add-ons as opt-in extensions, not required deps
+
+| Package | Enables | Plugin subcommands gated on it |
+|---------|---------|------------------------------|
+| `ruvector-onnx-embeddings-wasm` | ONNX runtime | `embed text`, `embed adaptive`, `llm embed` |
+| `@ruvector/pi-brain` | Collective brain | `brain *` |
+| `@ruvector/ruvllm` | RuvLLM + SONA JS fallback | `sona *`, `llm *` |
+| `@ruvector/graph-node` | Graph database (Cypher) | `graph -q ...` |
+| `@ruvector/router` | Semantic router | `router --route ...` |
+
+Rationale: these are heavy dependencies (ONNX runtime alone is large). Forcing them at install time penalizes users who only want hooks routing or RVF storage. Instead we provide a `vector-setup` skill and document the precise error message → install command mapping.
+
+### 3. Register MCP server with the same pin
+
+```bash
+claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start
+```
+
+Rationale: the MCP transport layer changes between minor versions of ruvector. Pinning the MCP command keeps the 103 exposed tools stable for downstream agents.
+
+### 4. Removed surface stays removed
+
+The plugin MUST NOT reintroduce the following invocations even if upstream re-adds equivalents under different names without prior coordination:
+
+- `compare`, `midstream`, top-level `index` (replaced by `create <path>` / `stats <path>`)
+- `embed --file`, `embed --batch --glob`, `embed --model poincare` (no equivalent flags exist)
+- `cluster --namespace --k` (replaced by `hooks graph-cluster <files>`)
+- `hooks route --task`, `hooks ast-analyze --file` (use positional arguments)
+- `brain agi *` (replaced by `brain status`, `brain search`, etc.)
+
+A future ADR may relax this if upstream introduces a stable equivalent and we update the smoke test accordingly.
+
+### 5. Smoke test as the contract
+
+`scripts/smoke.sh` verifies the contracted surface against any installed `ruvector@0.2.25`. It must remain green on every plugin change. Tests cover:
+
+- Version pin (`--version` returns `0.2.25`)
+- Top-level subcommand visibility (`hooks`, `embed`, `rvf`, `attention`, `gnn`, `brain`, `sona`, `create`, `stats`, `search`, `insert`)
+- `hooks route` accepts a positional task argument
+- `hooks ast-analyze` accepts a positional file argument
+- `hooks ast-complexity`, `attention list`, `rvf examples`, `gnn info`, `info`, `doctor` work
+- Removed surface (`compare`, `midstream`, `index`) returns `unknown command`
+
+### 6. Plugin version policy
+
+The plugin's own `version` field in `.claude-plugin/plugin.json` is bumped (patch) on every change to the CLI contract — regardless of whether the change is additive (new subcommand exposed) or a fix. This makes plugin version differences observable to downstream consumers.
+
+## Consequences
+
+**Positive:**
+
+- Every documented invocation in the plugin matches a real CLI surface that is verified by a smoke test.
+- New users hit a deterministic `vector-setup` flow instead of cryptic ONNX/Brain/SONA errors.
+- Future ruvector releases can be evaluated by running the smoke test against the new version before bumping the pin.
+- The "Capabilities" table in README is now a contract, not a wishlist.
+
+**Negative:**
+
+- Bumping the pin requires a deliberate test pass. New ruvector features land in the plugin only after a manual review.
+- Add-on packages (`ruvector-onnx-embeddings-wasm`, `@ruvector/pi-brain`, `@ruvector/ruvllm`) must be installed manually or via `/vector-setup`. Users who skip this and try `embed text` will hit the documented error.
+
+**Neutral:**
+
+- The plugin's "Search Capabilities" feature table now reflects the actual CLI surface. FlashAttention-3 et al. are listed under `attention list` rather than as standalone search modes.
+
+## Verification
+
+```bash
+# Plugin contract check
+bash plugins/ruflo-ruvector/scripts/smoke.sh
+# Expected: "11 passed, 0 failed"
+```
+
+## Related
+
+- `commands/vector.md` — full subcommand mapping
+- `skills/vector-setup/SKILL.md` — first-run installer
+- `agents/vector-engineer.md` — agent contract with replacement table
+- Upstream issue 401 (`optimize` not yet shipped)
@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Smoke test for ruflo-ruvector plugin against ruvector@0.2.25.
+# Exits non-zero if any contracted CLI surface is missing or behaves
+# differently from documented. Run after `npm install ruvector@0.2.25`
+# (or rely on the npx fetch).
+set -u
+PIN="ruvector@0.2.25"
+PASS=0
+FAIL=0
+WORKDIR="$(mktemp -d -t ruvector-smoke.XXXXXX)"
+trap 'rm -rf "$WORKDIR"' EXIT
+cd "$WORKDIR" || exit 2
+
+step() { printf "→ %s ... " "$1"; }
+ok()   { printf "PASS\n"; PASS=$((PASS+1)); }
+bad()  { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
+
+run() { npx -y "$PIN" "$@" 2>&1; }
+
+step "version pin"
+# --version output may include npm warnings; take the last non-empty line.
+ver=$(run --version | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | tail -1)
+[[ "$ver" == "0.2.25" ]] && ok || bad "expected 0.2.25, got '$ver'"
+
+step "top-level help mentions hooks/embed/rvf/attention/gnn/brain/sona"
+help=$(run --help)
+missing=""
+for c in hooks embed rvf attention gnn brain sona create stats search insert; do
+  grep -qE "^[[:space:]]+$c( |\$)" <<<"$help" || missing="$missing $c"
+done
+[[ -z "$missing" ]] && ok || bad "missing:$missing"
+
+step "hooks route is positional"
+out=$(run hooks route "test task")
+grep -q '"recommended"' <<<"$out" && ok || bad "no JSON 'recommended' field — got: $out"
+
+step "hooks ast-analyze on a sample TS file"
+echo 'export const x = 1;' > sample.ts
+out=$(run hooks ast-analyze sample.ts)
+grep -q "AST Analysis" <<<"$out" && ok || bad "ast-analyze did not return summary"
+
+step "hooks ast-complexity returns JSON"
+out=$(run hooks ast-complexity sample.ts)
+grep -q '"cyclomatic"' <<<"$out" && ok || bad "ast-complexity output unexpected"
+
+step "attention list shows mechanisms"
+out=$(run attention list)
+grep -q "FlashAttention" <<<"$out" && ok || bad "attention list missing FlashAttention"
+
+step "rvf examples lists at least 10 stores"
+out=$(run rvf examples)
+n=$(grep -cE '^\s+[a-z_]+\s+[0-9]' <<<"$out")
+[[ $n -ge 10 ]] && ok || bad "expected ≥10 RVF examples, got $n"
+
+step "gnn info reports Available"
+out=$(run gnn info)
+grep -q "Status:.*Available" <<<"$out" && ok || bad "gnn info did not report Available"
+
+step "info reports CLI Version 0.2.25"
+out=$(run info)
+grep -q "CLI Version: 0.2.25" <<<"$out" && ok || bad "info did not report 0.2.25"
+
+step "doctor exits 0"
+run doctor >/dev/null && ok || bad "doctor returned non-zero"
+
+step "removed surface stays removed (compare/midstream/index)"
+fail_removed=""
+for c in compare midstream index; do
+  # Don't pass --help — Commander will show top-level help instead of the error.
+  out=$(npx -y "$PIN" "$c" 2>&1)
+  grep -q "unknown command '$c'" <<<"$out" || fail_removed="$fail_removed $c"
+done
+[[ -z "$fail_removed" ]] && ok || bad "still present:$fail_removed"
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1
@@ -1,6 +1,6 @@
 ---
 name: vector-cluster
-description: Cluster vectors by similarity using npx ruvector k-means or density-based methods with labeled group summaries
+description: Cluster code by graph community detection via npx ruvector@0.2.25 hooks graph-cluster (spectral / Louvain)
 argument-hint: "<namespace> [--k N]"
 allowed-tools: Bash Read mcp__claude-flow__memory_search mcp__claude-flow__memory_store mcp__claude-flow__memory_list
 ---
@@ -15,28 +15,27 @@ Use this skill when you have a collection of embeddings and want to discover nat

 ## Steps

-1. **Ensure ruvector is available**:
+1. **Ensure ruvector@0.2.25 is available**:
   ```bash
-   npm ls ruvector 2>/dev/null || npm install ruvector
+   npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install ruvector@0.2.25
   ```
-2. **Run clustering**:
-   - With known cluster count: `npx ruvector cluster --namespace NAMESPACE --k N`
-   - With auto-detection: `npx ruvector cluster --namespace NAMESPACE --density`
-3. **Review output** -- ruvector reports: cluster ID, label, member count, cohesion score, and outliers (for density mode)
+2. **Run clustering** — in ruvector@0.2.25 the only working clustering is via `hooks graph-cluster` (spectral/Louvain over a code graph). The top-level `cluster` command is reserved for distributed cluster ops and is currently "Coming Soon" upstream.
+   ```bash
+   npx -y ruvector@0.2.25 hooks graph-cluster <files...>
+   npx -y ruvector@0.2.25 hooks graph-mincut <files...>
+   ```
+3. **Review output** — JSON with cluster assignments, community labels, and edges. If you see `"graph.nodes is not iterable"`, run `hooks init` first to seed the graph state.
 4. **Store results**:
-   `mcp__claude-flow__memory_store({ key: "clusters-NAMESPACE-TIMESTAMP", value: "CLUSTER_ASSIGNMENTS", namespace: "vector-clusters" })`
+   `mcp__claude-flow__memory_store({ key: "clusters-PROJECT-TIMESTAMP", value: "CLUSTER_ASSIGNMENTS", namespace: "vector-clusters" })`

 ## Interpreting results

 - **High cohesion** (>0.85): tight, well-defined cluster
 - **Medium cohesion** (0.6-0.85): related but diverse content
- **Low cohesion** (<0.6): loose grouping, try higher k
- **Outliers**: novel or anomalous entries worth investigating
+- **Low cohesion** (<0.6): loose grouping, try higher resolution
+- **Outliers**: novel or anomalous files worth investigating

-## Graph-based clustering (ruvector v2.1+)
+## Caveats

-ruvector supports Louvain community detection and spectral clustering for graph-structured data:
-```bash
-npx ruvector hooks graph-cluster --namespace NAMESPACE
-npx ruvector hooks graph-mincut --namespace NAMESPACE
-```
+- `cluster --namespace ... --k N` and `cluster --density` are **not** valid in ruvector@0.2.25 — those flags fall through to the distributed-cluster command, which only accepts `--status`, `--join`, `--leave`, `--nodes`, `--leader`, `--info`.
+- For namespaced k-means over arbitrary embeddings, run k-means in your own code against vectors stored in AgentDB.
@@ -1,6 +1,6 @@
 ---
 name: vector-embed
-description: Generate embeddings via npx ruvector (ONNX all-MiniLM-L6-v2, 384-dim), normalize, and store in HNSW index
+description: Generate embeddings via npx ruvector@0.2.25 embed text (ONNX all-MiniLM-L6-v2, 384-dim), normalize, and store in HNSW index
 argument-hint: "<text-or-file>"
 allowed-tools: Bash Read mcp__claude-flow__memory_store mcp__claude-flow__memory_search
 ---
@@ -15,29 +15,33 @@ Use this skill to embed text, code, or documents into 384-dimensional vectors fo

 ## Steps

-1. **Ensure ruvector is available**:
+1. **Ensure ruvector@0.2.25 is available**:
   ```bash
-   npm ls ruvector 2>/dev/null || npm install ruvector
+   npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install ruvector@0.2.25
   ```
-2. **Embed the input**:
-   - For text: `npx ruvector embed "your text here"`
-   - For a file: `npx ruvector embed --file src/module.ts`
-   - For batch: `npx ruvector embed --batch --glob "src/**/*.ts"`
-3. **Normalization** -- ruvector L2-normalizes by default (unit sphere, cosine similarity). Alternatives: `--norm l1`, `--norm minmax`, `--norm zscore`
-4. **Confirm** -- report vector ID, dimension (384), norm, and index stored in
+   If `embed text` later reports `ONNX WASM files not bundled`, also run:
+   ```bash
+   npm install ruvector-onnx-embeddings-wasm
+   ```
+2. **Embed the input** (use the `text` subcommand, with text as a positional arg):
+   - Single string: `npx -y ruvector@0.2.25 embed text "your text here"`
+   - With output file: `npx -y ruvector@0.2.25 embed text "your text here" -o vec.json`
+   - For a file: read its content via the Read tool, then pass it as the positional argument.
+   - For batch: loop over files in shell — ruvector@0.2.25 has no built-in `--batch`/`--glob` flags.
+3. **Adaptive (LoRA) variant**: `npx -y ruvector@0.2.25 embed text "..." --adaptive --domain code`
+4. **Confirm** — report vector dimension (384), norm, and any output path written.
 5. **Store metadata** in AgentDB if needed:
   `mcp__claude-flow__memory_store({ key: "embed-SOURCE", value: "VECTOR_METADATA", namespace: "vector-patterns" })`

 ## MCP alternative

-If ruvector MCP server is connected (`claude mcp add ruvector -- npx ruvector mcp start`):
- `hooks_rag_context` — semantic context retrieval
- `brain_search` — shared brain knowledge search
-
-## Batch embedding
-
+Register the MCP server once with the pinned version:
 ```bash
-npx ruvector embed --batch --glob "src/**/*.ts"
+claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start
 ```
+Then call MCP tools directly: `hooks_rag_context` (semantic context), `brain_search` (collective brain), `hooks_ast_analyze`, `hooks_route`.

-Reports total vectors inserted and index growth.
+## Caveats
+
+- The `embed --batch --glob` and `embed --file` flags do **not** exist in ruvector@0.2.25; only `embed text <text>` is supported. Read files yourself and call `embed text` per file.
+- ONNX runtime is not bundled by default. If embedding fails, install `ruvector-onnx-embeddings-wasm` or run `npx -y ruvector@0.2.25 doctor` to diagnose.
@@ -1,6 +1,6 @@
 ---
 name: vector-hyperbolic
-description: Embed hierarchical data in hyperbolic space via npx ruvector Poincare ball model, compute geodesic distances
+description: Embed hierarchical data via npx ruvector@0.2.25 embed text and project into the Poincare ball in user code (no --model poincare flag in 0.2.25)
 argument-hint: "<text> [--model poincare]"
 allowed-tools: Bash Read mcp__claude-flow__memory_store mcp__claude-flow__memory_search
 ---
@@ -15,24 +15,29 @@ Use this skill when your data has inherent hierarchy — dependency trees, modul

 ## Steps

-1. **Ensure ruvector is available**:
+1. **Ensure ruvector@0.2.25 is available**:
   ```bash
-   npm ls ruvector 2>/dev/null || npm install ruvector
+   npm ls ruvector 2>/dev/null | grep '0.2.25' || npm install ruvector@0.2.25
   ```
-2. **Embed in Poincare ball**:
+2. **Generate a base ONNX embedding** (ruvector@0.2.25 does not expose a `--model poincare` flag on `embed text`):
   ```bash
-   npx ruvector embed --model poincare "hierarchical concept"
+   npx -y ruvector@0.2.25 embed text "hierarchical concept" -o concept.vec.json
   ```
-   Coordinates near origin = generic/root; near boundary = specific/leaf.
-3. **Search in hyperbolic space**:
+3. **Project into the Poincare ball** in your own code (or via the experimental neural substrate):
   ```bash
-   npx ruvector search --model poincare "query" --limit 10
+   npx -y ruvector@0.2.25 embed neural --help
   ```
+   For an ad-hoc projection, normalize the 384-dim vector to live inside the unit ball (`x_i / (||x|| * (1 + epsilon))`) and persist the projected coordinates alongside the original embedding.
 4. **Geodesic distance**: `d(u, v) = arcosh(1 + 2 * ||u-v||^2 / ((1-||u||^2)(1-||v||^2)))`
   Distance grows logarithmically with tree depth, preserving hierarchy.
 5. **Store results**:
   `mcp__claude-flow__memory_store({ key: "hyperbolic-CONCEPT", value: "COORDINATES_AND_NEIGHBORS", namespace: "hyperbolic-embeddings" })`

+## Caveats
+
+- ruvector@0.2.25 has no first-class Poincare ball CLI flag. Treat hyperbolic projection as a post-processing step over a standard ONNX embedding.
+- If you need a hyperbolic search index, store projected coordinates in AgentDB and compute geodesic distance in your own retrieval code.
+
 ## Poincare ball properties

 | Property | Meaning |
@@ -0,0 +1,82 @@
+---
+name: vector-setup
+description: First-run setup for ruvector@0.2.25 — installs ONNX/Brain/SONA add-ons, registers the MCP server, and verifies the install via `doctor`
+argument-hint: "[--full]"
+allowed-tools: Bash Read
+---
+
+# Vector Setup
+
+Bootstraps `ruvector@0.2.25` and its optional add-ons so every `/vector` subcommand actually works on first run.
+
+## Why this exists
+
+Out of the box, several `/vector` subcommands fail with a confusing dep error:
+
+| Error | Missing package |
+|-------|-----------------|
+| `ONNX WASM files not bundled. The onnx/ directory is missing.` | `ruvector-onnx-embeddings-wasm` |
+| `Brain commands require @ruvector/pi-brain` | `@ruvector/pi-brain` |
+| `SONA not available. Native error: Cannot find module '/.../@ruvector/sona/index.js'` | `@ruvector/ruvllm` (JS fallback) |
+| `LLM commands require @ruvector/ruvllm` | `@ruvector/ruvllm` |
+
+This skill installs them in one pass.
+
+## Steps
+
+1. **Pin ruvector**:
+   ```bash
+   npm install ruvector@0.2.25
+   ```
+2. **Install the add-ons** (idempotent — only what's missing):
+   ```bash
+   npm install ruvector-onnx-embeddings-wasm \
+               @ruvector/pi-brain \
+               @ruvector/ruvllm
+   ```
+   For a leaner install, pass `--full` to also pull `@ruvector/graph-node` and `@ruvector/router`:
+   ```bash
+   npm install ruvector-onnx-embeddings-wasm \
+               @ruvector/pi-brain \
+               @ruvector/ruvllm \
+               @ruvector/graph-node \
+               @ruvector/router
+   ```
+3. **Verify the binary**:
+   ```bash
+   npx -y ruvector@0.2.25 doctor
+   npx -y ruvector@0.2.25 info
+   ```
+4. **Register the MCP server**:
+   ```bash
+   claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start
+   claude mcp list | grep ruvector
+   ```
+5. **Sanity check** the most common subcommands:
+   ```bash
+   npx -y ruvector@0.2.25 hooks route "test"
+   npx -y ruvector@0.2.25 attention list
+   npx -y ruvector@0.2.25 rvf examples
+   ```
+6. **(Optional) Generate a pi identity** for brain + edge:
+   ```bash
+   npx -y ruvector@0.2.25 identity generate
+   npx -y ruvector@0.2.25 identity show
+   ```
+
+## Smoke test
+
+For a deterministic verification of the install, run the plugin's bundled smoke script:
+```bash
+bash plugins/ruflo-ruvector/scripts/smoke.sh
+```
+
+It checks: version pin, top-level subcommand visibility, `hooks ast-analyze`, `hooks route`, `attention list`, `rvf examples`, and `info`. Exits non-zero if any drift from the contracted surface is detected.
+
+## What this does not install
+
+- Native Rust toolchain (optional; only needed for source builds)
+- Platform-specific native bindings (auto-detected by `@ruvector/core`)
+- `@ruvector/sona` native binding (the JS fallback via `@ruvector/ruvllm` is sufficient on macOS arm64; Linux x64 has its own native binding)
+
+If `doctor` still reports a problem after this skill runs, paste its output verbatim and ask.