oh-my-second-brain 0.1.8 → 0.2.0

package/core/skills/compile/SKILL.md

@@ -1,54 +1,55 @@
 ---
 name: compile
 version: 0.1.0
-description: Stateless per-concept compile worker — takes a concept name, source materials, and graph context; returns a synthesized Markdown page body with SHA-incremental skip, nashsu 2-step CoT, atomicstrata 2-phase separation, lucasastorian cascade backlinks, and provenance-weighted synthesis context.
+description: Agent-guided concept compile — synthesize a concept wiki page from source materials with incremental skip, two-phase write separation, cascade backlinks, and provenance-weighted context.
 trigger: /compile
 tags: [compile, wiki, synthesis, sha, incremental, second-brain, oms]
 ---
 
 ## compile
 
-Compile a concept page from source materials using the OMS compile engine.
+Synthesize a concept page from source materials. There is no `oms compile` CLI
+and no TypeScript compile worker — follow this recipe as the agent.
 
 ### When to use
 
-Use `compile` when you need to synthesize a concept wiki page from one or more source materials. The worker skips recompile when material SHA is unchanged (incremental by default).
+Use `compile` when you need to synthesize a concept wiki page from one or more
+source materials. Skip rewrite when the material fingerprint is unchanged.
 
 ### Inputs
 
-- `concept` — human-readable concept name (used in LLM prompts)
-- `materials` — list of `{ path, text, grade }` items (grade resolved from folder->grade map)
-- `graph` — compile graph providing `getBacklinks(docPath)` (use `createNullGraph()` when unavailable)
-- `llm` — injected LLM provider (use `createDeterministicStub()` for offline/tests)
-- `dotLlmwiki` — absolute path to `.llmwiki/` dotfolder (SHA cache location)
+- `concept` — human-readable concept name (used in prompts)
+- `materials` — list of `{ path, text, grade }` items (grade from folder→grade map)
+- backlinks — wiki pages that already link to this concept (empty if unknown)
 - `conceptId` — stable cache key (vault-relative path recommended)
 
+Gather materials with MCP `oms_retrieve_context` or `oms_get_document`.
+
 ### Output
 
-Returns `CascadeResult`:
-- `body` — synthesized Markdown with `[[wikilinks]]` (empty string when SHA unchanged / skipped)
+- `body` — synthesized Markdown with `[[wikilinks]]` (empty when skipped)
 - `sha` — SHA-256 fingerprint of the input materials
 - `provenance` — grades of contributing materials
-- `affected_backlinks` — vault paths of wiki pages that link to this concept (for M3 staleness)
+- `affected_backlinks` — vault paths of wiki pages that link to this concept
 
 ### Recipe
 
-1. Run Phase A (`phaseA`) to load and grade all source materials (pure read, no vault mutation).
-2. Call `compile(opts)` with the Phase A materials, graph, llm, and cache path.
-3. Check `wasSkipped(result)` — if true, skip downstream processing.
-4. If not skipped, run Phase B (`phaseB`) to write the body to `processed/` tier.
-5. Pass `result.affected_backlinks` to the wiki collection owner (M3) to mark stale pages.
+1. **Phase A** — load and grade all source materials (pure read, no vault mutation).
+2. Fingerprint the materials. If `{dotLlmwiki}/sha-cache.json` already has the
+   same SHA for `conceptId`, skip the rest.
+3. **Phase B** — write the synthesized body to the `processed/` tier only.
+4. Pass `affected_backlinks` to the wiki skill so those pages can be marked stale.
 
 ### Phase constraints
 
 - Phase A and Phase B never overlap in one execution context.
 - Phase B writes to `processed/` ONLY — never to `wiki/` directly.
-- Promotion from `processed/` to `wiki/` is the M3 collection owner's responsibility.
+- Promotion from `processed/` to `wiki/` is the wiki skill's responsibility.
 
 ### Provenance weighting
 
 Materials are sorted authored > curated > external-raw in synthesis context.
-Authored materials are labelled `[AUTHORED — preserve individual voice]` in the LLM prompt.
+Authored materials are labelled `[AUTHORED — preserve individual voice]` in the prompt.
 
 ### SHA cache
 

package/core/skills/distill/SKILL.md

@@ -17,6 +17,7 @@ tags:
 # Distill
 
 Run adversarial absorption analysis on a target and produce a structured report.
