oh-my-second-brain 0.1.8 → 0.2.0

package/adapters/claude-code/skills/retrieve/SKILL.md

@@ -38,14 +38,12 @@ Pass `semanticSearches` to issue typed sub-queries in a single call:
 | `lex`   | BM25 keyword search (exact terms, fast)          |
 | `vec`   | SQLite-vector semantic search (meaning-based)    |
 | `hyde`  | Hypothetical-document expansion before search    |
-| `graph` | Semantic candidates confined to graph neighbors  |
 
 ```
 semanticSearches: [
   { type: "lex",   query: "transformer attention" },
   { type: "vec",   query: "self-attention replaces recurrence" },
-  { type: "hyde",  query: "a paper about attention mechanisms" },
-  { type: "graph", query: "related concepts in my notes" }
+  { type: "hyde",  query: "a paper about attention mechanisms" }
 ]
 ```
 
@@ -62,11 +60,10 @@ to the set already selected by the OMS graph traversal.
 5. Choose semantic scope: `semanticScope: "global"` for broad vault-wide search;
    `semanticScope: "graph"` (gph mode) when candidates must stay inside the
    selected graph neighbors. Pass typed sub-queries via `semanticSearches`
-   using `lex`, `vec`, `hyde`, or `graph` types as appropriate.
+   using `lex`, `vec`, or `hyde` types as appropriate.
    Pass `semanticMode`, `semanticIntent`, `semanticLex`, `semanticVec`,
    `semanticHyde`, and `semanticMinScore` for additional control.
-   Use `semanticStorage: "qmd-sqlite"` for the default qmd-compatible SQLite
-   store; set `embeddingSyncBeforeSearch: true` only when the native semantic
+   Set `embeddingSyncBeforeSearch: true` only when the native semantic
    index must be refreshed before retrieval.
 6. Use `oms_sync_embeddings` for explicit update/embed sync.
 7. Use `oms_semantic_query`, `oms_semantic_status`, `oms_semantic_collections`,
@@ -94,7 +91,7 @@ Purpose: "Synthesize my transformer papers"
 ## Runtime
 
 Use MCP `oms_retrieve_context` for live graph/semantic retrieval. Pass typed
-sub-queries via `semanticSearches` (types: `lex`, `vec`, `hyde`, `graph`).
+sub-queries via `semanticSearches` (types: `lex`, `vec`, `hyde`).
 Use `semanticScope: "graph"` (gph mode) to confine semantic candidates to
 graph neighbors. Use MCP `oms_sync_embeddings` for native semantic-index sync.
 Use MCP `oms_get_document` or `oms_multi_get_documents` for document rehydration.

package/adapters/claude-code/skills/setup/SKILL.md

@@ -38,7 +38,7 @@ The CLI will:
 | `--vault <path>` | Path to your Obsidian vault root (default: current directory) |
 | `--yes` | Non-interactive: accept all defaults, no prompts |
 | `--suggest-fields` | Merge observed note frontmatter fields into concept schemas without mutating notes. |
-| `--install-claude` | Legacy setup-only dry-run that prints Claude Code plugin install and MCP registration commands. |
+| `--install-claude` | Legacy setup-only dry-run that prints the Claude Code plugin install command and plugin-owned MCP asset. |
 | `install --runtime <name>` | Install host adapter/MCP registration for `auto`, `all`, `claude`, `codex`, or `hermes`. |
 | `install --dry-run` | Preview host writes without mutating config. |
 | `install --execute` | Allow external host CLIs such as `claude plugin install` to run when available. |
@@ -71,9 +71,8 @@ Run `/oms-doctor` to validate your existing notes against the convention.
 
 ## Roadmap
 
-Setup plus `oms install`/`oms uninstall` host lifecycle commands are real and release-gated by unpacked npm tarball smoke tests. The MCP command starts
-the status/read/cache/retrieve/capture runtime (`oms_graph_status`, `oms_graph_build`,
+Setup plus `oms install`/`oms uninstall` host lifecycle commands are real and release-gated by unpacked npm tarball smoke tests. The plugin-owned MCP asset starts
+the status/read/cache/retrieve/write runtime (`oms_graph_status`, `oms_graph_build`,
 `oms_list_concepts`, `oms_retrieve_context`, `oms_retrieve_by_axis`,
-`oms_lazy_load_note`, `oms_validate_contract`, `oms_capture_prepare`,
-`oms_capture_commit`).
-Capture commit is gated by path-safety and contract validation.
+`oms_lazy_load_note`, `oms_validate_contract`, `write`).
+`write` is gated by path-safety and the kernel-owned contract.

package/adapters/claude-code/skills/uninstall/SKILL.md

