oh-my-second-brain 0.18.3 → 0.19.0

package/README.md

@@ -1,90 +1,271 @@
-# Oh My Second Brain
+<p align="center">
+  <img src="./assets/readme/hero.svg" alt="Oh My Second Brain. A quiet constellation of connected thoughts." width="100%" />
+</p>
+
+<h1 align="center">Oh My Second Brain</h1>
+
+<p align="center">
+  <strong>A constellation of knowledge, still yours.</strong><br />
+  A user-owned knowledge and convention layer for Obsidian, Markdown, and AI agents.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/oh-my-second-brain"><img src="https://img.shields.io/npm/v/oh-my-second-brain?style=flat-square&amp;color=8b9daa&amp;label=npm" alt="npm version" /></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%E2%89%A520-80b89b?style=flat-square" alt="Node.js 20 or later" /></a>
+  <a href="#mcp-tools--integrations"><img src="https://img.shields.io/badge/MCP-4_tools-97a8b1?style=flat-square" alt="4 MCP tools" /></a>
+  <a href="https://github.com/GoBeromsu/oh-my-second-brain/blob/main/package.json"><img src="https://img.shields.io/badge/license-MIT-d7c7a8?style=flat-square" alt="Package license: MIT" /></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start"><strong>Quick start</strong></a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#documentation">Documentation</a> ·
+  <a href="https://github.com/GoBeromsu/oh-my-second-brain/releases">Releases</a> ·
+  <a href="https://github.com/GoBeromsu/oh-my-second-brain/blob/main/README.ko.md">한국어</a>
+</p>
+
+---
+
+Your vault already holds ideas, decisions, and things you learned. **OMS helps your agents find that knowledge and write within the conventions you defined.** No new note format. No prescribed folder system. No handover of your knowledge to a single host.
+
+Obsidian stays the command center. Your notes stay plain Markdown, readable and editable even when OMS is not running. Connect Claude Code, Codex, or Hermes to the same vault through their host integrations.
+
+## Why OMS?
+
+<table>
+<tr>
+<td width="50%" valign="top">
+<h3>Recall what you already know</h3>
+Search your existing notes with lexical retrieval. Choose vector, HyDE, query expansion, or reranking explicitly when you need them.
+</td>
+<td width="50%" valign="top">
+<h3>Your vault, your vocabulary</h3>
+Define the meaning of folders, properties, and templates. OMS records your conventions instead of shipping a system you have to adopt.
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<h3>Give agents a shared contract</h3>
+Seal your vault conventions through setup. Supported write paths check the whole note against that contract before saving it.
+</td>
+<td width="50%" valign="top">
+<h3>Keep the files you own</h3>
+Keep using your Markdown notes and templates. Setup does not rewrite them, and the sealed contract lives outside the vault.
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<h3>Connect across hosts</h3>
+Use native integrations for Claude Code, Codex, and Hermes, with four MCP tools and six shared workflow skills.
+</td>
+<td width="50%" valign="top">
+<h3>Inspect, don't guess</h3>
+Check contract state, audit notes, inspect indexes, and review wikilink suggestions. Search and `doctor status` stay read-only.
+</td>
+</tr>
+</table>
+
+## Quick start
+
+**Requires Node.js 20 or later and an existing Obsidian or Markdown vault.** Replace `/path/to/vault` with your vault's absolute path.
+
+### 1. Install
 
-Oh My Second Brain (`oms`) connects an existing Obsidian or Markdown vault to AI hosts without taking ownership of its notes. The vault remains plain Markdown. Obsidian stays the command center: the notes are still files a person can read and edit when OMS is not running. OMS does not invent the meaning of a property, a folder, or a heading.
-
-## Vault contract
+```bash
+npm install -g oh-my-second-brain
+oms --help
+```
 
-Meaning stays with the user. The user seals the vault's contract once, in an interactive `oms setup` run at a terminal. The interview covers three parts together: folders (what each folder means and what may be placed there), the property pool (each property's type and intent), and templates (what each template in the template folder declares). The product hardcodes no property names, folders, or personas, and it has no Inbox fallback.
+### 2. Define your vault's conventions
 
-The sealed contract lives outside the vault, under `~/.oms/vaults/<vault-id>/`. The only OMS file inside the vault is `.oms/settings.json`, which holds `version`, `vaultId`, `templateFolder`, `embedding`, and `agentRepair`. Any other entry in `.oms/` is reported by `oms contract doctor` as an unexpected control file and is otherwise ignored. `.obsidian/types.json` is a read-only observation and never overrides the seal.
+Run setup in your terminal. The interview covers folders, properties, and templates, then seals the contract. Existing notes are not modified.
 