+There is no TypeScript distill engine — follow this recipe as the agent.
 
 ## Usage
 
@@ -26,15 +27,15 @@ Run adversarial absorption analysis on a target and produce a structured report.
 
 ## Steps
 
-1. Load the target as inert read-only text via `prepareCleanRoom(target)`.
-   The target is NEVER executed — it is treated as data only.
-2. Snapshot system state SHA before analysis (`snapshotSha`).
-3. Run red-team adversarial analysis via `runAnalysis(spec, provider)`.
-   Inject an LLM provider for production; inject the stub for dry-runs.
-4. Generate the absorption report via `generateReport(result, targetName)`.
-   The report has exactly 3 sections: §1 Patterns, §2 Risks, §3 Attribution.
-5. Verify mutation-detector: SHA after must equal SHA before (`detectMutation`).
-   Throw if state was mutated — distill must be fully stateless.
+1. Load the target as inert read-only text. The target is NEVER executed — it
+   is treated as data only.
+2. Snapshot a content hash of the working tree (or target file) before analysis.
+3. Run red-team adversarial analysis. Use a real model for production; keep
+   the pass read-only.
+4. Generate the absorption report. The report has exactly 3 sections:
+   §1 Patterns, §2 Risks, §3 Attribution.
+5. Verify the hash after analysis equals the hash before. Stop if anything
+   was mutated — distill must be fully stateless.
 6. Return the report string. Write it only if the caller explicitly requests it.
    No vault write, no code mutation happens inside distill.
 
@@ -54,20 +55,8 @@ The report is the only output. It contains:
 
 ## Constraints
 
-- Standalone: does not import from `src/engine/compile/` or `src/engine/wiki/`.
+- Standalone: does not depend on compile or wiki.
 - Vault-agnostic: `OMS_VAULT` environment variable is NOT required.
-- Stateless: no daemon, no watcher, no `setInterval` (R2).
-- Clean-room: target content is inert text — never executed (R6).
+- Stateless: no daemon, no watcher, no `setInterval`.
+- Clean-room: target content is inert text — never executed.
 - No vault write occurs inside distill — the caller decides what to do with the report.
-
-## Provider injection
-
-Inject an `AnalyzerProvider` to control the LLM backend:
-
-```typescript
-import { createStubAnalyzerProvider } from "src/engine/distill/analyzer.js";
-// Deterministic stub — no network; use in tests and dry-runs.
-const provider = createStubAnalyzerProvider();
-```
-
-For production, wrap a real LLM client in the `AnalyzerProvider` interface.