@@ -31,4 +31,4 @@ oms uninstall --runtime all --dry-run
 oms uninstall --runtime all --yes
 ```
 
-Use `--execute` only when you want Oh My Second Brain to call external host CLIs such as `claude mcp remove oms` or `claude plugin uninstall oms`.
+Use `--execute` only when you want Oh My Second Brain to call external host CLIs such as the scoped `claude mcp remove oms --scope local|project|user` commands or `claude plugin uninstall oms`.

package/adapters/claude-code/skills/wiki/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: oms-wiki
-description: Promote compiled concepts from processed/ into the wiki/ query surface, maintain the 5-state staleness ledger, regenerate navigation surfaces (index.md + log.md), and run 2-tier lint over the wiki collection.
+description: Two-path wiki skill — Path A: promote compiled concepts from processed/ into the wiki/ query surface; Path B (human authoring): build interlinked terminology notes in vault taxonomy folders via write.
 ---
 
 # Skill: oms-wiki (Claude Code)
 
-Promote compiled concepts into the wiki query surface and keep the staleness ledger, navigation surfaces, and lint clean.
+Two-path skill — thin pointer to `core/skills/wiki`. Requires `OMS_VAULT`.
 
 ## Invocation
 
@@ -13,23 +13,31 @@ Promote compiled concepts into the wiki query surface and keep the staleness led
 /wiki
 ```
 
-## What this skill does
+## Which path?
 
-Thin pointer to `core/skills/wiki`. Requires `OMS_VAULT`. Operates on the
-`wiki/` query surface only — never writes to `processed/` or `src/`.
+Check **before acting**:
+- **Path A:** you have compiled `processed/<concept>.md` output → promote into `wiki/`.
+- **Path B (human authoring):** you have only a topic + terms, no compile output → use MCP `write`, writes to vault taxonomy folders.
 
-## Agent-guided steps (v0)
+These paths are **mutually exclusive**.
 
-1. Verify `processed/<concept>.md` exists (Phase-B compile output from M2).
+---
+
+## Path A — promotion
+
+*(Only when `processed/<concept>.md` exists.)*
+
+### Agent-guided steps
+
+1. Verify `processed/<concept>.md` exists.
 2. Load the staleness ledger from `.llmwiki/staleness.json`.
-3. Run `runCollection()` — promotes `processed/→wiki/`, updates the ledger,
-   flips cascade backlinks, and detects stubs and orphans.
-4. Regenerate `wiki/index.md` (global catalog) and append an entry to `wiki/log.md`
-   via `regenerateIndex()` and `appendLog()`.
-5. Run `runLint()` — apply auto-fixes (index consistency, broken `[[wikilinks]]`,
-   See-Also sections) and report findings (conflicts, orphans, outdated refs) to stdout.
+3. Promote `processed/→wiki/`, update the ledger, flip cascade backlinks,
+   and detect stubs and orphans.
+4. Regenerate `wiki/index.md` and append an entry to `wiki/log.md`.
+5. Lint — auto-fix index consistency, broken `[[wikilinks]]`, and See-Also
+   sections; report conflicts, orphans, and outdated refs.
 
-## Staleness states
+### Staleness states
 
 | State | Meaning |
 |-------|---------|
@@ -41,17 +49,34 @@ Thin pointer to `core/skills/wiki`. Requires `OMS_VAULT`. Operates on the
 
 Full-rebuild escape hatch: delete `.llmwiki/staleness.json` — every page resets to DIRTY.
 
-## Runtime
+`processed/` is internal — NEVER synced to the Obsidian vault.
+A wiki run never triggers compile; compile never writes `wiki/` directly.
+
+---
+
+## Path B — Human authoring
+
+*(Only when no compiled `processed/` output exists.)*
+
+Build a hub/MOC note plus one standalone note per coined term, cross-linked with
+`[[wikilinks]]` and committed via MCP `write`.
+Writes to vault taxonomy folders — **never to `wiki/`**.
+
+### Admission gate
 
-Implemented in `src/engine/wiki/`: `collection.ts` (`runCollection()`),
-`ledger.ts` (`loadLedger()` / `saveLedger()` / `resetLedger()`),
-`navigation.ts` (`regenerateIndex()` / `appendLog()`), `lint.ts` (`runLint()`),
-`types.ts`.
+Apply before any MCP `write` call:
+- **Coined/proper term** (only ever means one specific technical thing) → standalone note.
+- **General noun** (meaning shifts by domain) → `## Term` section inside the hub note.
 
-`promoteToWiki()` in `collection.ts` is the sole entry point into `wiki/`.
+K8s example: `Pod`, `Service`, `Deployment`, `Ingress` → hub sections;
+`ReplicaSet`, `StatefulSet`, `DaemonSet`, `CronJob` → standalone notes.
 
-## NOTES
+### Agent-guided steps
 
-`processed/` is engine-internal and is NEVER synced to the Obsidian vault —
-only `wiki/` crosses the sync boundary. A wiki run never triggers compile;
-compile never writes `wiki/` directly.
+1. Ask for the **topic** and **term list**.
+2. Resolve the **target concept/folder** from `vault/.oms/taxonomy.yaml`.
+3. Apply the admission gate to every term.
+4. **Deduplicate**: MCP `write` `mode: "create"` per coined term; if the note already exists, reuse the `[[wikilink]]`.
+5. Draft coined-term notes (definition + `## See Also` back-link to hub). Commit terms first.
+6. Draft hub/MOC note (general-noun `## Term` sections + `## See Also` coined-term links). Commit hub last.
+7. Run `oms doctor` (non-blocking, exits 0).