-A template stays the user's own Markdown file in `templateFolder`. Sealing records what it declares; OMS never rewrites, copies, or applies it. `oms contract status` reports each sealed template as `active`, `drift`, or `missing` against the live file. A drifted template is reported, never re-sealed silently; the user re-seals it with `oms setup`. OMS does not parse or execute Templater, JavaScript, or a private token language.
+```bash
+oms setup --vault /path/to/vault
+oms setup status --vault /path/to/vault
+```
 
-The agent writes notes. One judge decides every write against the seal. A denied write leaves the file unchanged and returns only `{field, kind}` violations and one guidance command, never a rule value, a store path, or the contract body. A vault with no seal on this machine is not judged. When this machine holds seal evidence that no longer matches the vault, writes are refused as `contract-unreadable` until the user runs `oms setup` again. OMS has no completion call and no reviewer conversation: an allowed write means the note fits the sealed structure, not that it is worth keeping.
+### 3. Connect your agent
 
-The vault contract is recorded in ADR-007 (`docs/decisions/` in the source repository), which replaces the former ADR-013 through ADR-016. [ACKNOWLEDGMENTS](./ACKNOWLEDGMENTS.md) credits Ouroboros and Gajae Code's deep-interview as design ideas. Those credits are not a copied runtime and not a research result. Diagrams in this repository are explanatory sketches. These pages record the approved architecture. They are not a host-smoke result and not a product-gate pass.
+Install the integration for the host you use:
 
-The authority model is in [architecture](./docs/architecture.md). Vault files are in [conventions](./docs/conventions.md). Leaves are in [the CLI map](./docs/cli-map.md).
+```bash
+oms setup host install --runtime claude --vault /path/to/vault --yes
+```
 
-## Setup
+Replace `claude` with `codex` or `hermes`; use `all` to install all three. Host integration is optional if you only need the CLI. See the [installation guide](./docs/install.md) for Hermes profiles, model setup, and removal.
 
-`oms setup` is the same command as `oms contract setup`. It interviews the whole vault and seals the contract. It writes only `.oms/settings.json` inside the vault and never modifies notes. The interactive interview refuses to run without a terminal or under `OMS_NON_INTERACTIVE=1`. An agent seals only through the `setup` skill: `oms setup --questions` prints the questions, the agent asks the owner each one, and `oms setup --answers <file|->` seals a first or stricter contract. A reseal that loosens is refused there and left to the owner's terminal. Run it again at any time to re-seal.
+### 4. Put your knowledge to work
 
 ```bash
-oms setup --vault /path/to/vault
-oms contract status --vault /path/to/vault
+# Build the derived search index explicitly.
+oms doctor sync-embeddings --mode sync --vault /path/to/vault
+
+# Start with lexical search. No vector model required.
+oms search "project decisions" --vault /path/to/vault
 ```
 
-`oms contract extract --template <path>` shows what one template declares without printing values. `oms contract doctor` diagnoses the seal, stale locks, orphaned generations, unexpected control files, and hook transport failures; `--fix` only re-indexes a moved or unindexed vault. Any other broken seal is recovered by running `oms setup` again. Model lifecycle stands alone as `oms model install|select|waive|status`.
+**Try asking your connected agent:**
 
-## CLI
+> Find my notes about this project and surface the decisions I have already made.
 
-```text
-oms bridge add|remove|status                   Manage repository-to-vault target bridges
-oms contract setup|extract|status|doctor       Seal the vault contract, or inspect and diagnose it
-oms graph build|status                         Build or inspect the note graph
-oms hook pre                                   Judge a Claude write against the vault contract
-oms host install|remove|sync|status            Manage host assets and MCP registrations
-oms index sync|embed|repair|status|clean       Manage derived search state
-oms link suggest|check                         Suggest or check note wikilinks
-oms model install|select|waive|status          Manage local model selection
-oms note audit|get                             Audit notes against the contract, or read them
-oms package check|update                       Check or update the OMS package
-oms search query|context                       Run an explicit query or retrieve structured context
-oms serve mcp|http                             Start the stdio MCP or local HTTP server
-oms setup                                      Interview the vault and seal its contract
-oms status                                     Show the read-only aggregate status
-```
+> Check this note against my vault contract and show me what needs attention.
 
-`oh-my-second-brain` is the full command; `oms` is its short alias. These fourteen families, the seven skills, and the five MCP tools are three different sets. The leaf map is [the CLI map](./docs/cli-map.md).
+> Suggest related notes I could link to, without changing any files.
 
-### Help contract
+These are example requests, not captured run results. Available workflows and write enforcement differ by host as described below.
 
-Every recognized command accepts `--help` and `-h`, exits 0, and performs no side effects. An unknown command combined with `--help` exits 1.
+## How it works
 
