@theglitchking/semantic-memory 1.0.0

package/dist/schema-F3RTY6SQ.js

@@ -0,0 +1,12 @@
+import {
+  installDefaultSchema,
+  loadSchema,
+  validateNote
+} from "./chunk-E2Z4J4MK.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  installDefaultSchema,
+  loadSchema,
+  validateNote
+};
+//# sourceMappingURL=schema-F3RTY6SQ.js.map

package/dist/schema-F3RTY6SQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/search-27WYAI24.js

@@ -0,0 +1,202 @@
+import {
+  Embedder,
+  GraphBuilder,
+  TextSearch,
+  VectorIndex
+} from "./chunk-25EIQWXL.js";
+import {
+  Indexer
+} from "./chunk-HODDRXJK.js";
+import "./chunk-PZ5AY32C.js";
+
+// src/cli/search.ts
+import { join, resolve } from "path";
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+async function runSearch(opts) {
+  const notesPath = resolve(opts.notes);
+  if (!existsSync(notesPath)) {
+    throw new Error(`notes directory not found: ${notesPath}`);
+  }
+  const indexer = new Indexer(notesPath);
+  const indexPath = join(notesPath, ".semantic-sidekick-index");
+  let documents = existsSync(indexPath) ? await indexer.loadDocsCache(indexPath) : null;
+  if (!documents) {
+    documents = await indexer.indexAll();
+  }
+  if (documents.length === 0) return [];
+  const limit = opts.limit ?? 8;
+  if (opts.textOnly) {
+    const textSearch = new TextSearch();
+    textSearch.setDocuments(documents);
+    const keywords = extractKeywords(opts.query);
+    if (keywords.length === 0) return [];
+    const scoreByPath = /* @__PURE__ */ new Map();
+    for (const kw of keywords) {
+      const results = textSearch.search({ pattern: kw, limit: 50 });
+      for (const r of results) {
+        const existing = scoreByPath.get(r.path);
+        const doc = documents.find((d) => d.path === r.path);
+        if (existing) {
+          existing.hits += 1;
+        } else {
+          scoreByPath.set(r.path, {
+            hits: 1,
+            firstSnippet: r.snippet,
+            title: r.title,
+            mtime: doc?.mtime ?? ""
+          });
+        }
+      }
+    }
+    const hits = Array.from(scoreByPath.entries()).map(([path, v]) => ({
+      path,
+      title: v.title,
+      score: v.hits / keywords.length,
+      snippet: v.firstSnippet,
+      mtime: v.mtime
+    })).sort((a, b) => b.score - a.score).slice(0, limit);
+    return hits;
+  }
+  if (!existsSync(indexPath)) {
+    throw new Error(`index not built at ${indexPath} \u2014 run: semantic-sidekick --notes ${notesPath} --reindex`);
+  }
+  const embedder = new Embedder();
+  await embedder.init();
+  const metaPath = join(indexPath, "meta.json");
+  if (existsSync(metaPath)) {
+    try {
+      const meta = JSON.parse(await readFile(metaPath, "utf-8"));
+      if (meta.model && meta.model !== embedder.getModel()) {
+        throw new Error(`model mismatch (cached=${meta.model}, current=${embedder.getModel()}) \u2014 run --reindex`);
+      }
+    } catch (e) {
+      if (e instanceof Error && e.message.startsWith("model mismatch")) throw e;
+    }
+  }
+  const vectorIndex = new VectorIndex(embedder.getDimensions());
+  const loaded = await vectorIndex.load(indexPath);
+  if (!loaded) {
+    throw new Error(`could not load vector index at ${indexPath} \u2014 run --reindex`);
+  }
+  const graph = new GraphBuilder();
+  await graph.load(indexPath);
+  const docByPath = new Map(documents.map((d) => [d.path, d]));
+  const queryEmbed = await embedder.embed(opts.query);
+  const semantic = vectorIndex.search(queryEmbed, limit * 3);
+  const graphResults = graph.searchGraph(opts.query, 2);
+  const graphPaths = new Set(graphResults.map((r) => r.path));
+  const hybrid = semantic.map((r) => {
+    const doc = docByPath.get(r.path);
+    let score = graphPaths.has(r.path) ? r.score * 1.3 : r.score;
+    if (doc?.loadPriority !== void 0) {
+      score *= 1 + (doc.loadPriority - 5) * 0.04;
+    }
+    return { ...r, score };
+  }).sort((a, b) => b.score - a.score).slice(0, limit);
+  return hybrid.map((r) => {
+    const doc = docByPath.get(r.path);
+    return {
+      path: r.path,
+      title: r.title ?? doc?.title,
+      score: r.score,
+      snippet: r.snippet,
+      mtime: doc?.mtime
+    };
+  });
+}
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "by",
+  "can",
+  "do",
+  "does",
+  "for",
+  "from",
+  "how",
+  "i",
+  "if",
+  "in",
+  "is",
+  "it",
+  "its",
+  "of",
+  "on",
+  "or",
+  "our",
+  "should",
+  "that",
+  "the",
+  "this",
+  "to",
+  "was",
+  "we",
+  "what",
+  "when",
+  "where",
+  "which",
+  "why",
+  "will",
+  "with",
+  "you",
+  "your",
+  "have",
+  "has",
+  "had",
+  "but",
+  "not",
+  "so",
+  "any",
+  "all",
+  "about",
+  "there",
+  "their",
+  "they",
+  "them",
+  "these",
+  "those",
+  "would",
+  "could",
+  "might",
+  "may",
+  "really",
+  "just",
+  "like",
+  "some",
+  "more",
+  "than",
+  "into",
+  "out",
+  "up",
+  "down",
+  "need",
+  "want",
+  "get",
+  "got",
+  "also",
+  "very",
+  "much"
+]);
+function extractKeywords(query) {
+  const tokens = query.toLowerCase().replace(/[^\w\s-]/g, " ").split(/\s+/).filter((t) => t.length > 2 && !STOPWORDS.has(t));
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const t of tokens) {
+    if (!seen.has(t)) {
+      seen.add(t);
+      out.push(t);
+    }
+    if (out.length >= 6) break;
+  }
+  return out;
+}
+export {
+  runSearch
+};
+//# sourceMappingURL=search-27WYAI24.js.map