package/core/skills/link/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: link
+version: 0.1.0
+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 notes that already exist, via oms linkify or oms_link_apply.
+trigger: /link
+tags: [link, wikilink, linkify, term, backlink, second-brain, oms]
+---
+
+## link
+
+Keep the vault interlinked. There is no autolink daemon — follow this recipe as
+the agent. Requires `OMS_VAULT` (or a resolved vault target).
+
+## Which path?
+
+Determine which path applies **before acting**:
+
+| | Path A — pre-write | Path B — retrofit |
+|---|---|---|
+| **When to use** | You are about to write or rewrite a note | The note already exists on disk |
+| **Entry point** | MCP `oms_link_suggest` on a sibling note, then MCP `write` | `oms linkify` (report) → `oms linkify --apply --yes`, or MCP `oms_link_suggest` → `oms_link_apply` |
+| **Writes to** | The new note only | Existing notes in scope |
+| **Prerequisite** | Term notes exist to link at | Term notes exist to link at |
+
+These paths are **mutually exclusive and never combined in a single invocation.**
+
+---
+
+## The link universe — term notes only
+
+A link target is a note bound to the `term` concept in `vault/.oms/taxonomy.yaml`.
+Notes bound to any other concept are never proposed as targets, in either path.
+Surface forms of a target are its **basename** and its frontmatter **`aliases`**.
+
+If a run reports `0 term note(s) available as link targets`, the vault has no
+term layer yet — build one with the `wiki` skill (Path B) first. Linking is not
+the tool that creates vocabulary; it is the tool that connects it.
+
+## Three rules the engine enforces — do not fight them
+
+1. **Surface-anchored.** A candidate exists only because the term's basename or
+   alias literally appears in the note. Retrieval never invents a link. Do not
+   hand-add a `[[link]]` to a note whose title does not appear in the text —
+   write the sentence that mentions it instead.
+2. **First occurrence only.** One link per target note per body. A term linked
+   ten times is noise, not navigation.
+3. **Ambiguity is reported, never auto-resolved.** When 2+ notes claim one span,
+   the candidate carries `ambiguous: true` and every `rivalPaths` entry. Ask the
+   user which note is meant, or skip the span. Never guess.
+
+Protected regions are masked out before matching: frontmatter, fenced and inline
+code, existing wikilinks and markdown links, image embeds, HTML, headings, URLs,
+block ids, and tags. A "missing" link inside any of those is correct behavior.
+
+---
+
+## Path A — pre-write linking
+
+*(Use while drafting. The goal is that the body arrives on disk already linked,
+so no retrofit pass is ever needed for this note.)*
+
+### Agent-guided steps
+
+1. Establish the vocabulary **before** drafting: 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 list IS the vault's
+   current term vocabulary.
+2. Draft the body using those exact surface forms, and write `[[wikilinks]]`
+   inline as you compose — first mention of each term only.
+3. Commit through MCP `write`. Host `Write`/`Edit` never touches vault `.md`.
+4. Re-check with `oms_link_suggest` on the committed note. Zero candidates means
+   the draft was already fully linked; remaining candidates are terms you missed.
+
+### Example agent steps (Path A)
+
+```
+User: "Write a note about our retrieval pipeline."
+
+1. oms_link_suggest { notePath: "notes/software-engineering/indexing.md" }
+   → targets: notes/terms/embedding.md, notes/terms/reranker.md, notes/terms/chunk.md
+2. Draft body mentioning embedding / reranker / chunk, each first mention
+   written as [[embedding]], [[reranker]], [[chunk]]
+3. write { mode: "create", notePath: "notes/software-engineering/retrieval-pipeline.md", ... }
+4. oms_link_suggest on the new note → 0 candidates ✓
+```
+
+---
+
+## Path B — retrofit existing notes
+
+*(Use when the note is already on disk. Report first, always.)*
+
+### Batch — `oms linkify` (whole vault or one folder)
+
+```bash
+oms linkify --folder notes          # report only, writes nothing
+oms linkify --folder notes --apply --yes   # rewrite in place
+```
+
+`--apply` without `--yes` refuses before reading a single note and writes
+nothing. Show the user the report and get agreement before adding `--yes`.
+Every write still goes through the capture kernel, so path safety and the
+concept contract hold exactly as they do for MCP `write`.
+
+### Single note — `oms_link_suggest` → `oms_link_apply`
+
+Use when the user wants to accept some candidates and reject others:
+
+1. `oms_link_suggest { notePath, folder? }` → candidates + `baseContentHash`.
+2. Present the candidates; drop ambiguous ones the user does not resolve.
+3. `oms_link_apply { notePath, baseContentHash, candidateIds, folder? }` —
+   pass back the **same** `baseContentHash` and the **same** `folder` scope.
+
+`oms_link_apply` refuses without writing when the note changed since the
+suggest call (`note-changed`), when a candidate's text moved (`candidate-drift`),
+or when accepted candidates overlap. A refusal is a correct outcome: re-run
+`oms_link_suggest` for fresh offsets rather than retrying the stale ids.
+
+### Example agent steps (Path B)
+
+```
+User: "Link up the notes I wrote last week."
+
+1. oms linkify --folder notes            ← report only
+   → 14 candidate(s) across 9 note(s); 2 marked ambiguous
+2. Show the report; ask which note the 2 ambiguous spans mean
+3. Accepted whole folder → oms linkify --folder notes --apply --yes
+   Accepted per-note → oms_link_suggest → oms_link_apply with the chosen ids
+4. Run `oms doctor` (non-blocking, exits 0)
+```

package/core/skills/retrieve/SKILL.md

@@ -51,7 +51,6 @@ For semantic retrieval, keep semantic-index and search controls on the OMS retri
 - pass `semanticMode: "query" | "search" | "vsearch"` to choose hybrid, lexical, or vector search
 - pass `semanticIntent`, `semanticLex`, `semanticVec`, `semanticHyde`, or `semanticSearches` for typed query documents
 - pass `semanticMinScore`, `semanticAll`, `semanticFull`, `semanticLineNumbers`, or `semanticFullPath` when the retrieval task needs search flags