-A plain `oms search query <text>` is lexical-only. `--vec` and `--hyde` select their respective channels; `--expand` explicitly enables G004 expansion, `--max-queries` accepts an integer from 1 through 32, and `--rerank` is opt-in. `oms search context` is the separate structured-context surface. Embedding is `oms index embed`; sync and repair are distinct index modes. `oms index status --view status|collections|contexts` preserves all three read-only views, while `oms index clean` removes eligible derived state.
+**You define the meaning. Your agent writes the content. OMS checks the structure.**
 
-Lexical, vector, HyDE, and typed-axis queries still include notes that would fail the contract. A missing or damaged contract does not stop search. Vector search requires a complete `OMS_EMBEDDING_PROVIDER`/`OMS_EMBEDDING_MODEL` pair. HyDE also requires `OMS_GENERATE_PROVIDER`/`OMS_GENERATE_MODEL`. Reranking requires `OMS_RERANK_PROVIDER`/`OMS_RERANK_MODEL`. Missing, incomplete, or uninstalled selections fail loudly. G004 expansion is an explicit available capability; it makes no replacement, parity, or outperformance claim.
+| Layer | What belongs there |
+| :--- | :--- |
+| **Your vault** | Your Markdown notes, folders, properties, and original templates. Obsidian remains the command center. |
+| **Your contract** | The conventions confirmed through `oms setup`, sealed outside the vault under `~/.oms/vaults/<vault-id>/`. |
+| **OMS** | Retrieval, contract judgment on supported writes, link inspection, and explicit index maintenance. |
+| **Your agent** | Reads context, composes notes, and uses the appropriate host workflow. You and the agent decide what is worth keeping. |
 
-`oms note audit` judges existing notes against the seal and reports `{path, field, kind}` entries; it never rewrites a note. Create, append, update, and backfill are retired note operations. Link apply is not an operation. There is no note renderer or compatibility path for retired operations.
+> [!IMPORTANT]
+> **Set up the contract before relying on write checks.** A vault with no seal on this machine is not contract-judged; general path and input safeguards still apply. A contract violation leaves the file unchanged. An allowed write means structural compliance, not factual accuracy or quality approval.
 
-## MCP tools
+<details>
+<summary><strong>The vault contract, in detail</strong></summary>
 
-`oms serve mcp` exposes exactly five public tools:
+- **Meaning is user-owned.** The interview covers folders, the property pool, and templates together. OMS hardcodes no property names, folders, or personas and has no Inbox fallback.
+- **One control file inside the vault.** `.oms/settings.json` holds `version`, `vaultId`, `templateFolder`, `embedding`, and `agentRepair`. Other `.oms/` entries are ignored and reported as unexpected control files by `oms doctor contract`. `.obsidian/types.json` is a read-only observation, not an override of the seal.
+- **Templates stay yours.** OMS records what each template declares. It never rewrites or copies a template file, and does not parse or execute Templater, JavaScript, or a private token language. A write only fills what is mechanical in the note being written: `{{title}}`, `{{date}}` and `{{time}}` variables, date and datetime defaults on a new note, and the chosen template's missing headings. It never supplies a required value.
+- **Drift is visible.** `oms setup status` reports templates as `active`, `drift`, or `missing`. It never silently re-seals a changed template.
+- **One judge, bounded feedback.** Denied writes return `{field, kind}` violations and one guidance command, not rule values, store paths, or the contract body.
+- **Mismatched seal evidence blocks writes.** When this machine's evidence no longer matches the vault, writes fail with `contract-unreadable` until the owner runs `oms setup` again. A machine with no seal is a different case: its vault is not contract-judged.
 
-`write` · `search` · `link` · `status` · `doctor`
+See [architecture](./docs/architecture.md), [conventions](./docs/conventions.md), and [ADR-007](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/docs/decisions/ADR-007-vault-contract-ontology.md).
 
-The seven skills (`distill`, `doctor`, `link`, `search`, `setup`, `status`, `write`) are host workflows. `distill` and `setup` are tool-less; `setup` asks the owner each setup question and seals a first or stricter contract.
+</details>
 
-The five tools are a subset of those skills, and neither set is the fourteen CLI families. Detail capabilities remain `op` values under the five tools. Sealing has no MCP operation and no skill.
+<details>
+<summary><strong>Setup, template interpretation, and recovery</strong></summary>
 
-`write {path, content, template?}` judges the whole note and saves it only when it is allowed. `template` is optional and names the sealed template the note follows. `status` and every search operation are read-only. The `doctor` tool validates the seal, audits notes, and runs explicit index maintenance; it does not backfill notes. Claude's native Write, Edit, MultiEdit, and NotebookEdit inside the vault reach the same judge through `oms hook pre`; Codex and Hermes have no write hook, so their notes are judged only through MCP `write`.
+`oms setup` in a terminal runs the interactive interview and seals the contract. `oms interview` is the same terminal interview on its own command; it requires a terminal and refuses to run under `OMS_NON_INTERACTIVE=1`.
 
