@theglitchking/semantic-memory 1.0.0

package/skills/outage-silence/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: outage-silence
+description: Incident/outage mode skill for semantic-sidekick. Activates when the user signals an active production issue — prompts containing "down", "broken", "customers", "production", "rollback", "oncall", "paging", "alert", "incident", "5xx", "timeout", "cascading", or when the user pastes stack traces, error logs, alert timestamps, or terse operational requests ("what's the status of X?"). Preempts vault-first and research-mode — this is a hard-preempt mode. Suppresses all proactive vault activity (no auto-search, no auto-synthesis prompt, no capture cue chatter). Claude goes terse, action-oriented, and accepts that anything the user needs in the vault during an incident they will explicitly /vault for. On mode exit, a postmortem capture prompt is emitted — the one capture ritual that survives this mode. Does NOT activate on generic "bug" talk, planning for future resilience, or reading incident postmortems after the fact. Only actual in-flight incidents.
+---
+
+# outage-silence
+
+**You are in outage-silence.** A customer-visible production issue is in flight. Everything optional is off. You are brief, operational, and help with what is being asked — nothing more.
+
+## Mode entry (how you got here)
+
+One of:
+- **Explicit:** user ran `/mode outage-silence`.
+- **Strong lexical signal:** "down", "broken", "customers", "production", "rollback", "oncall", "paging", "alert", "incident", a pasted stack trace, or a timestamp of the form `2026-04-21T15:32:00Z 5xx` / similar alert shape.
+- **Escalating urgency signal:** user sends terse, imperative turns with no "please" or context-setting. The tone itself is a signal.
+
+This mode has **asymmetric cost-of-error**: false-negative (failing to enter when you should) is very expensive (the vault fires during a fire, drowning the user in context). False-positive (entering when you shouldn't) is cheap (the user says "ok not actually an outage" and you exit). So enter on weaker signal than you would for research-mode.
+
+## What changes from default behavior
+
+### 1. No proactive vault activity
+
+- **Do not** call `mcp__semantic-vault__search_hybrid` unless the user explicitly asks ("check the vault for X" / `/vault X`).
+- **Do not** cite vault paths unless the user asks. The `<vault-context>` block from the hook is still there; mentally set it aside.
+- **Do not** suggest filing anything. "Worth capturing this as a gotcha?" is a peace-time question.
+- **Do not** emit capture-cue prompts mid-session. The Stop hook's capture-pending file is still accumulating, but you don't surface it.
+
+### 2. Terse, operational responses
+
+- Match the user's energy. If they're typing 4-word imperatives, match that register.
+- Lead with the answer or action. No preamble.
+- No long explanations. No hedging. If you don't know, say so in a sentence.
+- Code snippets and commands are welcome; prose paragraphs are not.
+
+### 3. Visible mode indicator
+
+Prefix the first line of every response with `[outage]`. Users need to know you're in this mode so they can spot when you're still silent after the fire is out.
+
+### 4. Explicit vault escape hatch
+
+If the user types `/vault <query>` or explicitly asks ("search the vault for past keycloak outages"), call the vault tools — this mode suppresses *auto* vault use, not *explicit* use.
+
+### 5. Mode-exit capture is mandatory
+
+When `/mode vault-first` (or any other mode) is invoked AND the current mode is `outage-silence`, the transition capture prompt fires — this is handled by the Stop/mode-change hooks. The prompt asks you to draft a postmortem:
+- Timeline of events as observed.
+- Root cause as understood.
+- Fix applied.
+- Preventive actions to file as gotcha notes.
+
+Do the draft. Offer it as a dry-run `synthesize_note` for the user to review before applying. This is the one synthesis that happens in/around outage-silence, and it's non-negotiable — if you don't capture, the next outage repeats the lesson.
+
+## Interaction with hooks
+
+- `SessionStart` preload still fires — ignore it unless the user brings it up.
+- `UserPromptSubmit` injection still fires — ignore unless explicitly consulted.
+- `Stop` hook transition-capture: on exit from outage-silence, the transition-capture path emits a postmortem-specific prompt (not the generic capture prompt). Respect it.
+
+## Failure modes
+
+- **Proactively searching the vault during an incident** — the explicit anti-goal. If you feel the pull to say "this is covered in X.md", suppress it unless the user asked.
+- **Writing long explanations instead of short directives** — tone mismatch makes you feel like dead weight during a fire.
+- **Skipping the postmortem on exit** — equivalent to the incident not happening for future-you.
+- **Entering on weak signal ("my test is broken")** — not an outage. Stay in vault-first / research-mode.
+- **Not exiting when the user says "ok it's fixed, what just happened?"** — that's your cue. Switch to `vault-first` mode visibly and draft the postmortem.
+
+## What success looks like
+
+- User: "5xx spiking, customers seeing errors". You: `[outage]` + a concrete first question ("which service?" / "any recent deploy?" / "any error in the logs you can paste?"). No vault mentions.
+- User pastes stack trace. You: `[outage]` + terse diagnostic hypothesis + specific command to verify.
+- Incident resolves. User: "ok fixed, it was the redis connection pool". You: `[outage]` + one-sentence acknowledgment + offer the postmortem draft (dry-run synthesize_note) before exiting mode.
+- User: "ok exiting outage mode". You emit the postmortem draft, confirm with user, apply (or reject per user input), then behave as vault-first.

package/skills/research-mode/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: research-mode
+description: Aggressive-vault mode skill for semantic-sidekick. Activates when the user signals an open-ended research or investigation session — prompts containing "I'm researching", "help me investigate", "look into", "do a deep dive on", "what's the best X for Y", "compare X and Y", "survey the landscape of", "how do other projects solve", or when the user pastes/introduces multiple external sources (URLs, papers, blog posts) in a short span. Unlike vault-first (which nudges toward the vault on project-scoped prose), research-mode treats every turn as vault-eligible and forces synthesis on transition out. Does NOT activate on short project operational questions ("how do we deploy") — those are vault-first territory. Does NOT activate during an active incident (outage-silence preempts). Strong signal beats weak signal; once entered, the mode sticks through topic shifts within the research arc and only exits on explicit /mode change, session end, or a hard topic break (e.g., user asks an unrelated operational question).
+---
+
+# research-mode
+
+**You are in research-mode.** The user is doing sustained investigation — not a one-off question. The vault is a *working surface*, not a reference: every turn produces or modifies durable artifacts, every source gets filed, every finding gets synthesized before the session closes.
+
+## Mode entry (how you got here)
+
+One of:
+- **Explicit:** user ran `/mode research`.
+- **Strong lexical signal:** user said "I'm researching", "let's investigate", "deep dive", "survey", "compare X and Y", "what's the best X for Y", "look into".
+- **Sustained source introduction:** user pasted or linked ≥3 external URLs / papers / docs in the last few turns and is asking evaluative questions about them.
+
+Weak single-word hints (e.g., "research" as a noun, "look") are insufficient — the mode is too behavior-altering to enter on ambient signal. If you're unsure whether this is research-mode vs vault-first, default to vault-first.
+
+## What changes from default behavior
+
+### 1. Every source becomes a filed note
+
+Whenever the user introduces an external source you end up relying on — a URL they link, a paper they paste, a doc they point at — **file it via `mcp__semantic-vault__ingest_source`** with:
+- `source.source_uri` — the link or path.
+- `source.source_title` — the actual title from the source (don't make one up).
+- `source.source_summary` — your paragraph-length distillation.
+- `units` — one per distinct finding/claim you extract from the source.
+
+The ingest call also writes a `log_event` automatically — session provenance is preserved.
+
+Don't accumulate URLs in the chat and lose them at session end. That's the failure mode this mode exists to prevent.
+
+### 2. Proactive vault checks every non-trivial turn
+
+On each substantive user turn, before answering:
+- Call `mcp__semantic-vault__search_hybrid` with the current topic focus.
+- If prior research notes exist, read them in full via `read_note` and weave them into your answer — don't re-research ground you've already covered.
+- Cite every note you used (paths at end of response).
+
+The "is this already in the vault?" question runs automatically — not just on explicit user ask.
+
+### 3. Synthesis is mandatory on mode exit
+
+Before the session ends — or before `/mode` changes you away from research — you MUST produce a `synthesize_note` that:
+- Names the overall topic.
+- Summarizes the findings in your own words.
+- Cites the source-notes created during the session (`derived_from`).
+- Uses confidence=`high` only if you've read multiple corroborating sources, `medium` for single-source claims, `low` for speculation.
+
+This is the highest-leverage moment in the whole system: 3 hours of research with no synthesis → findings evaporate. 3 hours of research + 30 seconds of synthesis → compounding knowledge.
+
+If the Stop hook fires with a `<vault-capture-prompt>` block, treat it as a hard requirement — do the synthesis before closing, or explicitly reject individual items with reasoning ("that one was already in the vault" / "that was a dead end, not worth capturing").
+
+### 4. Relevance decay, not time decay
+
+The mode stays active across short topic shifts within the research arc ("X → Y as a related question" → stay in research). It exits on:
+- Explicit `/mode vault-first` or `/mode outage-silence`.
+- Session end (SessionStart resets to vault-first).
+- A hard topic break — user pivots to an operational question about the current project ("ok now how do we deploy this?"). That's vault-first territory; acknowledge the mode shift visibly and exit.
+
+Do not exit on short silences or tool-use lulls — 20 turns of reading-and-taking-notes is still research.
+
+## Visible mode indicator
+
+Prefix the first sentence of every research-mode response with `[research]`. Users should always be able to see which mode you're operating in so they can override if you've routed wrong.
+
+## Interaction with hooks
+
+- `SessionStart` preload still fires; treat it as seed context like in vault-first.
+- `UserPromptSubmit` injection still fires; in research-mode, the hits more strongly influence which vault notes you read before answering.
+- `Stop` hook: capture-pending cues accumulated during the session will include research findings; synthesize them before letting Stop close. If the Stop hook's `decision: "block"` fires, don't just emit one synthesize_note to appease it — address each pending item specifically.
+
+## Failure modes
+
+- **Answering without filing sources** — the single biggest failure. If you used a URL in your answer, it gets an `ingest_source` call. No exceptions.
+- **Synthesizing at session end with thin provenance** — if `derived_from` on the synthesis-note is empty, you didn't file the sources. Back up, file them, then re-synthesize.
+- **Staying in research-mode through an unrelated operational question** — exit visibly ("switching out of research-mode for this operational question") and answer from vault-first.
+- **Entering research-mode on a single casual "research" mention** — too aggressive. Prefer vault-first when the signal is weak.
+
+## What success looks like
+
+- Multi-source compare ("what's the best vector DB for <100k docs?") → you search the vault for prior research, do web research as needed, call `ingest_source` per source, then `synthesize_note` before answering. The chat response is a pointer to the synthesis note, not the full answer.
+- 2-hour investigation into a new topic → 1 synthesis note + 4-6 source notes in the vault, all linked. Next session's vault-first preload surfaces them automatically.
+- User shifts to "ok now let's implement this" → you exit research-mode visibly and switch to operational/implementation behavior (with vault-first still nudging).

package/skills/semantic-first/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: semantic-first
+description: Route documentation lookups, internal procedure questions, repo architectural/vocabulary/convention questions, and research tasks through the semantic-sidekick and semantic-vault MCP servers BEFORE falling back to any other search strategy. Use this skill whenever the user asks how something works in this repo, what the convention is, where a procedure or guide lives, what the project calls something, why code is structured a certain way, OR asks any research question — comparative evaluations ("is there a better X"), tool/library/API recommendations ("what's the best X for Y"), best-of surveys, or any "look into X" / "research X" / "investigate X" phrasing. Also use for all research note-taking — findings go into .claude/.vault as markdown with structured frontmatter, not scattered across the conversation. Triggers on prose/conceptual questions about a codebase or domain, not on pure code-symbol lookups (those are Grep jobs). Ships with the semantic-sidekick plugin and probes MCP availability at runtime — the docs-lookup flow degrades gracefully when hit-em-with-the-docs is not installed, and the vault-research flow degrades gracefully when semantic-sidekick itself isn't wired up.
+---
+
+# semantic-first
+
+Route documentation and research through the semantic-sidekick ecosystem before anything else.
+
+## Why this skill exists
+
+The semantic-sidekick plugin installs one or two MCP servers depending on what else is present:
+
+- **`semantic-vault`** — semantic + keyword search and full read/write over `.claude/.vault/`, a research scratchpad that persists across sessions. Available whenever the semantic-sidekick plugin is installed.
+- **`semantic-sidekick`** — the same engine pointed at a read-only docs index (by default `.documentation/`). Available only when the companion plugin `hit-em-with-the-docs` is also installed, since that's the plugin that owns the docs directory structure.
+
+Without explicit routing, Claude's default reflex is to `Grep`/`Glob` the repo when the user asks a conceptual question, and to dump web-research findings straight into the chat where they're lost when the session ends. Both defaults waste the infrastructure the user set up. This skill corrects that.
+
+## Two flows, gated independently
+
+This skill has two flows, and they depend on different MCP servers. Probe each one independently — don't assume that if one works the other does, and don't no-op the whole skill just because half of it is unavailable.
+
+| Flow | What it does | Depends on | Tool namespace |
+|---|---|---|---|
+| **A. Docs lookup** | Find how something works in this repo | `hit-em-with-the-docs` being installed | `mcp__semantic-sidekick__*` |
+| **B. Research notes** | Capture findings to a persistent vault | `semantic-sidekick` being installed (which it is, since this skill ships with it — but the user can still have the MCP misconfigured) | `mcp__semantic-vault__*` |
+
+## Flow A — documentation / procedure / repo-nuance lookups
+
+**Triggers on prose questions about the current repo or project:**
+
+- "How does this repo handle X?"
+- "Where's the guide for Y?"
+- "What's our process for Z?"
+- "Why is this structured this way?"
+- "What does this project call X?"
+- "Is there a convention for Y?"
+- "Is there a `<thing>` in this repo that does X?" — note this is **prose about whether a capability exists**, which semantic-sidekick answers well from design docs, even though a naive read would send it to Grep.
+
+**Does NOT trigger on code-symbol lookups** like "where is function `parseAuth` defined" or "show me the `User` class" — those are `Grep`/`Glob` jobs. The line is *prose vs. symbol*: if the answer is a line or two of prose that would typically live in a design doc, README, or procedure, this flow applies. If the answer is a specific file path and line number that only exists in source code, it doesn't.
+
+**When in doubt, try semantic-sidekick first anyway.** The cost of one extra `search_hybrid` call is tiny; the cost of grep-spelunking for something that's documented in plain English is several wasted minutes.
+
+**Procedure:**
+
+1. **Probe availability** once per task. Call `mcp__semantic-sidekick__get_stats` with no arguments. If the tool is not in the session, or `get_stats` errors, or the stats show an empty/missing index, drop to [Fallback: docs lookup](#fallback-docs-lookup) below. Otherwise the index is live and you can search it.
+2. **Search with hybrid retrieval.** Use `mcp__semantic-sidekick__search_hybrid` with the user's question (or a condensed form of it) as the query. Hybrid search combines semantic embeddings with keyword matching and outperforms either individually for most real questions. Keep `top_k` modest (5–10); you can always widen if the first pass is thin.
+3. **Read the top hits in full.** For each promising result, call `mcp__semantic-sidekick__read_note`. Do not answer from search snippets alone — snippets lose surrounding context and produce confident-sounding wrong answers. Reading 2–3 full notes is almost always cheaper than correcting a wrong answer later.
+4. **Traverse the graph when the question is multi-part.** If a note references `[[wikilinks]]` or has `dependencies:` / `related:` frontmatter, use `mcp__semantic-sidekick__forwardlinks` / `backlinks` to follow the chain. This is especially valuable for questions like "how does X work end-to-end" or "what's the deploy process for each environment" — where the full answer is spread across linked notes.
+5. **Answer from what you read, with filename citations.** Tell the user which notes you pulled the answer from so they can jump to the source. If the answer genuinely isn't in the index, say so explicitly — don't backfill with guesses or pivot silently to web search.
+
+### Fallback: docs lookup
+
+If step 1 indicates the `semantic-sidekick` MCP is unavailable (the `hit-em-with-the-docs` plugin isn't installed, the `.mcp.json` isn't wired up, or the index is empty), degrade:
+
+- Tell the user, in one sentence, that the semantic docs index isn't available and you're falling back to direct file search. Visibility matters — it lets them fix the config and get the fast path back.
+- Use `Glob` to enumerate `*.md` files in likely locations: `docs/`, `documentation/`, `.documentation/`, `README.md`, `CONTRIBUTING.md`, `.claude/`, and the repo root.
+- Use `Grep` for keywords from the question across those files.
+- If nothing promising turns up in markdown, *then* expand to `Grep` over source code as a last resort.
+
+This is strictly worse than semantic search — but a visible fallback is much better than a silent one.
+
+## Flow B — research tasks (internal or external)
+
+**Triggers on evaluative, comparative, or exploratory questions:**
+
+- "Is there a better X than Y?"
+- "What's the best X for Y?"
+- "Look into X."
+- "Research Y."
+- "Investigate how other projects solve Z."
+- Any request that would naturally involve `WebSearch` / `WebFetch`.
+
+**Also triggers on mixed questions** like "how does this repo use X, and is there a better alternative?" — handle the repo half via Flow A, then continue into Flow B for the alternatives half. The two flows compose naturally.
+
+**Procedure:**
+
+1. **If the question has a repo-context component, do Flow A first.** "How do we currently handle X" before "is there a better X" — you can't evaluate alternatives without understanding the current solution.
+2. **Probe vault availability.** Call `mcp__semantic-vault__get_stats`. If it errors or the tool isn't present, drop to [Fallback: vault notes](#fallback-vault-notes). Otherwise the vault is live.
+3. **Check the vault for prior research.** Call `mcp__semantic-vault__search_hybrid` with the topic. If past-you already investigated this, reuse the note — update it in place via `mcp__semantic-vault__update_note` rather than starting over. This is the main reason the vault exists.
+4. **Do the actual research.** Use `WebSearch` / `WebFetch` / whatever tools are appropriate. Read multiple sources where you can — a single source is a single opinion.
+5. **Write the findings to `.claude/.vault` as you go.** Use `mcp__semantic-vault__create_note` (or `update_note`). The full frontmatter format is in `references/vault-frontmatter.md` — read that file once per session before writing your first note.
+6. **Link the note.** Use `[[wikilinks]]` to related notes in the body, and fill in `dependencies` / `related` / `supersedes` in the frontmatter so future sessions can traverse the graph. Unlinked notes are graveyards — they get written once and never found again.
+7. **Answer the user from the note you just wrote.** The note is the canonical artifact; the chat response is a short summary with a pointer to the filename. The user's future self (or another session) can re-read the note; they can't re-read the chat.
+
+### Fallback: vault notes
+
+If step 2 indicates the `semantic-vault` MCP is unavailable but `.claude/.vault/` exists as a directory (or you can create it), use the `Write` tool directly — still follow the frontmatter format in `references/vault-frontmatter.md`. A session without the MCP server still has a filesystem; don't skip note-taking just because the semantic indexing won't happen. The index can be rebuilt later; lost notes can't.
+
+If neither the MCP nor a filesystem `.claude/.vault/` directory is available *and* you can't create it (e.g., permission error), tell the user and put the findings directly in the chat as a clearly-marked "research findings" block — better than losing them entirely.
+
+## The vault frontmatter is non-negotiable
+
+Every `.md` file created in `.claude/.vault/` must start with YAML frontmatter. See `references/vault-frontmatter.md` for the full field reference and rationale. The short version is that the format is adapted from the 22-field docs frontmatter used elsewhere in the semantic-sidekick ecosystem, with the RAG-chunker fields dropped and two research-specific fields (`source`, `confidence`) added. A note without frontmatter won't index properly and becomes invisible to future searches — which defeats the whole point of writing it.
+
+## Interaction with other Claude systems
+
+- **The memory system** (`~/.claude/projects/**/memory/`) is for durable facts about the user and the project (who they are, what they prefer, what constraints are in play). It is NOT for research artifacts. Research goes in the vault; facts go in memory. When in doubt: *is this a body of findings on a specific topic?* → vault. *Is this a fact that would be useful to a completely different task?* → memory.
+- **`Grep`/`Glob`** are for code-symbol lookups and as a Flow A fallback. Not the default for conceptual prose questions when semantic-sidekick is available.
+- **`WebSearch`/`WebFetch`** are research *inputs* — their outputs should flow into vault notes, not into the conversation only. The chat response summarizes; the note preserves.
+
+## What success looks like
+
+- User asks "how does this repo handle auth?" → you call `search_hybrid`, read 2–3 notes, answer with filename citations. Tool call budget: 3–5. No `Grep`.
+- User asks "what's the best CRM for small businesses?" → you search the vault for prior research (none), do web research, write `.claude/.vault/crm-smb-evaluation.md` with full frontmatter, answer from the note.
+- User asks the same CRM question a week later → you find the existing note in the vault, skim it, either answer directly or update it with fresh findings and bump `last_updated`.
+- User installs the skill in a repo without `hit-em-with-the-docs` → Flow A probe fails, you tell the user once, fall back to Glob/Grep for docs lookup. Flow B (vault) still works because `semantic-vault` is available.
+- User's `.mcp.json` is broken entirely → both probes fail, you tell them, fall back to filesystem for both flows. You don't pretend everything's fine.
+
+## What failure looks like
+
+- Grep'ing the repo for a conceptual question when `mcp__semantic-sidekick__search_hybrid` is sitting right there.
+- Writing research findings into the chat response and leaving no artifact on disk.
+- Writing vault notes without frontmatter, or with ad-hoc frontmatter that won't index.
+- Silently no-op'ing when an MCP server is missing instead of telling the user and falling back.
+- Triggering on code-symbol lookups ("where is `parseAuth` defined") and wasting tool calls on semantic search for something `Grep` would answer in 100ms.
+- Assuming both MCP servers travel together. They don't — the vault ships with this plugin, the docs index ships with `hit-em-with-the-docs`. Probe them separately.

package/skills/semantic-first/evals/evals.json

@@ -0,0 +1,37 @@
+{
+  "skill_name": "semantic-first",
+  "evals": [
+    {
+      "id": 1,
+      "name": "flow-a-capability-existence-user-delete",
+      "flow": "A",
+      "prompt": "Is there a user delete in this repo that deletes a user AND their data completely?",
+      "expected_output": "Ambiguous-on-purpose case: a naive read sends this to Grep for a delete symbol, but the answer (whether the capability exists and how it's designed) lives in prose in design docs. The skill should try mcp__semantic-sidekick__search_hybrid first and only fall through to code search if the docs don't answer it. Success = used semantic search first, cited specific note filenames, did not start with grep.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "name": "flow-a-multi-part-infra-question",
+      "flow": "A",
+      "prompt": "What kind of git method is being used, and how many environments and domains/subdomains are there in each environment, and what are they?",
+      "expected_output": "Multi-part factual question where the answer is spread across several docs (git workflow, environments, domains all documented separately). Skill should use search_hybrid, read multiple notes, and ideally traverse via forwardlinks/backlinks to link the pieces together. Should cite each note used. No grepping source code. Success = pulled from multiple notes, composed a complete multi-part answer, cited filenames.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "name": "flow-b-pure-external-research",
+      "flow": "B",
+      "prompt": "What's the best CRM platform for a small business team of 10?",
+      "expected_output": "Pure external research, no repo context. Skill should: (1) search the vault for prior research on CRM evaluation, (2) do web research via WebSearch/WebFetch, (3) write a new .md file to .claude/.vault/ with full frontmatter (all required fields from references/vault-frontmatter.md), (4) answer from the note with a filename pointer. Success = a file was created at .claude/.vault/<slug>.md, frontmatter has all required fields with sensible values, note body has actual research content (not a stub), chat response cites the note filename.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "name": "flow-b-mixed-composition",
+      "flow": "B",
+      "prompt": "We use HashiCorp Vault for secrets management in this repo — is there a better alternative we should consider?",
+      "expected_output": "Hardest test: requires composing Flow A (find how the repo currently uses HashiCorp Vault, cite docs) with Flow B (research alternatives via web search, write vault note). The skill should NOT pick one flow and drop the other. Success = (1) semantic-sidekick was searched for current usage and specific notes were cited, (2) web research was performed for alternatives, (3) a .md file was written to .claude/.vault/ with full frontmatter and source: mixed (since it combines docs-lookup and web-research), (4) final answer references both the repo's current setup and the researched alternatives with explicit confidence, (5) the vault note contains a 'what we currently do' section drawn from Flow A findings.",
+      "files": []
+    }
+  ]
+}

package/skills/semantic-first/references/vault-frontmatter.md

@@ -0,0 +1,133 @@
+# Vault note frontmatter — field reference
+
+Every `.md` file written into `.claude/.vault/` must start with YAML frontmatter in this exact format. The schema is adapted from the 22-field docs frontmatter used by the semantic-sidekick ecosystem, with RAG-chunker fields removed (they're meaningless for scratchpad notes) and two research-specific fields added (`source`, `confidence`) because research artifacts need epistemic provenance.
+
+## The template
+
+Copy this and fill it in for every new note. Don't skip fields — if a field doesn't apply, use `null`, `[]`, or the default shown in the comment. Missing fields break graph traversal and semantic indexing.
+
+```yaml
+---
+title: "Note Title"
+tier: research              # research | investigation | scratch | finding | decision
+topic: null                 # short kebab-case topic, e.g. "hashicorp-vault", "crm-evaluation", or null
+domains:                    # free-form list; common values: security, backend, frontend, devops, infrastructure, product, tooling, ai
+  - security
+audience:                   # who would find this note useful; free-form: self | team | all | <role>
+  - self
+tags:                       # free-form keyword tags; used by search_hybrid
+  - secrets
+  - vault
+status: active              # active | superseded | draft | archived
+last_updated: '2026-04-15'  # ISO date, quoted string
+source: web-research        # web-research | docs-lookup | conversation | experimentation | mixed
+complexity: low             # low | medium | high — how hard the topic is to reason about
+confidence: medium          # low | medium | high — how much future-you should trust these notes
+keywords:                   # precise search terms (more specific than tags)
+  - hashicorp-vault
+  - secret-management
+dependencies: []            # notes that should be read first (filenames or [[wikilinks]])
+related: []                 # parallel/complementary notes
+supersedes: []              # notes this replaces (old investigations that are now wrong)
+summary: One-sentence description of what this note contains.
+owner: self                 # self | team | <username>
+---
+```
+
+## Field-by-field rationale
+
+| Field | Purpose | Notes |
+|---|---|---|
+| `title` | Human-readable. Shows up in search results. | Be specific: "HashiCorp Vault vs Infisical comparison" beats "Secrets research". |
+| `tier` | What kind of note this is. | `research` = multi-source investigation. `investigation` = debugging a specific problem. `scratch` = quick notes, low confidence. `finding` = a conclusion distilled from research. `decision` = an architectural choice and its rationale. |
+| `topic` | A coarse grouping tag. | Kebab-case. `null` if the note doesn't cluster with others. |
+| `domains` | Broad technical areas. | Free-form list. Multiple is fine. Used for filtering. |
+| `audience` | Who benefits from reading this. | Default `[self]`. Use `[team]` or `[all]` only if the note is a finished artifact worth sharing. |
+| `tags` | Free-form keywords. | These are the primary filter dimension in `search_hybrid`. Err on the side of more tags. |
+| `status` | Is this note still valid? | `active` for current work. `superseded` when replaced by a newer investigation (fill `supersedes` on the new note). `draft` for in-progress. `archived` when deliberately retired. |
+| `last_updated` | ISO date, quoted. | Bump this on every edit, even small ones. |
+| `source` | Where the information came from. | `web-research` = Google/WebFetch. `docs-lookup` = pulled from semantic-sidekick. `conversation` = came from the user in chat. `experimentation` = ran something and observed results. `mixed` = combination. This is epistemic provenance and matters for re-reading later. |
+| `complexity` | How hard is this topic. | Affects reading-time expectations and whether future-you should budget extra time. |
+| `confidence` | How much to trust this note. | The single most valuable field for research notes. `low` confidence on a CRM recommendation after reading one blog post is useful information; pretending it's `high` is worse than not writing the note at all. |
+| `keywords` | Precise search terms. | More specific than `tags` — actual names, product names, technical terms that exact-match searches will hit. |
+| `dependencies` | Prerequisite notes. | `[[wikilinks]]` or filenames. Lets the graph traversal follow "what should I read first?". |
+| `related` | Parallel notes. | Complementary topics, not prerequisites. |
+| `supersedes` | Notes this replaces. | When you revisit a topic and the old note is now wrong, list it here and mark the old note's `status: superseded`. |
+| `summary` | One sentence. | This is what shows up in search snippets — make it dense and informative. |
+| `owner` | Who wrote it. | `self` by default. `team` for shared findings. `<username>` if you want to attribute. |
+
+## What got dropped from the 22-field docs format, and why
+
+The published-docs format includes these fields that are *not* in the vault format:
+
+- `feature` → merged into `topic` and `tags`. Research notes rarely map to a single feature.
+- `version` → research notes aren't versioned artifacts; they're snapshots in time.
+- `size_kb`, `line_count`, `read_time_min` → auto-computed by the docs metadata generator for RAG chunking. Irrelevant for scratchpad notes.
+- `load_priority` → used by published docs to hint load order; not meaningful for vault notes.
+- `chunk_strategy` → RAG chunking hint; not used by the vault indexer in the same way.
+
+If the user ever decides to promote a vault note to published docs, they'll need to add these fields back. Until then, they're noise.
+
+## Two fields added to the vault format
+
+- `source` — where the findings came from. Not in the docs format because published docs are the source of truth. Research notes aren't — knowing whether a conclusion is based on a blog post, a spec, or an experiment is critical for judging its weight later.
+- `confidence` — how confident past-you was. Research notes lose value quickly if future-you can't tell whether the author was confident or speculating. A note that says "this library is the best choice" with `confidence: low` is actionable; one without confidence information is a trap.
+
+## Example: fully filled-in note
+
+```yaml
+---
+title: "HashiCorp Vault vs Infisical for SMB secret management"
+tier: research
+topic: secrets-management
+domains:
+  - security
+  - devops
+audience:
+  - self
+  - team
+tags:
+  - secrets
+  - hashicorp-vault
+  - infisical
+  - comparison
+status: active
+last_updated: '2026-04-15'
+source: mixed
+complexity: medium
+confidence: medium
+keywords:
+  - hashicorp-vault
+  - infisical
+  - secret-management
+  - smb
+dependencies: []
+related:
+  - secrets-rotation-patterns.md
+supersedes: []
+summary: Comparison of HashiCorp Vault and Infisical for small-to-medium business secret management, with cost, ops overhead, and feature tradeoffs.
+owner: self
+---
+
+# HashiCorp Vault vs Infisical for SMB secret management
+
+## TL;DR
+
+<one paragraph conclusion>
+
+## What we currently do
+
+<if Flow A surfaced this, summarize from semantic-sidekick findings and cite the docs>
+
+## Options evaluated
+
+### HashiCorp Vault
+...
+
+### Infisical
+...
+
+## Recommendation
+
+<with explicit confidence level>
+```

package/skills/vault-first/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: vault-first
+description: Default mode skill for semantic-sidekick. Treats the markdown vault as present context, not retrievable-on-demand storage. Activates on any operational, architectural, or "how/why/where does this project…" question about the current project, product, or codebase — including prose questions like "how do we deploy", "what's our process for X", "why is Y structured this way", "where does Z live", "how does auth work here", "what are the conventions", operational runbook questions, and gotcha/known-issue lookups. Also activates when hooks have injected <vault-context> blocks into the conversation. Does NOT activate on pure code-symbol lookups ("where is function X defined" → Grep) or on research/evaluative questions about external tools ("is there a better X than Y" → semantic-first's research flow). Coexists with semantic-first — semantic-first handles routing between docs index + research vault; vault-first is the behavioral mode that actually uses them on every relevant prompt rather than waiting to be asked.
+---
+
+# vault-first
+
+**Default mode.** The vault is present, not retrievable. Use it on every relevant prompt, cite what you find, and say it out loud when you didn't find anything.
+
+## Why this skill exists
+
+A 500-note vault that Claude only consults when explicitly asked is a liability — the knowledge creates false confidence ("we've documented that") while being silently bypassed. `semantic-first` routes lookups *when Claude decides to look*. `vault-first` is the decision layer: for any project-scoped prose question, Claude looks *by default*, before answering from memory or guessing.
+
+This skill is one of three mode skills in the sidekick routing system (`vault-first`, `research-mode`, `outage-silence`). It is the default when none of the others apply.
+
+## When you are in vault-first mode
+
+You are in vault-first mode when:
+
+- The user's question is about **this specific project, product, or codebase** and the answer would naturally live in a design doc, runbook, ADR, troubleshooting guide, or decision log.
+- The user asks "how", "why", "where", or "what's our X" about anything project-scoped.
+- A hook has injected a `<vault-context>` block into the conversation — that block is the result of a proactive search; treat it as presented context, not a reference dump.
+- None of the other mode skills (`research-mode`, `outage-silence`) have fired.
+
+## What vault-first mode changes about your behavior
+
+### 1. Look at injected context first
+
+If the conversation contains a `<vault-context>` block (from `SessionStart` preload or `UserPromptSubmit` search-on-prompt), read the listed note paths and snippets before you do anything else. The hook already did a hybrid search for you — the top hits are sitting in front of you. Do not re-run the same search.
+
+If the injected context is enough to answer, answer from it and cite the note paths.
+
+### 2. If injected context is thin or missing, search the vault yourself
+
+Call `mcp__semantic-vault__search_hybrid` (or `search_text` for exact-match needs) with the user's question as the query. Read 2–3 promising hits in full via `mcp__semantic-vault__read_note` before answering. Do not answer from snippets alone — snippets lose context and produce confidently wrong answers.
+
+### 3. Cite, or say "not in vault" — **only when the prompt is actually a vault lookup**
+
+Read this carefully: the cite-or-deflect rule applies **only when the user asked a project-scoped prose question that a filed note could plausibly answer**. That's the narrow case. For everything else, **ignore the `<vault-context>` block silently** — the hook injects it unconditionally, but the rule does not.
+
+**DO cite-or-deflect when:**
+- User asks "how does X work here?", "what's our process for Y?", "where does Z live?", "why is this structured this way?"
+- User asks an operational runbook / troubleshooting / gotcha question
+- User asks a decision-history question ("why did we choose X?")
+
+**DO NOT narrate "not in vault" when:**
+- The user's prompt is a **meta-question about the tool** ("is semantic-vault the same as semantic-sidekick?", "should I install this somewhere?", "what command do I run?")
+- The user is **debugging the plugin itself** ("/mcp shows only one server", "getting ERR_MODULE_NOT_FOUND")
+- The user asks a **yes/no or status check** ("did that work?", "are you stuck?", "should I restart?")
+- The user is **giving a directive** ("proceed", "fix it", "merge the PR")
+- The user is asking about **Claude Code** itself, or about your capabilities generally
+- The prompt is **conversational/social** ("thanks", "ok", "got it")
+
+In all the "DO NOT" cases: the `<vault-context>` block is injected automatically by the UserPromptSubmit hook but is not relevant. Pretend it isn't there. Answer the user's actual question directly. Do not open your response with any variant of "not in vault" — that is noise, not honest deflection.
+
+The cue for applying cite-or-deflect is the *shape of the user's question*, not the presence of a `<vault-context>` block.
+
+**When you DO apply cite-or-deflect:**
+- **Cite:** "…per `runbooks/deploy-staging.md` and `decisions/2026-03-auth-migration.md`." List the paths so the user can open them.
+- **Deflect:** "This isn't in the vault. Nearest matches were `X.md` and `Y.md` but neither covers Z. Want me to [search the web / ask more / file a stub note]?"
+
+Do not silently pivot to web search, do not guess from training data, and do not say "the vault has something like this" without naming files. If you haven't named a file, you haven't cited.
+
+### 4. Offer to capture when you fill a gap
+
+If you had to answer from outside the vault (web search, training knowledge, the user telling you something new), offer once to file a note: *"Worth capturing this in the vault as `gotchas/foo.md`?"* — then let the user decide. This is the ingest loop's entry point; don't force it, but don't skip it.
+
+## Boundary conditions — when vault-first does NOT fire
+
+- **Code-symbol lookups.** "Where is `parseAuth` defined?" → `Grep`. "Show me the `User` model." → `Glob`. If the answer is a file + line, the vault is the wrong tool.
+- **Pure external research.** "What's the best vector DB for <100k docs?" → `semantic-first`'s Flow B (research vault + web).
+- **Active incidents.** If the user mentions "down", "broken", "customers", "rollback", "oncall", an alert timestamp, or pasted error logs, `outage-silence` takes over. Stop auto-firing search. Wait for explicit `/vault` request.
+- **Meta-questions about Claude, Claude Code, or this plugin itself.** "How do I use `/clear`?", "is semantic-vault the same as semantic-sidekick?", "should I reinstall?" → these aren't vault lookups. Answer directly, do not narrate "not in vault".
+- **Tool/debug/status prompts.** "getting this error…", "did that work?", "are you stuck?", "what command do I run?" → operational meta. Not vault lookups.
+- **Directives and conversational turns.** "proceed", "merge please", "thanks", "ok go" → just act/acknowledge. Do not deflect.
+
+## Interaction with hooks
+
+Two hooks participate in this mode:
+
+- **`SessionStart` hook** — runs a hybrid search seeded from cwd and branch, injects the top-K hits as a `<vault-context>` block at session start. You should see it in your context when this skill first activates.
+- **`UserPromptSubmit` hook** — runs a keyword search on each user prompt, fingerprinted against recent queries, and injects a `<vault-context>` block if the fingerprint is new. That is why you sometimes see injected hits and sometimes don't — the hook deliberately suppresses re-firing for near-identical prompts.
+
+If you see `<vault-context source="sessionstart">` or `<vault-context source="prompt">` in your context, those are hook outputs. Treat them as the vault speaking first.
+
+## What success looks like
+
+- User asks "how do we handle MFA enforcement?" with no `vault-first` prior mention — you read the injected `<vault-context>` block, pull `features/authentication/mfa-enforcement-overview.md`, answer with citation. Tool budget: 1 read.
+- User asks a project question where the hook injected nothing — you run `search_hybrid` yourself, read 2 hits, answer + cite. Tool budget: 2 reads + 1 search.
+- User asks something genuinely not in the vault — you say "not in vault", name the nearest misses, offer to capture after the user gives you the answer.
+- `outage-silence` fires — you go quiet on the vault, no proactive search, wait for `/vault`.
+
+## What failure looks like
+
+- Ignoring the `<vault-context>` block and running a fresh search anyway — wastes the preload work.
+- Answering project questions from training data without citing the vault.
+- Saying "the docs cover this" without naming the file.
+- Silently falling back to `Grep` when the project question has an obvious prose answer in the vault.
+- Firing vault-first during an outage and drowning the user in search context when they need terse operational help.
+- **Opening responses with "not in vault" on non-lookup prompts** (meta-questions, debugging, directives, status checks). The `<vault-context>` block fires on every prompt because the hook is unconditional; the skill is the filter. If the prompt isn't a lookup, silently ignore the injected context. "Not in vault" should only appear when the user *asked* something and the vault *didn't answer it*.