package/dist/search-27WYAI24.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/search.ts"],"sourcesContent":["import { join, resolve } from \"node:path\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { Indexer } from \"../core/indexer.js\";\nimport { Embedder } from \"../core/embedder.js\";\nimport { GraphBuilder } from \"../core/graph.js\";\nimport { VectorIndex } from \"../core/vector.js\";\nimport { TextSearch } from \"../core/search-text.js\";\n\nexport interface SearchCliOptions {\n  notes: string;\n  query: string;\n  limit?: number;\n  textOnly?: boolean;\n  json?: boolean;\n}\n\nexport interface SearchHit {\n  path: string;\n  title?: string;\n  score: number;\n  snippet?: string;\n  mtime?: string;\n}\n\nexport async function runSearch(opts: SearchCliOptions): Promise<SearchHit[]> {\n  const notesPath = resolve(opts.notes);\n  if (!existsSync(notesPath)) {\n    throw new Error(`notes directory not found: ${notesPath}`);\n  }\n\n  const indexer = new Indexer(notesPath);\n  const indexPath = join(notesPath, \".semantic-sidekick-index\");\n\n  // Prefer the parsed-doc cache written by reindex — avoids re-parsing 500+ files\n  // on every hook call. Falls back to a full parse if the cache is missing.\n  let documents = existsSync(indexPath) ? await indexer.loadDocsCache(indexPath) : null;\n  if (!documents) {\n    documents = await indexer.indexAll();\n  }\n  if (documents.length === 0) return [];\n\n  const limit = opts.limit ?? 8;\n\n  if (opts.textOnly) {\n    const textSearch = new TextSearch();\n    textSearch.setDocuments(documents);\n    const keywords = extractKeywords(opts.query);\n    if (keywords.length === 0) return [];\n    const scoreByPath = new Map<string, { hits: number; firstSnippet?: string; title?: string; mtime: string }>();\n    for (const kw of keywords) {\n      const results = textSearch.search({ pattern: kw, limit: 50 });\n      for (const r of results) {\n        const existing = scoreByPath.get(r.path);\n        const doc = documents.find((d) => d.path === r.path);\n        if (existing) {\n          existing.hits += 1;\n        } else {\n          scoreByPath.set(r.path, {\n            hits: 1,\n            firstSnippet: r.snippet,\n            title: r.title,\n            mtime: doc?.mtime ?? \"\",\n          });\n        }\n      }\n    }\n    const hits: SearchHit[] = Array.from(scoreByPath.entries())\n      .map(([path, v]) => ({\n        path,\n        title: v.title,\n        score: v.hits / keywords.length,\n        snippet: v.firstSnippet,\n        mtime: v.mtime,\n      }))\n      .sort((a, b) => b.score - a.score)\n      .slice(0, limit);\n    return hits;\n  }\n\n  // Hybrid path: load cached index, embed query, search + graph rerank.\n  if (!existsSync(indexPath)) {\n    throw new Error(`index not built at ${indexPath} — run: semantic-sidekick --notes ${notesPath} --reindex`);\n  }\n\n  const embedder = new Embedder();\n  await embedder.init();\n\n  const metaPath = join(indexPath, \"meta.json\");\n  if (existsSync(metaPath)) {\n    try {\n      const meta = JSON.parse(await readFile(metaPath, \"utf-8\")) as { model?: string };\n      if (meta.model && meta.model !== embedder.getModel()) {\n        throw new Error(`model mismatch (cached=${meta.model}, current=${embedder.getModel()}) — run --reindex`);\n      }\n    } catch (e) {\n      if (e instanceof Error && e.message.startsWith(\"model mismatch\")) throw e;\n    }\n  }\n\n  const vectorIndex = new VectorIndex(embedder.getDimensions());\n  const loaded = await vectorIndex.load(indexPath);\n  if (!loaded) {\n    throw new Error(`could not load vector index at ${indexPath} — run --reindex`);\n  }\n\n  const graph = new GraphBuilder();\n  await graph.load(indexPath);\n\n  const docByPath = new Map(documents.map((d) => [d.path, d]));\n  const queryEmbed = await embedder.embed(opts.query);\n  const semantic = vectorIndex.search(queryEmbed, limit * 3);\n  const graphResults = graph.searchGraph(opts.query, 2);\n  const graphPaths = new Set(graphResults.map((r) => r.path));\n\n  const hybrid = semantic\n    .map((r) => {\n      const doc = docByPath.get(r.path);\n      let score = graphPaths.has(r.path) ? r.score * 1.3 : r.score;\n      if (doc?.loadPriority !== undefined) {\n        score *= 1 + (doc.loadPriority - 5) * 0.04;\n      }\n      return { ...r, score };\n    })\n    .sort((a, b) => b.score - a.score)\n    .slice(0, limit);\n\n  return hybrid.map((r) => {\n    const doc = docByPath.get(r.path);\n    return {\n      path: r.path,\n      title: (r as any).title ?? doc?.title,\n      score: r.score,\n      snippet: (r as any).snippet,\n      mtime: doc?.mtime,\n    };\n  });\n}\n\nconst STOPWORDS = new Set([\n  \"a\", \"an\", \"and\", \"are\", \"as\", \"at\", \"be\", \"by\", \"can\", \"do\", \"does\", \"for\", \"from\",\n  \"how\", \"i\", \"if\", \"in\", \"is\", \"it\", \"its\", \"of\", \"on\", \"or\", \"our\", \"should\", \"that\",\n  \"the\", \"this\", \"to\", \"was\", \"we\", \"what\", \"when\", \"where\", \"which\", \"why\", \"will\",\n  \"with\", \"you\", \"your\", \"have\", \"has\", \"had\", \"but\", \"not\", \"so\", \"any\", \"all\",\n  \"about\", \"there\", \"their\", \"they\", \"them\", \"these\", \"those\", \"would\", \"could\",\n  \"might\", \"may\", \"really\", \"just\", \"like\", \"some\", \"more\", \"than\", \"into\", \"out\",\n  \"up\", \"down\", \"need\", \"want\", \"get\", \"got\", \"also\", \"very\", \"much\",\n]);\n\nfunction extractKeywords(query: string): string[] {\n  const tokens = query\n    .toLowerCase()\n    .replace(/[^\\w\\s-]/g, \" \")\n    .split(/\\s+/)\n    .filter((t) => t.length > 2 && !STOPWORDS.has(t));\n  const seen = new Set<string>();\n  const out: string[] = [];\n  for (const t of tokens) {\n    if (!seen.has(t)) {\n      seen.add(t);\n      out.push(t);\n    }\n    if (out.length >= 6) break;\n  }\n  return out;\n}\n"],"mappings":"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","names":[]}