package/adapters/claude-code/skills/write/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: oms-write
+description: Write a vault note through the Oh My Second Brain kernel contract.
+---
+
+# Skill: oms-write (Claude Code)
+
+## Invocation
+
+```
+/oms-write
+```
+
+Call MCP `write`. Do not use host Write/Edit for vault `.md` files.
+
+`mode` is `create`, `append`, or `update`. The kernel owns `.oms` and returns `ask`, `inbox`, `written`, or `rejected`.

package/adapters/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults \u2014 Codex native rules, skills, and MCP adapter.",
   "_note": "oms install writes Codex MCP config, installs ~/.codex/rules/oms.md, and installs ~/.codex/skills/oms-*.",
   "skills": "./skills/",

package/adapters/codex/AGENTS.md

@@ -10,7 +10,7 @@ This vault is governed by Oh My Second Brain conventions stored in `.oms/`.
 - Run `oms doctor` to validate notes against the convention (exits 0, non-blocking).
 - Read `.oms/taxonomy.yaml` and `.oms/concepts/*.yaml` for folder and field declarations.
 
-**Capture:** Use `$oms-capture` skill or follow the librarian persona.
+**Write:** Use `$oms-write`. Call MCP `write`. Do not use host Write/Edit for vault `.md` files.
 **Retrieve:** Use `$oms-retrieve` skill or follow the retriever persona with declared lenses.
 
-> **v0 native install:** `oms install --runtime codex` installs Codex rules, `$oms-*` skills, and a managed Codex MCP config. Use Oh My Second Brain MCP tools for capture/retrieve and CLI commands for lifecycle.
+> **v0 native install:** `oms install --runtime codex` installs Codex rules, `$oms-*` skills, and a managed Codex MCP config. Use Oh My Second Brain MCP tools for write/retrieve and CLI commands for lifecycle.

package/adapters/codex/rules/oms.md

@@ -14,7 +14,7 @@ Oh My Second Brain is a convention harness, not a content generator. The user ow
 | install host integration | `$oms-install` or `oms install --runtime codex --vault <path> --yes` |
 | uninstall host integration | `$oms-uninstall` or `oms uninstall --runtime codex --yes` |
 | validate notes | `$oms-doctor` or `oms doctor --vault <path>` |
-| capture knowledge | use MCP `oms_capture_prepare` then `oms_capture_commit` |
+| write a vault note | use `$oms-write` / MCP `write` (`create`, `append`, or `update`) |
 | retrieve knowledge | use MCP `oms_retrieve_context`, then `oms_lazy_load_note` only when needed |
 
 ## Safety

package/adapters/codex/skills/oms-compile/SKILL.md

@@ -1,18 +1,16 @@
 ---
 name: oms-compile
-description: Stateless per-concept compile worker — synthesizes a concept wiki page from source materials with SHA-incremental skip, provenance weighting, and cascade backlinks.
+description: Agent-guided concept compile — synthesize a concept wiki page from source materials with incremental skip, provenance weighting, and cascade backlinks.
 ---
 
 # oms-compile
 
-Thin pointer to `core/skills/compile`. Runs two strict phases:
+Thin pointer to `core/skills/compile`. There is no `oms compile` CLI. Two phases:
 
-1. **Phase A** — load and grade source materials (pure read, no vault mutation). Resolve backlinks from the compile graph.
-2. **Phase B** — write synthesized `body` to `processed/` tier only; never to `wiki/` directly.
+1. **Phase A** — load and grade source materials (pure read). Resolve backlinks.
+2. **Phase B** — write synthesized `body` to `processed/` only; never to `wiki/`.
 
-Check `wasSkipped(result)` before Phase B — skip if material SHA is unchanged.
-Pass `result.affected_backlinks` to the M3 wiki collection owner to mark stale pages.
+Skip Phase B if the material SHA is unchanged.
+Pass affected backlinks to the wiki skill to mark stale pages.
 Provenance order: authored > curated > external-raw.
-Delete `{dotLlmwiki}/sha-cache.json` to force a full recompile of all concepts.
-
-NOTE: Wiki mirror deferred — depends on M3.
+Delete `{dotLlmwiki}/sha-cache.json` to force a full recompile.

package/adapters/codex/skills/oms-distill/SKILL.md

@@ -7,13 +7,8 @@ description: Standalone meta-absorption skill — analyzes any target in a clean
 
 Thin pointer to `core/skills/distill`. Vault-agnostic — `OMS_VAULT` not required.
 
-Rules:
-
-1. Load target via `prepareCleanRoom(target)` — inert read-only text only; never execute it.
-2. Snapshot SHA before analysis. Run `runAnalysis(spec, provider)`.
-3. Generate report via `generateReport(result, targetName)`: §1 Patterns, §2 Risks, §3 Attribution.
-4. Verify mutation detector: SHA after must equal SHA before. Throw if mutated.
+1. Load the target as inert read-only text; never execute it.
+2. Snapshot a content hash before analysis. Run a read-only red-team pass.
+3. Write the report: §1 Patterns, §2 Risks, §3 Attribution.
+4. Verify the hash is unchanged. Stop if anything mutated.
 5. Return the report string. No vault write occurs inside distill.