-## Install
+The `setup` skill asks the owner each question via `oms setup --questions` and submits answers with `oms setup --answers <file|->`. This path can seal a first or stricter contract; a loosening reseal stays with the owner's terminal. The MCP `interview` tool continues the interview across calls: `op: questions` is read-only, and `answer`, `confirm`, and `seal` record to the interview log on a verified target. It seals only the proposal the owner confirmed and never reclaims a stale seal lock.
 
-Node.js 20 or later is required.
+`oms setup extract --template <path>` returns a template source and its computed hash. The agent reads each template and submits its interpretation with `oms setup --interpretations <file>`. The owner confirms that interpretation before it drives the interview.
 
-```bash
-npm install -g oh-my-second-brain
-oms host install --runtime all --vault /path/to/vault --yes
+`oms doctor contract` diagnoses seal problems, stale locks, orphaned generations, unexpected control files, and hook transport failures. Its `--fix` only re-indexes a moved or unindexed vault. Other broken seals are recovered through `oms setup`.
+
+Model lifecycle is separate: `oms setup model install|select|waive|status`.
+
+</details>
+
+## MCP tools & integrations
+
+**One domain kernel, with host-native integrations.**
+
+`write` · `search` · `interview` · `doctor`
+
+| MCP tool | Purpose |
+| :--- | :--- |
+| `write` | Judge a whole note against the sealed contract and save an allowed write. |
+| `search` | Retrieve notes, structured context, or wikilink suggestions without changing the vault. |
+| `interview` | Continue the vault interview: list open questions, record answers, and seal only the proposal the owner confirmed. |
+| `doctor` | Read-only `status`; diagnose the contract, audit notes, check links, and run explicit index maintenance. |
+
+The six skills are `distill`, `doctor`, `interview`, `search`, `setup`, and `write`.
+
+`distill` and `setup` are tool-less workflows; sealing has no MCP operation. Detail capabilities use `op` values under the four tools. Tool annotations are per tool: only `search` is marked read-only, because `write` and the `doctor` repairs mutate and `interview` is kept conservative.
+
+| Host | Integration | Write checks |
+| :--- | :--- | :--- |
+| **Claude Code** | Native plugin assets, skills, and MCP | MCP `write` plus `oms hook pre` for native Write, Edit, MultiEdit, and NotebookEdit. |
+| **Codex** | Native plugin assets, guidance, and MCP | MCP `write`; no native write hook. |
+| **Hermes** | Profile-scoped skills, guidance, and MCP | MCP `write`; no native write hook. |
+
+> [!NOTE]
+> Claude's hook rejects a judged contract violation, but allows the write with a warning if the hook itself cannot run. Native file writes in Codex and Hermes do not pass through the OMS judge. This is not a filesystem-wide sandbox.
+
+For Gajae-Code, install the marketplace plugin with `gjc plugin install oms@oms`; it discovers the six skills at the package-root `skills/` path. See [host assets](./docs/adapters.md) for integration details.
+
+<details>
+<summary><strong>Host maintenance and vault targeting</strong></summary>
+
+Host installation stores a signed maintenance pointer at `${XDG_CONFIG_HOME:-~/.config}/oms/vault.json` and stamps `oms serve mcp --vault /path/to/vault` into managed host entries. Only `oms setup host install|remove|sync|status` use that pointer to maintain integrations.
+
+Runtime target resolution does not read it. Precedence is **explicit target → local vault controls → bridge → `OMS_VAULT` → current directory**. The current-directory fallback is read-only: sealing, note writes, and derived-state repair cannot use it.
+
+`oms setup package update` updates the package only. Run `oms setup host sync` separately to synchronize installed host assets. See [verified targets](./docs/verified-target.md).
+
+</details>
+
+## Search your way
+
+**Lexical by default. Additional retrieval channels by choice.** Search includes notes that fail the contract; a missing or damaged contract does not stop retrieval.
+
+| Capability | How to select it | Requirement |
+| :--- | :--- | :--- |
+| Lexical search | `oms search <text>` | No vector model required. |
+| Vector search | `--vec <text>` | Complete `OMS_EMBEDDING_PROVIDER` / `OMS_EMBEDDING_MODEL` pair. |
+| HyDE | `--hyde <text>` | Embedding pair plus `OMS_GENERATE_PROVIDER` / `OMS_GENERATE_MODEL`. |
+| Query expansion | `--expand` | Explicit G004 expansion; `--max-queries` accepts 1–32. |
+| Reranking | `--rerank` | Complete `OMS_RERANK_PROVIDER` / `OMS_RERANK_MODEL` pair. |
+
+Missing, incomplete, or uninstalled model selections fail loudly rather than silently switching to another capability. These are available retrieval options, not a claim of parity or superiority over another engine.
+
+Use `oms search --context` for structured context and `oms search --path <note>` to read one note exactly. Indexing is explicit: `oms doctor sync-embeddings --mode sync|embed|repair` selects one of three distinct modes. See [the CLI map](./docs/cli-map.md) for all operations.
+
+## CLI reference
+
+`oms` is the short alias of `oh-my-second-brain`, with seven CLI families. 0.19 replaced the 0.18 families; see the [0.19 migration guide](./docs/migration-0.19.md).
+
+```text
+oms search <text>                               Search notes; lexical by default
+oms search --path|--context|--link              Read one note, gather context, or suggest links
+oms interview                                   Interview the vault owner in a terminal and seal
+oms write <path>                                Save a note from stdin when the contract allows it
+oms setup                                       Seal the contract (--questions/--answers for agents)
+oms setup extract|status                        Show a template source or the contract posture
+oms setup host install|remove|sync|status       Manage host assets and MCP registrations
+oms setup model install|select|waive|status     Manage local model selection
+oms setup package check|update                  Check or update the OMS package
+oms setup bridge add|remove|status              Manage repository-to-vault bridges
+oms doctor status                               Show read-only vault health
+oms doctor contract|audit|link-check            Diagnose the contract, notes, or wikilinks
+oms doctor sync-embeddings|cleanup|build-graph  Maintain the derived index and graph
+oms serve mcp|http                              Start the MCP or local HTTP server
+oms hook pre                                    Judge a Claude write against the contract
 ```
 
-For Gajae-Code, install the npm package as a marketplace plugin: `gjc plugin install oms@oms`. GJC discovers the six OMS skills at the package-root `skills/` convention path.
+<details>
+<summary><strong>Command behavior and removed commands</strong></summary>
+
+Every recognized command accepts `--help` and `-h`, exits 0, and has no side effects. An unknown command combined with `--help` exits 1. A family removed in 0.19 exits 1 and names its replacement.
+
+`oms doctor audit` reports `{path, field, kind}` entries without rewriting notes. Notes are written as whole content through `oms write <path> < note.md` or MCP `write {path, content, template?, ifMatch?, check?}`; both take the same write pipeline, and `template` optionally names the sealed template being followed. Overwriting an existing note needs `ifMatch` (`--if-match`) with its current `sha256:` revision; `check` (`--check`) judges without touching disk. An allowed write returns a receipt with the new revision and updates the keyword index of an existing engine store in the same call, so the note is searchable at once. There is no completion call or reviewer conversation.
+
+`oms doctor cleanup` removes eligible derived state. `oms doctor build-graph` rebuilds the note graph.
+
+Note `create`, `append`, `update`, and `backfill` are retired operations. There is no `link apply`, note renderer, or compatibility path for those retired operations.
+
+</details>
+
+## Documentation
+
+| Start here | Go deeper |
+| :--- | :--- |
+| [Installation](./docs/install.md): install, setup, models, removal | [Architecture](./docs/architecture.md): authority and domain boundaries |
+| [Vault conventions](./docs/conventions.md): settings and sealed contracts | [CLI map](./docs/cli-map.md): command and MCP operation mapping |
+| [Host integrations](./docs/adapters.md): Claude Code, Codex, Hermes | [Verified targets](./docs/verified-target.md): safe vault resolution |
+| [Releases](https://github.com/GoBeromsu/oh-my-second-brain/releases): published versions | [Changelog](./CHANGELOG.md): what changed and why |
+
+## Contributing & credits
 
-Host installation records the canonical vault in `${XDG_CONFIG_HOME:-~/.config}/oms/vault.json` and stamps `oms serve mcp --vault /path/to/vault` into each managed host entry. `oms host install|remove|sync|status` use that signed pointer only to maintain host integrations. `oms package update` updates the package but never syncs hosts implicitly; run `oms host sync` separately.
+Contributions are welcome. Start with the [contributing guide](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/CONTRIBUTING.md), or [open an issue](https://github.com/GoBeromsu/oh-my-second-brain/issues) with a reproducible problem or a focused proposal.
 
-Runtime target resolution never reads the host-maintenance pointer. Its precedence is explicit target, local vault controls, bridge, `OMS_VAULT`, then the current directory only as a safe read-only fallback. Sealing, note writes, and derived-state repair cannot use that fallback.
+[ACKNOWLEDGMENTS](./ACKNOWLEDGMENTS.md) records design influences, including Ouroboros and Gajae Code's deep-interview. Those credits describe ideas, not a copied runtime or a research result. The original constellation illustration is inspired by the connected-note landscape at [beomsukoh.com](https://beomsukoh.com/). Illustrations explain concepts; they are not product screenshots, host-smoke evidence, or product-gate results.
 
-`OMS_VAULT` is the supported environment fallback when no explicit, local, or bridge target exists.
+---
 
-See [installation](./docs/install.md), [architecture](./docs/architecture.md), [conventions](./docs/conventions.md), [the CLI map](./docs/cli-map.md), [host assets](./docs/adapters.md), and [verified targets](./docs/verified-target.md).
+<p align="center">
+  <strong>Your notes stay yours.</strong><br />
+  Built by <a href="https://github.com/GoBeromsu">Beomsu Koh</a> · Package licensed MIT
+</p>

package/assets/claude/CLAUDE.md

@@ -9,7 +9,7 @@ outside the vault, and it is not yours to read.
 
 ## Writing
 
-Write vault notes with MCP `write {path, content, template?}` (the `/write`
+Write vault notes with MCP `write {path, content, template?, ifMatch?, check?}` (the `/write`
 skill). A denial gives only `{field, kind}` and a guidance command. Never ask
 about or guess the contract's location or values.
 
@@ -33,12 +33,17 @@ about or guess the contract's location or values.
 - `/search` is read-only across lexical, vector, HyDE, and axis retrieval. It
   also returns notes that would fail the contract. It never writes or repairs.
   Unavailable backends fail loudly and are never replaced with a fake match.
-- `/status` reads health. `oms contract status` and `oms contract doctor` are
-  for diagnosis. They report the seal's posture and template drift without
-  printing any value.
+- `/doctor status` reads health, and `/doctor link-check` checks a note's
+  wikilinks; both are read-only. `oms doctor status`, `oms setup status`, and
+  `oms doctor contract` are for diagnosis. They report the seal's posture and
+  template drift without printing any value.
+- `/search link` suggests wikilinks for a note; you apply only the ones the
+  user accepts.
+- `/interview` continues the vault interview: it lists open questions, records
+  the user's answers, and seals only a proposal the user confirmed.
 - `/doctor` runs explicit, supported index and control repairs. It never
   backfills notes. A broken or missing seal is fixed by the user running
   `oms setup`.
 
-Seven skills share five MCP tools: `write`, `search`, `link`, `distill`,
-`setup`, `status`, and `doctor`. `distill` and `setup` have no tool.
+Six skills share four MCP tools: `write`, `search`, `interview`, `distill`,
+`setup`, and `doctor`. `distill` and `setup` have no tool.

package/assets/claude/hooks/oms-guard.mjs

@@ -14,7 +14,7 @@
  *
  * The judge's deny is forwarded as is. When the judge cannot be reached (spawn failure,
  * non-zero exit, timeout, malformed output) the write is allowed with one stderr line and
- * the failure kind is recorded in `~/.oms/guard-events.jsonl` for `oms contract doctor`.
+ * the failure kind is recorded in `~/.oms/guard-events.jsonl` for `oms doctor contract`.
  * A payload that cannot be parsed (or exceeds the stdin cap) is denied when its raw text
  * names a configured vault or `~/.oms`, and otherwise allowed with one stderr line.
  *
@@ -43,10 +43,10 @@ const WRITE_TOOLS = new Set(["write", "edit", "multiedit", "notebookedit"]);
 const READ_TOOLS = new Set(["read", "grep", "glob"]);
 
 const ALLOW = JSON.stringify({ continue: true, suppressOutput: true });
-const CONTROL_PATH_REASON = `[oms] write denied: ${JSON.stringify([{ field: "path", kind: "control-path" }])} Run: oms status`;
-const SEARCH_REASON = `[oms] write denied: ${JSON.stringify([{ field: "path", kind: "control-path" }])} Narrow the search path or glob so it cannot reach ~/.oms. Run: oms status`;
-const UNSAFE_PATH_REASON = `[oms] write denied: ${JSON.stringify([{ field: "path", kind: "path-unsafe" }])} Run: oms status`;
-const INPUT_REASON = `[oms] write denied: ${JSON.stringify([{ field: "input", kind: "unsupported-input" }])} Run: oms host sync`;
+const CONTROL_PATH_REASON = `[oms] write denied: ${JSON.stringify([{ field: "path", kind: "control-path" }])} Run: oms doctor status`;
+const SEARCH_REASON = `[oms] write denied: ${JSON.stringify([{ field: "path", kind: "control-path" }])} Narrow the search path or glob so it cannot reach ~/.oms. Run: oms doctor status`;
+const UNSAFE_PATH_REASON = `[oms] write denied: ${JSON.stringify([{ field: "path", kind: "path-unsafe" }])} Run: oms doctor status`;
+const INPUT_REASON = `[oms] write denied: ${JSON.stringify([{ field: "input", kind: "unsupported-input" }])} Run: oms setup host sync`;
 
 /**
  * Prefer the co-located dist entry via `node <dist>` so the guard does not depend on the
@@ -172,7 +172,7 @@ function recordGuardEvent(kind) {
 function transportFailure(kind) {
   recordGuardEvent(kind);
   if (TRANSPORT_FAILURE_POLICY === "allow-warn") {
-    process.stderr.write("[oms] guard could not reach the judge; write allowed. Run: oms contract doctor\n");
+    process.stderr.write("[oms] guard could not reach the judge; write allowed. Run: oms doctor contract\n");
     allow();
   }
 }

package/assets/codex/AGENTS.md

@@ -14,7 +14,7 @@ the only OMS file.
 
 ## Writing
 
-Write vault notes with MCP `write {path, content, template?}` (`$oms-write`). A
+Write vault notes with MCP `write {path, content, template?, ifMatch?, check?}` (`$oms-write`). A
 denial gives only `{field, kind}` and a guidance command. Never ask about or
 guess the contract's location or values.
 
@@ -35,12 +35,13 @@ guess the contract's location or values.
   It also returns notes that would fail the contract. It never writes or
   repairs. Unavailable backends fail loudly and are never replaced with a fake
   match.
-- `$oms-status` reads health. `oms contract status` and `oms contract doctor`
+- `$oms-doctor` reads health (`op: status`) and checks wikilinks
+  (`op: link-check`). `oms setup status` and `oms doctor contract`
   are for diagnosis. They report the seal's posture and template drift without
   printing any value.
 - `$oms-doctor` runs explicit, supported index and control repairs. It never
   backfills notes. A broken or missing seal is fixed by the user running
   `oms setup`.
 
-Codex installs seven shared skills (`write`, `search`, `link`, `distill`,
-`setup`, `status`, `doctor`) backed by the five public MCP tools.
+Codex installs six shared skills (`write`, `search`, `interview`, `distill`,
+`setup`, `doctor`) backed by the four public MCP tools.

package/assets/codex/rules/oms.md

@@ -8,16 +8,16 @@ sealed contract is not yours to read.
 | User intent | Preferred surface |
 |---|---|
 | seal or change the vault contract | ask the user to run `oms setup` in a terminal |
-| install host integration | `oms host install --runtime codex --vault <path> --yes`, only when authorized |
-| write a note | `$oms-write`: MCP `write {path, content, template?}` |
+| install host integration | `oms setup host install --runtime codex --vault <path> --yes`, only when authorized |
+| write a note | `$oms-write`: MCP `write {path, content, template?, ifMatch?, check?}` |
 | retrieve knowledge | `$oms-search`; read-only, with no validation or repair side effects |
-| inspect health | `$oms-status`; `oms contract status` for the seal and template drift |
-| diagnose the seal | `oms contract doctor` |
+| inspect health | `$oms-doctor` (`op: status`); `oms setup status` for the seal and template drift |
+| diagnose the seal | `oms doctor contract` |
 | explicit supported control/index repair | `$oms-doctor` |
 
 ## Boundaries
 
-- Write vault notes with MCP `write {path, content, template?}`. A denial gives
+- Write vault notes with MCP `write {path, content, template?, ifMatch?, check?}`. A denial gives
   only `{field, kind}` and a guidance command. Never ask about or guess the
   contract's location or values.
 - A denied write leaves the file unchanged. Fix the content from what the user
@@ -25,7 +25,7 @@ sealed contract is not yours to read.
 - Codex has no write hook. Notes written with host file tools are not judged.
 - `~/.oms` is off-limits. Inside the vault, `.oms/settings.json` is the only
   OMS file.
-- Search and status stay read-only. Notes that would fail the contract remain
+- Search, interview, and `doctor` status stay read-only. Notes that would fail the contract remain
   searchable. Keep the requested backend's failure semantics, with no
   substitutes.
 - Uninstall removes only the integration assets OMS owns, never vault notes or

package/assets/hermes/README.md

@@ -1,17 +1,17 @@
 # Oh My Second Brain Hermes Adapter
 
-Installed by `oms host install --runtime hermes` into:
+Installed by `oms setup host install --runtime hermes` into:
 
 - `~/.hermes/skills/knowledge-management/oms/`
 - `~/.hermes/config.yaml` as `mcp_servers.oms`
 
-The shared skill bundle contains seven skills. Hermes resolves skills by bare
+The shared skill bundle contains six skills. Hermes resolves skills by bare
 name across every installed bundle, so the installer copies them with an `oms-`
 prefix in both the directory and the frontmatter `name`: `oms-write`,
-`oms-search`, `oms-link`, `oms-distill`, `oms-setup`, `oms-status`, and
+`oms-search`, `oms-interview`, `oms-distill`, `oms-setup`, and
 `oms-doctor`. The shared sources and the other hosts keep the unprefixed names.
 `SKILL_CAPABILITY_GUIDE.md` in the same directory maps each skill to its MCP
-tool or marks it as an agent recipe. Runtime operations use the five MCP tools
+tool or marks it as an agent recipe. Runtime operations use the four MCP tools
 through `oms serve mcp`.
 
 Hermes takes a skill's category from the first path segment only, so these
@@ -19,7 +19,7 @@ skills are listed under `knowledge-management`. Filter with
 `skills_list(category="knowledge-management")`; the category
 `knowledge-management/oms` matches nothing.
 
-Agents write notes with MCP `write {path, content, template?}`. OMS judges each
+Agents write notes with MCP `write {path, content, template?, ifMatch?, check?}`. OMS judges each
 note against the contract the user sealed with `oms setup`. A denial returns
 only `{field, kind}` and a guidance command. There is no completion operation
 and no reviewer protocol, so deciding whether a note is worth keeping and
@@ -28,4 +28,4 @@ repairing it belong to the user and the agent. See the [Hermes role guidance](./
 The adapter installs no model provider, no reviewer role, and no daemon.
 Installing assets proves only their presence, not that the host loaded them.
 
-Unlike Claude Code (`claude plugin install`), Hermes exposes no native marketplace or plugin-update command, so this adapter stays OMS-managed. `oms package update` updates OMS; `oms host sync --runtime hermes` separately refreshes registrations. Neither upgrades Hermes. `mcp_servers.oms` is edited surgically, leaving the rest of `~/.hermes/config.yaml` — including comments and key ordering — untouched. Existing profiles retain their own configuration and registration scope.
+Unlike Claude Code (`claude plugin install`), Hermes exposes no native marketplace or plugin-update command, so this adapter stays OMS-managed. `oms setup package update` updates OMS; `oms setup host sync --runtime hermes` separately refreshes registrations. Neither upgrades Hermes. `mcp_servers.oms` is edited surgically, leaving the rest of `~/.hermes/config.yaml` — including comments and key ordering — untouched. Existing profiles retain their own configuration and registration scope.

package/assets/hermes/SOUL.md

@@ -10,7 +10,7 @@ the only OMS file.
 
 ## Writing
 
-Write vault notes with MCP `write {path, content, template?}` (the `write`
+Write vault notes with MCP `write {path, content, template?, ifMatch?, check?}` (the `write`
 skill). A denial gives only `{field, kind}` and a guidance command. Never ask
 about or guess the contract's location or values.
 
@@ -30,17 +30,18 @@ about or guess the contract's location or values.
 - `search` is read-only across lexical, vector, HyDE, and axis retrieval. It
   also returns notes that would fail the contract. It never writes or repairs.
   Unavailable backends fail loudly.
-- `status` reads health. `oms contract status` and `oms contract doctor` are
-  for diagnosis. They report the seal's posture and template drift without
+- `doctor` with `op: status` reads health and `op: link-check` checks a
+  note's wikilinks; both are read-only. `oms setup status` and
+  `oms doctor contract` are for diagnosis. They report the seal's posture and template drift without
   printing any value.
 - `doctor` runs only explicit, supported repairs. It never rewrites ordinary
   notes or backfills guessed values. A broken or missing seal is fixed by the
   user running `oms setup`.
 
-Hermes uses the seven shared skills under an `oms-` prefix (`oms-write`,
-`oms-search`, `oms-link`, `oms-distill`, `oms-setup`, `oms-status`,
-`oms-doctor`) so their names never collide with another bundle's `setup` or
-`status`. Call them by the prefixed name. They are backed by the five public
+Hermes uses the six shared skills under an `oms-` prefix (`oms-write`,
+`oms-search`, `oms-interview`, `oms-distill`, `oms-setup`, `oms-doctor`) so
+their names never collide with another bundle's `setup` or `doctor`. Call them
+by the prefixed name. They are backed by the four public
 MCP tools; `SKILL_CAPABILITY_GUIDE.md` beside them maps each skill to its tool.
 Their skill category is `knowledge-management`, so list them with
 `skills_list(category="knowledge-management")`.

package/assets/hermes-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults — Hermes skill bundle and MCP adapter.",
-  "_note": "oms host install writes ~/.hermes/config.yaml mcp_servers.oms and installs the seven shared skills, prefixed `oms-`, with provenance under ~/.hermes/skills/knowledge-management/oms/."
+  "_note": "oms setup host install writes ~/.hermes/config.yaml mcp_servers.oms and installs the six shared skills, prefixed `oms-`, with provenance under ~/.hermes/skills/knowledge-management/oms/."
 }