package/docs/compat-matrix.md

@@ -0,0 +1,127 @@
+---
+title: TheGlitchKing stack compatibility matrix
+tier: reference
+domains:
+  - architecture
+  - distribution
+status: active
+last_updated: 2026-05-07
+version: 1.0.0
+audience:
+  - developers
+  - admin
+purpose: Canonical compatibility matrix for the TheGlitchKing memory-layer stack. Defines which combinations of underlying plugin versions are tested together and ship as a coherent set under each `dev-stack` meta-plugin version. This is the single source of truth referenced by every plugin's README.
+---
+
+# TheGlitchKing stack compatibility matrix
+
+This is **the** compatibility matrix for the TheGlitchKing memory-layer + planning + docs + translation stack. It documents which combinations of underlying plugin versions are tested together and ship as a coherent set under each `dev-stack` meta-plugin version.
+
+The matrix lives in `semantic-memory` (this repo) because semantic-memory is the runtime that consumes the other plugins as either:
+- producers writing into corpora (persistent-planning → `plans`, babel-fish → `project-map`, hit-em-with-the-docs → `docs`)
+- a frontmatter standard the runtime validates against (HEWTD)
+
+Every other plugin's README cross-references this doc as the canonical source.
+
+## Active matrix
+
+### `dev-stack@1.0.x` (current)
+
+| Plugin | Required range | Tested at |
+|---|---|---|
+| `@theglitchking/semantic-memory` | `^1.0.0` | 1.0.0 (Phase 2.0.0a — rebrand mechanics, runtime equivalent to semantic-sidekick 0.2.5) |
+| `@theglitchking/hit-em-with-the-docs` | `~2.2.0` | 2.2.0 (Phase 1.1.0 — `tier: "plan"` + conditional `version`) |
+| `@theglitchking/persistent-planning` | `^3.0.0` | 3.0.0 (Phase 1.2.0/1.3.0 — sm/lg modes + layered phase/task/atom/notes) |
+| `@theglitchking/babel-fish` | `^2.0.0` | 2.0.0 (existing release; integration with semantic-memory project-map corpus + glossary side-channel ships in Phase 3.1.0) |
+
+#### Why these ranges
+- **semantic-memory `^1.0.0`**: any 1.x is API-compatible. Multi-corpus refactor (Phase 2.0.0b) lands as 1.1.0; will not break the 1.0 tool surface (regression-snapshot suite gates this).
+- **hit-em-with-the-docs `~2.2.0`**: the `tier: "plan"` extension is the precise feature persistent-planning depends on. Tilde-range allows patch-level updates (2.2.x) without accepting a 2.3.0 that might re-shape the schema. Will widen to `^2.2.0` once 2.3 is known to be additive.
+- **persistent-planning `^3.0.0`**: any 3.x preserves the lg-mode contract (phase / task / atom / notes layers, HEWTD frontmatter, sm-mode preservation).
+- **babel-fish `^2.0.0`**: existing 2.0 release. Integration uses babel-fish's existing 19-section project-map output unchanged — semantic-memory consumes the artifact, doesn't drive babel-fish runtime.
+
+#### What's tested together
+- Each underlying plugin has its own test suite (preserved bit-for-bit through the rebrand)
+- semantic-memory regression-snapshot suite (`test/regression/`) gates the 33-tool surface across all of these
+- Phase 4.4.0 (persistent-planning testing) verifies sm + lg flows with semantic-memory present and absent
+- Phase 4.5.0 (babel-fish testing) verifies the glossary contract end-to-end with semantic-memory's translation verbs
+
+#### What's NOT tested together (documented gaps)
+- Multi-corpus runtime is preview-documented in semantic-memory 1.0.0a but not implemented; full integration tests with all six corpora active land in Phase 4.2.0 once 2.0.0b ships
+- Drift detection and translation verbs are not part of the 1.0 surface; they ship in Phase 3.1.0 / 3.3.0
+- pages-compat mode (1:1 surface mapping for semantic-pages migrators) ships in 2.0.0b
+
+## Future matrix (planned)
+
+### `dev-stack@1.1.x` (after semantic-memory 1.1.0 ships with multi-corpus)
+
+| Plugin | Range |
+|---|---|
+| `semantic-memory` | `^1.1.0` |
+| `hit-em-with-the-docs` | `~2.2.0` (unchanged) |
+| `persistent-planning` | `^3.0.0` (unchanged) |
+| `babel-fish` | `^2.0.0` (unchanged) |
+
+When 1.1 ships, dev-stack pin tightens to `^1.1.0` to ensure consumers get the multi-corpus runtime.
+
+### `dev-stack@1.2.x` (after Phase 3.1.0 — babel-fish glossary integration)
+
+When semantic-memory adds the `project-map` corpus + translation verbs (3.1.0 of the meta-plan = a minor of semantic-memory), babel-fish constraint may tighten to a specific minor that ships the glossary side-channel contract changes (TBD — could be 2.1.0 or 2.0.0 if the existing 19-section output already meets the contract).
+
+### `dev-stack@2.0.x` (after Phase 3.2.0 / 3.3.0 — code corpus + drift)
+
+Major bump if the drift-detection feature changes the way users author HEWTD docs (e.g. requires a new field). Otherwise stays at 1.x.
+
+## Coexistence with deprecated plugins
+
+| Plugin | Status | Coexists with dev-stack? |
+|---|---|---|
+| `semantic-sidekick` | Renamed to `semantic-memory` at 1.0.0a (PR #9) | Don't install both — semantic-memory IS the new name. Migrate via uninstall + install. |
+| `semantic-pages` | Deprecated as of 2026-05-07 (PR #5) | Yes — different MCP key (`semantic-vault` vs `semantic-memory`). Both can run side-by-side during the 12-month sunset. |
+
+## How to verify your install matches this matrix
+
+```bash
+# Check the meta-plugin version
+/plugin list --installed | grep dev-stack
+
+# Check each underlying plugin's version
+/plugin list --installed | grep -E "semantic-memory|hit-em-with-the-docs|persistent-planning|babel-fish"
+```
+
+Or via npm:
+
+```bash
+npm ls @theglitchking/semantic-memory @theglitchking/hit-em-with-the-docs @theglitchking/persistent-planning @theglitchking/babel-fish
+```
+
+If any version falls outside the range listed above for your `dev-stack` version, you've drifted — either bump dev-stack or pin the underlying plugin manually in your `.mcp.json` / `package.json`.
+
+## Inter-PR coordination history
+
+This matrix was derived from the unified memory-layer plan tracked in `~/workspace/the-glitch-kingdom/persistent-planning/.planning/layered-planning-with-mcp-and-hewtd-frontmatter/task_plan.md`. Initial entries reflect the PRs landing in the May 2026 launch window:
+
+| PR | Repo | Status | Lands |
+|---|---|---|---|
+| #7, #8 | semantic-sidekick | Merged to main | offline packaging, regression baseline |
+| #3 | hit-em-with-the-docs | Open | HEWTD 2.2.0 — `tier: "plan"` + conditional version |
+| #1 | persistent-planning | Open | persistent-planning 3.0.0 — sm/lg + layered model |
+| #9 | semantic-sidekick | Open | semantic-memory 1.0.0a rebrand mechanics |
+| #5 | semantic-pages | Open | deprecation announcement |
+| (new repo) | dev-stack | Created private; pending visibility flip + publish | meta-plugin 1.0.0 |
+
+## Updating this matrix
+
+When a new minor of any underlying plugin ships:
+1. Verify it satisfies the existing range (e.g. semantic-memory 1.1.0 satisfies `^1.0.0`)
+2. If it does AND the integration is tested → no matrix change needed
+3. If it changes behavior in a way users should opt into → bump dev-stack minor and tighten the constraint
+4. If it requires breaking changes in another plugin → bump dev-stack major
+
+The matrix is hand-maintained. Automation (a CI job that pins from npm latest) is a future improvement.
+
+## See also
+
+- `~/workspace/the-glitch-kingdom/dev-stack/README.md` — meta-plugin README with install / upgrade flow
+- `~/workspace/the-glitch-kingdom/persistent-planning/.planning/layered-planning-with-mcp-and-hewtd-frontmatter/task_plan.md` — Phase 4.14.0 (cross-repo coordination)
+- Each underlying plugin's CHANGELOG for what shipped in the bumps reflected here

package/docs/corpora-json.md

@@ -0,0 +1,150 @@
+---
+title: corpora.json schema (preview, ships in 2.0.0b)
+tier: standard
+domains:
+  - architecture
+  - configuration
+status: draft
+last_updated: 2026-05-07
+version: 1.0.0
+audience:
+  - developers
+purpose: Preview the multi-corpus configuration file that semantic-memory will read in v2.0.0b. Documents the schema, defaults, and smart-middle activation contract before the implementation lands.
+---
+
+# `corpora.json` schema (preview)
+
+> **Status: planned for 2.0.0b.** This file documents the design of `corpora.json` so consumers and downstream plugins (persistent-planning, babel-fish) can plan against it. The implementation lands in the next release. v1.0.0 (this release) preserves the legacy single-vault behavior unchanged.
+
+`corpora.json` is the configuration file that tells semantic-memory which corpora to index and how. It lives at `<project-root>/.semantic/corpora.json` and is auto-bootstrapped on first run by the **smart-middle activation** heuristic.
+
+## Schema
+
+```json
+{
+  "schema_version": "1.0",
+  "corpora": [
+    {
+      "name": "vault",
+      "root": "./.claude/.vault",
+      "glob": "**/*.md",
+      "chunker": "markdown",
+      "enabled": true
+    },
+    {
+      "name": "code",
+      "root": "./src",
+      "glob": "**/*.{ts,tsx,js,jsx}",
+      "chunker": "tree-sitter-ts",
+      "enabled": true
+    },
+    {
+      "name": "plans",
+      "root": "./.planning",
+      "glob": "**/*.md",
+      "chunker": "markdown",
+      "enabled": true
+    },
+    {
+      "name": "docs",
+      "root": "./.documentation",
+      "glob": "**/*.md",
+      "chunker": "markdown",
+      "enabled": true
+    },
+    {
+      "name": "research",
+      "root": "./.research",
+      "glob": "**/*.md",
+      "chunker": "markdown",
+      "enabled": true
+    },
+    {
+      "name": "project-map",
+      "root": "./.babel-fish",
+      "glob": "**/*.md",
+      "chunker": "markdown",
+      "enabled": true,
+      "extras": {
+        "glossary_extractor": "babel-fish-vocabulary"
+      }
+    }
+  ]
+}
+```
+
+## Field reference
+
+### Top level
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `schema_version` | string | yes | Schema version of this file. Currently `"1.0"`. |
+| `corpora` | array of corpus objects | yes | One entry per corpus to register. |
+
+### Per corpus
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | string | yes | Corpus identifier. Used as the suffix for per-corpus search verbs (`search_<name>`). Reserved names: `vault`, `code`, `plans`, `docs`, `research`, `project-map`. Custom names allowed. |
+| `root` | string | yes | Directory to scan for content. Relative to project root. |
+| `glob` | string | yes | File pattern (glob syntax) for files to index within `root`. |
+| `chunker` | string | yes | Chunker to use. Built-in: `markdown`, `tree-sitter-ts`, `fixed-window`. |
+| `enabled` | boolean | no (default `true`) | If `false`, the corpus is registered but not indexed; search verbs return `{status: "no_index", results: []}`. |
+| `extras` | object | no | Chunker-specific or corpus-specific configuration. E.g. `glossary_extractor: "babel-fish-vocabulary"` activates the babel-fish glossary side-channel for the project-map corpus. |
+
+## Smart-middle activation
+
+On first run (when `<project-root>/.semantic/` doesn't exist), semantic-memory scans the project root for known markers:
+
+| Marker | Activates corpus |
+|---|---|
+| `.claude/.vault/` | `vault` |
+| `src/` (or detected source dir) with TS/JS files | `code` |
+| `.planning/` with `.meta/workspace.json` (lg mode) | `plans` |
+| `.documentation/` | `docs` |
+| `.research/` | `research` |
+| `.babel-fish/` with `01-vocabulary.md` | `project-map` |
+
+For each marker found, the corresponding corpus is added to `corpora.json` with `enabled: true`. Markers not found result in the corpus being omitted (or added with `enabled: false` for visibility — TBD).
+
+A decision banner is printed on first activation listing what got enabled and why.
+
+## Backwards compatibility
+
+For projects that have an existing `.claude/.vault/` and never ran v1.0.0+ before, the smart-middle activation creates a `corpora.json` with just `vault` enabled, pointing at the existing `.claude/.vault/` directory. **The existing `.semantic-sidekick-index/` directory continues to be the index location** (preserved for backwards compatibility).
+
+For projects that ARE v1.0.0a-only (no `corpora.json`), the legacy single-vault flow continues to work without any `corpora.json`. The auto-default reads `notes_path` from CLI args or environment, exactly as v0.x did.
+
+## Per-corpus search verbs (planned for 2.0.0b)
+
+Each registered corpus produces a corresponding `search_<name>` MCP verb:
+
+- `search_vault(query, limit?, ...filters)` — equivalent to today's `search_semantic` for the vault corpus
+- `search_code(query, language?, symbol_kind?, pathGlob?)` — when code corpus is active
+- `search_plans(query, ...filters)` — when plans corpus is active
+- `search_docs(query, ...filters)` — when docs corpus is active
+- `search_research(query, ...filters)` — when research corpus is active
+- `search_project_map(query, ...filters)` — when project-map corpus is active
+
+Plus a cross-corpus verb:
+
+- `search_all(query, corpus_filter?, limit?)` — searches across all enabled corpora and merges results
+
+Empty / missing corpora always return `{status: "no_index", results: []}` rather than erroring (the `no_index` contract). This means the agent can always attempt a search and learn from the empty result.
+
+## Conditional tool registration
+
+Workflow tools register only when their target corpus has data:
+
+- Plan workflow tools (`next_atom`, `update_atom_status`, ...) register iff `plans` corpus is active AND has data
+- Drift detection tools (`detect_drift`) register iff `code` corpus + at least one doc-bearing corpus are both active
+- Translation tools (`translate`, `reverse_translate`, `list_vocabulary`) register iff `project-map` corpus is active AND `glossary.json` is present
+
+Search tools always register and use the `no_index` contract for empty corpora.
+
+## See also
+
+- `docs/smart-middle-activation.md` — full smart-middle resolution rules
+- `docs/regression-snapshot.md` — the gate that protects existing tool surface during the multi-corpus refactor
+- `~/workspace/the-glitch-kingdom/persistent-planning/.planning/layered-planning-with-mcp-and-hewtd-frontmatter/task_plan.md` — the meta-plan

package/docs/regression-snapshot.md

@@ -0,0 +1,122 @@
+---
+title: Regression-Snapshot Suite
+tier: standard
+domains:
+  - testing
+  - operational
+status: active
+last_updated: 2026-05-07
+version: 1.0.0
+audience:
+  - developers
+purpose: Document the regression-snapshot suite, when it fails, how to interpret a failure, and the policy for updating snapshots intentionally.
+---
+
+# Regression-Snapshot Suite
+
+The regression suite under `test/regression/` is the **structural stability gate** for semantic-sidekick. It captures the shape of the MCP tool surface — every tool's name, description, input schema, and representative output structure — as vitest snapshots that fail loudly on any unintentional change.
+
+This is the load-bearing baseline for the **semantic-memory rebrand + multi-corpus refactor** (Phase 1.0.0 of the unified memory layer plan). The contract: every snapshot in this suite must remain unchanged through the rebrand unless an intentional break is documented and signed off.
+
+## What the suite covers
+
+### `test/regression/tool-surface.test.ts` — input contract
+
+Three snapshots:
+
+| Snapshot | Captures | Size |
+|---|---|---|
+| `tool-surface 1` | Full list of registered tools — name, description, complete JSON Schema for inputs | ~1000 lines |
+| `tool-name list (compact) 1` | Sorted list of tool names in default mode (33 entries) | ~35 lines |
+| `tool-name list in read-only mode 1` | Sorted list of tool names in `--read-only` mode (21 entries) | ~22 lines |
+
+Plus structural assertions:
+- Default mode exposes exactly 33 tools
+- `--read-only` mode exposes exactly 21 tools
+- Read-only mode never exposes any of the 12 write tools (explicit name list)
+
+### `test/regression/tool-outputs.test.ts` — output contract
+
+16 snapshots covering response shapes for:
+- **Deterministic read tools**: `read_note`, `read_multiple_notes`, `list_notes`, `get_frontmatter`, `backlinks`, `forwardlinks`, `graph_path`, `graph_statistics`, `get_stats`
+- **Lint tools**: `lint_vault` (rule-name structure)
+- **Embedding-dependent tools** (structural only — see below): `search_semantic`, `search_text`, `search_hybrid`, `search_graph`
+
+## Embedding-dependent vs deterministic snapshots
+
+Search tools that route through the embedder produce slightly different scores across runs (within a tolerance). Snapshotting their full output would create false-positive failures.
+
+The suite handles this with two strategies:
+
+1. **Strip volatile fields**: `mtime`, `lastIndexed`, embedding scores are removed (or reduced to presence-checks) before snapshotting.
+2. **Shape-only snapshots**: For `search_semantic` / `search_hybrid` / `search_graph`, the snapshot captures only the *keys present* in a result, not the values. The shape regresses if a field is added or removed; embedding score drift never breaks the test.
+
+## When a snapshot fails
+
+A regression-snapshot failure means the tool surface or output shape changed since the snapshot was last written. There are three responses:
+
+### 1. The change is unintentional → fix the regression
+
+This is the default assumption during the semantic-memory rebrand. Investigate what changed, restore the previous behavior. Do not update the snapshot.
+
+### 2. The change is intentional and documented
+
+Examples:
+- Adding a new MCP tool (the surface snapshot will gain an entry)
+- Extending an existing tool's input schema (the surface snapshot will show the new field)
+- Adding a field to a tool's output (the output snapshot will show the new key)
+
+Process:
+1. Confirm the change is intentional and matches the published plan
+2. Update snapshots: `npm test -- -u test/regression/`
+3. Review the diff in the snapshot file as part of the PR
+4. Document the intentional break in the relevant CHANGELOG entry (semantic-memory CHANGELOG, probably under the version that introduces it)
+5. Sign-off in the PR description: explicit acknowledgment that this is a deliberate break
+
+### 3. The change reflects an upgrade to the embedding model or chunker
+
+If the embedding model changes (e.g., MiniLM-L6 → BGE-m3) or the chunker changes (markdown → tree-sitter for some corpus), the deterministic snapshots may legitimately need to update. Treat as case 2 — explicit, documented, signed off. Note the model/chunker change in the CHANGELOG.
+
+## Updating snapshots
+
+```bash
+# Update only the regression suite
+npm test -- -u test/regression/
+
+# Update everything (use sparingly)
+npm test -- -u
+```
+
+Always inspect the resulting diff before committing. A snapshot diff that touches more than the file you changed is a signal that something else regressed.
+
+## Capture process (how the baseline was created)
+
+Captured 2026-05-07 BEFORE any sidekick code changes for the semantic-memory rebrand. Three commits established the baseline:
+
+1. `test(regression): golden snapshots for MCP tool surface` — input contracts (3 snapshots, 6 tests)
+2. `test(regression): golden snapshots for MCP tool output shapes` — output contracts (16 snapshots, 16 tests)
+3. `docs(regression): document the snapshot suite` — this file
+
+Combined: 19 snapshots / 22 regression tests / 0 failures at baseline.
+
+The full sidekick suite at baseline: 211 tests across 26 files, 21.85s.
+
+## Performance baseline (separate, deferred)
+
+A performance baseline (query latency p50/p95, index size per chunk count) is mentioned in the regression plan but is captured separately by `scripts/regression-perf-baseline.js` (TBD). It is **informational, not gated** — a 10% performance budget will be enforced in Phase 4.2.0, not now.
+
+## Suite lifecycle
+
+The regression suite is a **gate during refactoring**. After the semantic-memory rebrand and multi-corpus refactor are complete, the suite should be re-evaluated:
+
+- Snapshots that captured `--read-only` 21-tool surface may need to evolve to reflect new conditional tool registration (workflow / drift / translation verbs).
+- Output snapshots may need to evolve as new corpora come online and result shapes grow corpus tags.
+- The suite itself should evolve from "lock current behavior" to "verify multi-corpus behavior remains stable as new corpora are added."
+
+That evolution happens at Phase 4.2.0 (per the plan). Until then: this suite is the immutable baseline.
+
+## Related
+
+- Plan: `~/workspace/the-glitch-kingdom/persistent-planning/.planning/layered-planning-with-mcp-and-hewtd-frontmatter/task_plan.md`
+- Companion behavior tests: `test/integration/mcp-server.test.ts`, `test/e2e/stdio-server.test.ts`
+- Vitest snapshot docs: https://vitest.dev/guide/snapshot.html