-6. Use `createStubAnalyzerProvider()` for offline/test runs.
-
-NOTE: Wiki mirror deferred — depends on M3.

package/adapters/codex/skills/oms-link/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: oms-link
+description: Two-path note-linking skill — Path A (pre-write): compose a new note body that already carries [[wikilinks]] to existing term notes; Path B (retrofit): add missing links to existing notes via oms linkify or oms_link_apply.
+---
+
+# oms-link
+
+Thin pointer to `core/skills/link`. Requires `OMS_VAULT`.
+
+Determine which path applies before acting. These paths are **mutually exclusive**.
+
+Link targets are ONLY notes bound to the `term` concept in `vault/.oms/taxonomy.yaml`; their surface forms are the basename and the frontmatter `aliases`. Three engine rules hold in both paths: a link exists only where the term literally appears (surface-anchored, never invented by retrieval); first occurrence per target note only; ambiguity (`ambiguous: true` + `rivalPaths`) is reported and never auto-resolved — ask the user or skip the span. Frontmatter, code, existing links, headings, URLs, and tags are masked out, so a "missing" link inside any of them is correct.
+
+## Path A — pre-write linking
+
+*(Use while drafting, so the note lands already linked and needs no retrofit.)*
+
+1. Call MCP `oms_link_suggest` on an existing note in the same folder (or run `oms linkify --folder <folder>` in report mode) and read the `targetPath` list — that is the vault's current term vocabulary.
+2. Draft the body with those exact surface forms, writing `[[wikilinks]]` inline at the first mention of each term.
+3. Commit via MCP `write`. Host file edits never touch vault `.md`.
+4. Re-check with `oms_link_suggest`: zero candidates means the draft was already fully linked.
+
+NOTE: `0 term note(s) available as link targets` means the vault has no term layer yet — build one with the `oms-wiki` skill first.
+
+## Path B — retrofit existing notes
+
+*(Use when the note is already on disk. Report first, always.)*
+
+1. `oms linkify --folder <folder>` — report only, writes nothing.
+2. Show the report and get agreement before mutating anything.
+3. Whole folder → `oms linkify --folder <folder> --apply --yes`. `--apply` without `--yes` refuses before reading any note and writes nothing.
+4. Per-note acceptance → `oms_link_suggest { notePath, folder? }` returns candidates plus `baseContentHash`; drop unresolved ambiguous ones; then `oms_link_apply { notePath, baseContentHash, candidateIds, folder? }` with the SAME `baseContentHash` and the SAME `folder` scope.
+5. Run `oms doctor` after a retrofit run (non-blocking, exits 0).
+
+NOTE: `oms_link_apply` refuses without writing on `note-changed`, `candidate-drift`, or overlapping candidates. Re-run `oms_link_suggest` for fresh offsets instead of retrying stale ids. Every write — CLI or MCP — goes through the capture kernel, so path safety and the concept contract hold.

package/adapters/codex/skills/oms-retrieve/SKILL.md

@@ -16,12 +16,11 @@ the selected OMS graph candidates.
 
 Pass typed sub-queries via `semanticSearches` to combine search strategies in one call:
 `type: "lex"` for BM25 keyword search, `type: "vec"` for SQLite-vector semantic
-search, `type: "hyde"` for hypothetical-document expansion, and `type: "graph"` for
-semantic candidates confined to graph neighbors. Pass `semanticMode`, `semanticIntent`,
-`semanticLex`, `semanticVec`, `semanticHyde`, and `semanticMinScore` for additional
-typed or thresholded control. Pass `semanticStorage: "qmd-sqlite"` for the default
-qmd-compatible SQLite store, and `embeddingSyncBeforeSearch: true` when the native
-semantic index must be refreshed before retrieval, or call `oms_sync_embeddings` explicitly.
+search, and `type: "hyde"` for hypothetical-document expansion. Pass `semanticMode`,
+`semanticIntent`, `semanticLex`, `semanticVec`, `semanticHyde`, and
+`semanticMinScore` for additional typed or thresholded control. Pass
+`embeddingSyncBeforeSearch: true` when the native semantic index must be refreshed
+before retrieval, or call `oms_sync_embeddings` explicitly.
 Use read-only `oms_get_document` or `oms_multi_get_documents` to rehydrate selected
 docids, paths, globs, or line ranges. Use `oms_semantic_query`,
 `oms_semantic_status`, `oms_semantic_collections`, or `oms_semantic_contexts` for

package/adapters/codex/skills/oms-wiki/SKILL.md

@@ -1,19 +1,39 @@
 ---
 name: oms-wiki
