prism-mcp-server 18.0.2 → 19.0.1

package/README.md

@@ -1,280 +1,206 @@
-# 🧠 Prism Coder
+# Prism Coder
 
-🌐 **Read in your language:** 🇬🇧 English · [🇪🇸 Español](docs/i18n/README_es.md) · [🇫🇷 Français](docs/i18n/README_fr.md) · [🇵🇹 Português](docs/i18n/README_pt.md) · [🇷🇴 Română](docs/i18n/README_ro.md) · [🇺🇦 Українська](docs/i18n/README_uk.md) · [🇷🇺 Русский](docs/i18n/README_ru.md) · [🇩🇪 Deutsch](docs/i18n/README_de.md) · [🇯🇵 日本語](docs/i18n/README_ja.md) · [🇰🇷 한국어](docs/i18n/README_ko.md) · [🇨🇳 中文](docs/i18n/README_zh.md) · [🇸🇦 العربية](docs/i18n/README_ar.md)
+**Give your AI agent memory that lasts.** Persistent sessions, knowledge graphs, and offline tool-routing — fully local and free.
 
-**Persistent memory + tool-calling intelligence for AI agents.** *(formerly Prism MCP)*
-
-A Model Context Protocol server that gives Claude, Cursor, and other AI tools a Mind Palace — long-term memory that survives across sessions, with semantic search, cognitive routing, a visual dashboard, and the `prism-coder:1b7` / `prism-coder:8b` / `prism-coder:14b` / `prism-coder:32b` LLM fleet for offline tool-calling.
-
-[![npm](https://img.shields.io/npm/v/prism-mcp-server?color=cb0000&label=npm%20%E2%80%94%20prism-mcp-server)](https://www.npmjs.com/package/prism-mcp-server)
-[![VS Marketplace](https://img.shields.io/visual-studio-marketplace/v/synalux-ai.synalux?label=VS%20Code&color=007ACC)](https://marketplace.visualstudio.com/items?itemName=synalux-ai.synalux)
-[![Website](https://img.shields.io/badge/website-synalux.ai%2Fprism--mcp-6B4FBB)](https://synalux.ai/prism-mcp)
+[![npm](https://img.shields.io/npm/v/prism-mcp-server?color=cb0000&label=npm)](https://www.npmjs.com/package/prism-mcp-server)
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-00ADD8)](https://github.com/modelcontextprotocol/servers)
-[![Smithery](https://img.shields.io/badge/Smithery-listed-6B4FBB)](https://smithery.ai/server/@dcostenco/prism-mcp)
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
+[![Models on HuggingFace](https://img.shields.io/badge/🤗-prism--coder-yellow)](https://huggingface.co/dcostenco)
+
+<p align="center">
+  <img src="docs/v11_hivemind_multi_agent_dashboard.jpg" alt="Prism Coder — Mind Palace Dashboard with Knowledge Graph and Multi-Agent Hivemind" width="700" />
+</p>
+
+Prism Coder is an [MCP server](https://modelcontextprotocol.io) that gives Claude, Cursor, and other AI tools long-term memory that survives across sessions. It ships with the open-weight `prism-coder` model fleet (2B–32B) for fast, offline tool-routing — no cloud required.
 
-> **Renamed in v14.0.0:** the project is now **Prism Coder** to cover both the Mind Palace memory server *and* the `prism-coder:1b7` / `prism-coder:8b` / `prism-coder:14b` / `prism-coder:32b` LLM fleet on HuggingFace + Ollama. The npm package stays `prism-mcp-server` so existing install URLs and `mcp.json` entries keep working — the `prism-coder` binary has been the canonical entry point since v12.
+**No account needed. No API keys. Runs on your machine.**  
+A paid subscription adds cloud sync, higher model tiers, and team features through the [Synalux portal](https://synalux.ai).
 
 ---
 
-## What Prism Coder does
+## Quickstart
 
-### 💾 Your AI remembers across sessions
-Every conversation feeds the Mind Palace. Next session, your AI agent loads the right context automatically — no re-explaining.
+The free tier needs no account, no API key, and no cloud. Add the server to your MCP client:
 
-### 🔍 Semantic search over your history
-Ask "what did I decide about the auth flow last month?" and get the answer with citations. Vector search + keyword + graph traversal.
+```json
+{
+  "mcpServers": {
+    "prism": {
+      "command": "npx",
+      "args": ["-y", "prism-mcp-server"]
+    }
+  }
+}
+```
 
-### 🧬 Cognitive routing
-Different memory types live in different stores: episodic (what happened), semantic (what's true), procedural (how to do X). The router picks where to store and where to retrieve.
+Open Claude Desktop or Cursor and your agent now has memory backed by a local SQLite database (`~/.prism-mcp/data.db`).
 
-### 🔄 Proactive session drift detection *(new in v15, HRR-powered in v17)*
-Your AI agent can now detect when it has drifted from your original goals — mid-session, automatically — and self-correct before you notice the problem.
+**Optional — local model fleet** for offline tool-routing. Pull whichever fits your hardware:
 
-Three direct Prism calls:
-1. **`session_save_ledger`** — snapshot current state
-2. **`session_detect_drift`** — HRR-powered semantic comparison of current work vs original goals, returns `on_track / minor_drift / major_drift` with domain-specific signals (BCBA/Coding/AAC)
-3. **`session_compact_ledger`** — if drifted, compress and reload only what matters
+```bash
+ollama pull dcostenco/prism-coder:2b    # 2.3 GB · mobile / lightweight (99.1% routing accuracy)
+ollama pull dcostenco/prism-coder:4b    # 3.4 GB · verifier (100% accuracy)
+ollama pull dcostenco/prism-coder:9b    # 5.8 GB · default router (100% accuracy, Qwen3.5)
+ollama pull dcostenco/prism-coder:32b   # 19 GB  · complex tasks (100% accuracy)
+```
 
-When major drift is detected, the alert routes to the **Synalux portal** so it's visible across sessions and devices — not just in the current conversation.
+Prism detects both the namespaced (`dcostenco/prism-coder:9b`) and bare (`prism-coder:9b`) Ollama tags automatically.
 
-**Real example it caught:** A training session promised BFCL ≥90% for three AI models. The agent spent 3 hours debugging audio bugs instead. The drift check surfaced: "Training goal unmet. Layer3 corpus missing from all training sets. 0 BFCL scores measured." The session immediately re-aligned.
+---
 
-No scripts. No cron. No hooks. Three tool calls, Prism handles the rest.
+## What it does
 
-### 🛡 PHI Guard *(v17+)*
-Automatic Protected Health Information detection and redaction in the memory pipeline. Every `session_save_ledger` and `session_save_handoff` call passes through the PHI guard before storage.
+Your AI agent forgets everything between sessions. Prism fixes that — and adds verification, drift detection, and multi-agent coordination on top.
 
-**What it catches:** DOBs, SSNs, MRNs, phone numbers, email addresses, and other structured HIPAA identifiers (18 categories). Redaction is deterministic (regex + pattern matching, no LLM) — zero false negatives on format-constrained identifiers (SSN, MRN, phone, email). Names require NER for reliable detection and are best-effort.
+### Mind Palace — persistent memory that survives across sessions
 
-**Fail-closed:** PHI detection errors log to stderr (never suppressed) and block the save. Metric: `phi_guard.detected` count per category is always emitted for audit compliance.
+Every conversation feeds a persistent store. The next session loads the right context automatically — no re-explaining.
 
-### ⚡ Prompt-based skill routing *(v17+)*
-114 agent skills auto-load based on prompt keywords. No manual skill selection needed — the MCP server scans the user's prompt and injects the relevant skill instructions into the session context before the AI responds.
+<p align="center">
+  <img src="docs/mind-palace-dashboard.png" alt="Mind Palace Dashboard — project state, neural graph, pending TODOs" width="700" />
+</p>
 
-### 💰 Tier enforcement *(v17.1+)*
-`prism_infer` now enforces subscription-tier gates: model ceiling, max tokens, daily limits, and cloud fallback are all gated by your plan. Free users get local-only inference up to 4b; paid tiers unlock higher models, more tokens, and cloud fallback. Flat-rate seat caps via `max_seats` per plan.
+The dashboard shows your current project state, pending TODOs, intent health, and a neural knowledge graph — all built automatically from your agent sessions.
 
-### 🛡 Local-first — security + speed
-Free tier runs entirely on your machine — SQLite, local embedding model, no API keys, no cloud. Paid tier adds cloud sync via Synalux portal.
+### Knowledge Graph — semantic + keyword + graph search
 
-**Why local models matter:**
+Ask "what did I decide about the auth flow last month?" and get an answer with citations, combining vector similarity, full-text search, and graph traversal.
 
-| | Cloud LLM | Local `prism-coder` |
-|--|---|---|
-| Tool-call latency | 200ms–3s | **~1.6s (1.7B) / ~1.1s (14B)** |
-| API key required | Yes | **No** |
-| Data sent externally | Every prompt | **Nothing (free tier)** |
-| Works offline | ❌ | ✅ |
-| Cost at scale | $0.002–0.06/call | **$0** |
-| HIPAA | Requires BAA | **On-prem = no BAA** |
+<p align="center">
+  <img src="docs/knowledge-graph.jpg" alt="Knowledge Graph — 190 keywords, 47 edges, 12 projects visualized" width="500" />
+</p>
 
-Install in one command — no config, no keys, no vendor agreements:
-```bash
-ollama pull dcostenco/prism-coder:14b   # 9 GB  · default router · Mac M2+ / iPad Pro
-ollama pull dcostenco/prism-coder:4b    # 2.5 GB · verifier · iPhone 15/16 Pro
-ollama pull dcostenco/prism-coder:1b7   # 2.2 GB · ultra-low RAM / Apple Watch
-ollama pull dcostenco/prism-coder:32b   # 19 GB  · complex tasks · Mac M2 Ultra+
-ollama pull dcostenco/prism-coder:8b    # 4.7 GB · balanced · iPhone/iPad 8GB
-```
+### Session History — immutable audit trail
 
-Prism MCP detects both the namespaced (`dcostenco/prism-coder:14b`) and bare (`prism-coder:14b`) Ollama tag forms automatically — nothing else to configure. If you want the bare tags as aliases for direct `ollama run prism-coder:14b` use, run:
+Every session is logged with files changed, decisions made, and TODOs. Search, filter, and replay any past session.
 
-```bash
-prism register-models           # aliases */prism-coder:* → prism-coder:* via `ollama cp`
-prism register-models --dry-run # preview what would be aliased
-```
+<p align="center">
+  <img src="docs/session-ledger.jpg" alt="Session Ledger — 93 sessions, 847 decisions logged across 12 projects" width="700" />
+</p>
 
-### Cascade architecture
+### Session Drift Detection
 
-Three-tier local cascade with cloud fallback:
+Long agent sessions can wander from their original goal. `session_detect_drift` compares current work against the stated goal and returns `on_track / minor_drift / major_drift` so the agent can self-correct.
 
-```
-Query arrives
-  │
-  ▼
-prism-coder:14b ── routes (100% eval_300) ──▶  serve  (~3s, 9GB, FREE)
-  │                                              │
-  │                                    knowledge_search (RAG context)
-  │                                              │
-  ▼                                              ▼
-prism-coder:4b ── verifies claims ──────────▶  grounded response
-  │                 (2.5GB, <1s)
-  │
-  ▼  (complex tasks only, explicit ceiling="32b")
-prism-coder:32b ── deep reasoning ──────────▶  serve  (~8s, 19GB, FREE)
-  │
-  ▼  (cloud fallback when local insufficient)
-Claude Sonnet 4 ────────────────────────────▶  serve  (cloud, ~$0.01/req)
-```
+### Behavioral Verification — catch bad edits before they happen
 
-| Tier | Model | Role | RAM | Latency | Cost |
-|------|-------|------|-----|---------|------|
-| **Default** | prism-coder:14b | Router + general inference | 9 GB | ~3s | $0 |
-| **Verifier** | prism-coder:4b | Grounding claims check | 2.5 GB | <1s | $0 |
-| **Complex** | prism-coder:32b | Deep reasoning (on-demand) | 19 GB | ~8s | $0 |
-| **Cloud** | Claude Sonnet 4 | Fallback for max quality | — | ~5-10s | ~$0.01 |
+AI agents apply patterns from checklists without understanding the real-world impact. The `verify_behavior` tool challenges the agent with a scenario it must answer **before** editing — forcing it to think through what the end user will experience.
 
-**Mobile / offline cascade** (Prism AAC iOS):
 ```
-prism-coder:14b (iPad Pro 16GB) → prism-coder:4b (iPhone 8GB)
-  → prism-coder:1.7b (any device, always fits)
+Agent: "I'll revert this kitchen display change"
+Prism: "⚠️ Scenario: A cook sees a 3-item ticket. One item is voided.
+        What should the cook see after the void?"
+Agent: "The ticket stays visible with the remaining 2 items."
+Prism: "Correct — your revert would hide the ticket entirely."
 ```
 
-### Knowledge ingestion — teach Prism your codebase
-
-Your code knowledge lives in the knowledge graph, not in model weights. Routing stays at 100%.
-
-```bash
-bash scripts/knowledge-ingest/setup.sh   # one-time setup
-# Then every git commit auto-indexes changed files into the knowledge graph
-```
+17 built-in domains (billing, auth, ordering, clinical, HR, and more). Custom domains per workspace on Enterprise. No hooks needed — works in any MCP client.
 
-Three entry points:
-- **MCP tool**: `knowledge_ingest` — AI says "learn this code"
-- **GitHub webhook**: `POST /api/github/webhook` — auto on push
-- **REST API**: `POST /api/v1/prism/ingest` — open interface
+### Time Travel
 
-See [KNOWLEDGE_INGESTION.md](docs/KNOWLEDGE_INGESTION.md) for full setup guide.
+Roll back to any previous session state. Compare diffs between versions. Restore a known-good state with one click.
 
-### Routing accuracy
+<p align="center">
+  <img src="docs/time-travel-timeline.jpg" alt="Time Travel — version timeline with diff view and one-click restore" width="500" />
+</p>
 
-**Head-to-head: prism-coder:14b vs Claude Opus** (25-case benchmark, production system prompt, May 2026):
+### Cognitive Routing
 
-| Metric | prism-coder:14b | Claude Opus 4 |
-|---|---|---|
-| **Overall accuracy** | **96% (24/25)** | 88% (22/25) |
-| **Tool routing** (15 tests) | **93% (14/15)** | 80% (12/15) |
-| **Abstention** (10 tests) | **100% (10/10)** | **100% (10/10)** |
-| **Avg latency** | **0.8s** | 5.5s |
-| **Cost per query** | **$0** | ~$0.017 |
-| **Annual @ 1K/day** | **$0** | ~$6,100 |
+Three memory types, automatically sorted: **episodic** (what happened — session logs, decisions), **semantic** (what's true — facts, architecture), and **procedural** (how to do X — workflows, patterns). When you search, the router picks the right store instead of dumping everything.
 
-prism-coder:14b beats Opus on tool routing — 7x faster, free, runs offline.
+### Multi-Agent Hivemind
 
-**eval_300** (300 cases, 17 tools + NO_TOOL, 9 categories, 3-seed validated):
+Coordinate multiple AI agents working on the same project. Each agent has its own session, but they share memory through the knowledge graph. The Hivemind Radar shows real-time agent status, tasks, and activity.
 
-| Model | eval_300 strict | Size | Latency |
-|---|---|---|---|
-| **prism-coder:32b** | **300/300 (100%)** | 19 GB | ~1.4s |
-| **prism-coder:14b** | **299/300 (99.7%)** | 9 GB | ~0.8s |
-| **prism-coder:4b** | **300/300 (100%)** | 2.5 GB | ~0.5s |
-| **prism-coder:1.7b** | **300/300 (100%)** | 2.2 GB | ~1.6s |
+<p align="center">
+  <img src="docs/hivemind-radar.jpg" alt="Hivemind Radar — 5 agents with real-time status, tasks, and activity feed" width="500" />
+</p>
 
-Categories: abstention, adversarial traps, cascade, disambiguation, edge cases, multi-intent, natural phrasing, parameter extraction, verifier prompts.
+### Neural Search
 
-**What this means**: a child in a hospital without WiFi, a nonverbal adult on an airplane, or a family on a budget gets Claude-grade routing accuracy with zero cloud dependency — the AAC path routes correctly **100% of the time across all tiers**.
+Search across all memories with highlighted results, knowledge graph editing, and memory density metrics.
 
-**What it does NOT mean**: these scores measure routing precision on a 17-tool taxonomy, not general intelligence. Claude outperforms on everything outside this task. The value is **offline reliability at zero cost**, not replacing Claude. Code and clinical knowledge come from RAG via `knowledge_search`.
+<p align="center">
+  <img src="docs/v6_cognitive_load_dashboard.jpg" alt="Neural Search with Knowledge Graph Editor and Memory Density" width="500" />
+</p>
 
-### 🔍 L3 Grounding Verifier
+---
 
-Fail-closed fact-checking layer. When `prism_infer` receives an `evidence` payload, a separate verifier model (default: `prism-coder:4b`) checks every factual claim in the draft against the evidence before serving it. This is the third layer (L3) of the cascade — after tool routing (L1) and confidence gating (L2).
+## Local-first and privacy
 
-**Three-tier pre-check:**
+The free tier runs entirely on your machine. Paid tiers add cloud sync through the Synalux portal, which is what enables cross-device memory and team sharing.
 
-| Tier | Condition | Action |
+| | Local tier (free) | Cloud tier (paid) |
 |---|---|---|
-| **0 — Conversational** | Draft has no numbers, dates, names, codes, or $ amounts | Serve without verification |
-| **0a — No evidence** | Assertive draft + zero evidence snippets | Refuse (fail-closed) |
-| **2 — NLI** | Assertive draft + evidence provided | Verify each claim against evidence |
+| Memory storage | Local SQLite | Synalux portal (Supabase-backed) |
+| Inference | Local Ollama models | Local models + cloud fallback |
+| API keys required | None | Synalux subscription key |
+| Web search / scrape | Not included | Via Synalux portal (provider keys server-side) |
+| What leaves your machine | Nothing | Memory text + file paths + search queries, sent to the portal over TLS (PHI-redacted before transit) |
+| Works offline | ✅ | Local features yes; sync/cloud no |
 
-**Per-claim verdicts:**
-- `ENTAILED` — claim matches evidence (including arithmetic identity: "3" ≈ "three")
-- `CONTRADICTED` — evidence states a different value for the same fact → **refuse**
-- `NEUTRAL` — claim not covered by evidence → **refuse** (fail-closed default)
+**Handling sensitive data.** All cloud writes pass through automatic redaction (SSNs, dates of birth, medical record numbers, phone numbers, emails, and clinical identifiers are stripped before transit). For regulated workloads, run the **local tier** for full air-gap, or use **Enterprise** which includes a HIPAA Business Associate Agreement.
 
-**Fail-closed guarantees:** HTTP errors, malformed JSON, timeouts → all treated as refusal. The caller gets the specific claim that failed and can retry with more evidence or fall back to cloud.
-
-**Usage with `prism_infer`:**
-```json
-{
-  "prompt": "What was the patient's last A1C?",
-  "evidence": [
-    { "source": "lab_2026-05-01", "content": "HbA1c: 6.8% (ref <7.0)" }
-  ]
-}
-```
+---
 
-**Structured output:**
-```json
-{
-  "output": "The patient's last A1C was 6.8%.",
-  "verification": {
-    "action": "served",
-    "claims": [{ "text": "A1C was 6.8%", "verdict": "ENTAILED" }],
-    "verifierChain": [{ "model": "prism-coder:4b", "verdict": "ENTAILED", "latencyMs": 340 }]
-  }
-}
-```
+## Models
 
-When a claim is contradicted or unsupported:
-```json
-{
-  "output": "⚠ Verification failed: claim 'A1C was 7.2%' is CONTRADICTED by evidence.",
-  "verification": {
-    "action": "refused_fabricated",
-    "refusalClaim": "A1C was 7.2%"
-  }
-}
-```
+The `prism-coder` fleet uses Qwen3.5 for MCP tool-routing. The 9B is fine-tuned with LoRA (r=128, all 64 layers including DeltaNet); the 2B and 4B use stock Qwen3.5-4B at different quantization levels. They are **not** general-purpose chat models — they route reliably and run offline; Claude and other frontier models remain better at reasoning, coding, and open-domain work. The intended pattern is local routing with an optional cloud fallback for hard cases.
 
-The verifier model (`prism-coder:4b`) is intentionally different from the inference model — satisfying the independent-reviewer principle. Requires a paid plan (see [Plans](#plans)). Set `verify: false` to explicitly skip verification even when evidence is provided.
+| Model | Ollama tag | Size | [BFCL](https://gorilla.cs.berkeley.edu/blogs/12_bfcl_v3_multi_turn.html) Accuracy | Role | Tier |
+|---|---|---|---|---|---|
+| Qwen3.5-4B Q3_K_M | `prism-coder:2b` | 2.3 GB | 99.1% × 3 seeds | iPhone / mobile first gate | Free |
+| Qwen3.5-4B Q4_K_M | `prism-coder:4b` | 3.4 GB | 100% × 3 seeds | Verifier | Free |
+| Qwen3.5-9B (LoRA) | `prism-coder:9b` | 5.8 GB | 100% × 3 seeds | Default router | Standard+ |
+| prism-coder:32b | `prism-coder:32b` | 19 GB | 100% × 3 seeds | Complex tasks | Advanced+ |
 
-### 🧠 HRR Semantic Drift Detection (v17.0)
-Detects when long AI agent sessions drift from their original goal — using Holographic Reduced Representations for temporal trajectory encoding and anomaly detection.
+Weights: [huggingface.co/dcostenco](https://huggingface.co/dcostenco) (public GGUF). Latency depends on model size and hardware — see [Benchmarks](#benchmarks) to measure it on your own machine rather than trusting a printed number.
 
-**Three domains, one detector:**
-| Domain | Signals | Safety |
-|---|---|---|
-| **BCBA/Clinical** | Client specificity decay, function-intervention alignment (4 functions), contraindication detection (epilepsy/pica/dysphagia/diabetes) | PHI-safe, deterministic |
-| **Coding** | File scope entropy, summary vagueness, test coverage ratio, trajectory HRR divergence | Adaptive threshold for refactors |
-| **AAC** | Prediction accuracy, vocabulary stagnation, topic divergence | Emergency phrases always ≥ 0.95 |
+### Cascade
 
-**Research-backed:** trajectory association (Frady et al. 2018), HDAD anomaly detection (Wang et al. 2021), unit-modulus projection (Ganesan et al. NeurIPS 2021). 306 tests across 8 files, zero failures. Use `session_detect_drift` with optional `domain` parameter.
+```
+query → prism-coder:9b (local router, default)
+      → prism-coder:4b (grounding verifier)
+      → prism-coder:2b (iPhone / mobile, auto-selected by RAM)
+      → prism-coder:32b (complex tasks, on demand)
+      → cloud fallback (paid tiers, for max quality)
+```
 
-### ⚡ Zero-search retrieval *(new in v15.8)*
-Holographic Reduced Representations (HRR) via Rust WASM for instant memory retrieval without a database query.
+### Multi-Layer Verification
 
-**Three adaptive strategies:**
-- **GloVe embeddings** (offline, 50K words) — 87% Top-1 accuracy, stable at 200+ concepts
-- **API embeddings** (Gemini/Voyage) — 90%+ accuracy when online
-- **NeurIPS 2021 projection** — unit-modulus normalization for numerical stability
+Every tool-grounded answer on paid tiers passes through deterministic L3 routing rules and an NLI grounding verifier before reaching the user. Free-tier users get the deterministic gates (L1, L3-Tool, L3-Tier0) without the model-based NLI check.
 
-**Retrieval cascade:** HRR (~0.2ms) → FTS5 (~50ms) → Supabase (~200ms)
+| Layer | What | Model | Cost |
+|---|---|---|---|
+| **L1** | Crisis/medical safety gate | None (regex) | 0 ms |
+| **L3-Tool** | Tool name remap + false-positive rejection | None (deterministic) | 0 ms |
+| **L3-Tier0** | Integer grounding (set membership) | None (deterministic) | 0 ms |
+| **L3-Tier2** | NLI verifier (claim → ENTAILED/NEUTRAL/CONTRADICTED) | prism-coder:2b | ~200 ms |
+| **L4** | Hallucination judge (opt-out for clinical) | prism-coder:4b | ~500 ms |
 
-| Metric | HRR (WASM) | FTS5 | Supabase Vector |
-|--------|-----------|------|-----------------|
-| Latency | **0.2ms** | 50ms | 200ms |
-| Speedup | **1x** | 250x slower | 1000x slower |
-| Offline | **Yes** | Yes | No |
-| Accuracy (GloVe) | **87% Top-1** | 95%+ | 95%+ |
-| Hologram size | **8KB** | Index varies | Cloud |
+Fail-closed on the verified path: when the grounding verifier runs (Standard tier and up), timeout, ambiguity, or missing evidence yields a refusal, not pass-through. Free-tier users get the deterministic L1/L3-Tool gates but not the NLI verifier.
 
-HRR acts as Tier 0 — if confidence is high, FTS5 is skipped entirely. Falls through gracefully when HRR has no match. 97 dedicated tests (72 system + 25 API/client). Built with Rust + `rustfft` + `wasm-bindgen` (229KB binary).
+---
 
-**HRR AAC prediction benchmark** — real-world impact on Prism AAC word prediction (10 scenarios, 54 integration tests):
+## Benchmarks
 
-| Scenario | Baseline Top-1 | +HRR Top-1 | Top-1 Lift | MRR Lift |
-|----------|---------------|------------|-----------|----------|
-| Core AAC phrases | 36.7% | 46.7% | **+27.3%** | +6.0% |
-| Personal vocabulary | 70.4% | 81.5% | **+15.8%** | +9.2% |
-| Mixed (all phrases) | 47.2% | 56.9% | **+20.6%** | +5.7% |
-| Cross-session recall | 80.0% | 80.0% | +0.0% | +0.0% |
+**Reproduce every number yourself.** All evals are open-source and self-contained:
 
-Top-1 = correct word is tile #1. MRR = Mean Reciprocal Rank. Zero Top-5 regressions in any scenario. HRR encodes bigrams + trigrams from every spoken phrase; probes take ~0.2ms — safe on every keystroke. All Synalux apps (clinical, AAC, PrismCoach) share HRR via the portal `/api/v1/hrr` endpoint.
+```bash
+git clone https://github.com/dcostenco/prism-coder && cd prism-coder
+pip install anthropic requests
+python3 tests/benchmarks/prism-routing-100/benchmark.py --models 2b 4b 9b 32b
+```
 
-**Memory retrieval comparison:**
+**Routing eval (115 cases, 12 categories, 3-seed mean).** Routing accuracy includes the deterministic L3 correction layer — the same rules that run in production. On this narrow tool-routing task all fleet models achieve near-perfect accuracy. Be honest with yourself about what that means: the eval is **near-saturated** for this taxonomy — it measures whether the right one of a small set of MCP tools is selected, not general capability. The useful takeaway is **offline routing reliability at zero cost**, not that a 2.3 GB model rivals a frontier model in general.
 
-| System | Retrieval | Offline | Cost | Latency |
-|--------|-----------|---------|------|---------|
-| **Prism Coder** | **HRR + FTS5 + Supabase cascade** | **Yes** | **$0** | **0.2ms** |
-| Mem0 | Vector DB (Qdrant/Pinecone) | No | $249/mo | ~100ms |
-| Zep | Vector DB + temporal graph | No | $99/mo | ~80ms |
-| Hermes (NousResearch) | HRR + SQLite | Yes | Free | ~5ms |
+| Model | Routing accuracy | Notes |
+|---|---|---|
+| prism-coder:2b (Q3_K_M) | 99.1% × 3 seeds | 1 failure: regex→knowledge_search |
+| prism-coder:4b / 9b / 32b | 100% × 3 seeds | Perfect on all 115 cases |
+| Claude (frontier, same eval) | ~98% | Stronger everywhere outside this narrow task |
 
-### 🌐 Multi-agent Hivemind
-Multiple AI agents share the same Mind Palace. Each agent has a role (dev / qa / pm / etc.) and sees scoped context. Heartbeat + roster for coordination.
+**Memory uplift (LoCoMo-Plus, self-published).** A separate long-context dialogue benchmark ([dcostenco/Locomo-Plus](https://github.com/dcostenco/Locomo-Plus)) measures how much structured memory helps a base model retain multi-day context. Results show large gains when a model is paired with Prism memory versus running raw. Note this benchmark is authored, run, and LLM-judged by this project — treat it as a reproducible demonstration, not an independent third-party result, and run it yourself with the commands in that repo.
 
 ---
 
@@ -282,658 +208,264 @@ Multiple AI agents share the same Mind Palace. Each agent has a role (dev / qa /
 
 ### vs AI coding assistants
 
-| Feature | Prism Coder | GitHub Copilot | Cursor | Windsurf | Amazon Q | Tabnine | Devin |
-|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| Local inference (1.7B–32B) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Works offline (local-only mode) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Open-weight models (HuggingFace) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Data stays on machine (local tier) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Persistent cross-session memory | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Cognitive routing (episodic/semantic) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Session drift detection (HRR) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| L3 grounding verifier | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Multi-agent hivemind | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| MCP server (tools + memory for agents) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Cloud fallback (14b → 32b → Sonnet) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Web IDE | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
-| VS Code extension | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ |
-| HIPAA / air-gapped ready | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Flat-rate pricing (not per-seat) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-
-### vs local AI tools
-
-| Feature | Prism Coder | Ollama | LM Studio | Jan.ai | Mem0 | Zep |
+These tables are the maintainer's assessment as of June 2026. Verify claims that matter to you — products change fast.
+
+| Feature | Prism Coder | GitHub Copilot | Cursor | Windsurf | Amazon Q | Devin |
 |---|:---:|:---:|:---:|:---:|:---:|:---:|
-| Local inference (1.7B–32B cascade) | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
-| Automatic cloud fallback | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Persistent cross-session memory | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ |
-| Knowledge ingestion (MCP + webhook + REST) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Cognitive routing (3-store) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| L3 grounding verifier | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Local inference (open-weight) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Works fully offline | ✅ (free tier) | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Persistent cross-session memory | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Session drift detection | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Native MCP server | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Web IDE + VS Code extension | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Analytics dashboard | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ |
+| L3 grounding verifier | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Behavioral verification (pre-edit) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| MCP server (tools + memory) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Web IDE | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ |
+| VS Code extension | ✅ | ✅ | — | — | ✅ | ❌ |
+| Flat-rate team pricing | ✅ | ❌ (per-seat) | ❌ (per-seat) | ❌ | ❌ | ❌ |
+| HIPAA BAA available | ✅ (Enterprise) | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+### vs local AI / memory tools
+
+| Feature | Prism Coder | Ollama | LM Studio | Mem0 | Zep |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Local inference cascade | ✅ | ✅ | ✅ | ❌ | ❌ |
+| Cloud fallback | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Persistent cross-session memory | ✅ | ❌ | ❌ | ✅ | ✅ |
+| Knowledge ingestion (MCP + webhook) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Cognitive routing (3-store) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Session drift detection | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Native MCP server | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Web IDE + VS Code extension | ✅ | ❌ | ❌ | ❌ | ❌ |
 
 ### Pricing — flat-rate, not per-seat
 
-| | **Prism Coder** | GitHub Copilot | Cursor | Windsurf | Amazon Q | Tabnine |
-|---|:---:|:---:|:---:|:---:|:---:|:---:|
-| **Individual** | **$19/mo** | $10/mo | $20/mo | $15–20/mo | $19/mo | $39/mo |
-| **Team (5 devs)** | **$49/mo flat** | $95/mo | $200/mo | $200/mo | $95/mo | $295/mo |
-| **Enterprise (25 devs)** | **$99/mo flat** | $195/mo | $1,000/mo | Custom | Custom | Custom |
-| **Cost per dev (team)** | **$9.80** | $19 | $40 | $40 | $19 | $59 |
-| **Annual savings (5 devs)** | — | **$552** | **$1,812** | **$1,812** | **$552** | **$2,952** |
+| | **Prism Coder** | GitHub Copilot | Cursor | Amazon Q |
+|---|:---:|:---:|:---:|:---:|
+| **Individual** | **$19/mo** | $10/mo | $20/mo | $19/mo |
+| **Team (5 devs)** | **$49/mo flat** | $95/mo | $200/mo | $95/mo |
+| **Enterprise (25 devs)** | **$99/mo flat** | $195/mo | $1,000/mo | Custom |
 
 ---
 
 ## Plans
 
-| | **Free** | **Standard $19/mo** | **Advanced $49/mo** | **Enterprise $99/mo** |
+All on-device models are free to run locally via Ollama on every tier. A subscription gates **cloud** features, higher model ceilings, and increased limits. Local model ceilings are advisory — on-device models run on your Ollama regardless of plan; the ceiling gates cloud inference and `prism_infer` routing.
+
+| | **Free** | **Standard** $19/mo | **Advanced** $49/mo | **Enterprise** $99/mo |
 |---|---|---|---|---|
-| **Seats included** | 1 | 1 | up to 5 | up to 25 |
-| **Local model ceiling** | up to 4b | up to 14b | up to 32b | up to 32b |
-| **Daily inference limit** | 50 | 200 | 2,000 | 100,000 |
-| **Max output tokens** | 512 | 1,024 | 2,048 | 4,096 |
-| **Cloud fallback** | — | Claude Sonnet 4 | Claude Sonnet 4 | Priority + Sonnet 4 |
-| **L3 grounding verifier** | — | ✅ | ✅ | ✅ |
-| **Knowledge search** | limited | unlimited | unlimited | unlimited |
-| **Session memory** | limited | unlimited | unlimited | unlimited |
-| **Analytics dashboard** | — | ✅ | ✅ | ✅ |
-| **HIPAA BAA** | — | — | — | ✅ |
-
-All on-device models are open-weight and free to run locally via Ollama. The subscription gates cloud features, higher model tiers, and increased limits. Need 25+ seats? [Contact sales](https://synalux.ai/contact). 14-day free trial on all paid plans. [Subscribe →](https://synalux.ai/pricing)
+| Seats | 1 | 1 | up to 5 | up to 25 |
+| Local model ceiling | up to 4b | up to 9b | up to 32b | up to 32b |
+| Daily cloud inference | -- | 200 | 2,000 | 100,000 |
+| Cloud Coder (Web IDE) | -- | 100/day | 1,000/day | 100,000/day |
+| Cloud search | -- | 50/day | 500/day | 100,000/day |
+| Max output tokens | 512 | 1,024 | 2,048 | 4,096 |
+| Cloud fallback | -- | Claude Sonnet 4 | Claude Sonnet 4 | Priority + Sonnet 4 |
+| Grounding verifier (fact-check AI output) | -- | ✅ | ✅ | ✅ |
+| Memory sync (cloud) | -- | ✅ | ✅ | ✅ |
+| Knowledge / session memory | limited | unlimited | unlimited | unlimited |
+| Analytics dashboard | -- | ✅ | ✅ | ✅ |
+| HIPAA BAA | -- | -- | -- | ✅ |
+
+14-day free trial on paid plans. 25+ seats: [contact sales](https://synalux.ai/support)
 
 ---
 
-## Get started
-
-```bash
-# Install globally
-npm install -g prism-mcp-server
-
-# Or use npx (no install)
-npx prism-mcp-server
-```
-
-Add to Claude Desktop / Cursor config:
-
-```json
-{
-  "mcpServers": {
-    "prism": {
-      "command": "npx",
-      "args": ["-y", "prism-mcp-server"]
-    }
-  }
-}
-```
-
-That's it. Open Claude / Cursor and your AI now has memory.
+## How agents use it
 
-More setup details in [`docs/SETUP_GEMINI.md`](docs/SETUP_GEMINI.md).
-
-### Monitoring & Observability *(new in v16.2)*
-
-Built-in Datadog integration — every tool call is logged with tool name, project, and latency. Zero config for self-hosted users (logs to stdout); set `DD_API_KEY` to send structured logs to Datadog HTTP intake.
-
-```bash
-# Enable Datadog logging (optional)
-export DD_API_KEY=your_datadog_api_key
-
-# Enable OpenTelemetry tracing (optional — works with Jaeger, Zipkin, Datadog, Grafana Tempo)
-export PRISM_OTEL_ENABLED=true
-export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
-```
-
-**What's tracked automatically:**
-- `mcp.tool.success` — tool name, project, duration (ms) on every successful call
-- `mcp.tool.error` — tool name, error message, stack trace on failures
-- OpenTelemetry spans with `tool.name` and `project` attributes on all 50 tool handlers
-
-| Dashboard | What it tracks |
-|-----------|---------------|
-| [Prism MCP — Server Analytics](https://app.datadoghq.com/dashboard/tdm-92f-myh/prism-mcp--server-analytics) | Tool call volume, latency per tool (avg/p95), errors by tool, project activity, knowledge search/ingest, session memory ops |
-
-### In-app analytics for paid users *(new in v16.2)*
-
-Paid Synalux subscribers get a built-in analytics dashboard at `/app/memory-analytics`:
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Analytics                              [standard] plan │
-├─────────────────────────────────────────────────────────┤
-│  📝 Sessions: 147  🔄 Handoffs: 23  📚 Knowledge: 89  │
-│  📁 Projects: 5    💾 Memory: 42 KB                    │
-├─────────────────────────────────────────────────────────┤
-│  Today's Usage    🧠 47/200  🔎 12/50  💬 85/200       │
-├─────────────────────────────────────────────────────────┤
-│  30-Day Trend     ▂▃▅▇▆▄▃▅▆▇█▇▅▃▂▃▅▆▇▅▃▂▁▂▃▅▇▆▅▃    │
-├─────────────────────────────────────────────────────────┤
-│  Top Projects     prism-mcp (45) · portal (32) · ...   │
-│  Compaction       3 entries > 5KB — run compact_ledger  │
-└─────────────────────────────────────────────────────────┘
-```
-
-- **Free tier**: paywall with upgrade CTA
-- **Standard+**: session counts, handoffs, knowledge entries, daily quotas with tier limits, 30-day activity trend, project breakdown, compaction candidates
-
----
-
-## How AI agents use it
+Prism exposes 40+ MCP tools. The core memory loop:
 
 | Tool | What it does |
 |---|---|
-| `session_load_context` | Recover prior session's state on boot |
-| `session_save_ledger` | Append immutable session log entry |
+| `session_load_context` | Recover the prior session's state on boot |
+| `session_save_ledger` | Append an immutable session log entry |
 | `session_save_handoff` | Save live state for the next session |
 | `knowledge_search` | Semantic + keyword search over all memories |
-| `query_memory_natural` | Natural-language Q&A over your Mind Palace |
-| `extract_entities` | Pull people / projects / decisions from text |
-| `session_detect_drift` | HRR-powered semantic drift detection (BCBA/Coding/AAC) |
-| `session_synthesize_edges` | Auto-link related memories into a graph |
+| `query_memory_natural` | Natural-language Q&A over the memory store |
+| `session_detect_drift` | Detect when a session has drifted from its goal |
+| `verify_behavior` | Pre-edit scenario challenge — catch bad changes before they happen |
+| `knowledge_ingest` | Teach Prism a codebase or document |
 
-(35+ tools total — full TypeScript signatures in `src/tools/`. Architecture overview in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).)
+Full TypeScript signatures live in [`src/tools/`](src/tools/); architecture in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
 
 <details>
-<summary>🔄 How Prism handles context compaction and context loss</summary>
-
-The LLM context window is treated as ephemeral scratch space. All durable state lives in Prism's persistent store (SQLite / Supabase). Context compaction is a non-event.
-
-**Boot protocol** — every session (including post-compaction) begins with a mandatory `session_load_context` call, enforced via `CLAUDE.md`. The agent is fully oriented before writing a single byte of response.
-
-**Two persistent stores:**
-- `session_save_ledger` — immutable append-only work log (decisions, files changed, summaries)
-- `session_save_handoff` — versioned live-state snapshot (current task, TODOs, open context)
-
-**Ledger compaction** (`session_compact_ledger`) — when a project exceeds a threshold (default: 50 entries), Prism summarizes old entries via LLM into a rollup row, soft-archives originals, and links them via `spawned_from` graph edges. Runs on a 12-hour background scheduler.
-
-→ Full details: [`docs/COMPACTION.md`](docs/COMPACTION.md)
+<summary>How Prism survives context compaction</summary>
 
+The LLM context window is treated as ephemeral scratch space; durable state lives in the persistent store (SQLite locally, the portal in the cloud). Every session begins with a mandatory `session_load_context` call, so the agent is oriented before it writes a response. When a project exceeds a threshold (default 50 entries), `session_compact_ledger` summarizes old entries into a rollup, soft-archives the originals, and links them in the graph. See [`docs/COMPACTION.md`](docs/COMPACTION.md)
 </details>
 
 ---
 
-## Models
-
-Prism Coder inference cascades through fine-tuned models first, with Claude as a quality-gate fallback. Models route through the Synalux router (authentication + subscription required). Cascade: Cloud (OpenRouter) → Ollama local → Claude fallback.
-
-| Model | Ollama tag | Where | Tier | Latency |
-|---|---|---|---|---|
-| **prism-coder:1.7b** | `prism-coder:1b7` (v42) | On-device (Mac/local) · iOS via llama.cpp | Free | ~1.6s |
-| **prism-coder:8b** | `prism-coder:8b` (v36) | On-device iPhone/iPad 8GB+ · local Mac | Free | ~0.8s |
-| **prism-coder:14b** | `prism-coder:14b` (v36) | On-device Mac 24GB+ · iPad Pro · Cloud A100 | Standard+ | ~1.1s |
-| **prism-coder:32b** | `prism-coder:32b` (v7 MoE) | Cloud (OpenRouter) A100 80GB via Synalux | Pro/Enterprise | ~0.8s |
-
-Models use the Synalux SFT corpus (AAC + Prism MCP tool taxonomy + clinical workflows). **Internal quality gate: ≥ 90% on the Prism 102-case eval before production promotion.**
-
-> **Training note**: Base Qwen3 models are strong tool-routers out of the box. Heavy fine-tuning regresses tool-vs-plain-text decisions; light-touch polish recipes (small corpus, balanced tool/plain-text split) are the published path. Production adapter selection and retrain methodology are managed in the Synalux portal.
-
-**Per-category breakdown — [Prism 102-case eval](tests/benchmarks/prism-routing-100/README.md) (3-seed mean, v36/v7 system prompt, May 2026):**
-
-| Model | Overall | Load ctx | Save | Srch mem | Handoff | Compact | Know srch | AAC | Translate | No-tool | Info | Edge | Avg lat | Inv |
-|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
-| **prism-coder:32b** v7 | **100.0%** | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | **100%** | 0.8s | 0 |
-| **prism-coder:8b** v36 | **100.0%** | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | **100%** | 0.8s | 0 |
-| **prism-coder:14b** v36 | **100.0%** | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | **100%** | 1.1s | 0 |
-| **Claude Opus 4.7** | **98.3%** | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 83% | 3.0s | 0 |
-| **prism-coder:1.7b** v42 | **100.0%** | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | 100% | **100%** | 1.6s | 0 |
-
-> **Methodology**: 102-case pool across 12 categories. Scores are 3-seed mean (seeds 2027/2028/2029, zero variance across all seeds). All fine-tuned models use the Qwen3 nothink template with keyword-trigger routing prompts and `-> respond directly (no tool)` for the no-tool class. Full runner: [`tests/benchmarks/prism-routing-100/benchmark.py`](tests/benchmarks/prism-routing-100/benchmark.py) · Cascade runner: [`tests/benchmarks/cascade-14b-32b-opus/cascade_eval.py`](tests/benchmarks/cascade-14b-32b-opus/cascade_eval.py).
->
-> **These are NOT general-purpose LLM benchmarks.** This eval measures routing precision on 6 specific MCP tools. The prism-coder models are specialists trained on this exact task — they match or exceed Claude on routing while Claude dominates on general reasoning, coding, and open-domain QA. The value is **offline reliability at zero cost**, not replacing cloud AI.
-
-**iOS deployment:** On-device inference via **llama.cpp Swift SPM**. Auto-selects by device RAM: 14B on iPad Pro 16GB (100% routing), 8B on iPhone/iPad 8GB (100%, OOM fallback to 1.7B at 100%). CoreML not viable — coremltools doesn't support Qwen3 attention ops. Integration: `LLMEngine.swift` → `prismNativeBridge.askAI()` → token stream. WiFi fallback: Mac Ollama (`OLLAMA_HOST=0.0.0.0`).
-
-### Benchmarks — run them yourself
-
-All benchmarks are open-source. Reproduce every number in this README:
-
-```bash
-git clone https://github.com/dcostenco/prism-coder
-cd prism-coder
-pip install anthropic requests
-
-# Per-model solo eval (102 cases, 3 seeds)
-python3 tests/benchmarks/prism-routing-100/benchmark.py --models 14b 8b 32b 1b7 opus
-
-# Cascade eval — 14B → 32B → Opus (Claude Opus as etalon)
-export ANTHROPIC_API_KEY=sk-ant-...
-ollama pull dcostenco/prism-coder:14b dcostenco/prism-coder:32b
-python3 tests/benchmarks/cascade-14b-32b-opus/cascade_eval.py
-```
-
-**Not a general function-calling benchmark.** This measures routing precision on 6 specific MCP tools. We don't claim to beat Claude on general capabilities. We match or exceed Claude on the ONE task that matters for offline AAC: correct tool routing, every time, under 2 seconds, with zero cloud.
-
-| Benchmark | Source | What it measures |
-|---|---|---|
-| Per-model BFCL | [`tests/benchmarks/prism-routing-100/`](tests/benchmarks/prism-routing-100/) | Solo accuracy per model, 12 categories |
-| Cascade vs Opus | [`tests/benchmarks/cascade-14b-32b-opus/`](tests/benchmarks/cascade-14b-32b-opus/) | Tier distribution, Opus engagement rate, cascade accuracy |
-| LoCoMo-Plus (Cognitive) | [`dcostenco/Locomo-Plus`](https://github.com/dcostenco/Locomo-Plus) | Long-context dialogue coherence and historical memory retention |
-
-### Cognitive Dialogue Memory (LoCoMo-Plus Benchmark)
-
-LoCoMo-Plus is a long-context, multi-day dialogue benchmark designed to test an AI agent's memory retention, context awareness, and ability to coherently reference historical dialogue evidence.
-
-The **Cognitive** subset (401 multi-day dialogue scenarios) was evaluated head-to-head comparing raw baseline models against the **Prism-MCP** framework (using local SQLite semantic memory). Graded by a neutral `gemini-2.5-flash` model acting as judge (scoring on coherence, continuity, and fact accuracy):
-
-| Configuration | Samples | Total Score | Average Score | Absolute Delta | Relative Error Reduction |
-| :--- | :---: | :---: | :---: | :---: | :---: |
-| **Gemini-2.5-flash (Baseline)** | 401 | 278.0 / 401 | **69.33%** | — | — |
-| **Prism-MCP (Gemini-2.5-flash + Memory)** | 401 | 361.0 / 401 | **90.02%** | **+20.69pp** | **67.5%** |
-| **Gemini-3.1-pro-preview (Baseline)** | 401 | 272.0 / 401 | **67.83%** | — | — |
-| **Prism-MCP (Gemini-3.1-pro + Memory)** | 401 | 382.0 / 401 | **95.26%** | **+27.43pp** | **85.3%** |
-| **Gemini-3.5-flash (Baseline)** | 401 | 237.0 / 401 | **59.10%** | — | — |
-| **Prism-MCP (Gemini-3.5-flash + Memory)** | 401 | 388.0 / 401 | **96.76%** | **+37.66pp** | **92.1%** |
-| **Claude Sonnet 4.6 (Baseline)** | 401 | 290.0 / 401 | **72.32%** | — | — |
-| **Prism-MCP (Claude Sonnet 4.6 + Memory)** | 401 | 357.0 / 401 | **89.03%** | **+16.71pp** | **60.4%** |
-
-**Key Takeaways**:
-* **Pure attention limits**: Even the strongest frontier model tested — Claude Sonnet 4.6 at **72.32%** — misses over a quarter of cognitive memory cues without external memory. Gemini 3.5 Flash baseline sits at **59.10%**. Both suffer from attention dilution when parsing massive multi-day transcripts directly in active context.
-* **Prism lifts every model**: Prism-MCP yields large gains regardless of base model — from +16.71pp (Claude) to +37.66pp (Gemini 3.5 Flash). Even Claude's stronger native recall benefits from structured retrieval, jumping from 72.32% to **89.03%**.
-* **Best overall**: Prism-MCP + Gemini 3.5 Flash achieves the highest score (**96.76%**), eliminating 92.1% of baseline errors. This makes the cheapest model + Prism more accurate than the most expensive model alone.
-* **Claude vs Gemini (raw)**: Claude Sonnet 4.6 outperforms all Gemini baselines by a wide margin (+13.22pp over Flash 3.5, +4.49pp over Pro 3.1), confirming stronger native long-context recall.
-
-<details>
-<summary>🔍 View Test Case Schema & Sample</summary>
-
-A representative test sample from the `unified_cognitive_only.json` ([GitHub source](https://github.com/dcostenco/Locomo-Plus/blob/main/data/unified_cognitive_only.json)) dataset contains a multi-turn chat history with a memory "needle" placed days prior, followed by a cued dialogue prompt:
-
-```json
-{
-  "category": "Cognitive",
-  "input_prompt": "Caroline said, \"...\"\nMelanie said, \"...\"",
-  "trigger": "Melanie said, \"Hey, Caroline! Nice to hear from you! Love the necklace, any special meaning to it?\"",
-  "evidence": "Swedish grandmother's necklace was gifted to Caroline",
-  "answer": "Yes, this necklace was a gift from my grandmother in my home country, Sweden."
-}
-```
-
-When evaluated:
-* **Baseline models** without memory frequently output a generic guess (e.g., "Thanks, it was a gift from a friend") or fail to reference the Sweden/grandmother relationship.
-* **Prism-MCP** automatically embeds the prior turns, stores them in SQLite, and when cued, retrieves the precise "Swedish grandmother" evidence turn via semantic vectors to inject it into active context.
-</details>
-
-<details>
-<summary>💻 View How to Reproduce Publicly (Test Source & Guide)</summary>
-
-To run and review the evaluation suite on your local setup using the benchmark runner scripts (`evaluate_qa.py` and `llm_as_judge.py`):
-
-```bash
-# 1. Clone the LoCoMo-Plus evaluation codebase
-git clone https://github.com/dcostenco/Locomo-Plus /tmp/Locomo-Plus
-cd /tmp/Locomo-Plus
-
-# 2. Run Baseline Gemini 3.1 Pro Evaluation (concurrency 5)
-export GOOGLE_API_KEY="your-api-key"
-PYTHONPATH=/tmp/Locomo-Plus python3 evaluation_framework/task_eval/evaluate_qa.py \
-  --data-file data/unified_cognitive_only.json \
-  --out-file output/gemini_3.1_pro_pred.json \
-  --model gemini-3.1-pro-preview \
-  --backend call_gemini \
-  --concurrency 5
-
-# 3. Run Prism-MCP powered by Gemini 3.1 Pro Evaluation (concurrency 1 to guard SQLite locks)
-export PRISM_TEXT_MODEL=gemini-3.1-pro-preview
-PYTHONPATH=/tmp/Locomo-Plus python3 evaluation_framework/task_eval/evaluate_qa.py \
-  --data-file data/unified_cognitive_only.json \
-  --out-file output/prism_gemini_3.1_pro_pred.json \
-  --model gemini-3.1-pro-preview \
-  --backend call_prism \
-  --concurrency 1
-
-# 4. Run Claude Sonnet 4.6 Baseline Evaluation (concurrency 3, rate-limit safe)
-export ANTHROPIC_API_KEY="your-api-key"
-PYTHONPATH=/tmp/Locomo-Plus python3 evaluation_framework/task_eval/evaluate_qa.py \
-  --data-file data/unified_cognitive_only.json \
-  --out-file output/claude_sonnet46_pred.json \
-  --model claude-sonnet-4-6 \
-  --backend call_claude \
-  --concurrency 3
-
-# 5. Grade results using the LLM-as-a-Judge script
-PYTHONPATH=/tmp/Locomo-Plus python3 evaluation_framework/task_eval/llm_as_judge.py \
-  --input-file output/prism_gemini_3.1_pro_pred.json \
-  --out-file output/prism_gemini_3.1_pro_judged.json \
-  --model gemini-2.5-flash \
-  --backend call_gemini \
-  --concurrency 5 \
-  --summary-file output/prism_gemini_3.1_pro_summary.json
-```
-</details>
-
-### Models on HuggingFace
-
-| Model | HuggingFace | Solo BFCL | Cascade role | Size |
-|---|---|---|---|---|
-| prism-coder:32b | [dcostenco/prism-coder-32b](https://huggingface.co/dcostenco/prism-coder-32b) | **100.0%** routing (v7 MoE) | Tier 2 (catches ~1% 14B misses) | 16 GB |
-| prism-coder:8b | [dcostenco/prism-coder-8b](https://huggingface.co/dcostenco/prism-coder-8b) | **100.0%** routing (v36) | Mobile tier | 4.7 GB |
-| prism-coder:14b | [dcostenco/prism-coder-14b](https://huggingface.co/dcostenco/prism-coder-14b) | **100.0%** routing (v36) | Tier 1 (serves ~99% of traffic) | 8.4 GB |
-| prism-coder:1.7b | [dcostenco/prism-coder-1.7b](https://huggingface.co/dcostenco/prism-coder-1.7b) | **100.0%** routing (v42) | On-device / always-fits fallback | 1.1 GB |
-| prism-ide:14b | [dcostenco/prism-ide](https://huggingface.co/dcostenco/prism-ide) | **22/22** TypeScript eval (v1) | Code generation tier 1 (~1.1s) | 8.4 GB |
-| prism-ide:32b | [dcostenco/prism-ide](https://huggingface.co/dcostenco/prism-ide) | Complex code + multi-file (v3) | Code generation tier 2 (~0.8s MoE) | 16 GB |
-
-## Self-hosted / Local AI (Enterprise)
-
-Run the full Prism model stack on your own hardware — zero cloud, zero latency, full data sovereignty.
-
-**Requirements:** Mac M2 Pro+ (48GB recommended) or Linux with NVIDIA GPU · [Ollama](https://ollama.com)
+## CLI
 
 ```bash
-# On-device tier — 1.1 GB (any machine, iPhone) — 100% routing
-ollama pull dcostenco/prism-coder:1b7
-
-# Mobile tier — 4.7 GB (iPhone/iPad 8GB, Mac M1+) — 100% routing
-ollama pull dcostenco/prism-coder:8b
-
-# Standard tier — 8.4 GB (Mac 24GB+, iPad Pro 16GB) — 100% routing
-ollama pull dcostenco/prism-coder:14b
-
-# Reasoning tier — 16 GB (Mac M2 Ultra+, 30B-A3B MoE) — 100% routing
-ollama pull dcostenco/prism-coder:32b
+prism load <project>      # load session context
+prism save                # save ledger + handoff
+prism search <query>      # search code across repos (exact / regex / symbol / semantic)
+prism review <files...>   # AI code review — security, performance, style
+prism scan <files...>     # security scan — secrets, licenses, Dockerfile
+prism push                # push local SQLite to the cloud backend
+prism register-models     # alias dcostenco/prism-coder:* -> prism-coder:*
 ```
 
-Set `LOCAL_LLM_URL=http://localhost:11434` in your portal config. Routing is automatic:
+### `prism search` — semantic code search
 
-**Desktop/server**: 14B → 32B → Claude Sonnet 4 fallback · **Mobile/offline**: 14B → 8B → 1.7B
+<p align="center">
+  <img src="docs/scm_search_cli.jpg" alt="prism search — semantic code search with relevance scores" width="500" />
+</p>
 
-iOS/mobile on same WiFi: `OLLAMA_HOST=0.0.0.0 ollama serve` on the Mac, then point `LOCAL_LLM_URL` at the Mac's IP.  
-Routing accuracy (May 2026, v36/v7 system prompt, 3-seed mean): 32B v7 = **100.0%** · 8B v36 = **100.0%** · 14B v36 = **100.0%** · 1.7B v42 = **100.0%**  
-Cascade (14B→32B): **100.0%** · Opus solo: 98.3% · Opus engaged: **0% of requests** → [Full results](tests/benchmarks/cascade-14b-32b-opus/README.md)
+### `prism review` — AI code review with HIPAA checks
 
----
+<p align="center">
+  <img src="docs/scm_review_cli.jpg" alt="prism review — AI code review with security and HIPAA findings" width="400" />
+</p>
 
-## What you can build with it
+### `prism scan` — security scanner for secrets, Dockerfiles, licenses
 
-- **Persistent coding assistant** that remembers your codebase, your decisions, your team's conventions
-- **Research agent** that builds knowledge over time — Auto-Scholar pipeline ingests papers / docs and synthesizes
-- **Clinical scribe** that retains patient context across visits (HIPAA-compliant cloud + local)
-- **Customer support agent** that learns from every ticket
-- **Writing assistant** that knows your voice, your prior drafts, and what you've already published
+<p align="center">
+  <img src="docs/scm_scan_cli.jpg" alt="prism scan — security scan finding secrets and container issues" width="400" />
+</p>
 
 ---
 
 ## Companions
 
-### 🌐 Website & Docs
+Prism works alongside these tools — use whichever fits your workflow.
 
-**[synalux.ai/prism-mcp](https://synalux.ai/prism-mcp)** — full documentation, dashboard, subscription plans, and model downloads.
+### Web IDE — Prism Coder
 
-### 💻 Web IDE — Prism Coder
+A browser-based IDE at [synalux.ai/coder](https://synalux.ai/coder). Import any GitHub repo and get:
 
-Use Prism Coder directly in your browser — no install, no desktop app required. Standalone coding IDE with the prism-coder agent built in. Works with any Prism plan (no Synalux health subscription needed).
+- **Monaco editor** with multi-tab, split view, syntax highlighting, and VS Code keybindings
+- **In-browser Node.js** via WebContainer (your code runs in the browser sandbox, not on a server)
+- **Integrated terminal** — WebContainer shell in-browser; optional server PTY via WebSocket when connected to a dev server
+- **AI Agent Mode** — describe a task and the agent creates files, runs type-checks, and verifies
+- **Source control** — commit, branch, push/pull, stash, blame, tag management
+- **Live Share** — real-time collaborative editing with session links
+- **Node.js debugger** via Chrome DevTools Protocol
+- **Tasks runner** (VS Code `tasks.json` compatible), **Problems panel** (Monaco diagnostics)
+- **12-language i18n** — full UI localization
 
-**[synalux.ai/coder](https://synalux.ai/coder)**
+<p align="center">
+  <img src="docs/screenshots/agent-mode.png" alt="Prism Coder IDE — Agent Mode creating a component with auto-fix and type-checking" width="500" />
+</p>
 
-| Feature | Detail |
-|---|---|
-| Agent | prism-coder:8b offline · Claude Sonnet 4 (Standard+) |
-| Integrations | GitHub repos · same Prism account, no separate sign-up |
-| Plans | Free (4b) · Standard $19/mo (14b) · Advanced $49/mo (32b) · Enterprise $99/mo |
+<p align="center">
+  <img src="docs/screenshots/collaboration.png" alt="Prism Coder IDE — Live Share with team members and real-time cursor tracking" width="500" />
+</p>
 
-### 🧩 VS Code Extension — Synalux
+Standard+ plans get cloud AI and higher rate limits. Free tier works with local Ollama. Code execution uses the in-browser WebContainer by default; Live Share and the optional PTY terminal connect to external servers when explicitly enabled.
 
-Memory-augmented AI inside VS Code, powered by Prism. 20 multimodal tools, multi-agent orchestration, 12-language support. Works offline (Ollama) or cloud (OpenRouter). HIPAA-compliant healthcare workflows.
+### VS Code Extension — Synalux
 
-[![VS Marketplace](https://img.shields.io/visual-studio-marketplace/v/synalux-ai.synalux?label=VS%20Marketplace&color=007ACC)](https://marketplace.visualstudio.com/items?itemName=synalux-ai.synalux)
+Memory-augmented AI inside VS Code with clinical practice management features. Install from the marketplace:
 
 ```bash
-# Install from terminal
 code --install-extension synalux-ai.synalux
 ```
 
-Or open VS Code → Extensions (⇧⌘X) → search **"Synalux"** → Install.
+[![VS Marketplace](https://img.shields.io/visual-studio-marketplace/v/synalux-ai.synalux?label=VS%20Marketplace&color=007ACC)](https://marketplace.visualstudio.com/items?itemName=synalux-ai.synalux)
 
-### 📦 npm / npx
+AI chat, voice input, SOAP note generator, team collaboration, and video calls — all inside VS Code. Routes through local Ollama by default; cloud on paid tiers.
 
-```bash
-# Run without installing (always latest version)
-npx prism-mcp-server
+<details>
+<summary>Feature details</summary>
 
-# Or install globally
-npm install -g prism-mcp-server
-prism load my-project
-```
+- **AI**: Chat participant (`@synalux`), multi-agent pipeline, voice input, model switching, 10 tones
+- **Clinical**: SOAP note generator, role-based access, document signing, patient board
+- **Collaboration**: Team chat, DMs, video calls, customer board, visual builder, DevContainers
+- **Privacy**: Local Ollama by default. `preferLocal=true` tries local first. Enterprise BAA available.
+</details>
 
-Package: [`prism-mcp-server` on npm](https://www.npmjs.com/package/prism-mcp-server)
+### Prism AAC
 
-### PrismAAC
+Communication app for non-speaking users, powered by the on-device prism-coder fleet for phrase prediction. macOS / iOS / web.
 
-AAC communication app for non-speaking users. Powered by Prism's spreading-activation phrase ranking + on-device 7B model. macOS / iOS / Android via web. → [github.com/dcostenco/prism-aac](https://github.com/dcostenco/prism-aac)
+See [github.com/dcostenco/prism-aac](https://github.com/dcostenco/prism-aac)
 
 ---
 
-## 🆕 Prism as Foundation (v14.0.0)
-
-As of v14.0.0, Prism's algorithm exports are a **stable public contract** under SemVer. External systems can port `actrActivation.ts` (ACT-R cognitive decay), `spreadingActivation.ts` (the 0.7 similarity + 0.3 activation hybrid score), `routerExperience.ts` (experience bias with `MIN_SAMPLES=5` cold-start gate), `compactionHandler.ts` (the 25KB prompt-budget cap), and `graphMetrics.ts` (warning ratios) with citations and pin a Prism version.
-
-### Reference consumers
-
-| Consumer | What it uses from Prism |
-|---|---|
-| [Audit hooks framework](https://github.com/dcostenco/prism-coder/blob/main/docs/WOW_FEATURES.md#7-the-recipe-combining-all-of-the-above) | ACT-R decay (`d=0.25` lesson rate), spreading activation hybrid score (0.7/0.3), experience bias (`MIN_SAMPLES=5`, `MAX_BIAS_CAP=0.15`), graph-metrics warning ratios (0.20 / 0.30 / 0.40), compaction's 25KB prompt-budget. **327 tests pin every constant** — CI catches divergence automatically. |
-| [PrismAAC](https://github.com/dcostenco/prism-aac) | Spreading-activation phrase ranking (recency × frequency × per-user history). Caregiver corrections auto-harvest into the personalization corpus via the audit-hooks postflight harvester. The on-device 7B model + this algorithm stack is what makes PrismAAC defensible. |
-| Synalux portal | Tier-aware model routing using experience bias on prior outcomes per fingerprint. HIPAA-compliant clinical scribe with on-device-first privacy guarantees. |
-
-## CLI Reference
-
-Prism Coder includes a CLI for session management, code review, and sync operations.
-
-```bash
-prism load <project>          # Load session context (same as session_load_context MCP tool)
-prism save                    # Save session state (ledger + handoff)
-prism ledger <project>        # Save a session log entry (same as session_save_ledger)
-prism handoff <project>       # Update live project state for next session
-prism push                    # Push local SQLite data to Supabase cloud
-prism sync                    # Cross-backend data synchronization
-prism search <query>          # Search code across repos (exact, regex, symbol, semantic)
-prism review <files...>       # AI code review — security, performance, style
-prism scan <files...>         # Security scan — secrets, licenses, Dockerfile
-prism dora                    # Show DORA metrics for current project
-prism scm                     # Source control, AI review, security scanning
-prism verify                  # Manage the verification harness
-prism status                  # Check verification state and config drift
-prism generate                # Bless current rubric as canonical
-prism register-models         # Alias dcostenco/prism-coder:* → prism-coder:*
-```
-
-## Testing
-
-```bash
-npm test                           # 2,676 test cases across 89 files (vitest)
-npm test -- --coverage             # coverage report
-python3 tests/benchmarks/prism-routing-100/benchmark.py --models 1b7 14b 32b
-```
-
-**Pinned in CI** — 327 tests enforce every constant: ACT-R decay `d=0.25`, spreading-activation hybrid score `0.7/0.3`, experience bias `MIN_SAMPLES=5` / `MAX_BIAS_CAP=0.15`, graph-metrics warning ratios `0.20 / 0.30 / 0.40`, compaction's 25KB prompt-budget. CI catches divergence automatically.
-
-**Coverage areas**:
-- HRR zero-search retrieval (97 tests: 3 embedding strategies, edge cases, persistence, adaptive cascade, API client, chat integration)
-- Knowledge ingestion (32 tests: chunker, Q&A gen, webhook, security, storage round-trip)
-- Prism infer cascade (110 tests: tier selection, cloud fallback, grounding verifier)
-- Compaction handler (rollup creation, concurrency guard, LLM failure)
-- Model picker (20 tests: 14b default ceiling, 4b verifier, RAM gating)
-- Storage round-trip (12 architectural guard tests preventing bypass)
-- BCBA skill integration
-- Deep storage tier
-- Dashboard rendering
-- Routing benchmarks (eval_300: 300 cases, 17 tools)
+## Git Hooks (Portable)
 
-## Migration
-
-### Local SQLite → Synalux portal
-
-If you've been running Prism on the free tier and want to move historical session data into the paid-tier portal, use the migration script:
+Pre-commit and pre-push security hooks that work with any editor, any AI tool, and direct CLI. No Claude Code dependency.
 
 ```bash
-# dry run first — prints what would be migrated, hits no network
-node scripts/migrate-local-to-portal.mjs --dry-run
-
-# real run — pushes ledger + handoff entries through POST /api/v1/prism/memory
-PRISM_SYNALUX_API_KEY=synalux_sk_... \
-  node scripts/migrate-local-to-portal.mjs
-
-# scope to one project
-node scripts/migrate-local-to-portal.mjs --project=my-project
+# Install in all repos (one-time)
+bash synalux-private/scripts/install-git-hooks.sh
 
-# include scholar entries (excluded by default — usually large + low-value)
-node scripts/migrate-local-to-portal.mjs --include-scholar
+# Or install manually in a single repo
+cp hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+cp hooks/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-push
 ```
 
-**What it does**: reads `~/.prism-mcp/data.db` via `@libsql/client` (already a runtime dep — no extra install), exchanges the refresh token for a JWT (cached + auto-refreshed before expiry), and POSTs each ledger entry and handoff to the portal. Failures are logged with the source row id; successes are counted at the end.
+| Hook | What it checks | Mode |
+|------|----------------|------|
+| `pre-commit` | Dead code, orphan services, scaffold code, missing auth | `PRECOMMIT_MODE=advisory\|block\|off` |
+| `pre-push` | 19-rule security audit (SSRF, SQL injection, secrets, IDOR, etc.) | `PREPUSH_MODE=advisory\|block\|off` |
 
-**Credentials**: `PRISM_SYNALUX_API_KEY` from env. If unset, the script also checks `~/prism/.env` for `PRISM_SYNALUX_API_KEY=...` as a convenience for dev workflows.
+Default mode is `advisory` (warn but allow). Set `*_MODE=block` for hard enforcement. Hooks look for full audit scripts in the repo first (`hooks/lib/`), then `~/.claude/hooks/` fallback, then minimal inline checks.
 
-**Idempotency**: handoffs are written with the portal's CRDT merge (last-write-wins per project+role); ledger entries are append-only and de-duped server-side by `(project, conversation_id, summary)`. Re-running on the same DB is safe.
+---
 
-**One-shot only**: this script is a migration tool, not a sync daemon. Once you've moved, set `PRISM_STORAGE=synalux` (or leave it on `auto` and let the resolver pick synalux when credentials are present) and the MCP server writes directly to the portal going forward.
+## Self-hosting (Enterprise)
 
-## Production Infrastructure
+Run the full model stack on your own hardware — no cloud, full data sovereignty.
 
-### Architecture
+**Requirements:** Mac M2 Pro+ (48 GB recommended) or Linux + NVIDIA GPU, plus [Ollama](https://ollama.com).
 
-```
-  CLIENTS
-  ┌─────────────────────┐  ┌─────────────────────────────┐
-  │  prism-aac (iOS/web)│  │  Claude Code · Cursor · IDE │
-  │  Vercel             │  │  MCP config → Railway URL   │
-  └──────────┬──────────┘  └─────────────┬───────────────┘
-             │ inference                  │ memory
-             ▼                            ▼
-  ┌──────────────────────┐  ┌─────────────────────────────┐
-  │  SYNALUX ROUTER      │  │  prism-mcp SERVER           │
-  │  Vercel              │  │                             │
-  │  • JWT auth          │  │  Primary   — Railway        │
-  │  • tier enforcement  │  │  Standby   — Fly.io         │
-  │  • complexity route  │  │  Fallback  — Supabase REST  │
-  │  • proxy to cloud    │  │  auto-failover chain        │
-  └──────────┬───────────┘  └─────────────┬───────────────┘
-             │                            │
-             ▼                            ▼
-  ┌──────────────────────────────┐  ┌─────────────────────────────┐
-  │  OPENROUTER / LOCAL          │  │  SUPABASE                   │
-  │                              │  │  session ledgers            │
-  │  Cloud: Claude Sonnet 4      │  │  knowledge graph            │
-  │  Routing: prism-coder        │  │  handoffs & todos           │
-  │   :32b(100%) :14b(100%)      │  │                             │
-  │   :8b(100%)  :1b7(100%)      │  │  source of truth            │
-  │  Code:    prism-ide          │  │                             │
-  │   :14b · :32b                │  │                             │
-  └──────────────────────────────┘  └─────────────────────────────┘
+```bash
+ollama pull dcostenco/prism-coder:9b       # default router
+export LOCAL_LLM_URL=http://localhost:11434
 ```
 
-### Service Routing
+Routing is automatic: `9b → 4b → cloud fallback` on desktop/server, `2b → cloud fallback` on mobile/iPhone. For iOS or another machine on the same network, run `OLLAMA_HOST=0.0.0.0 ollama serve` and point `LOCAL_LLM_URL` at the host's IP.
 
-**LLM Backends**
-
-| Surface | Primary | Fallback | Local |
-|---|---|---|---|
-| AI Chat (free) | Gemini 2.5 Flash (direct API) | Claude Haiku 3.5 | prism-coder:14b via Ollama |
-| AI Chat (paid) | Claude Sonnet 4 (OpenRouter) | Claude Haiku 3.5 | prism-coder:14b via Ollama |
-| Prism Coder (tool-calling) | Claude Haiku 3.5 (OpenRouter) | — | prism-coder:14b via Ollama |
-| Prism AAC | Local prism-coder:14b | Gemini 2.5 Flash / Claude | prism-coder:8b / :1b7 |
-
-**Web Search**
-
-| Surface | Primary | Fallback |
-|---|---|---|
-| AI Chat `@search` | Firecrawl | — |
-| Prism MCP agents (cloud) | Firecrawl | — |
-| Prism MCP server (local) | Firecrawl (via MCP tools) | — |
-| Clinical research | PubMed + ERIC + Semantic Scholar | DuckDuckGo |
+---
 
-**TTS (Text-to-Speech)**
+## Configuration reference
 
-| Tier | Engine | Offline |
+| Variable | Purpose | Default |
 |---|---|---|
-| 1 | Inworld TTS-2 (cloud) | — |
-| 1.5 | Kokoro-82M neural (WASM) | en/es/fr/pt/ja/zh |
-| 2 | OS Web Speech API | all |
-| 3 | WASM espeak-ng | all |
-
-**Other Services**
+| `PRISM_STORAGE` | `local` / `synalux` / `supabase` / `auto` | `auto` |
+| `PRISM_SYNALUX_API_KEY` | Paid-tier portal key (`synalux_sk_...`) | -- (local if unset) |
+| `LOCAL_LLM_URL` | Ollama endpoint | `http://localhost:11434` |
+| `PRISM_FORCE_LOCAL` | Force local SQLite regardless of credentials | `false` |
 
-| Service | Provider | Purpose |
-|---|---|---|
-| Payments | Stripe | Subscriptions, checkout |
-| Email | Resend | Transactional (invites, shares) |
-| Video | LiveKit | Telehealth, case conferences |
-| SMS | Twilio | Emergency alerts, caregiver notifications |
-| Translation | Offline dictionary (1,261 × 20 langs) | AAC, Watch |
+With no variables set, Prism runs fully local. Set `PRISM_SYNALUX_API_KEY` (and leave `PRISM_STORAGE=auto`) to use the cloud backend.
 
-## Synalux Inference Router
+---
 
-All Prism AAC model inference is protected behind Synalux as a mandatory router. Models are **never accessible directly** — all traffic goes through Synalux for auth, billing, and rate limiting.
+## Testing
 
+```bash
+npm test                 # full suite (vitest)
+npm test -- --coverage   # coverage report
 ```
-┌──────────────────────────────────────────────────────────┐
-│  CLIENT LAYER                                            │
-│  prism-aac (iOS/web)         │   Synalux Portal          │
-└──────────────┬───────────────────────────────────────────┘
-               │ POST /api/v1/prism-aac/inference
-               │ Authorization: Bearer <user-JWT>
-               ▼
-┌──────────────────────────────────────────────────────────┐
-│  SYNALUX ROUTER                                          │
-│  1. Verify JWT (no anonymous access)                     │
-│  2. Check subscription tier                              │
-│  3. Enforce rate limit (per-tier daily cap)               │
-│  4. Route to model tier by complexity                    │
-│  5. Proxy → OpenRouter / Gemini (key never exposed)      │
-│  6. Log → aac_inference_log (audit trail)                │
-└──────────┬───────────────────────────────┬───────────────┘
-           │                               │
-           ▼                               ▼
-  ┌────────────────────┐      ┌──────────────────────┐
-  │  LOCAL (Ollama)    │      │  CLOUD (OpenRouter)  │
-  │  prism-coder:14b   │      │  Claude Sonnet 4     │
-  │  prism-coder:8b    │      │  Claude Haiku 3.5    │
-  │  prism-coder:1b7   │      │  Gemini 2.5 Flash    │
-  │  free, offline     │      │  paid tiers          │
-  └────────────────────┘      └──────────────────────┘
-
-On-device (free, offline):
-  prism-coder:1b7 GGUF Q4_K_M (1.1 GB) → any Apple device
-  prism-coder:8b  GGUF Q4_K_M (4.7 GB) → iPhone/iPad 8 GB+
-  prism-coder:14b GGUF Q4_K_M (8.4 GB) → Mac/iPad Pro 16 GB+
-
-HuggingFace: dcostenco/prism-coder-{14b,8b,32b,1.7b} (public GGUF weights)
-```
-
-| Plan | Cloud model | Daily limit | On-device |
-|---|---|---|---|
-| **Free** | — | unlimited local | prism-coder:1.7b (100%) + 8b (100%) + 14b (100%) |
-| **Standard $19/mo** | Claude Sonnet 4 | 200 req | + cloud fallback |
-| **Pro $49/mo** | prism-coder:32b | 2,000 req | + reasoning tier |
-| **Enterprise $99/mo** | prism-coder:32b priority | unlimited | + HIPAA BAA + custom fine-tuning |
 
-All on-device models are **free for every tier** — no subscription needed for local inference. Offline translation (1,261 phrases × 20 languages) included in all plans.
-
-[Subscribe →](https://synalux.ai/pricing)
-
-See [`docs/WOW_FEATURES.md`](docs/WOW_FEATURES.md) for the algorithm catalogue. Release notes in [`docs/releases/v14.0.0-prism-as-foundation.md`](docs/releases/v14.0.0-prism-as-foundation.md).
+Coverage spans HRR retrieval, knowledge ingestion, the inference cascade and grounding verifier, compaction, the model picker, and storage round-trips.
 
 ---
 
-<details>
-<summary>📚 Architecture, cognitive systems, and full feature catalog</summary>
+## Migration: local to cloud
 
-**Detailed docs in this repo:**
-- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — system architecture, memory routing, HRR
-- [`docs/COMPACTION.md`](docs/COMPACTION.md) — how Prism handles LLM context compaction and ledger compaction
-- [`docs/SETUP_GEMINI.md`](docs/SETUP_GEMINI.md) — Gemini configuration
-- [`docs/self-improving-agent.md`](docs/self-improving-agent.md) — adversarial eval / anti-sycophancy
-- [`docs/rfcs/`](docs/rfcs/) — design RFCs
-- [`docs/releases/`](docs/releases/) — per-version release notes
-- [`CHANGELOG.md`](CHANGELOG.md) — version history (v12.5 Unified Billing, v11.6 Hivemind, v11.5.1 Auto-Scholar, etc.)
-- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contributor guide
+To move free-tier history into the paid portal:
 
-**The original 1933-line README is preserved in git history.** To browse the prior version (full feature catalog, Cognitive Architecture v7.8, Autonomous Cognitive OS v9.0, HRR Zero-Search, Adversarial Evaluation walkthroughs, Universal Import patterns, competitive analysis vs LangMem/MemGPT/Letta/Zep, v12.5 Unified Billing details, v11.6 Hivemind, v11.5.1 Auto-Scholar): `git show HEAD~1:README.md`.
+```bash
+node scripts/migrate-local-to-portal.mjs --dry-run        # preview, no network
+PRISM_SYNALUX_API_KEY=synalux_sk_... \
+  node scripts/migrate-local-to-portal.mjs                # push ledger + handoffs
+```
 
-</details>
+It reads `~/.prism-mcp/data.db` and POSTs entries to the portal. Ledger entries are append-only and de-duped server-side; handoffs use last-write-wins per project. Re-running on the same DB is safe. This is a one-shot migration, not a sync daemon — after it, set `PRISM_STORAGE=synalux` (or leave it on `auto`).
 
 ---
 
 ## License
 
-[AGPL-3.0](LICENSE) — Open source. Same license as Prism AAC. Commercial use via Synalux subscription for hosted/managed deployment.
+| Product | License |
+|---|---|
+| **prism-mcp-server** (this repo) | [AGPL-3.0](LICENSE) |
+| **VS Code extension** (synalux-ai.synalux) | BSL-1.1 |
+| **Web IDE** (synalux.ai/coder) | Synalux Terms of Service |
+| **Prism AAC** | AGPL-3.0 |
+
+The AGPL-3.0 license covers the MCP server and its source code. The VS Code extension and Web IDE are separate products with their own licenses. Commercial hosted/managed deployment of the MCP server is available via the Synalux subscription.