-- pass `semanticStorage: "qmd-sqlite"` for the default qmd-compatible SQLite store, or `semanticStorage: "oms-native-json"` only for the legacy JSON fallback
 - pass `embeddingSyncBeforeSearch: true` when the native semantic index must be fresh before retrieval
 - use `oms_sync_embeddings` for an explicit semantic-index sync without doing a retrieval query
 - use `oms_semantic_query`, `oms_semantic_status`, `oms_semantic_collections`, and `oms_semantic_contexts` for qmd-compatible semantic follow-ups on the native OMS index

package/core/skills/setup/SKILL.md

@@ -157,11 +157,10 @@ Paths outside `agent_writable_zone` are read-only to all agents.
 > Interview output is written ONLY to `vault/.oms/taxonomy.yaml`.
 > Writing to `core/ontology/taxonomy.yaml` or any engine path is FORBIDDEN.
 
-This guard is enforced by construction in `src/engine/setup/writer.ts`:
+This guard is enforced by `oms setup` (`src/cli/setup-command.ts`) and by this skill:
 
-- `writeTaxonomyToVaultOverride(vaultRoot, data)` resolves the canonical path as
-  `{vaultRoot}/.oms/taxonomy.yaml` and refuses any path that escapes `{vaultRoot}/.oms/`.
-- Any attempt to write to the engine default throws before touching disk.
+- The only write target is `{vaultRoot}/.oms/taxonomy.yaml`.
+- Never write to `core/ontology/taxonomy.yaml` or any other engine path.
 
 **Why this matters:** The engine default at `core/ontology/taxonomy.yaml` is the shared
 fallback for every vault. Overwriting it would silently propagate one vault's assumptions
@@ -184,11 +183,10 @@ to all future users. Vault-local overrides preserve this separation permanently.
 
 4. **Validate completeness** — confirm all 6 output keys are present and non-empty.
 
-5. **Write** to `{vaultRoot}/.oms/taxonomy.yaml` ONLY via
-   `writeTaxonomyToVaultOverride(vaultRoot, data)`:
-   - Create `{vaultRoot}/.oms/` if it does not exist.
-   - Merge with any existing file (do not clobber unrelated keys).
-   - Ensure `version: 1` (upgrade from v0 if needed).
+5. **Write** to `{vaultRoot}/.oms/taxonomy.yaml` ONLY:
+   - Prefer `oms setup --vault <path>` for the non-interactive/default path.
+   - If writing during the interview, create `{vaultRoot}/.oms/` if needed, merge
+     with any existing file (do not clobber unrelated keys), and keep `version: 1`.
 
 6. **Confirm** — print the written path and the resolved values. Never silently succeed.
 