-description: Promote compiled concepts from processed/ into the wiki/ query surface, maintain the 5-state staleness ledger, regenerate navigation surfaces (index.md + log.md), and run 2-tier lint over the wiki collection.
+description: Two-path wiki skill — Path A: promote compiled concepts from processed/ into the wiki/ query surface; Path B (human authoring): build interlinked terminology notes in vault taxonomy folders via write.
 ---
 
 # oms-wiki
 
 Thin pointer to `core/skills/wiki`. Requires `OMS_VAULT`.
 
-Rules:
+Determine which path applies before acting. These paths are **mutually exclusive**.
 
-1. Verify `processed/<concept>.md` exists (Phase-B compile output from M2).
+## Path A — promotion
+
+*(Use only when `processed/<concept>.md` already exists.)*
+
+1. Verify `processed/<concept>.md` exists.
 2. Load staleness ledger from `.llmwiki/staleness.json`.
-3. Run `runCollection()`: promotes `processed/→wiki/`, updates ledger, flips cascade backlinks, detects stubs and orphans.
-4. Regenerate `wiki/index.md` and append to `wiki/log.md` via `regenerateIndex()` and `appendLog()`.
-5. Run `runLint()`: auto-fix (index consistency, broken links, See-Also) and report-only (conflicts, orphans, outdated refs).
-6. `promoteToWiki()` in `collection.ts` is the sole entry point into `wiki/`. Never write `processed/` from this skill.
+3. Promote `processed/→wiki/`, update ledger, flip cascade backlinks, detect stubs and orphans.
+4. Regenerate `wiki/index.md` and append to `wiki/log.md`.
+5. Lint: auto-fix (index consistency, broken links, See-Also) and report-only (conflicts, orphans, outdated refs).
+
+NOTE: `processed/` is internal — never synced to the Obsidian vault. Only `wiki/` crosses the sync boundary.
+
+## Path B — Human authoring
+
+*(Use when you have only a topic + terms and no compiled `processed/` output.)*
+
+1. Ask the user for a **topic** and **term list** (or extract terms from freeform source text).
+2. Resolve the **target concept/folder** from `vault/.oms/taxonomy.yaml`.
+3. Apply the **admission gate** to every term:
+   - Coined/proper term (only ever means one specific technical thing) → standalone note.
+   - General noun (meaning shifts by domain) → `## Term` section inside the hub note only.
+   - K8s example: `Pod`, `Service`, `Deployment`, `Ingress` → hub sections; `ReplicaSet`, `StatefulSet`, `DaemonSet`, `CronJob` → standalone notes.
+4. **Deduplicate**: call MCP `write` with `mode: "create"` for each coined term; if the note already exists, reuse the `[[wikilink]]`.
+5. Draft coined-term notes: frontmatter from the concept's required fields + definition + `## See Also` back-link to the hub. Commit terms first via MCP `write`.
+6. Draft hub/MOC note: general-noun `## Term` sections + `## See Also` listing all coined-term `[[wikilinks]]`. Commit hub last via MCP `write`.
+7. Run `oms doctor` after all notes are committed (non-blocking, exits 0).
 
-NOTE: `processed/` is engine-internal — never synced to the Obsidian vault. Only `wiki/` crosses the sync boundary.
+NOTE: Path B writes to vault taxonomy folders — **never to `wiki/`**.

package/adapters/codex/skills/oms-write/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: oms-write
+description: Write a vault note through the Oh My Second Brain kernel contract.
+---
+
+# oms-write
+
+Call MCP `write`. Do not use host Write/Edit for vault `.md` files.
+
+`mode` is `create`, `append`, or `update`. The kernel owns `.oms` and returns `ask`, `inbox`, `written`, or `rejected`.

package/adapters/hermes/README.md

@@ -5,4 +5,6 @@ Installed by `oms install --runtime hermes` into:
 - `~/.hermes/skills/knowledge-management/oms/`
 - `~/.hermes/config.yaml` as `mcp_servers.oms`
 
-The skill bundle mirrors Oh My Second Brain's capture/retrieve/setup/doctor lifecycle and uses the Oh My Second Brain MCP server for runtime operations.
+The skill bundle mirrors Oh My Second Brain's write/retrieve/setup/doctor lifecycle and uses the Oh My Second Brain MCP server for runtime operations.
+
+Unlike Claude Code (`claude plugin install`), Hermes exposes no native marketplace or plugin-update command, so this adapter stays OMS-managed: `oms update` reconciles it by re-running the same install path. `mcp_servers.oms` is edited surgically, leaving the rest of `~/.hermes/config.yaml` — including comments and key ordering — untouched.

package/adapters/hermes/SOUL.md

@@ -11,9 +11,8 @@ This vault is governed by Oh My Second Brain conventions stored in `.oms/`.
 - Read `.oms/taxonomy.yaml` for folder-to-concept bindings.
 - Read `.oms/concepts/*.yaml` for field declarations and lenses.
 
-**Capture:** Follow the librarian persona — resolve concept, resolve folder from taxonomy,
-construct required frontmatter, write note, then run `oms doctor`.
+**Write:** Use the `write` skill. Call MCP `write`. Do not use host Write/Edit for vault `.md` files.
 
 **Retrieve:** Follow the retriever persona — identify purpose, match lens, project lens fields only.
 
