vector-setup

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 @sparkleideas/ruvector-pi-brain	@sparkleideas/ruvector-pi-brain
SONA not available. Native error: Cannot find module '/.../@sparkleideas/ruvector-sona/index.js'	@sparkleideas/ruvector-ruvllm (JS fallback)
LLM commands require @sparkleideas/ruvector-ruvllm	@sparkleideas/ruvector-ruvllm

This skill installs them in one pass.

Steps

1. Pin ruvector:

   npm install ruvector@0.2.25
   

2. Install the add-ons (idempotent — only what's missing):

   npm install ruvector-onnx-embeddings-wasm \
               @sparkleideas/ruvector-pi-brain \
               @sparkleideas/ruvector-ruvllm
   

   For a leaner install, pass --full to also pull @sparkleideas/ruvector-graph-node and @sparkleideas/ruvector-router:

   npm install ruvector-onnx-embeddings-wasm \
               @sparkleideas/ruvector-pi-brain \
               @sparkleideas/ruvector-ruvllm \
               @sparkleideas/ruvector-graph-node \
               @sparkleideas/ruvector-router
   

3. Verify the binary:

   npx -y ruvector@0.2.25 doctor
   npx -y ruvector@0.2.25 info
   

4. Register the MCP server:

   claude mcp add ruvector -- npx -y ruvector@0.2.25 mcp start
   claude mcp list | grep ruvector
   

5. Sanity check the most common subcommands:

   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:

   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 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 @sparkleideas/ruvector-core)
• @sparkleideas/ruvector-sona native binding (the JS fallback via @sparkleideas/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.

Known third-party issues (no fork action — ADR-0293 D11)

Two ruvector@0.2.25 rough edges are upstream third-party behaviour, identical whether you run the public ruvector or any rebranded build — they are NOT fork divergences and there is no fork-side fix:

• ruvector embed first-run ONNX bundling gap — the ONNX WASM files are not bundled in the base package; ruvector embed fails until ruvector-onnx-embeddings-wasm is installed (step 2 above). Ruflo's own embeddings path (embeddings_* / mcp__ruflo__embeddings_generate) uses transformers.js mpnet and is unaffected.
• ruvector stats redb/JSON bug — stats can error against the native redb store. This is a ruvector@0.2.25 native-db issue; use ruvector info / doctor for install health instead.

Both are tracked upstream (ruvnet/ruvector); do not file fork housekeeping or attempt a fork patch for them.