@@ -239,10 +237,10 @@ Run the `doctor` skill to validate existing notes against the resolved conventio
 oms doctor [--vault <path>]
 ```
 
-## Executable helpers
+## Executable helper
 
-Pure stateless helpers live in `src/engine/setup/` (co-located vitest tests):
+Use the live CLI writer, not a parallel engine setup module:
 
-- `types.ts` — `DimensionScore`, `InterviewConfig`, `TaxonomyOutput`, `BindingDimension`
-- `ambiguity.ts` — `computeAmbiguity()`, `meetsThreshold()`, `validateScores()`
-- `writer.ts` — `writeTaxonomyToVaultOverride()`, `resolveVaultOverridePath()` (Non-Sticky Guard)
+```bash
+oms setup [--vault <path>] [--yes]
+```

package/core/skills/vault-lint/SKILL.md

@@ -19,7 +19,7 @@ checker is safe to call at any time — it is read-only by default.
 ### Inputs
 
 - `vaultRoot` — absolute path to the vault root directory
-- `ontology` — loaded `Ontology` object (use `loadOntology(ontologyDir)` from `src/ontology/loader.ts`)
+- `ontology` — loaded `Ontology` object (use `loadOntology(ontologyDir)` from `src/core/ontology/loader.ts`)
 - `options.autofixEnabled` — optional human-gate flag (default `false`); set `true` ONLY after explicit user confirmation; currently a no-op reserved for future implementation
 
 ### Output

package/core/skills/wiki/SKILL.md

@@ -1,35 +1,55 @@
 ---
 name: wiki
 version: 0.1.0
-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, maintain the staleness ledger, and lint; Path B (human authoring): build interlinked terminology notes directly in vault taxonomy folders via write.
 trigger: /wiki
 tags: [wiki, collection, staleness, navigation, lint, second-brain, oms]
 ---
 
 ## wiki
 
-Manage the wiki collection — the read-only query surface of the oh-my-secondbrain engine.
+Manage the wiki collection and author interlinked vault notes. There is no
+TypeScript wiki engine — follow this recipe as the agent.
 
-## What this skill does
+## Which path?
 
-1. Verify the M2 compile output exists in `processed/` for the target concept.
+Determine which path applies **before acting**:
+
+| | Path A — promotion | Path B — Human authoring |
+|---|---|---|
+| **When to use** | You have compiled `processed/<concept>.md` output | You have only a topic + terms; no compile output exists |
+| **Entry point** | Promote files, then update ledger + index | MCP `write` |
+| **Writes to** | `wiki/` (query surface) | Vault taxonomy folders (`vault/.oms/taxonomy.yaml`) |
+| **Prerequisite** | `processed/<concept>.md` must exist | None — user provides topic and term list |
+
+These paths are **mutually exclusive and never combined in a single invocation.**
+
+---
+
+## Path A — promotion
+
+*(Use only when `processed/<concept>.md` already exists.)*
+
+### What this skill does
+
+1. Verify the compile output exists in `processed/` for the target concept.
 2. Check the staleness ledger (`.llmwiki/staleness.json`) for current state.
-3. Run `runCollection()` to promote `processed/→wiki/`, update the ledger, flip cascade backlinks, detect stubs and orphans, and regenerate navigation surfaces.
+3. Promote `processed/→wiki/`, update the ledger, flip cascade backlinks, detect stubs and orphans, and regenerate navigation surfaces.
 4. Regenerate `wiki/index.md` (global catalog) and append an entry to `wiki/log.md`.
-5. Run `runLint()` — apply auto-fixes (index consistency, broken links, See-Also) and report findings (conflicts, orphans, outdated refs) to stdout.
+5. Lint — apply auto-fixes (index consistency, broken links, See-Also) and report findings (conflicts, orphans, outdated refs).
 
-## 3-phase hard separation
+### 3-phase hard separation
 
 ```
-Research (M1) → Compile (M2, sequential) → Wiki (read-only query surface)
+Research → Compile (sequential) → Wiki (read-only query surface)
 ```
 
 A wiki query never triggers compile. Compile never writes `wiki/` directly.
-`promoteToWiki()` in `collection.ts` is the sole entry point into `wiki/`.
+Promotion is the sole entry point into `wiki/`.
 
-**Sync boundary:** `processed/` is internal compile state and is **NEVER synced to the Obsidian vault** — only `wiki/` crosses the Obsidian sync boundary. `processed/` stays non-synced (engine-internal); `wiki/` is the synced, user-visible surface.
+**Sync boundary:** `processed/` is internal compile state and is **NEVER synced to the Obsidian vault** — only `wiki/` crosses the Obsidian sync boundary.
 
-## Staleness states
+### Staleness states
 
 | State | Meaning |
 |-------|---------|
@@ -41,7 +61,7 @@ A wiki query never triggers compile. Compile never writes `wiki/` directly.
 
 Full-rebuild escape hatch: delete `.llmwiki/staleness.json` — every page resets to DIRTY on the next collection run.
 
-## Lint tiers
+### Lint tiers
 
 **Auto-fix** (runs automatically, mutates `wiki/` files):
 - Index consistency — page in `wiki/` but absent from `index.md`
@@ -53,28 +73,87 @@ Full-rebuild escape hatch: delete `.llmwiki/staleness.json` — every page reset
 - Orphan pages
 - Outdated refs (DIRTY pages in the ledger)
 
-## Engine
-
-Implemented in `src/engine/wiki/`:
-
-- `collection.ts` — `runCollection()` orchestrates the full cycle
-- `ledger.ts` — 5-state FSM, `loadLedger()` / `saveLedger()` / `resetLedger()`
-- `navigation.ts` — `regenerateIndex()` + `appendLog()`
-- `lint.ts` — `runLint()`
-- `types.ts` — local type definitions
-
-## Example agent steps
+### Example agent steps (Path A)
 
 ```
 User: "Promote the Alpha concept into the wiki after compile."
 
 1. Verify processed/alpha.md exists (Phase-B compile output)
 2. Load ledger from .llmwiki/staleness.json