-> **v0 native install:** `oms install --runtime hermes` installs a Hermes skill bundle and registers Oh My Second Brain MCP in `~/.hermes/config.yaml`. Use Oh My Second Brain MCP tools for capture/retrieve and CLI commands for lifecycle.
+> **v0 native install:** `oms install --runtime hermes` installs a Hermes skill bundle and registers Oh My Second Brain MCP in `~/.hermes/config.yaml`. Use Oh My Second Brain MCP tools for write/retrieve and CLI commands for lifecycle.

package/adapters/hermes/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults \u2014 Hermes skill bundle and MCP adapter.",
   "_note": "oms install writes ~/.hermes/config.yaml mcp_servers.oms and installs skills under ~/.hermes/skills/knowledge-management/oms/.",
   "skills": "./skills/"

package/adapters/hermes/skills/compile/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: compile
-description: Stateless per-concept compile worker — synthesizes a concept wiki page from source materials with SHA-incremental skip, provenance weighting, and cascade backlinks.
+description: Agent-guided concept compile — synthesize a concept wiki page from source materials with incremental skip, provenance weighting, and cascade backlinks.
 ---
 
 # oms-compile
 
-Thin pointer to `core/skills/compile`. Runs two strict phases:
+Thin pointer to `core/skills/compile`. There is no `oms compile` CLI.
 
-Phase A — load and grade source materials (pure read, no vault mutation). Resolve backlinks from the compile graph.
-Phase B — write synthesized body to `processed/` tier only; never to `wiki/` directly.
+Phase A — load and grade source materials (pure read). Resolve backlinks.
+Phase B — write synthesized body to `processed/` only; never to `wiki/`.
 
-Check `wasSkipped(result)` before Phase B — skip if material SHA is unchanged. Pass `result.affected_backlinks` to the M3 wiki collection owner to mark stale pages. Provenance order: authored > curated > external-raw. Delete `{dotLlmwiki}/sha-cache.json` to force a full recompile.
-
-NOTE: Wiki mirror deferred — depends on M3.
+Skip Phase B if the material SHA is unchanged. Pass affected backlinks to the wiki skill. Provenance order: authored > curated > external-raw. Delete `{dotLlmwiki}/sha-cache.json` to force a full recompile.

package/adapters/hermes/skills/distill/SKILL.md

@@ -7,6 +7,4 @@ description: Standalone meta-absorption skill — analyzes any target in a clean
 
 Thin pointer to `core/skills/distill`. Vault-agnostic — `OMS_VAULT` not required.
 
-Load target via `prepareCleanRoom(target)` — inert text only, never execute. Snapshot SHA, run `runAnalysis(spec, provider)`, generate report via `generateReport(result, targetName)`. Report has exactly three sections: §1 Patterns, §2 Risks, §3 Attribution. Verify mutation detector after: SHA must be unchanged. Return the report string — no vault write occurs inside distill. Use `createStubAnalyzerProvider()` for offline/test runs.
-
-NOTE: Wiki mirror deferred — depends on M3.
+Load the target as inert text only, never execute. Snapshot a content hash, run a read-only red-team pass, then write §1 Patterns, §2 Risks, §3 Attribution. Verify the hash is unchanged. Return the report string — no vault write occurs inside distill.

package/adapters/hermes/skills/link/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: link
+description: Two-path note-linking skill — Path A (pre-write): compose a new note body that already carries [[wikilinks]] to existing term notes; Path B (retrofit): add missing links to existing notes via oms linkify or oms_link_apply.
+---
+
+# oms-link
+
+Thin pointer to `core/skills/link`. Requires `OMS_VAULT`.
+
+Link targets are ONLY notes bound to the `term` concept in `vault/.oms/taxonomy.yaml`; their surface forms are the basename and the frontmatter `aliases`. Three engine rules hold in both paths: a link exists only where the term literally appears (surface-anchored — retrieval never invents one); first occurrence per target note only; ambiguity (`ambiguous: true` + `rivalPaths`) is reported, never auto-resolved — ask the user or skip the span. Frontmatter, code, existing links, headings, URLs, and tags are masked out, so a "missing" link inside any of them is correct.
+
+**Path A (pre-write) — use while drafting the note:** Call MCP `oms_link_suggest` on an existing note in the same folder (or run `oms linkify --folder <folder>` in report mode) and read the `targetPath` list — that is the vault's current term vocabulary. Draft the body with those exact surface forms, writing `[[wikilinks]]` inline at the first mention of each term, then commit via MCP `write` (host file edits never touch vault `.md`). Re-check with `oms_link_suggest`: zero candidates means the draft was already fully linked.
+
+NOTE: `0 term note(s) available as link targets` means the vault has no term layer yet — build one with the `wiki` skill first.
+
+**Path B (retrofit) — use when the note already exists:** Run `oms linkify --folder <folder>` first; it reports only and writes nothing. Show the report and get agreement before mutating. For a whole folder use `oms linkify --folder <folder> --apply --yes` — `--apply` without `--yes` refuses before reading any note and writes nothing. For per-note acceptance call `oms_link_suggest { notePath, folder? }` for candidates plus `baseContentHash`, drop unresolved ambiguous ones, then `oms_link_apply { notePath, baseContentHash, candidateIds, folder? }` with the SAME `baseContentHash` and the SAME `folder` scope. Run `oms doctor` afterwards (non-blocking, exits 0).
+
+NOTE: `oms_link_apply` refuses without writing on `note-changed`, `candidate-drift`, or overlapping candidates. Re-run `oms_link_suggest` for fresh offsets instead of retrying stale ids. Every write — CLI or MCP — goes through the capture kernel, so path safety and the concept contract hold. The two paths are mutually exclusive.

