oh-my-second-brain 0.1.8 → 0.1.9

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.1.9",
   "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/retrieve/SKILL.md

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

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

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

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

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

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

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