-3. runCollection({ conceptId: "concepts/alpha.md", conceptName: "Alpha", ... })
-   → promotes processed/alpha.md → wiki/alpha.md
-   → marks concepts/alpha.md CLEAN in ledger
-   → flips CLEAN backlinks to DIRTY
-   → detects stubs (dangling wikilinks) and orphans
-   → regenerates wiki/index.md and appends to wiki/log.md
-4. runLint({ wikiDir, ledger }) → apply auto-fixes, print report-only findings
+3. Copy processed/alpha.md → wiki/alpha.md
+   → mark concepts/alpha.md CLEAN in ledger
+   → flip CLEAN backlinks to DIRTY
+   → detect stubs (dangling wikilinks) and orphans
+   → regenerate wiki/index.md and append to wiki/log.md
+4. Apply auto-fixes; print report-only findings
+```
+
+---
+
+## Path B — Human authoring
+
+*(Use when you have only a topic + terms and no compiled `processed/` output.)*
+
+Build an interlinked cluster of vault notes: one hub/MOC note plus one standalone note
+per coined term, cross-linked with Obsidian `[[wikilinks]]` and committed through
+MCP `write`. Writes to vault taxonomy folders declared
+in `vault/.oms/taxonomy.yaml` — **never to `wiki/`**.
+
+Implements [#43](https://github.com/GoBeromsu/oh-my-second-brain/issues/43).
+
+### Admission gate — coined terms vs general nouns
+
+Before creating any note, apply this test to every candidate term:
+
+> **Does the word exist in ordinary language and shift meaning by domain?**
+> → Explain it as a `## Term` section inside the hub note (the hub supplies the context).
+>
+> **Does it only ever mean one specific technical thing — a coined or proper term?**
+> → Give it its own standalone terminology note.
+
+**Kubernetes example:**
+
+| Term | Classification | Placement |
+|------|---------------|-----------|
+| `Pod` | General noun (grouping in many domains) | Section in the Kubernetes hub note |
+| `Service` | General noun (a service in many domains) | Section in the Kubernetes hub note |
+| `Deployment` | General noun (deploying software anywhere) | Section in the Kubernetes hub note |
+| `Ingress` | General noun (network ingress is domain-agnostic) | Section in the Kubernetes hub note |
+| `ReplicaSet` | Coined Kubernetes term, no prior meaning | Standalone note → `[[ReplicaSet]]` |
+| `StatefulSet` | Coined Kubernetes term, no prior meaning | Standalone note → `[[StatefulSet]]` |
+| `DaemonSet` | Coined Kubernetes term, no prior meaning | Standalone note → `[[DaemonSet]]` |
+| `CronJob` | Coined compound, specific k8s resource type | Standalone note → `[[CronJob]]` |
+
+Apply this gate **before** calling MCP `write`. General-noun terms never become standalone notes.
+
+### Agent-guided steps (Path B, v0)
+
+1. Ask the user for the **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.
+4. **Deduplicate**: call MCP `write` with `mode: "create"` per coined term; if status is `rejected` because the note exists, reuse the existing `[[wikilink]]`.
+5. Draft one note per coined term — frontmatter from the concept's required fields + definition + `## See Also` back-link to the hub.
+6. Draft the hub/MOC note — general-noun `## Term` sections + `## See Also` listing all coined-term `[[wikilinks]]`.
+7. Commit terms first, hub last, via MCP `write`.
+8. Run `oms doctor` (non-blocking, exits 0).
+
+### Example agent steps (Path B)
+
+```
+User: "Build a Kubernetes wiki: Pod, Service, Deployment, Ingress, ReplicaSet, StatefulSet, DaemonSet, CronJob"
+
+Admission gate:
+  Pod, Service, Deployment, Ingress → general nouns → hub sections
+  ReplicaSet, StatefulSet, DaemonSet, CronJob → coined terms → own notes
+
+Dedup check: MCP write create per coined term → proceed when not already present
+
+→ vault/notes/software-engineering/replicaset.md    (coined, committed first)
+→ vault/notes/software-engineering/statefulset.md   (coined, committed first)
+→ vault/notes/software-engineering/daemonset.md     (coined, committed first)
+→ vault/notes/software-engineering/cronjob.md       (coined, committed first)
+→ vault/notes/software-engineering/kubernetes.md    (hub: Pod/Service/Deployment/Ingress as
+                                                      sections; See Also: [[ReplicaSet]] etc.)
+
+oms doctor  ← verify (exits 0, non-blocking)
 ```