package/adapters/hermes/skills/retrieve/SKILL.md

@@ -16,12 +16,11 @@ the selected OMS graph candidates.
 
 Pass typed sub-queries via `semanticSearches` to combine search strategies in one call:
 `type: "lex"` for BM25 keyword search, `type: "vec"` for SQLite-vector semantic
-search, `type: "hyde"` for hypothetical-document expansion, and `type: "graph"` for
-semantic candidates confined to graph neighbors. Pass `semanticMode`, `semanticIntent`,
-`semanticLex`, `semanticVec`, `semanticHyde`, and `semanticMinScore` for additional
-typed or thresholded control. Pass `semanticStorage: "qmd-sqlite"` for the default
-qmd-compatible SQLite store, and `embeddingSyncBeforeSearch: true` when the native
-semantic index must be refreshed before retrieval, or call `oms_sync_embeddings` explicitly.
+search, and `type: "hyde"` for hypothetical-document expansion. Pass `semanticMode`,
+`semanticIntent`, `semanticLex`, `semanticVec`, `semanticHyde`, and
+`semanticMinScore` for additional typed or thresholded control. Pass
+`embeddingSyncBeforeSearch: true` when the native semantic index must be refreshed
+before retrieval, or call `oms_sync_embeddings` explicitly.
 Use read-only `oms_get_document` or `oms_multi_get_documents` to rehydrate selected
 docids, paths, globs, or line ranges. Use `oms_semantic_query`,
 `oms_semantic_status`, `oms_semantic_collections`, or `oms_semantic_contexts` for

package/adapters/hermes/skills/setup/SKILL.md

@@ -28,7 +28,10 @@ oms setup --vault <vault> --suggest-fields
 Then, when host registration is desired:
 
 ```bash
-oms install --runtime codex --vault <vault> --yes
+oms install --runtime hermes --vault <vault> --yes
 ```
 
-Setup interviews folder intent, concept binding, optional observed fields, and retrieval lenses. It rejects lenses that reference unknown fields. Do not modify vault notes during setup. Oh My Second Brain writes only `vault/.oms/taxonomy.yaml` and `vault/.oms/concepts/`, preserving existing concept files while adding missing defaults or selected observed fields.
+Setup interviews folder intent, concept binding, optional observed fields, and retrieval lenses.
+It rejects lenses that reference unknown fields. Do not modify vault notes during setup.
+Oh My Second Brain writes only `vault/.oms/taxonomy.yaml` and `vault/.oms/concepts/`,
+preserving existing concept files while adding missing defaults or selected observed fields.

package/adapters/hermes/skills/wiki/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: wiki
-description: Promote compiled concepts from processed/ into the wiki/ query surface, maintain the 5-state staleness ledger, regenerate navigation surfaces (index.md + log.md), and run 2-tier lint over the wiki collection.
+description: Two-path wiki skill — Path A: promote compiled concepts from processed/ into the wiki/ query surface; Path B (human authoring): build interlinked terminology notes in vault taxonomy folders via write.
 ---
 
 # oms-wiki
 
 Thin pointer to `core/skills/wiki`. Requires `OMS_VAULT`.
 
-Verify `processed/<concept>.md` exists (Phase-B compile output from M2), load staleness ledger from `.llmwiki/staleness.json`, run `runCollection()` to promote `processed/→wiki/`, update the ledger, flip cascade backlinks, detect stubs and orphans. Regenerate `wiki/index.md` and append to `wiki/log.md` via `regenerateIndex()` and `appendLog()`. Run `runLint()` — auto-fix index consistency, broken `[[wikilinks]]`, and See-Also sections; report conflicts, orphans, and outdated refs to stdout. `promoteToWiki()` in `collection.ts` is the sole entry point into `wiki/`. Only `wiki/` crosses the Obsidian sync boundary; `processed/` is engine-internal.
+**Path A — use when `processed/<concept>.md` exists:** Verify the file exists, load `.llmwiki/staleness.json`, promote `processed/→wiki/`, update the ledger, flip cascade backlinks, detect stubs and orphans. Regenerate `wiki/index.md` and append to `wiki/log.md`. Lint — auto-fix index consistency, broken `[[wikilinks]]`, and See-Also sections; report conflicts, orphans, and outdated refs. Only `wiki/` crosses the Obsidian sync boundary; `processed/` is internal.
 
 NOTE: Delete `.llmwiki/staleness.json` to force a full rebuild — every page resets to DIRTY.
