oh-my-second-brain 0.1.8 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-19
+
+### Added
+- The npm package now ships `CHANGELOG.md`, so release notes are available offline and in version control.
+- Releases are published by CI from `oms-v*` tags with npm provenance and an auto-generated GitHub Release whose notes come from the CHANGELOG.
+- Maintainers release with a single command: `npm run release -- <X.Y.Z>` rolls the `[Unreleased]` section into a versioned entry, bumps all version carriers (package.json, plugin manifests), commits, tags, and pushes atomically.
+
+#### Note linking
+
+- `term` is now a first-class concept in the core ontology, bound to a `terms/` folder. A term note is the one place you define a piece of vocabulary, and its new `aliases` frontmatter field lists every other way you write that word.
+- Two MCP tools turn those terms into links. `oms_link_suggest` is read-only: it ranks the spans in a note that could point at a term note and hands back a hash of the content it looked at. `oms_link_apply` writes, but only the candidates you accepted, and only while that hash still matches, so a note you edited in the meantime is never overwritten by a stale suggestion.
+- `oms linkify [--folder <f>] [--apply] [--yes]` does the same job in bulk over notes you already have. It reports and changes nothing by default; mutation needs both `--apply` and `--yes`.
+- Matching understands Korean josa, so `아타락시아를` links as `[[ataraxia|아타락시아]]를` instead of being skipped for not matching the bare term.
+- A note-linking skill ships to Claude, Codex, and Hermes, so each host knows the suggest-review-apply loop without you explaining it every session.
+
+#### Updates and install
+
+- A root `.claude-plugin/marketplace.json` makes OMS discoverable through Claude Code's native plugin marketplace. Claude installs now go through `claude plugin marketplace add` plus `claude plugin install oms@oms`, and fall back to the local plugin path when the marketplace flow can't complete, so offline and dev checkouts still work.
+- The MCP server tells you when a newer version exists. It reads a 24-hour cache at boot and appends one line to its `instructions`; the registry lookup happens in a bounded background refresh, never on the startup path. `OMS_UPDATE_NOTICE=0` turns it off.
+- A test and a CI release-tag guard now check that `marketplace.json` and `package.json` agree on the version, so a release can't ship a marketplace manifest pointing at the wrong build.
+
+### Changed
+
+- Wikilinks resolve through frontmatter `aliases`. `[[some-alias]]` used to resolve to nothing; it now finds the note that claims that alias, which means alias links count as real graph edges during retrieval.
+- Installing several hosts at once no longer stops at the first failure. Each runtime is isolated, so a broken Codex config can't cost you your Claude and Hermes install.
+- Hermes config writes are an upsert instead of a full overwrite: your comments and key ordering in `~/.hermes/config.yaml` survive an install or update.
+- Claude's third-party marketplace auto-update stays off unless you turn it on. Install prints how to enable `extraKnownMarketplaces.<name>.autoUpdate` in `~/.claude/settings.json` rather than flipping it for you; the `claude` CLI owns that setting.
+
+### Fixed
+
+- The MCP server reports its real package version instead of a hardcoded `0.0.0`, so host-side version checks and bug reports show what you're actually running.
+
+## [0.1.9] - 2026-08-14
+
+### Added
+- MCP `write` is now the single vault write window, with `mode: create | append | update`, returning `ask`, `inbox`, `written`, or `rejected` so the agent always knows what happened to a note (#52).
+- A contract gate validates required fields, types, enums, and routing law before anything touches the vault. Extra keys survive the round trip (`additionalProperties: preserve`).
+- Thin write skills for each host: `/oms-write` on Claude, `$oms-write` on Codex, and `write` on Hermes.
+
+### Changed
+- **Breaking:** capture skills are gone (`/oms-capture`, `$oms-capture`, Hermes `capture`), along with the MCP aliases `oms_capture_prepare` and `oms_capture_commit`. After upgrading, reinstall the host adapters with `oms update --yes` or `oms install --runtime <host> --vault <path> --yes`.
+
+### Fixed
+- Transitive production advisories cleared through same-major overrides for `hono`, `@hono/node-server`, `body-parser`, `fast-uri`, `ip-address`, `nanoid`, and `tar`. No new runtime dependencies were added.
+
+## [0.1.8] - 2026-06-17
+
+### Fixed
+- Upstage Solar embeddings work again: the model id `solar-embedding-1-passage` didn't exist, so every embedding call returned HTTP 400. It's now `embedding-passage` (4096d).
+- `embed()` guards its inputs. Empty input becomes a zero vector, and input over 4000 tokens is shrunk and retried, so one oversized or empty chunk no longer fails a whole vault sync.
+- Transitive high-severity advisory in `hono` (pulled in by `@modelcontextprotocol/sdk`) resolved via `overrides: hono ^4.12.25`.
+
+### Changed
+- Claude Code, Codex, and Hermes adapter manifests are synced to 0.1.8.
+
+## [0.1.7] - 2026-06-05
+
+> No GitHub Release was published for the `oms-v0.1.7` tag. This section is reconstructed from the commits between `oms-v0.1.6` and `oms-v0.1.7`.
+
+### Added
+- Live graph retrieval plus fail-soft qmd fusion, so retrieval keeps working when the optional qmd side is unavailable.
+- MCP retrieval context surfaced to hosts.
+
+### Changed
+- The npm package root is the runtime asset root: built releases resolve `core/` and `adapters/` from the package root, matching the source layout.
+- `oh-my-second-brain` becomes the canonical repository, npm package, and installed command, with `oms` kept as a compatibility alias for existing MCP, skill, and vault `.oms` surfaces.
+- Install docs point at 0.1.7 so the one-line and npm install examples resolve to the published version.
+- The release workflow no longer requires an `NPM_TOKEN` preflight, allowing npm trusted publishing over OIDC while still using `NODE_AUTH_TOKEN` when the secret exists.
+
+### Fixed
+- Frontmatter diagnostics are tolerant: malformed frontmatter no longer blocks retrieve or build paths.
+
+## [0.1.6] - 2026-06-02
+
+### Changed
+- The project is published to npm as `oh-my-second-brain`, while `oms` stays the CLI, MCP, skill, and repo slug.
+- The installer defaults to the published npm package instead of `npx` against GitHub release URLs.
+- Host MCP registration now points at the installed `oms mcp --vault ...` command.
+
+## [0.1.5] - 2026-06-02
+
+### Changed
+- Oh My Second Brain is the project and display name; `oms` remains the short technical slug for the package, CLI, MCP server, skills, and release assets.
+- Human-facing docs, adapter manifests, host shims, skills, CLI output, MCP tool titles, and installer text all use the Oh My Second Brain name.
+- Release package URLs point at `oms-v0.1.5` / `oms-0.1.5.tgz`.

package/README.ko.md

@@ -0,0 +1,127 @@
+# Oh My Second Brain
+
+> Obsidian 및 일반 마크다운 지식 볼트를 위한, 호스트에 종속되지 않고 사용자가 소유하는 컨벤션 레이어.
+
+[English](./README.md) · **한국어**
+
+[![npm](https://img.shields.io/npm/v/oh-my-second-brain)](https://www.npmjs.com/package/oh-my-second-brain)
+![license](https://img.shields.io/npm/l/oh-my-second-brain)
+
+Oh My Second Brain(`oms`)은 기존 Obsidian/마크다운 볼트를 에이전트가 읽을 수 있는 지식 베이스로 만든다. 볼트가 가진 고유한 폴더/프론트매터 컨벤션을 로드하고, 그에 맞게 노트를 검증하고, 로컬 링크 그래프를 만들고, 이 모든 것을 단일 MCP 서버를 통해 AI 코딩 호스트(Claude Code, Codex, Hermes)에 노출한다. 특정 호스트에 종속되지 않으며 노트를 다른 곳으로 옮기지도 않는다.
+
+**컨벤션 우선, 사용자 소유**가 원칙이다. 볼트는 그대로 일반 마크다운으로 남고, 온톨로지는 사용자가 통제하는 커밋된 `.oms/` 폴더에 살며, 어떤 것도 독점 저장소 뒤에 숨지 않는다.
+
+## 동작 방식
+
+```
+core (한 번만 작성)                        adapters (호스트마다 하나)
+  온톨로지 로딩                              claude-code  .claude-plugin + CLAUDE.md   /sigil
+  컨벤션 검증                    +           codex        .codex-plugin + AGENTS.md    $sigil
+  그래프 + 시맨틱 런타임                      hermes       manifest.json + SOUL.md      (MCP/tools)
+  MCP 서버 (capture/retrieve/validate)
+```
+
+- **core**는 호스트에 독립적이다: 온톨로지, 검증, 그래프/시맨틱 엔진, MCP 서버.
+- 각 **adapter**는 호스트 하나의 구조적 차이(매니페스트 스키마, 컨벤션 파일, 호출 sigil)만 흡수한다. 호스트를 추가한다는 건 core를 건드리는 게 아니라 adapter 디렉터리 하나를 더하는 일이다.
+- 호스트 간 연결 메커니즘은 모든 호스트가 함께 쓰는 단일 **MCP 서버**(`oms mcp`)다.
+
+## 요구 사항
+
+- Node.js 20 이상
+- `PATH`에 `npm`
+- Obsidian 볼트 또는 마크다운 노트 폴더
+- (선택) 호스트 CLI: `claude`, `codex`, `hermes`
+- (선택) [시맨틱 검색](#시맨틱-검색-선택)용 임베딩 백엔드
+
+## 설치
+
+원라인 설치(게시된 npm 패키지 사용):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/GoBeromsu/oh-my-second-brain/main/scripts/install.sh | bash
+```
+
+호스트를 선택하고 볼트를 지정:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/GoBeromsu/oh-my-second-brain/main/scripts/install.sh | bash -s -- --runtime all --vault /path/to/vault
+```
+
+또는 npm으로:
+
+```bash
+npm install -g oh-my-second-brain
+oms install --runtime all --vault /path/to/vault --dry-run   # 미리보기
+oms install --runtime all --vault /path/to/vault --yes       # 적용
+```
+
+전체 가이드: [docs/install.md](./docs/install.md).
+
+## 호스트
+
+| 호스트 | 매니페스트 | 컨벤션 파일 | Sigil | 상태 |
+|------|----------|-----------|-------|--------|
+| **claude-code** | `.claude-plugin/plugin.json` | `CLAUDE.md` | `/` | 설치 가능 |
+| **codex** | `.codex-plugin/plugin.json` | `AGENTS.md` | `$` | 네이티브 스킬 + MCP |
+| **hermes** | `manifest.json` | `SOUL.md` | (MCP/tools) | 네이티브 스킬 + MCP |
+
+`oms install`은 호스트 네이티브 규칙/스킬과 관리형 `oms` MCP 등록을 작성하며, `oms uninstall`로 되돌릴 수 있다. 호스트별 상세: [adapters/README.md](./adapters/README.md).
+
+## CLI
+
+```
+oms setup      기존 볼트를 컨벤션으로 채택 (.oms/taxonomy.yaml 작성, 노트는 수정하지 않음)
+oms install    호스트 어댑터 + MCP 등록 설치
+oms uninstall  호스트 어댑터 + MCP 등록 제거
+oms update     패키지 업데이트 확인/적용 후 어댑터 재조정
+oms doctor     온톨로지 기준 노트 검증 (broken-link + orphan 탐지)
+oms semantic   네이티브 마크다운 시맨틱 인덱스 / 검색 / 조회
+oms mcp        stdio MCP 서버 시작
+oms hook       볼트 가드 훅 (Claude Code pre/post tool-use)
+```
+
+`oh-my-second-brain`이 정식 명령이고, `oms`는 짧은 별칭이다.
+
+## MCP 도구
+
+`oms mcp`는 상태, 읽기, 검색, 검증, 게이트된 write 도구를 노출한다:
+
+`oms_graph_status` · `oms_graph_build` · `oms_list_concepts` · `oms_retrieve_context` · `oms_retrieve_by_axis` · `oms_sync_embeddings` · `oms_semantic_query` · `oms_get_document` · `oms_multi_get_documents` · `oms_lazy_load_note` · `oms_validate_contract` · `write`
+
+`write`는 경로 안전성, 볼트 격리, 커널이 소유한 컨셉 계약으로 게이트된다.
+
+## 볼트 구조 (`.oms/`)
+
+`oms setup`은 볼트를 커밋된 `.oms/` 폴더로 채택하며, 두 개의 레이어를 둔다(ADR-006):
+
+- **Contract (기계 검증)** — `taxonomy.yaml`(폴더 → intent → concept)와 `concepts/*.yaml`(노트 타입별 프론트매터 선언). `vault-lint`와 `oms_validate_contract`가 강제한다.
+- **Governance (사람 의도)** — `governance/`의 ADR과 규칙. 기계가 파싱하지 않는다.
+- `.oms/cache/`(파생 그래프/임베딩 아티팩트)는 gitignore된다.
+
+`setup`은 `.oms/taxonomy.yaml`을 작성하고 기존 `.oms/concepts/`를 보존하며, 노트는 절대 수정하지 않는다.
+
+## 시맨틱 검색 (선택)
+
+시맨틱 검색에는 실제 임베딩 모델이 필요하다 — 프로덕션 경로에 가짜/해시 폴백은 없다(ADR-007). 로컬 GGUF 모델(`OMS_MODEL_PATH`) **또는** 임베딩 API 키(`UPSTAGE_API_KEY`) 중 하나를 설정한 뒤 동기화·질의한다:
+
+```bash
+oms semantic sync  --vault /path/to/vault --collection vault
+oms semantic query "무엇을 찾아야 하나?" --vault /path/to/vault
+```
+
+모델을 설정하지 않아도 그래프 기반 검색과 컨벤션 검증은 그대로 동작한다.
+
+## 개발
+
+```bash
+npm install
+npm run build
+npm test
+npm run release:check   # lint + build + test + audit + pack + artifact-smoke + plugin 검증
+```
+
+릴리스 절차: [docs/release.md](./docs/release.md).
+
+## 라이선스
+
+MIT. 상위 출처 크레딧은 [ACKNOWLEDGMENTS.md](./ACKNOWLEDGMENTS.md) 참고.

package/README.md

@@ -0,0 +1,128 @@
+# Oh My Second Brain
+
+> A host-agnostic, user-owned convention layer for Obsidian and plain-markdown knowledge vaults.
+
+**English** · [한국어](./README.ko.md)
+
+[![npm](https://img.shields.io/npm/v/oh-my-second-brain)](https://www.npmjs.com/package/oh-my-second-brain)
+![license](https://img.shields.io/npm/l/oh-my-second-brain)
+
+Oh My Second Brain (`oms`) turns an existing Obsidian/markdown vault into an agent-readable knowledge base. It loads your vault's own folder/frontmatter conventions, validates notes against them, builds a local link graph, and exposes all of it to AI coding hosts (Claude Code, Codex, Hermes) through a single MCP server — without locking you into any one host or moving your notes.
+
+It is **convention-first and user-owned**: your vault stays plain markdown, the ontology lives in a committed `.oms/` folder you control, and nothing is hidden behind a proprietary store.
+
+## How it works
+
+```
+core (written once)                       adapters (one per host)
+  ontology loading                          claude-code  .claude-plugin + CLAUDE.md   /sigil
+  convention validation         +           codex        .codex-plugin + AGENTS.md    $sigil
+  graph + semantic runtime                  hermes       manifest.json + SOUL.md      (MCP/tools)
+  MCP server (capture/retrieve/validate)
+```
+
+- **core** is host-agnostic: ontology, validation, the graph/semantic engine, and the MCP server.
+- each **adapter** absorbs exactly one host's structural differences (manifest schema, convention file, invocation sigil) — adding a host means adding an adapter directory, not touching core.
+- the cross-host mechanism is one **MCP server** (`oms mcp`) that every host talks to.
+
+## Requirements
+
+- Node.js 20+
+- `npm` on `PATH`
+- An Obsidian vault, or any folder of markdown notes
+- Optional host CLIs: `claude`, `codex`, `hermes`
+- Optional embedding backend for [semantic search](#semantic-search-optional)
+
+## Install
+
+One-line (uses the published npm package):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/GoBeromsu/oh-my-second-brain/main/scripts/install.sh | bash
+```
+
+Pick hosts and point at a vault:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/GoBeromsu/oh-my-second-brain/main/scripts/install.sh | bash -s -- --runtime all --vault /path/to/vault
+```
+
+Or via npm:
+
+```bash
+npm install -g oh-my-second-brain
+oms install --runtime all --vault /path/to/vault --dry-run   # preview
+oms install --runtime all --vault /path/to/vault --yes       # apply
+```
+
+Full guide: [docs/install.md](./docs/install.md).
+
+## Hosts
+
+| Host | Manifest | Convention file | Sigil | Status |
+|------|----------|-----------------|-------|--------|
+| **claude-code** | `.claude-plugin/plugin.json` | `CLAUDE.md` | `/` | installable |
+| **codex** | `.codex-plugin/plugin.json` | `AGENTS.md` | `$` | native skills + MCP |
+| **hermes** | `manifest.json` | `SOUL.md` | (MCP/tools) | native skills + MCP |
+
+`oms install` writes the host-native rules/skills and a managed `oms` MCP registration, and is reversible with `oms uninstall`. Per-host details: [adapters/README.md](./adapters/README.md).
+
+## CLI
+
+```
+oms setup      Adopt an existing vault into the convention (writes .oms/taxonomy.yaml; never edits notes)
+oms install    Install host adapters + MCP registration
+oms uninstall  Remove host adapters + MCP registration
+oms update     Check/apply a package update, then reconcile adapters
+oms doctor     Validate note frontmatter against the ontology (aggregated by field & concept)
+oms lint       Check vault link health: broken [[wikilinks]] + orphan notes
+oms semantic   Native markdown semantic index / search / get
+oms mcp        Start the stdio MCP server
+oms hook       Vault guard hooks (Claude Code pre/post tool-use)
+```
+
+`oh-my-second-brain` is the canonical command; `oms` is the short alias.
+
+## MCP tools
+
+`oms mcp` exposes status, read, retrieve, validation, and gated write tools, including:
+
+`oms_graph_status` · `oms_graph_build` · `oms_list_concepts` · `oms_retrieve_context` · `oms_retrieve_by_axis` · `oms_sync_embeddings` · `oms_semantic_query` · `oms_get_document` · `oms_multi_get_documents` · `oms_lazy_load_note` · `oms_validate_contract` · `write`
+
+`write` is gated by path-safety, vault-confinement, and the kernel-owned concept contract.
+
+## Vault layout (`.oms/`)
+
+`oms setup` adopts your vault into a committed `.oms/` folder with two layers (ADR-006):
+
+- **Contract (machine-validated)** — `taxonomy.yaml` (folder → intent → concept) and `concepts/*.yaml` (per-note-type frontmatter declarations). Enforced by `vault-lint` and `oms_validate_contract`.
+- **Governance (human intent)** — `governance/` ADRs and rules; never machine-parsed.
+- `.oms/cache/` (derived graph/embedding artifacts) is gitignored.
+
+`setup` writes `.oms/taxonomy.yaml`, preserves existing `.oms/concepts/`, and never modifies your notes.
+
+## Semantic search (optional)
+
+Semantic retrieval requires a real embedding model — there is no fake/hash fallback (ADR-007). Configure embeddings explicitly with `OMS_EMBEDDING_PROVIDER` + `OMS_EMBEDDING_MODEL` (`gguf` with a local GGUF model path, or `upstage` with a model id and `UPSTAGE_API_KEY`), then sync and query:
+
+```bash
+oms semantic sync  --vault /path/to/vault --collection vault
+oms semantic query "what should I retrieve?" --vault /path/to/vault
+```
+
+Without a configured model, graph-based retrieval and convention validation still work.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run release:check   # lint + build + test + audit + pack + artifact-smoke + plugin validate
+```
+
+Release process: [docs/release.md](./docs/release.md).
+
+## License
+
+MIT. See [ACKNOWLEDGMENTS.md](./ACKNOWLEDGMENTS.md) for upstream credits.

package/adapters/README.md

@@ -2,7 +2,7 @@
 
 ## Principle
 
-Oh My Second Brain's **core** (ontology loading, convention validation, graph/search runtime targets, and MCP server once implemented) is written once.
+Oh My Second Brain's **core** (ontology loading, convention validation, graph/search runtime targets, and MCP server) is written once.
 Each **adapter** absorbs exactly one host's structural differences — manifest schema,
 hook format, invocation sigil, and convention-file name — so adding a new host
 means adding one new adapter directory, not touching core.
@@ -51,13 +51,13 @@ Release contract: the npm tarball must include `adapters/claude-code/` because `
   - Each path must contain a `SKILL.md`.
 - **Convention file**: `CLAUDE.md` — append `adapters/claude-code/CLAUDE.md` to your project's `CLAUDE.md`.
 - **Sigil**: `/` (e.g. `/oms-setup`).
-- **Hooks**: none in v0 (hook format is `hooks/hooks.json` multi-script array — roadmap).
+- **Hooks**: `oms install --runtime claude` can upsert OMS guard entries in `~/.claude/settings.json` while preserving existing non-OMS hooks.
 - **Install**: `claude plugin install path/to/adapters/claude-code` or point Claude Code at the adapter directory.
 
 ### codex (native skills + MCP install v0)
 
 - **Manifest**: `.codex-plugin/plugin.json`
-  - Schema differs from claude-code: codex uses a unified `codex-native-hook.mjs` instead of `hooks.json`.
+  - Schema differs from claude-code: codex declares its skill directory and MCP server manifest directly.
   - Skills are invoked with `$` sigil instead of `/`.
 - **Convention file**: `AGENTS.md` — append `adapters/codex/AGENTS.md` to your project's `AGENTS.md`.
 - **Status**: v0 native install. `oms install --runtime codex` installs `~/.codex/rules/oms.md`, namespaced `~/.codex/skills/oms-*`, a managed `[mcp_servers.oms]` block in `~/.codex/config.toml`, and a copy of the adapter under `~/.codex/plugins/oms`.
@@ -75,17 +75,17 @@ Release contract: the npm tarball must include `adapters/claude-code/` because `
 ## MCP Backbone
 
 The cross-host mechanism is an **MCP server** (`src/mcp/server.ts`) that exposes
-contract validation, retrieve, graph/status, and gated capture tools.
+contract validation, retrieve, graph/status, and gated write tools.
 
 All three hosts natively support MCP (`.mcp.json` for claude-code and codex; "any MCP server" for Hermes).
 In the current repository, `src/mcp/server.ts` starts a real stdio MCP server via `oms mcp`.
 
-The MCP server currently exposes status/read/cache/retrieve/capture tools:
+The MCP server currently exposes status/read/cache/retrieve/write tools:
 `oms_graph_status`, `oms_graph_build`, `oms_list_concepts`,
 `oms_retrieve_context`, `oms_sync_embeddings`, `oms_get_document`, `oms_multi_get_documents`,
 `oms_retrieve_by_axis`, `oms_lazy_load_note`,
-`oms_validate_contract`, `oms_capture_prepare`, and `oms_capture_commit`.
-Capture commit is gated by path-safety, vault-confinement, and contract validation. The CLI (`oms setup`, `oms install`, `oms uninstall`, `oms doctor`) remains the real surface for lifecycle commands.
+`oms_validate_contract`, and `write`.
+`write` is gated by path-safety, vault-confinement, and contract validation. The CLI (`oms setup`, `oms install`, `oms uninstall`, `oms doctor`) remains the real surface for lifecycle commands.
 
 ---
 
@@ -94,6 +94,6 @@ Capture commit is gated by path-safety, vault-confinement, and contract validati
 1. Create `adapters/<host>/`.
 2. Write the host-specific manifest in the correct subdirectory and schema.
 3. Write the convention-file shim (`CLAUDE.md` / `AGENTS.md` / `SOUL.md` / whatever the host uses).
-4. Write skill wrappers that shell out to `oms <verb>` (for lifecycle) or call the MCP server (for capture/retrieve).
+4. Write skill wrappers that shell out to `oms <verb>` (for lifecycle) or call the MCP server (for write/retrieve).
 5. Document the host's structural differences in this table.
 6. Do **not** modify `core/` or add host-specific logic to shared code.

package/adapters/claude-code/.claude-plugin/plugin.json

@@ -1,11 +1,12 @@
 {
   "name": "oms",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults — capture, retrieve, and validate knowledge under a declared semantic convention.",
   "author": {
     "name": "gobeumsu"
   },
   "license": "MIT",
+  "mcpServers": "./.mcp.json",
   "keywords": [
     "obsidian",
     "knowledge-base",
@@ -17,7 +18,7 @@
     "./skills/setup/",
     "./skills/doctor/",
     "./skills/define/",
-    "./skills/capture/",
+    "./skills/write/",
     "./skills/retrieve/",
     "./skills/uninstall/",
     "./skills/update/"

package/adapters/claude-code/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "oms": {
+      "command": "oms",
+      "args": ["mcp"]
+    }
+  }
+}

package/adapters/claude-code/CLAUDE.md

@@ -12,15 +12,14 @@ All knowledge capture and retrieval must follow the declared semantic convention
 - Read `.oms/taxonomy.yaml` to understand which folders hold which concepts.
 - Read `.oms/concepts/*.yaml` to understand field requirements and lenses.
 
-**When capturing new knowledge:**
-- Use the `/oms-capture` skill or follow the librarian persona (`core/agents/librarian.md`).
-- Every note must carry the required frontmatter fields for its concept.
-- Place notes in the folder declared in the taxonomy — do not invent new folders without updating `.oms/taxonomy.yaml`.
+**When writing vault notes:**
+- Use the `/oms-write` skill. Call MCP `write`. Do not use host Write/Edit for vault `.md` files.
+- The kernel fills and checks frontmatter from `.oms`. `ask` or `rejected` means fix and call `write` again.
 
 **When retrieving knowledge:**
 - Use the `/oms-retrieve` skill or follow the retriever persona (`core/agents/retriever.md`).
 - Apply the concept's declared lens for the retrieval purpose (synthesis, audit, etc.).
 - Return only the fields the lens specifies — do not dump full frontmatter.
 
-**Convention violations are warnings, not errors (v0).**
-`oms doctor` always exits 0. Fix violations incrementally.
+**Doctor is advisory. Write is not.**
+`oms doctor` always exits 0. MCP `write` rejects contract violations.

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

@@ -1,11 +1,11 @@
 ---
 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.
 ---
 
 # Skill: oms-compile (Claude Code)
 
-Synthesize a concept wiki page from source materials using the OMS compile engine.
+Synthesize a concept wiki page from source materials.
 
 ## Invocation
 
@@ -15,38 +15,13 @@ Synthesize a concept wiki page from source materials using the OMS compile engin
 
 ## What this skill does
 
-Conceptually shells out to:
+Thin pointer to `core/skills/compile`. There is no `oms compile` CLI.
 
-```bash
-oms compile <concept>
-```
-
-Thin pointer to `core/skills/compile`. The engine runs Phase A (load + grade
-materials, pure read) then Phase B (write body to `processed/` tier). Promotion
-from `processed/` to `wiki/` is the M3 collection owner's responsibility.
-
-## Agent-guided steps (v0)
-
-1. Identify the **concept** name and locate its source materials.
-2. Run **Phase A** — load and grade all materials; resolve backlinks from the compile graph.
-3. Call `compile(opts)` with materials, graph, llm, and `dotLlmwiki` cache path.
-4. Check `wasSkipped(result)` — if the material SHA is unchanged, skip downstream.
-5. Run **Phase B** — write `result.body` to the `processed/` tier only.
-6. Pass `result.affected_backlinks` to the wiki collection owner (M3) to mark stale pages.
-
-## Provenance order
-
-Authored > curated > external-raw. Authored materials carry a
-`[AUTHORED — preserve individual voice]` label in the LLM prompt.
-
-## Runtime
-
-No MCP tool is required for compile itself — it is a pure TypeScript call.
-Use `oms_retrieve_context` or `oms_get_document` to gather source materials
-before invoking compile. Delete `{dotLlmwiki}/sha-cache.json` to force a
-full recompile of all concepts.
-
-## NOTES
+1. **Phase A** — load and grade materials; resolve backlinks (pure read).
+2. Skip rewrite if the material SHA is unchanged.
+3. **Phase B** — write the body to `processed/` only.
+4. Pass affected backlinks to the wiki skill so those pages can be marked stale.
 
-Wiki mirror deferred — the `wiki` skill is built by a parallel milestone (M3)
-and its adapter mirror is intentionally deferred until that milestone lands.
+Provenance order: authored > curated > external-raw.
+Use `oms_retrieve_context` or `oms_get_document` to gather source materials.
+Delete `{dotLlmwiki}/sha-cache.json` to force a full recompile.

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

@@ -18,31 +18,11 @@ Run adversarial absorption analysis on a target and produce a structured report.
 Thin pointer to `core/skills/distill`. Vault-agnostic — `OMS_VAULT` is NOT
 required. The target is treated as inert read-only text and is never executed.
 
-## Agent-guided steps (v0)
-
-1. Load the target via `prepareCleanRoom(target)` — treat as inert data only.
-2. Snapshot system state SHA before analysis (`snapshotSha`).
-3. Run red-team adversarial analysis via `runAnalysis(spec, provider)`.
-   Inject a stub provider for dry-runs; a real LLM client for production.
-4. Generate the report via `generateReport(result, targetName)`.
-   The report has exactly three sections: §1 Patterns, §2 Risks, §3 Attribution.
-5. Verify the 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 data only.
+2. Snapshot a content hash before analysis.
+3. Run red-team analysis (read-only).
+4. Write the report: §1 Patterns, §2 Risks, §3 Attribution.
+5. Verify the hash is unchanged. Stop if anything mutated.
 6. Return the report string. Write it only if the user explicitly requests it.
 
-## Report sections
-
-- **§1 Patterns** — ranked by `absorb_confidence` (highest first), with `file:line` citations.
-- **§2 Risks** — ranked by severity: critical → high → medium → low.
-- **§3 Attribution** — repo, URL, and license note for `ACKNOWLEDGMENTS.md`.
-
-## Runtime
-
-No vault write occurs inside distill. Does not import from `src/engine/compile/`
-or `src/engine/wiki/`. Use `createStubAnalyzerProvider()` from
-`src/engine/distill/analyzer.js` for deterministic offline testing.
-
-## NOTES
-
-Wiki mirror deferred — the `wiki` skill is built by a parallel milestone (M3)
-and its adapter mirror is intentionally deferred until that milestone lands.
+No vault write occurs inside distill.

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

@@ -0,0 +1,87 @@
+---
+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.
+---
+
+# Skill: oms-link (Claude Code)
+
+Two-path skill — thin pointer to `core/skills/link`. Requires `OMS_VAULT`.
+
+## Invocation
+
+```
+/link
+```
+
+## Which path?
+
+Check **before acting**:
+- **Path A (pre-write):** you are about to write the note → learn the term
+  vocabulary first, then draft a body that already contains `[[wikilinks]]`.
+- **Path B (retrofit):** the note already exists → `oms linkify` or
+  MCP `oms_link_suggest` → `oms_link_apply`.
+
+These paths are **mutually exclusive**.
+
+## The link universe
+
+Only notes bound to the `term` concept in `vault/.oms/taxonomy.yaml` are link
+targets; their surface forms are the basename and the frontmatter `aliases`.
+`0 term note(s) available as link targets` means the vault has no term layer —
+build one with the `wiki` skill first.
+
+Three engine rules, not negotiable:
+- **Surface-anchored** — a link exists only where the term literally appears.
+- **First occurrence only** — one link per target note per body.
+- **Ambiguity is reported, never resolved** — `ambiguous: true` plus `rivalPaths`
+  means ask the user or skip the span.
+
+Frontmatter, code, existing links, headings, URLs, and tags are masked out; a
+"missing" link inside any of them is correct.
+
+---
+
+## Path A — pre-write linking
+
+*(Only while drafting, so no retrofit pass is ever needed for this note.)*
+
+### Agent-guided steps
+
+1. Call MCP `oms_link_suggest` on an existing note in the same folder (or
+   `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 `Write`/`Edit` never touches vault `.md`.
+4. Re-check with `oms_link_suggest`; zero candidates means the draft was already
+   fully linked.
+
+---
+
+## Path B — retrofit existing notes
+
+*(Only when the note is already on disk. Report first, always.)*
+
+### Batch
+
+```bash
+oms linkify --folder notes                  # report only, writes nothing
+oms linkify --folder notes --apply --yes    # rewrite in place
+```
+
+`--apply` without `--yes` refuses before reading any note and writes nothing.
+Show the report and get agreement before adding `--yes`. Writes go through the
+capture kernel, so path safety and the concept contract hold.
+
+### Single note
+
+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 on `note-changed`, `candidate-drift`,
+or overlapping candidates. Re-run `oms_link_suggest` for fresh offsets instead
+of retrying stale ids.
+
+After a retrofit run, run `oms doctor` (non-blocking, exits 0).