package/core/skills/write/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: write
+description: Write a vault note through the Oh My Second Brain kernel contract.
+---
+
+# write
+
+Vault notes go through MCP `write` only. Do not use host Write/Edit for vault `.md` files.
+
+`mode` is `create`, `append`, or `update`. The kernel owns `.oms` and returns one status:
+
+- `ask` — fill the missing or invalid fields and call `write` again
+- `inbox` — tell the user; do not invent a folder
+- `written` — done
+- `rejected` — fix `violations` or `reason` and call `write` again

package/dist/capture/safe.d.ts

@@ -1,6 +1,10 @@
-import type { Ontology } from "../ontology/types.js";
+import { type WriteContractViolation, type WriteFieldDescriptor } from "../conventions/write-contract.js";
+import { type WriteRejection, type WriteReceipt, type WriteTargetSource } from "../conventions/write-protocol.js";
+import type { Concept, Ontology } from "../core/ontology/types.js";
 export type CapturePrepareAction = "ready" | "ask-missing-fields" | "route-to-inbox";
 export type CaptureWriteMode = "create" | "append";
+export type WriteMode = "create" | "append" | "update";
+export type WriteStatus = "ask" | "inbox" | "written" | "rejected";
 export interface CapturePrepareInput {
     vault: string;
     ontology: Ontology;
@@ -16,10 +20,17 @@ export interface CapturePlan {
     notePath: string;
     missingFields: string[];
     frontmatter: Record<string, unknown>;
+    fields: WriteFieldDescriptor[];
+    violations: WriteContractViolation[];
     reason?: string;
 }
+export interface WriteTarget {
+    vault: string;
+    source: WriteTargetSource;
+}
 export interface CaptureCommitInput {
     vault: string;
+    source: WriteTargetSource;
     ontology: Ontology;
     notePath: string;
     frontmatter: Record<string, unknown>;
@@ -31,6 +42,55 @@ export interface CaptureCommitResult {
     mode: CaptureWriteMode;
     notePath: string;
 }
+export interface WriteNoteInput {
+    target: WriteTarget;
+    ontology: Ontology;
+    mode: WriteMode;
+    dryRun: boolean;
+    concept?: string;
+    folder?: string;
+    filename?: string;
+    notePath?: string;
+    frontmatter?: Record<string, unknown>;
+    body?: string;
+    /**
+     * Test-only DI seam for the postcondition read-back. Defaults to reading the
+     * persisted file with node:fs/promises. Exists so tests can force a
+     * postcondition failure deterministically without mocking node:fs/promises.
+     */
+    readBack?: (fullPath: string) => Promise<string>;
+}
+export interface WriteNoteResult {
+    status: WriteStatus;
+    mode: WriteMode;
+    notePath: string;
+    concept: string | null;
+    folder: string;
+    fields: WriteFieldDescriptor[];
+    frontmatter: Record<string, unknown>;
+    missingFields: string[];
+    violations: WriteContractViolation[];
+    reason?: string;
+    rejection?: WriteRejection;
+    receipt?: WriteReceipt;
+}
 export declare function safeVaultNotePath(vault: string, notePath: string): string;
 export declare function prepareCapture(input: CapturePrepareInput): CapturePlan;
+export interface StagedEvaluation {
+    ok: boolean;
+    violations: WriteContractViolation[];
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+/**
+ * Acceptance Criteria - staged evaluation (pre-persist).
+ *
+ * Parses the note content that is ABOUT to be written and re-runs the kernel
+ * write contract against the RENDERED frontmatter. This catches divergence
+ * between the caller-supplied frontmatter and what actually lands on disk
+ * (yaml round-trip artifacts such as `NaN` rendering as `.nan` and parsing
+ * back as `null`).
+ */
+export declare function evaluateStagedNote(stagedContent: string, concept: Concept, notePath: string, strictZones: ReadonlySet<string>): StagedEvaluation;
+export declare function writeNote(input: WriteNoteInput): Promise<WriteNoteResult>;
 export declare function commitCapture(input: CaptureCommitInput): Promise<CaptureCommitResult>;