+
+**Path B (human authoring) — use when you have only a topic + terms, no compile output:** Ask for topic and term list. Resolve the target folder from `vault/.oms/taxonomy.yaml`. Apply the admission gate: coined/proper terms (only ever mean one specific technical thing) → standalone note; general nouns (meaning shifts by domain) → `## Term` section inside the hub note only. K8s example: `Pod`, `Service`, `Deployment`, `Ingress` → hub sections; `ReplicaSet`, `StatefulSet`, `DaemonSet`, `CronJob` → standalone notes. Deduplicate via MCP `write` (`mode: "create"`) — if the note already exists, reuse the `[[wikilink]]`. Commit coined-term notes first (definition + `## See Also` back-link to hub), then commit the hub/MOC note (general-noun sections + `## See Also` links). Run `oms doctor` (non-blocking, exits 0). Writes to vault taxonomy folders — never to `wiki/`.

package/adapters/hermes/skills/write/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: write
+description: Write a vault note through the Oh My Second Brain kernel contract.
+---
+
+# write
+
+Call MCP `write`. Do not use host Write/Edit for vault `.md` files.
+
+`mode` is `create`, `append`, or `update`. The kernel owns `.oms` and returns `ask`, `inbox`, `written`, or `rejected`.

package/core/AGENTS.md

@@ -46,6 +46,7 @@ A **field** is one frontmatter key — the smallest unit of convention. Each fie
 | `intent`   | Semantic purpose: *what this field is FOR.* |
 | `normalize` | Optional: `kebab`, `lower`, or `trim` — applied at validation. |
 | `immutable` | Advisory: once written, should not change (v0: no-op, forward-compat). |
+| `enum` | Optional closed vocabulary for string fields; values outside it are lint violations. |
 
 Users grow their convention field-by-field. There is no mandatory field list.
 
@@ -77,7 +78,7 @@ folders:
     concept: inbox
 ```
 
-A folder may bind to one concept, multiple concepts (list), or `null` (not yet assigned).
+A folder may bind to one concept, multiple concepts (list), or `null` (not yet assigned). A folder binding may set `agentWritable: true`; paired with `routingLawStrict: true`, notes in that folder must carry `created_by`. Top-level `exclude` entries are vault-relative globs skipped by audit/lint scans.
 
 ---
 
@@ -105,6 +106,7 @@ Oh My Second Brain enforces what the user declared; it does not touch anything e
 ## Quick Reference for Host Agents
 
 - To understand a note: look up its folder in the taxonomy → read the `concept.intent`.
-- To validate frontmatter: load the concept's `fields`; check `required` + `type`.
+- To validate frontmatter: load the concept's `fields`; check `required`, `type`, and any `enum`.
 - To retrieve knowledge: apply the relevant `lens` to surface the fields that matter.
+- To audit a vault: honor taxonomy `exclude` globs and routing-law flags.
 - When in doubt, preserve: `additionalProperties: preserve` means unknown keys are safe.

package/core/agents/librarian.md

@@ -21,7 +21,8 @@ It reads the convention first, then acts.
 2. **Folder resolution** — look up the correct target folder from `vault/.oms/taxonomy.yaml` based on the matched concept.
 3. **Frontmatter construction** — fill every `required: true` field; fill known optional fields; leave undeclared fields untouched.
 4. **Note creation** — write the file at the resolved path; use the concept's naming convention (default: `YYYY-MM-DD-<slug>.md`).
-5. **Post-capture validation** — run `npx oh-my-second-brain doctor` (non-blocking) to confirm the new note is clean.
+5. **Write through the kernel** — call MCP `write`. Do not use host Write/Edit for vault `.md` files.
+6. **Post-write validation** — run `npx oh-my-second-brain doctor` (non-blocking) to confirm the new note is clean.
 
 ## Decision rules
 
@@ -40,4 +41,4 @@ It reads the convention first, then acts.
 
 ## Skill
 
-Invoke via the `capture` skill: `core/skills/capture/SKILL.md`.
+Invoke via the `write` skill: `core/skills/write/SKILL.md`.

package/core/ontology/concepts/term.yaml

@@ -0,0 +1,12 @@
+concept: term
+intent: "A named unit of vocabulary the vault defines once and links to everywhere else."
+folder: terms
+fields:
+  - name: title
+    type: string
+    required: true
+    intent: "The canonical name of the term; the wikilink target other notes point at."
+  - name: aliases
+    type: list
+    required: false
+    intent: "Alternative surface forms and synonyms that should link back to this term."

package/core/ontology/taxonomy.yaml

@@ -9,3 +9,6 @@ folders:
   inbox:
     intent: "Raw unprocessed captures awaiting triage; nothing required yet."
     concept: inbox
+  terms:
+    intent: "Defined vocabulary the vault links to from other notes."
+    concept: term