@theglitchking/semantic-memory 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,71 @@
+{
+  "name": "semantic-memory-marketplace",
+  "owner": {
+    "name": "TheGlitchKing",
+    "email": "theglitchking@users.noreply.github.com"
+  },
+  "metadata": {
+    "description": "Single-plugin marketplace for semantic-memory — the unified memory-layer plugin (rebrand of semantic-sidekick at v1.0.0). One MCP server, multiple typed corpora, unified cross-corpus knowledge graph, conditional tool registration, drift detection, and human↔code translation.",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "semantic-memory",
+      "description": "Unified memory-layer plugin for Claude Code. One MCP server, multiple typed corpora (vault / code / plans / docs / research / project-map), unified cross-corpus knowledge graph, conditional tool registration based on active corpora, in-process drift detection, and human↔code translation. Rebrand of semantic-sidekick at v1.0.0; existing semantic-sidekick plugins continue to work under the legacy name during the transition period.",
+      "version": "1.0.0",
+      "author": {
+        "name": "TheGlitchKing"
+      },
+      "homepage": "https://github.com/TheGlitchKing/semantic-sidekick",
+      "repository": "https://github.com/TheGlitchKing/semantic-sidekick.git",
+      "license": "MIT",
+      "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "memory-layer",
+        "semantic-search",
+        "knowledge-graph",
+        "multi-corpus",
+        "code-search",
+        "drift-detection",
+        "translation",
+        "markdown",
+        "vault",
+        "activation",
+        "routing",
+        "hooks",
+        "skills",
+        "vault-first",
+        "research-mode",
+        "outage-silence",
+        "provenance",
+        "synthesize-note",
+        "ingest-source",
+        "karpathy-wiki",
+        "claude-code",
+        "claude"
+      ],
+      "category": "search",
+      "tags": [
+        "claude-plugin",
+        "mcp-server",
+        "memory-layer",
+        "semantic-search",
+        "knowledge-graph",
+        "multi-corpus",
+        "drift-detection",
+        "translation",
+        "activation-hooks",
+        "mode-routing",
+        "provenance",
+        "vault",
+        "markdown"
+      ],
+      "source": {
+        "source": "npm",
+        "package": "@theglitchking/semantic-memory"
+      },
+      "strict": true
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "name": "semantic-memory",
+  "description": "Unified memory-layer plugin for Claude Code. One MCP server, multiple typed corpora (vault / code / plans / docs / research / project-map), unified cross-corpus knowledge graph, conditional tool registration, in-process drift detection, and human↔code translation. Rebrand of `semantic-sidekick` at v1.0.0 — see CHANGELOG for migration.",
+  "version": "1.0.0",
+  "author": {
+    "name": "TheGlitchKing",
+    "email": "theglitchking@users.noreply.github.com"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/TheGlitchKing/semantic-sidekick",
+  "repository": "https://github.com/TheGlitchKing/semantic-sidekick",
+  "keywords": [
+    "mcp",
+    "memory-layer",
+    "semantic-search",
+    "knowledge-graph",
+    "multi-corpus",
+    "markdown",
+    "vault",
+    "code-search",
+    "drift-detection",
+    "translation",
+    "activation",
+    "routing",
+    "hooks",
+    "skills",
+    "vault-first",
+    "research-mode",
+    "outage-silence",
+    "provenance",
+    "synthesize-note",
+    "ingest-source"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,233 @@
+# Changelog
+
+All notable changes to semantic-memory (formerly semantic-sidekick) will be documented here.
+
+## [1.0.0] - 2026-05-07 — Rebrand to `semantic-memory`
+
+### Renamed (publication identity)
+
+- **npm package**: `@theglitchking/semantic-sidekick` → `@theglitchking/semantic-memory`
+- **Claude Code plugin name**: `semantic-sidekick` → `semantic-memory`
+- **Marketplace name**: `semantic-sidekick-marketplace` → `semantic-memory-marketplace`
+- **MCP server name**: `semantic-sidekick` → `semantic-memory` (announced in initialize handshake)
+- **CLI binary**: `bin/semantic-memory` is the new primary; `bin/semantic-sidekick` is preserved as an alias during the transition
+
+### Why
+
+`semantic-sidekick` framed the plugin as a "vault helper" because that's what it was at v0.x. v1.0.0 introduces a multi-corpus architecture: vault, code, plans, docs, research, project-map. The plugin is no longer a sidekick — it's the unified memory layer for Claude Code. The new name reflects the actual scope.
+
+### Preserved (no migration required for existing installs)
+
+- **Internal storage layout** is unchanged: `<project>/.semantic-sidekick-index/` continues to be the index directory, `~/.semantic-sidekick/models/` continues to be the model cache. Existing users do NOT need to re-index or re-download models when they upgrade.
+- **All 33 existing MCP tools** remain registered under the same names with the same input schemas and the same output structures. The regression-snapshot suite (`test/regression/`) gates this guarantee — every tool's surface is bit-for-bit preserved.
+- **The `--read-only` mode** continues to suppress the same 12 write tools (21-tool surface).
+- **All existing slash commands, hooks, skills, and capture flow** are unchanged.
+- **`bin/semantic-sidekick` shell command** continues to work as an alias for `bin/semantic-memory`.
+- **Configuration files** (`.claude/semantic-sidekick.json`, `.claude/.semantic-sidekick-update-cache.json`) keep their names. The claude-plugin-runtime `pluginName: "semantic-sidekick"` is preserved so update tracking continues without state loss.
+
+### Phase 2.0.0a (this release) — what shipped
+
+This is the **mechanical rebrand** portion of Phase 2.0.0 of the unified memory-layer plan tracked in `~/workspace/the-glitch-kingdom/persistent-planning/.planning/layered-planning-with-mcp-and-hewtd-frontmatter/task_plan.md`. It includes:
+
+- All publication-identity renames listed above
+- Preview docs for the planned multi-corpus architecture (`docs/corpora-json.md`, `docs/smart-middle-activation.md`)
+- README rebrand framing
+- Bin alias for `semantic-memory`
+
+### Phase 2.0.0b (next release) — what's coming
+
+The actual multi-corpus refactor — registry-driven indexer, per-corpus search verbs (`search_vault`, `search_code`, ...), `search_all` cross-corpus verb, smart-middle first-run detection, `corpora.json` schema implementation — ships in a follow-up PR. Until that lands, semantic-memory's runtime behavior is identical to semantic-sidekick 0.2.5.
+
+### Migration for existing users
+
+```bash
+# Uninstall the old plugin
+/plugin uninstall semantic-sidekick
+
+# Install the new one (same marketplace repo, new plugin name)
+/plugin marketplace add https://github.com/TheGlitchKing/semantic-sidekick
+/plugin install semantic-memory@semantic-memory-marketplace
+```
+
+Or for npm/global installs:
+
+```bash
+npm uninstall -g @theglitchking/semantic-sidekick
+npm install -g @theglitchking/semantic-memory
+```
+
+Or as a project devDependency:
+
+```bash
+npm uninstall @theglitchking/semantic-sidekick
+npm install --save-dev @theglitchking/semantic-memory
+```
+
+Existing on-disk state (the index, model cache, hooks, skills, slash commands) requires no changes. The new package reads from the same paths as the old one.
+
+### Inter-PR dependencies (this release)
+
+- Hard-depends on: nothing (the regression-snapshot baseline already lives on main and gates this release)
+- Soft-coupled with: hit-em-with-the-docs#3 (HEWTD 2.2.0 — `tier: "plan"` schema extension); persistent-planning#1 (3.0.0 lg-mode). Neither blocks this release; both ship coordinated for a coherent ecosystem-wide v1.0 launch.
+
+## [0.2.5] - 2026-04-28
+
+### Fixed
+- **`<vault-context>` hook injected an unconditional cite-or-deflect imperative
+  on every prompt.** The injected block ended with `Instructions: Read the top
+  hits ... cite filenames in your response. If none of these actually answer
+  the question, say "not in vault" and name the nearest misses.` That string is
+  more specific and immediate than the CLAUDE.md rule that says "ignore on
+  non-lookup prompts," so models in consumer projects (e.g. RE-InvestorHub)
+  obeyed the inline string and blurted citations like
+  `Vault citation: keycloak-custom-image.md unrelated — not in vault for this`
+  on debugging, status, and directive prompts.
+
+  Fix: rewrote the Instructions string in `hooks/vault-context.js` to be
+  conditional and aligned with the CLAUDE.md cite-or-deflect rule — apply only
+  on project prose lookups; ignore silently on meta/tool/debugging/status/
+  directive/conversational prompts; explicitly forbid the "X unrelated"
+  narration. Also gated `main()` on script invocation so the hook can be
+  imported by tests, and added a regression test asserting the new shape.
+  Suite: 189/189.
+
+## [0.2.4] - 2026-04-26
+
+### Fixed
+- **Stop hook emitted invalid output shape on early-exit paths.** The `183aa30`
+  fix patched `emitStop()` and the catch block to write `{}` instead of the
+  SessionStart-shaped `{hookSpecificOutput: {hookEventName: "Stop"}}` envelope
+  (Stop's schema rejects `hookSpecificOutput`). But two earlier short-circuits
+  in `main()` — when `findVaultPath` or `findCliBin` returns null — were still
+  routing through the generic `emit()` helper, which wrote the broken envelope
+  unconditionally. This surfaced in projects where Claude opened in a subdir
+  without a local `.mcp.json` or local `node_modules/@theglitchking/...`,
+  producing `Stop hook error: Hook JSON output validation failed — (root):
+  Invalid input` on every response.
+
+  Fix: introduced `emitNoop(eventName)` helper that branches on Stop and writes
+  `{}` for it. Wired into both early-exits and the catch block. Two regression
+  assertions added to `test/phase4/mode-hook.test.ts` covering the no-vault
+  and no-CLI-bin paths. Suite: 188/188.
+
+## [0.2.3] - 2026-04-22
+
+### Fixed
+- **`vault-first` skill + CLAUDE.md rule over-triggered "not in vault"
+  deflection.** The rule was written as "cite or deflect on every answer";
+  in practice the UserPromptSubmit hook injects `<vault-context>` on *every*
+  prompt (including meta-questions, debugging, yes/no, directives, and
+  conversational turns), so Claude was opening every response with "not in
+  vault" regardless of whether the prompt was actually a vault-eligible
+  project lookup.
+
+  Fix: the cite-or-deflect rule now explicitly applies only when the *user's
+  question shape* is a project/operational lookup. Meta/tool/debug/status/
+  directive prompts → silently ignore the injected block. The filter is the
+  user's intent, not the hook's output. Updated in both `skills/vault-first/SKILL.md`
+  and the CLAUDE.md rule block.
+
+## [0.2.2] - 2026-04-22
+
+### Fixed
+- **Docs MCP (`semantic-sidekick`) was silently removed by reconcile on every
+  SessionStart when `hit-em-with-the-docs` was enabled per-project but not
+  globally.** `reconcile.js:hewtdEnabled()` only checked `~/.claude/settings.json`;
+  per-project enablement (project `.claude/settings.json` or `.claude/settings.local.json`)
+  was ignored. Since isOurEntry recognized the docs entry as ours, the reconcile
+  removal path deleted it on every boot.
+- Fix: `hewtdEnabled(projectRoot)` now checks all three scopes (user, project,
+  project-local) and returns true if hewtd is enabled in any of them. The docs
+  MCP now persists correctly for project-scope installs.
+
+## [0.2.1] - 2026-04-22
+
+### Fixed (critical)
+- **SessionStart hook no longer crashes with `ERR_MODULE_NOT_FOUND` when
+  installed via `/plugin install`.** Claude Code's plugin extractor unpacks
+  the npm tarball but does not run `npm install` — so `hooks/session-start.js`'s
+  static `import { runSessionStart } from "@theglitchking/claude-plugin-runtime"`
+  failed at load time, producing the reported errors:
+
+      SessionStart:resume hook error
+      Failed with non-blocking status code: node:internal/modules/cjs/loader:1386
+      Failed with non-blocking status code: node:internal/modules/package_json_reader:314
+
+  Fix: rewrite `session-start.js` so the critical path (reconcile .mcp.json,
+  ensure .claude/.vault) uses zero external deps — `reconcile.js` is pure
+  node built-ins. The `claude-plugin-runtime` integration (auto-update policy)
+  is now a best-effort dynamic import — skipped silently when not resolvable.
+  The hook always emits a valid SessionStart response and never blocks the
+  session, even if every optional component is missing.
+
+## [0.2.0] - 2026-04-22
+
+### Phase 1 — Activation layer
+- `vault-first` skill at `skills/vault-first/SKILL.md` with cite-or-deflect contract.
+- SessionStart + UserPromptSubmit hooks backed by `hooks/vault-context.js`. Seeded search on session start; fingerprinted per-prompt injection with suppression of recent duplicates.
+- CLAUDE.md vault-first rule block enforcing cite-or-deflect at system-prompt level.
+- New `semantic-sidekick search` CLI subcommand (hybrid / text-only / JSON output) — hooks shell out instead of running an MCP client.
+- 10-prompt conversational test suite at `test/phase1/run.js`. Pass criterion ≥7/10; current ≥9/10.
+
+### Phase 2 — Structure + capture
+- Minimal default schema (`src/core/schema-default.ts`) with four types (note, decision, gotcha, source) + provenance fields + lint policy. Bootstrappable via `install_schema` MCP tool or `semantic-sidekick install-schema` CLI.
+- `apply_patch` MCP tool — atomic multi-note ChangeSet with pre-check, schema validation, reverse-order rollback, dry-run.
+- `synthesize_note` MCP tool — answer + sources → filed note with auto-wikilinks, routed through apply_patch.
+- Lint suite: `find_schema_violations`, `find_missing_provenance`, `find_stale`, `lint_vault` (full report). MCP tools + `semantic-sidekick lint` CLI + `scripts/pre-commit-lint.sh` template.
+- Stop hook with capture-cue detection (`\bbecause\b`, `\bthe fix was\b`, etc.) → `decision: "block"` prompt at session close.
+- Parsed-doc cache (`.semantic-sidekick-index/docs.cache.json`) — hook latency dropped ~6s → ~0.7s (9x).
+
+### Phase 3 — Ingest + maintenance
+- `ingest_source` MCP tool — source + extracted units → atomic ChangeSet with derived_from wiring. Auto-logs `kind=ingest` on success.
+- Structured `log.md` at vault root: human bullet line + machine-readable `yaml event` blocks per entry. `log_event` + `log_query` MCP tools.
+- Hierarchical INDEX.md auto-regen on apply_patch (creates/deletes/moves). Overflow signal at 100 entries.
+- `find_broken_links` lint — cross-note wikilink validation, skips code blocks.
+- `regenerate_index` MCP tool for manual regen.
+
+### Phase 4 — Routing + transitions
+- `research-mode` skill — aggressive vault behavior for sustained investigation; every source filed; synthesis mandatory on exit.
+- `outage-silence` skill — incident mode; suppresses auto-vault; forces postmortem on exit.
+- `/mode` slash command — explicit mode setter (ground truth). Writes `.claude/.sidekick-mode`.
+- `/vault <query>` slash command — explicit vault search, works in any mode including outage-silence.
+- CLAUDE.md routing rule — visible `[research]` / `[outage]` prefix, transition-capture contract.
+- Mode-aware hooks: UserPromptSubmit suppresses in outage-silence; Stop branches per mode (research-synthesis / outage-postmortem / vault-first generic).
+- SessionStart resets mode to `vault-first` (relevance-decay at session boundary).
+
+### Phase 4.5 — Auto-logging + state-delta preload
+- `apply_patch` / `synthesize_note` / `ingest_source` auto-log `kind=error` on failure, `kind=synthesis` / `kind=ingest` on success.
+- Hook crashes auto-log `kind=error` with stack excerpt (no longer stderr-only and lost).
+- SessionStart injects `<vault-state-since date="…">` block — 14-day log.md summary + 6 most recent entries. Future-Claude boots with "what past-me did this week."
+- Mode drift (session ended in non-default mode) auto-logs `kind=mode_change` at next SessionStart.
+- New CLI subcommands `log-event` + `log-query` so hooks and CI scripts write/read log.md without importing core.
+
+### Plugin packaging
+- `.claude-plugin/plugin.json` + `marketplace.json` updated for Phase 1–4.5 scope (category: knowledge).
+- `hooks/hooks.json` declares SessionStart + UserPromptSubmit + Stop hooks against `${CLAUDE_PLUGIN_ROOT}/hooks/vault-context.js`.
+- `package.json` `files[]` now ships `skills/{vault-first,research-mode,outage-silence}` and `scripts/pre-commit-lint.sh`.
+
+### Fixes
+- Stop hook output shape corrected — uses top-level `decision` / `reason` instead of `hookSpecificOutput` (which Claude Code rejects for Stop).
+- CLI `lint --json` stdout flush fixed — large JSON payloads were truncating mid-array when `process.exit` ran before flush.
+- `src/core/index.ts` exports all Phase 2/3 public APIs (applyPatch, buildSynthesizeChangeSet, buildIngestChangeSet, lintVault, logEvent/logQuery, schema helpers).
+
+### Tests
+- 186/186 tests passing (from 139 at 0.1.0).
+- 47 new tests across schema, patch, synthesize, lint, ingest, log, index-regen, mode-hook, state-delta, auto-logging.
+
+### Docs
+- Full operator's manual in `.documentation/`: INDEX + 14 topic docs + 4 per-phase change logs. See `.documentation/INDEX.md`.
+
+## [0.1.0] - 2026-04-21
+
+### Forked from semantic-pages 0.10.0
+Initial fork. Package renamed, bin renamed (`semantic-sidekick`), MCP server identifier changed, index directory changed (`.semantic-sidekick-index`). All retrieval functionality inherited unchanged from semantic-pages.
+
+### Planned (per `.planning/semantic-sidekick/task_plan.md`)
+- **Phase 1**: Activation layer — SessionStart + UserPromptSubmit hooks, `vault-first` skill with conversational cue detection, CLAUDE.md rule. Hypothesis test: does the vault get used without explicit invocation?
+- **Phase 2**: Structure — `vault.schema.yml`, provenance frontmatter, `apply_patch` MCP tool, `synthesize_note`, cheap lint.
+- **Phase 3**: Ingest + maintenance — `ingest_source`, structured log, hierarchical indexes.
+- **Phase 4**: Routing — mode skills (research / default / outage), signal weighting, transition capture.
+- **Phase 5**: Advanced — contradiction detection, situation snapshots, calibration loop.
+
+### Heritage
+Upstream substrate tracked at `git@github-glitch:TheGlitchKing/semantic-pages.git` (remote `upstream`, push disabled). Substrate fixes are cherry-picked from upstream; semantic-sidekick does not push back.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheGlitchKing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# semantic-memory (formerly semantic-sidekick)
+
+> A shelf is retrievable. A prosthesis is present.
+> A vault is local. Memory is layered.
+
+> **v1.0.0 rebrand** — `semantic-sidekick` → `semantic-memory`. The npm package, plugin name, MCP server name, and marketplace identity all change. **Internal storage layout (`.semantic-sidekick-index/`, `~/.semantic-sidekick/models/`) is preserved** — existing installs continue to read their indices and model caches without re-indexing or re-downloading. See [CHANGELOG.md](./CHANGELOG.md) for the full migration. The `bin/semantic-sidekick` command remains as an alias for `bin/semantic-memory` during the transition.
+
+semantic-memory is the unified memory-layer plugin for Claude Code. **One MCP server, multiple typed corpora** (vault, code, plans, docs, research, project-map), a unified cross-corpus knowledge graph, conditional tool registration based on which corpora are active, in-process drift detection, and human↔code translation via the babel-fish glossary side-channel.
+
+The original semantic-sidekick framing — activation / mode-routing / capture layer on top of [semantic-pages](https://github.com/TheGlitchKing/semantic-pages) — is preserved as the `vault` corpus's behavior. What's new in 1.0.0 is the multi-corpus architecture that absorbs documentation, code, plans, research, and babel-fish project-maps into the same MCP surface.
+
+## Status
+
+**Phases 1–4 shipped** (2026-04-22). Layers 2–5 fully implemented and committed to `feat/sidekick-layers`. Phase 5 (advanced calibration + contradiction detection) is explicitly gated per the plan ("only build when Phase 4 has been in use for ≥2 weeks and a specific failure demands it").
+
+| Phase | What it adds | Commit |
+|---|---|---|
+| **1 — Activation** | `vault-first` skill + SessionStart/UserPromptSubmit hooks + CLAUDE.md cite-or-deflect rule | `c8f722f` |
+| **2 — Structure + Capture** | schema, `apply_patch`, `synthesize_note`, lint (schema/provenance/stale), Stop-hook capture-on-close, parsed-doc cache (9x hook speedup) | `1807c58` |
+| **3 — Ingest + Maintenance** | `ingest_source`, structured `log.md` + `log_event`/`log_query`, hierarchical index auto-regen, broken-link lint | `b8d4492` |
+| **4 — Routing + Transitions** | `research-mode` + `outage-silence` skills, `/mode` + `/vault` commands, mode-aware hooks, transition-capture prompts | `75ee813` |
+
+Per-phase design docs live in `.documentation/phase-{1..4}-*.md`.
+
+## Quickstart as a Claude Code plugin
+
+```bash
+# Add the marketplace (from git)
+/plugin marketplace add https://github.com/TheGlitchKing/semantic-sidekick
+
+# Install the plugin
+/plugin install semantic-sidekick
+```
+
+On install:
+- `.mcp.json` is reconciled to point at `.claude/.vault` (or your `--notes <path>`).
+- Skills (`vault-first`, `research-mode`, `outage-silence`) are linked into `.claude/skills/`.
+- Hooks (`SessionStart`, `UserPromptSubmit`, `Stop`) register from `hooks/hooks.json`.
+- Commands (`/mode`, `/vault`) become available.
+
+First run: `semantic-sidekick --notes ./path/to/vault --reindex` to build the vector index (writes `.semantic-sidekick-index/`). Subsequent hook calls hit the cache in <1s.
+
+## Using the modes
+
+| Command | Effect |
+|---|---|
+| `/mode research` | Enter research-mode. Every source introduced gets filed via `ingest_source`; mandatory `synthesize_note` on exit. Visible `[research]` prefix. |
+| `/mode outage-silence` | Enter outage-silence. No proactive vault search. Terse responses. Postmortem drafted as `synthesize_note` on exit. Visible `[outage]` prefix. |
+| `/mode vault-first` | Return to default. Project-scoped prose questions trigger vault consultation with cite-or-deflect. |
+| `/mode status` | Print the current mode. |
+| `/vault <query>` | Explicit vault query. Always works, even in outage-silence. |
+
+## 33 MCP tools shipped
+
+Search (4): `search_semantic`, `search_text`, `search_graph`, `search_hybrid`  
+Read (3): `read_note`, `read_multiple_notes`, `list_notes`  
+Write (4): `create_note`, `update_note`, `delete_note`, `move_note`  
+Metadata (4): `get_frontmatter`, `update_frontmatter`, `manage_tags`, `rename_tag`  
+Graph (4): `backlinks`, `forwardlinks`, `graph_path`, `graph_statistics`  
+System (2): `get_stats`, `reindex`  
+**Patch/Synthesis (4):** `apply_patch`, `synthesize_note`, `ingest_source`, `install_schema`  
+**Lint (4):** `find_schema_violations`, `find_missing_provenance`, `find_stale`, `find_broken_links`, `lint_vault`  
+**Log/Maintenance (3):** `log_event`, `log_query`, `regenerate_index`
+
+## Relationship to semantic-pages
+
+- **Substrate** (retrieval, graph, MCP tools): inherited unchanged from semantic-pages.
+- **Upstream remote** tracks semantic-pages for cherry-picking substrate fixes. Push is disabled; sidekick does not push back.
+- **What's net-new in sidekick**: activation hooks, mode-routing skills, capture workflows (ingest/synthesize), lint suite, provenance + schema layer.
+
+## Architecture (five layers)
+
+1. **Substrate** — markdown vault + hybrid search + graph + MCP (inherited)
+2. **Structure** — schema, provenance frontmatter, atomic `apply_patch`, structured log
+3. **Workflows** — `ingest_source`, `synthesize_note`, lint suite
+4. **Activation** — SessionStart / UserPromptSubmit / Stop hooks, `vault-first` skill, CLAUDE.md rules
+5. **Routing** — mode skills (research / default / outage), signal weighting, transition capture
+
+See the originating design discussion in `.planning/semantic-sidekick/` for rationale and phase-by-phase build plan.
+
+## Development
+
+```bash
+npm install
+npm run build
+node dist/cli/index.js --version
+```
+
+## License
+
+MIT

package/bin/semantic-memory

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli/index.js";

package/bin/semantic-sidekick

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli/index.js";

package/commands/healthcheck.md

@@ -0,0 +1,6 @@
+---
+description: Verify the local semantic-sidekick install starts cleanly; self-heals npx-cache ERR_MODULE_NOT_FOUND
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/semantic-sidekick healthcheck` and relay the output. If it reports a fragile `.mcp.json` form, suggest running `/semantic-sidekick:normalize-config`.

package/commands/mode.md

@@ -0,0 +1,65 @@
+---
+description: Set or query the active semantic-sidekick mode (vault-first | research | outage-silence)
+argument-hint: "[research|vault-first|outage-silence|status]"
+allowed-tools: Bash(cat:*), Bash(cp:*), Bash(test:*), Bash(node:*), Read, Write
+---
+
+# /mode — semantic-sidekick mode control
+
+The user invoked `/mode $ARGUMENTS`. This is the explicit ground-truth override for the semantic-sidekick routing layer.
+
+## Your job
+
+1. **Parse `$ARGUMENTS`** — expected values: `research`, `vault-first`, `outage-silence`, `status` (or empty = status).
+
+2. **Read current mode** from `.claude/.sidekick-mode` (a plain text file containing just the mode name). If the file doesn't exist, the current mode is `vault-first` (default).
+
+3. **If the arg is `status` or empty**, print the current mode and exit:
+   ```
+   current mode: <mode>
+   ```
+
+4. **If the arg is a valid mode name** (`research`, `vault-first`, `outage-silence`), do the transition:
+
+   a. **If transitioning OUT of `research`** → emit the research-exit synthesis prompt:
+      > Exiting research-mode. Before switching: the session accumulated source notes and findings. Draft a `synthesize_note` now (dry-run first via `mcp__semantic-vault__synthesize_note` with `dry_run: true`, then apply if the preview looks right). Confirm with the user that the synthesis is filed before finishing the mode change.
+
+   b. **If transitioning OUT of `outage-silence`** → emit the outage-exit postmortem prompt:
+      > Exiting outage-silence. The incident is (presumably) resolved. Before switching: draft a postmortem as a `synthesize_note` with `type: gotcha` (or `decision` if the fix is architectural) covering timeline, root cause, fix, and preventive actions. Dry-run first, confirm with the user, then apply.
+
+   c. **Write the new mode** to `.claude/.sidekick-mode` (single line, no trailing newline noise):
+      ```bash
+      mkdir -p .claude && printf '%s' "<new-mode>" > .claude/.sidekick-mode
+      ```
+
+   d. **Report the transition** to the user in one line:
+      ```
+      mode: <old> → <new>
+      ```
+
+   e. If the new mode is `research` or `outage-silence`, invoke the corresponding skill (the skill description will carry you forward). The `vault-first` default is already ambient.
+
+5. **If the arg is an unknown value**, print a one-line error listing the valid values and exit.
+
+## Notes
+
+- The mode file is per-project, stored in `.claude/.sidekick-mode`. It persists across sessions.
+- `SessionStart` resets the mode to `vault-first` if the file is missing or contains an invalid value.
+- You (Claude) are also the router — the mode file is a signal, not a command. Even without `/mode`, skill descriptions route based on conversational cues. `/mode` is the explicit override.
+
+## Example
+
+User: `/mode research`
+
+You (on read): current mode is `vault-first` → transitioning to `research` → no exit-capture needed (not leaving research or outage). Write the file. Report:
+```
+mode: vault-first → research
+```
+Then follow the `research-mode` skill going forward.
+
+User: `/mode vault-first`
+
+You (on read): current mode is `research` → transitioning out of research → emit the synthesis prompt FIRST, wait for the user's go-ahead or confirmation that synthesis is filed, then write the file. Report:
+```
+mode: research → vault-first
+```

package/commands/normalize-config.md

@@ -0,0 +1,6 @@
+---
+description: Rewrite fragile npx-@latest entries in .mcp.json to the stable node-against-node_modules form
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/semantic-sidekick normalize-config` and report the result to the user. Mention that `.mcp.json.bak` was created as a safety backup, and that the MCPs need to be toggled in `/mcp` to pick up the change.

package/commands/policy.md

@@ -0,0 +1,16 @@
+---
+description: Get or set the semantic-sidekick update policy (auto | nudge | off)
+allowed-tools: Bash(npx:*)
+argument-hint: "[auto|nudge|off]"
+---
+
+Arguments: $ARGUMENTS
+
+- If `$ARGUMENTS` is empty, run `npx --no @theglitchking/semantic-sidekick policy` and report the current policy and config path.
+- If `$ARGUMENTS` is one of `auto`, `nudge`, `off`, run `npx --no @theglitchking/semantic-sidekick policy $ARGUMENTS` and confirm the new setting to the user.
+- If `$ARGUMENTS` is anything else, tell the user the valid values are `auto`, `nudge`, `off`.
+
+Policies:
+- `auto`  — auto-run `npm update @theglitchking/semantic-sidekick` at session start when a newer version is available.
+- `nudge` — print a one-liner when a newer version is available (default).
+- `off`   — do not check for updates.

package/commands/relink.md

@@ -0,0 +1,6 @@
+---
+description: Re-run the skill linker — refresh symlinks from node_modules into .claude/skills/
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/semantic-sidekick relink` and report the result.

package/commands/status.md

@@ -0,0 +1,6 @@
+---
+description: Show installed version, latest available version, current update policy, and hook registration state
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/semantic-sidekick status` and relay the output to the user verbatim.

package/commands/update.md

@@ -0,0 +1,6 @@
+---
+description: Update semantic-sidekick to the latest version (runs npm update + re-links skills)
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/semantic-sidekick update` and report the before/after versions to the user. If the project doesn't have a local install, fall back to `npx -y @theglitchking/semantic-sidekick update` and note that in your summary.

package/commands/vault.md

@@ -0,0 +1,21 @@
+---
+description: Explicit vault search — escape hatch that works in any mode including outage-silence
+argument-hint: "<natural-language query>"
+allowed-tools: mcp__semantic-vault__search_hybrid, mcp__semantic-vault__read_note, mcp__semantic-vault__get_stats
+---
+
+# /vault — explicit vault search
+
+The user typed `/vault $ARGUMENTS`. This is the explicit vault query that overrides mode gating.
+
+Even in `outage-silence` mode (which suppresses auto-vault activity), `/vault <query>` is always respected.
+
+## Your job
+
+1. **Run `mcp__semantic-vault__search_hybrid`** with `$ARGUMENTS` as the query.
+2. **Read the top 2–3 hits in full** via `mcp__semantic-vault__read_note`.
+3. **Answer the query using those notes**, citing the paths.
+4. **Do not** file anything (no `ingest_source` / `synthesize_note`) unless the user follows up asking to. This is a read path.
+5. **Stay in the current mode** — don't let a `/vault` call exit outage-silence or enter research-mode.
+
+If the query doesn't return useful hits, say "not in vault" and name the closest misses.