oh-my-second-brain 0.15.0 → 0.17.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "oms",
       "description": "Oh My Second Brain convention layer for Obsidian vaults — capture, retrieve, and validate knowledge under a declared semantic convention.",
-      "version": "0.15.0",
+      "version": "0.17.0",
       "author": {
         "name": "gobeumsu",
         "email": "gobeumsu@gmail.com"
@@ -37,5 +37,5 @@
       ]
     }
   ],
-  "version": "0.15.0"
+  "version": "0.17.0"
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "oms",
-  "version": "0.15.0",
-  "description": "Oh My Second Brain convention layer for Obsidian vaults — seven shared skills and five MCP tools under a declared semantic convention.",
+  "version": "0.17.0",
+  "description": "Oh My Second Brain convention layer for Obsidian vaults — eight shared skills and five MCP tools under a user-owned contract.",
   "author": {
     "name": "gobeumsu"
   },
@@ -20,7 +20,6 @@
     "./assets/skills/link/",
     "./assets/skills/search/",
     "./assets/skills/status/",
-    "./assets/skills/template/",
     "./assets/skills/write/"
   ]
 }

package/.codex-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "oms",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults — Codex native rules, skills, and MCP adapter.",
-  "_note": "oms host install writes Codex MCP config and provenance, installs ~/.codex/rules/oms.md, and installs the seven shared skills under ~/.codex/skills/oms-*.",
+  "_note": "oms host install writes Codex MCP config and provenance, installs ~/.codex/rules/oms.md, and installs the eight shared skills under ~/.codex/skills/oms-*.",
   "skills": "./assets/skills/",
   "mcpServers": "./.mcp.codex.json"
 }

package/ACKNOWLEDGMENTS.md

@@ -6,6 +6,26 @@ oh-my-secondbrain은 아래 공개 작업들의 아이디어와 구현에 빚지
 > 우리가 무엇을 흡수했는지(설계 로직·근거)는 `docs/research/*` 에 기록한다.
 > 관리 규칙: [`docs/rules/external-attribution.md`](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/docs/rules/external-attribution.md)
 
+## 계약·평가·인터뷰 설계
+
+### Ouroboros
+
+- **저자 / 기여자**: Q00와 Ouroboros 기여자
+- **URL**: https://github.com/Q00/ouroboros
+- **라이선스**: [MIT](https://github.com/Q00/ouroboros/blob/main/LICENSE)
+- **흡수 종류**: absorbed logic — 설계 아이디어 참고, 코드 직접 이식 없음
+- **배운 점**: 명시적 계약, 작성과 평가의 책임 분리, 기계 검사와 의미 평가의 구분, 실제 산출물의 근거에 기반한 완료 판정.
+- **감사**: Ouroboros의 계약 중심 설계와 단계적 검증에서 많은 것을 배웠다. 그 배움을 사용자가 자신의 지식 체계와 정책을 소유하는 OMS의 철학으로 구체화할 수 있도록 공개해 주신 프로젝트와 기여자분들께 진심으로 감사드린다.
+
+### Gajae Code
+
+- **저자 / 기여자**: Yeachan-Heo와 Gajae Code 기여자
+- **URL**: https://github.com/Yeachan-Heo/gajae-code
+- **라이선스**: [MIT](https://github.com/Yeachan-Heo/gajae-code/blob/main/LICENSE)
+- **흡수 종류**: absorbed logic — 인터뷰 상호작용 설계 참고, 코드 직접 이식 없음
+- **배운 점**: [deep-interview](https://github.com/Yeachan-Heo/gajae-code/blob/main/packages/coding-agent/src/defaults/gjc/skills/deep-interview/SKILL.md)의 맥락 사전 확인, 한 번에 한 질문, 자유답변의 의도 확인, 결정 기록과 최종 승인.
+- **감사**: 사용자에게 같은 설명을 반복하게 하기보다 이미 표현한 의도를 정리하고 필요한 결정만 확인하는 인터뷰 방식에서 배웠다. OMS의 설정·계약 인터뷰를 구체화하는 데 도움을 준 공개 작업에 감사드린다.
+
 ## LLM-Wiki 패턴 & 구현체
 
 - https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
@@ -146,9 +166,9 @@ M5 거버넌스/컨벤션/셋업/어댑터 레이어 구현 과정에서 아이
 
 | Pattern | Source | License | Note |
 |---------|--------|---------|------|
-| Two-layer `.oms/governance/` (decisions/ + rules/ + architecture.md) mirroring document-ontology discipline | craft-skills `documents` skill | Internal skill, no external restriction | STRUCTURE-ONLY — all YAML independently authored (ADR-003 / ADR-006) |
+| Two-layer `.oms/governance/` (decisions/ + rules/ + architecture.md) mirroring document-ontology discipline | craft-skills `documents` skill | Internal skill, no external restriction | STRUCTURE-ONLY — all YAML independently authored (구 ADR-003 / 구 ADR-006; 현재 ADR-008) |
 | Thick-router (private) + generic-leaf (public) topology; monorepo + `private/` gitignore isolation | deep-interview R19 / R20 (self) | N/A — internal | No external code; user-ratified design decisions |
-| Layer-1 CONTRACT / Layer-2 GOVERNANCE separation invariants | ADR-006 (self) | N/A — internal | User-ratified 2026-06-13 |
+| Layer-1 CONTRACT / Layer-2 GOVERNANCE separation invariants | 구 ADR-006 (self; 현재 ADR-008) | N/A — internal | User-ratified 2026-06-13 |
 
 **Shared skills** (`assets/skills/`)
 

package/CHANGELOG-assets.md

@@ -4,6 +4,18 @@ Skills, agents, templates, and host guidance changes belong here.
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-09-25
+
+- **Breaking: host guidance describes the sealed contract.** The `interview` and `template` skills are deleted, leaving six skills. Guidance tells agents to write whole notes through `write {path, content, template?}`, to stay inside the sealed property pool, never to read or write `~/.oms/`, and to ask the user to run `oms setup` on `contract-unreadable`.
+- **The `link` skill describes the payload it returns.** A suggestion carries a `baseContentHash` and a stable `id` per candidate, and `link { op: "check" }` requires `notePath`.
+
+## [0.16.0] - 2026-09-23
+- Live host-facing docs no longer show a copyable `interview-next` call without `proposals`. Confirming the template notice still starts that mode, but the same proposals array must reach review, answer, and commit.
+- Search, status, and write skills now say `templateNotice.next` is a mode hint, not a replayable `interview-next` CallToolRequest.
+
+- Eight shared skills now include a tool-less contract interview. Guidance separates agent-owned note writing from OMS guidance, saved-file checks, and completion using a separate reviewer; search and ordinary note errors do not start configuration interviews. Generated GJC mirrors share the authored skill bytes.
+- Reviewer guidance distinguishes host claims, agent transcription, and OMS-computed digests. Matching role-definition bytes is not proof of a separate launch, enforced tool restrictions, or whole-vault immutability.
+
 ## [0.15.0] - 2026-09-19
 
 - **Host guidance now teaches selected-folder template sources instead of per-file registration or folder modes.** It documents the exact `템플릿에 변경이 있습니다` / `확인하기` / `나중에` notice, host-only deferral, long-lived `templateNotice` results, and the resumable `interview-next` → `interview-answer` → `commit-contracts` flow that publishes only user-confirmed controls. Placement is write-time only (explicit destination, then taxonomy default, then `ask`); source review preserves Markdown bytes and does not invent a registration prerequisite, widget, or host configuration.

package/CHANGELOG-cli.md

@@ -4,6 +4,18 @@ Changes to the `oms` command surface belong here.
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-09-25
+
+- **Breaking: `oms template` is removed; the contract lives under `oms setup` and `oms contract setup|extract|status|doctor`.** `oms setup` is interactive only and refuses to run without a TTY or under `OMS_NON_INTERACTIVE=1`. `oms note guide` and `oms note check` are removed; `oms note audit` judges existing notes against the seal. `oms hook pre` replaces the retired hook leaves. Older `.oms/*` files are ignored and a `templateRoots` settings key is rejected. Upgrade order: (1) install this release and run `oms host sync`; (2) back up `.oms/settings.json` and keep only `version`, `vaultId`, `templateFolder` (formerly `templateRoots`), `embedding`, and `agentRepair`; (3) run `oms setup` at a terminal to seal the vault; (4) run `oms contract doctor` and review the unexpected control files it lists under `.oms/`; (5) keep those backups while a rollback to 0.16.0 is still possible.
+- **Breaking: `oms setup` is the interactive vault-contract seal, the same as `oms contract setup`.** It needs an interactive terminal and refuses `--dry-run`, `--yes`, `--approval-token`, `--approved-digest`, `--install-claude`, `--models-default`, `--models-descriptor`, `--models-no-default`, and `--template-folder`, naming the command that now owns each concern (`oms host install`, `oms model install --default`, `oms model install --descriptor`, `oms model waive --yes`). Embedding remedies point at `oms model install` and `oms model select` rather than `.oms/models.json`.
+- **`oms --help` describes real vault resolution.** It said an omitted `--vault` defaults to the current directory, hiding that resolution checks local vault controls, a bridge link, and `OMS_VAULT` first and treats the current directory as a read-only fallback that cannot admit a mutation.
+- **`oms note` drops an empty repeatable-flag branch.** The set was permanently empty, so its accumulation path could never execute and the option type promised arrays the parser never produced.
+- **`oms bridge` reports the stage that actually blocked.** Vault publication, global registry, reservation, and project projection each report their own bounded code and reason; stages that were never attempted are reported as unattempted rather than as failures, and malformed registry bytes are preserved exactly as found.
+
+## [0.16.0] - 2026-09-23
+
+- Host discovery reports the eight actual Codex skill paths and installed reviewer-definition health instead of the retired setup skill. Discovery and installation now resolve relative host-home overrides consistently; definition health is not reviewer execution proof.
+
 ## [0.15.0] - 2026-09-19
 
 - **Breaking: the template CLI now exposes a selected-folder census and linear review flow.** The exact leaves are `scan|list|show|add|update|move|remove|default|check|regenerate-types|review|answer|commit`; `scan` is read-only, `add <folder>` selects source scope, and `add --id <id> --from <file>` remains explicit source authoring rather than contract review. `answer <question-id> --answer <JSON> --census-digest <digest> --ledger-digest <digest|null>` forwards server-returned CAS fields, while `commit` adds the existing dry-run or `--yes --approved-digest` guard. This removes the per-file registration ritual without weakening verified-target writes; note creation considers `--folder <note-folder>` before a taxonomy default and then `ask`, with no template-creation target-folder form.

package/CHANGELOG-kernel.md

@@ -4,6 +4,22 @@ Domain logic changes belong here.
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-09-25
+
+- **Breaking: the sealed contract replaces the `.oms/` policy files.** Older `.oms/*` files (template policy, taxonomy, type projection) are no longer read; `oms contract doctor` reports them as unexpected control files. `.oms/settings.json` accepts only `version`, `vaultId`, `templateFolder`, `embedding`, and `agentRepair`, and a `templateRoots` key is rejected as `VAULT_SETTINGS_INVALID`. The contract is stored under `~/.oms/vaults/<vault-id>/` and one judge (`src/kernel/contract/judge.ts`) decides every write. Upgrade order: (1) install this release and run `oms host sync`; (2) back up `.oms/settings.json` and keep only `version`, `vaultId`, `templateFolder` (formerly `templateRoots`), `embedding`, and `agentRepair`; (3) run `oms setup` at a terminal to seal the vault; (4) run `oms contract doctor` and review the unexpected control files it lists under `.oms/`; (5) keep those backups while a rollback to 0.16.0 is still possible.
+- **Breaking: folder meaning and exclusion come from the sealed `folders.json`, and the embedding model from `.oms/settings.json`.** Search intent, the graph folder axis, and the exclusion inventory no longer read `.oms/taxonomy.json`; runtime code no longer reads or writes `.oms/models.json`, `.oms/taxonomy.json`, `.oms/template-policy.json`, or `contract-public.json`, so a vault's `.oms/` holds only `settings.json`. The selected embedding model is `settings.json` `embedding.model`; a vault configured only through `models.json` must reselect its model with `oms model select`. `parseModelsConfig` and `ModelsConfigV1` remain in the embed config module for callers that still parse a descriptor. The contracts index no longer re-exports the template policy.
+- Search query responses summarize at most 20 facet values and disclose truncation, keeping large link vocabularies out of ordinary agent responses without reducing hit counts or pagination. Collection facets are merged before summarizing. (#143)
+- **The decision records are consolidated into nine topic records** under `docs/decisions/`, and `docs/release.md` uses version placeholders instead of fixed 0.13.0-to-0.14.0 examples that could go stale.
+
+## [0.16.0] - 2026-09-23
+- Guide now binds a saved note to the template it declares when the caller omits `templateId`, matching check. Passing `templateId: null` still uses the default layer only.
+
+- Version 4 contracts compose a user-owned property pool, an always-on default layer, and optional additive template constraints. Approved Markdown remains byte-exact; raw source or managed-draft drift reports locally without replacing the approved snapshot. Full derived-projection validation and transaction-generation checks reject inconsistent writing evaluations.
+- Contract publication confines outputs to approved controls and managed drafts, checks exact approval and current-byte preconditions, and supports honest interrupted-publication recovery. A completed publication marker does not make later user draft edits a global reading failure.
+- Search source exclusions and taxonomy intent no longer require a valid writing contract. Missing raw templates or invalid policy cannot block ordinary-note scanning; explicit exclusion and taxonomy errors remain visible.
+- Native embedding diagnostics now use stderr through node-llama-cpp's logger callback, keeping diagnostic output separate from MCP stdout without suppressing warnings. (#133)
+- Native SQLite ABI mismatches report the actual Node executable, version, module ABI and addon path with rebuild guidance. The original loader error remains the cause; unrelated opening errors are not relabeled, and no backend fallback or automatic rebuild occurs. (#139)
+
 ## [0.15.0] - 2026-09-19
 
 - **Breaking: template contracts now reconcile from an explicit selected-folder census instead of per-file registration or auto/manual modes.** Every `.md` beneath the selected scope is classified for add, edit, delete, or rename; source bytes stay in place and only user-confirmed `.oms` controls publish. The two-tier freshness gate hashes raw shared authorities first and then isolates changed templates as pending while preserving unrelated note writes. Metadata and bounded body-node contracts (with per-node requiredness/order) replace opaque body assumptions; anchored resumable questions and a locked CAS preserve unaffected answers. Historical ledger census is not blanket stale rejection: current request CAS and per-answer anchors govern validity. Ambiguous repeated body nodes remain contextualized, missing required-body rules require explicit disposition, and placement is optional during review then resolves at note creation by explicit destination, taxonomy default, or `ask`.

package/CHANGELOG-mcp.md

@@ -4,6 +4,17 @@ MCP server tools and resources belong here.
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-09-25
+
+- **Breaking: `write` takes `{path, content, template?}` with no `op`.** The whole note is judged against the sealed contract and saved atomically only when allowed; a denial returns `{field, kind}` violations and one guidance command. The `guide`, `check`, and `template` operations and the `folderIntents` input are removed. `search` `templates` returns the sealed folders, property names and types, and templates; `doctor` `validate` diagnoses the seal, and `doctor` `regenerate-types` is removed with no alias.
+- **Breaking: retrieval metadata reads the sealed folder contract.** Search responses rename `taxonomyIntents` to `folderIntents`, semantic status reports `folderContext` instead of the taxonomy context, and `projectionSource` names `folders.json` (the sealed contract) instead of `.oms/template-policy.json`. A vault without a sealed contract reports `vault-invalid` and its remediation points at `oms setup`.
+- **An unreachable search fallback is gone.** Every `oms_semantic_query` path returns inside its own block, so the later ephemeral-lexical branch keyed on that tool name could never run. Search's model-free lexical path stays where it actually executes.
+- Tool schemas expose operation names and arguments at the top level so hosts can discover them without unpacking branch schemas. Strict operation-specific validation and approval requirements remain enforced. (#144)
+
+## [0.16.0] - 2026-09-23
+- Host-facing docs no longer show a copyable `interview-next` call without `proposals`. Confirming the template notice still starts that mode, but the same proposals array must reach review, answer, and commit.
+- The machine template notice `next` field is a mode hint (`skill: interview`, `mode: interview-next`), not a replayable CallToolRequest. OMS still does not invent proposals; `확인하기` enters `/interview`.
+
 ## [0.15.0] - 2026-09-19
 
 - The bundled MCP SDK now resolves `hono` 4.13.8, clearing the moderate advisory group that affected its HTTP transport's body and query parsing. Only the lockfile moves; no declared dependency is added or changed.

package/CHANGELOG-vendors.md

@@ -4,6 +4,17 @@ Per-host adapter and installer changes belong here.
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-09-25
+
+- **Breaking: the Claude guard follows the judge.** The PostToolUse hook and the `oms-post-guard` bin are removed, and `OMS_GUARD` no longer exists. The PreToolUse write matcher is now `Write|Edit|MultiEdit|NotebookEdit`, and a second PreToolUse entry for `Read|Grep|Glob` denies access under `~/.oms/`. A write that the judge finds in violation is denied; when the judge cannot run, the call is allowed with a warning. The hook output format changed accordingly. Codex and Hermes still declare no write hook. Run `oms host sync` after upgrading to rewrite the registration.
+- **The `oms-reviewer` host role is retired.** It was built around a completion protocol that no longer exists, so no surface could produce its request or consume its result. The Claude plugin agent, the Codex custom-agent role and its shipped asset, the harness reviewer registry, and the reviewer asset-health lane are gone with no alias. `oms host remove` still deletes a role and provenance sidecar an earlier version installed, and only when the OMS-written provenance record proves ownership; a foreign agent file is still left in place and reported.
+- **Shipped host instructions no longer describe a completion reviewer or a retry budget.** The Claude and Codex guidance and the installed Hermes adapter README drop the semantic reviewer handshake and the finite retry budget; `agentRepair` lives in the portable `.oms/settings.json`.
+
+## [0.16.0] - 2026-09-23
+
+- Codex installs an optional provenance-owned reviewer role while preserving unowned collisions; a genuine generic separate subagent remains valid without custom-role discovery. Dry-run skill paths now match the eight installed shared skills.
+- Hermes guidance uses its native fresh-conversation delegation with inherited tools and explicit non-modification instructions, without claiming unavailable sandbox enforcement.
+
 ## [0.15.0] - 2026-09-19
 
 - **Claude, Codex, and Hermes guidance now aligns with folder-sourced template contracts.** Each native host surface explains selected-folder census without per-file registration or folder modes, the exact minimal notice and host-only `나중에`, and the resumable `interview-next` → `interview-answer` → `commit-contracts` flow. Review preserves source bytes and publishes only user-confirmed controls; affected-template pending remains scoped while shared-authority failures stay fail-closed globally. Note creation uses explicit folder, taxonomy default, then `ask`, without changing the host-specific skill/tool asymmetry.

package/CHANGELOG.md

@@ -10,6 +10,13 @@ This aggregate changelog contains changes that span multiple layers.
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-09-25
+
+- **Breaking: the vault contract is sealed once by the user and judged on every write.** The interactive `oms setup` interviews folders, the property pool, and templates together and seals the contract under `~/.oms/vaults/<vault-id>/`, outside the vault; `.oms/settings.json` is the only OMS file inside it. One judge decides MCP `write {path, content, template?}` and the Claude guard hook, and a violation is refused with `{field, kind}` entries and one guidance command. `oms template`, the MCP `write` guide, check, and template operations, the `interview` and `template` skills, the PostToolUse hook, and `OMS_GUARD` are removed. The public surface is six skills, five MCP tools, and fourteen CLI families. Upgrade order: (1) install this release and run `oms host sync`; (2) back up `.oms/settings.json` and keep only `version`, `vaultId`, `templateFolder` (formerly `templateRoots`), `embedding`, and `agentRepair`; (3) run `oms setup` at a terminal to seal the vault; (4) run `oms contract doctor` and review the unexpected control files it lists under `.oms/`; (5) keep those backups while a rollback to 0.16.0 is still possible.
+
+## [0.16.0] - 2026-09-23
+- **Breaking: OMS is a user-owned contract and completion harness, not a note writer or template renderer.** Version 4 of `.oms/template-policy.json` is the only approved structure and meaning: an always-on empty default layer, optional templates that only add or tighten, and unmanaged frontmatter left unchecked. Agents write and repair notes. OMS guides, checks the saved file, and completes from a separate host review. Search stays read-only even when the contract is missing or mid-publish. Contract meaning enters only through explicit `proposals` on `interview-next`, `interview-answer`, and `commit-contracts`; a recorded answer whose proposals were omitted is refused rather than dropped. The public surface is eight skills (`interview` and `template` are tool-less), five MCP tools, and fourteen CLI families. Retired v3 registration, note-write, link-apply, and renderer paths are deleted, not aliased. The machine template notice `next` field is a mode hint into `/interview`, not a replayable CallToolRequest.
+
 ## [0.15.0] - 2026-09-19
 
 - **Breaking: a selected template folder, not a per-file registration step, is what makes a template usable.** Every `.md` beneath a folder you explicitly select is a census candidate tracked by content hash, so adding, editing, deleting, or renaming a source is picked up without registering each file and without the retired auto/manual folder modes. This spans layers deliberately: the kernel owns the census, contract derivation, interview ledger, and guarded reconcile; the CLI gains `oms template review|answer|commit`; MCP gains the matching `interview-next`, `interview-answer`, and `commit-contracts` modes plus the notice carrier; and the shared skills and host guidance describe one vocabulary. The five MCP tools and seven skills are unchanged.

package/README.ko.md

@@ -1,143 +1,74 @@
 # Oh My Second Brain
 
-Oh My Second Brain(`oms`)은 기존 Obsidian/Markdown 볼트를 노트 소유권을 빼앗지 않고 AI 호스트에 연결한다. 볼트는 계속 평범한 Markdown이다.
+Oh My Second Brain(`oms`)은 기존 Obsidian·Markdown 볼트를 AI 호스트와 연결하되 노트의 소유권은 가져가지 않는다. 볼트는 계속 평문 Markdown이고, Obsidian이 사령탑으로 남는다. OMS가 꺼져 있어도 노트는 사람이 읽고 고칠 수 있는 파일이다. OMS는 속성·폴더·heading의 의미를 스스로 만들어내지 않는다.
 
-## 템플릿·온톨로지 볼트 모델
+## 볼트 계약
 
-- 볼트에 실제로 존재하는 Obsidian `.md` 템플릿이 관리 노트의 frontmatter 형태와 본문 골격을 소유한다.
-- 각 템플릿은 경로·digest와 독립적인 안정적 `templateId`를 가지며, 볼트 전체의 `BaseContract` 하나를 상속한다.
-- `.obsidian/types.json`은 읽기 전용 타입 권위다.
-- 사용자 소유 온톨로지는 계속 활성 상태다. `.oms/template-policy.json`은 노트·필드 의미와 필수값, 형식, 허용값, 기본값, 이름 규칙, 정체성, 바인딩을 기록한다.
-- `.oms/taxonomy.json`은 폴더·링크 의미와 배치를 소유하며, 작성된 폴더 의미는 `folder-ontology` 검색 축으로 노출된다. runtime의 유일한 권위다.
-- `.oms/types.json`은 쓰기·검색용 검증된 파생 projection이다. 직접 편집하지 않는다.
+의미는 사용자에게 남는다. 사용자는 터미널에서 대화형 `oms setup`을 한 번 실행해 볼트 계약을 봉인한다. 인터뷰는 세 부분을 함께 다룬다. 폴더(각 폴더의 의미와 배치 가능 대상), 속성 pool(각 속성의 type과 intent), 템플릿(템플릿 폴더의 각 템플릿이 선언하는 것)이다. 제품은 속성 이름·폴더·페르소나를 하드코딩하지 않고 Inbox fallback도 없다.
 
-제거된 것은 노트 정체성으로서의 `concept`와 번들 runtime 기본값이지, 의미 계층으로서의 온톨로지가 아니다.
+봉인된 계약은 볼트 밖 `~/.oms/vaults/<vault-id>/`에 있다. 볼트 안의 OMS 파일은 `.oms/settings.json` 하나이며 `version`, `vaultId`, `templateFolder`, `embedding`, `agentRepair`를 담는다. `.oms/`의 다른 항목은 `oms contract doctor`가 예상하지 않은 제어 파일로 보고하고, 그 밖에는 무시한다. `.obsidian/types.json`은 읽기 전용 관측값이며 봉인을 덮어쓰지 않는다.
 
-## 설정
+템플릿은 `templateFolder` 안의 사용자 Markdown 파일 그대로 남는다. 봉인은 템플릿이 선언한 것을 기록할 뿐이며, OMS는 템플릿을 다시 쓰거나 복사하거나 노트에 적용하지 않는다. `oms contract status`는 봉인된 각 템플릿을 live 파일과 비교해 `active`, `drift`, `missing`으로 보고한다. drift는 보고만 하고 조용히 재봉인하지 않는다. 재봉인은 사용자가 `oms setup`으로 한다. OMS는 Templater, JavaScript, 전용 token 언어를 해석하거나 실행하지 않는다.
 
-Setup은 명시적으로 선택한 템플릿 폴더 안의 기존 템플릿을 재귀 탐색하고
-migration을 제안한다. 노트 타입 기본값을 번들로 강요하지 않으며 노트를
-수정하지 않는다.
+노트를 쓰는 주체는 에이전트다. 하나의 판정자가 모든 쓰기를 봉인에 비추어 판정한다. 거부된 쓰기는 파일을 바꾸지 않고 `{field, kind}` 위반과 안내 명령 하나만 돌려주며, 규칙 값·저장소 경로·계약 본문은 돌려주지 않는다. 이 기기에 봉인이 없는 볼트는 판정하지 않는다. 이 기기의 봉인 증거가 볼트와 맞지 않으면 사용자가 `oms setup`을 다시 실행할 때까지 쓰기를 `contract-unreadable`로 거부한다. OMS에는 완료 호출도 리뷰어 대화도 없다. 허용된 쓰기는 노트가 봉인된 구조에 맞는다는 뜻이지 보존할 가치가 있다는 뜻이 아니다.
 
-```bash
-oms setup --vault /path/to/vault --dry-run
-oms setup --vault /path/to/vault --yes --approved-digest <표시된-digest>
-```
+볼트 계약은 ADR-007(소스 저장소의 `docs/decisions/`)에 기록되며, 구 ADR-013–016을 대체한다. [ACKNOWLEDGMENTS](./ACKNOWLEDGMENTS.md)는 Ouroboros와 Gajae Code의 deep-interview를 설계 아이디어로 밝힌다. 이는 runtime 복제도 연구 결과도 아니다. 저장소의 도식은 설명용 스케치다. 이 문서들은 승인된 아키텍처 기록이지 host smoke 결과나 제품 gate 통과가 아니다.
 
-관리 템플릿 변경도 dry-run, 호출자가 검토한 정확한 digest, CAS, transaction, 사후조건 receipt를 거친다.
-
-## 템플릿 흐름
-
-명시적으로 선택한 템플릿 폴더 아래의 모든 `.md`는 템플릿 원본
-후보가 된다. review는 원본을 검증하고 같은 위치의 바이트를 보존하며,
-파일별 등록 절차나 auto/manual 폴더 mode는 필요하지 않다. OMS는
-메타데이터 계약(frontmatter key·type·requiredness·`filledBy`)과 제한된
-본문 구조(ATX heading, fence code block, fence 밖의 ordered/unordered list
-run, `<!-- oms:content -->`, 문서 순서/EOL/BOM/final-newline)를 함께
-도출한다. paragraph, setext heading, 모든 Markdown을 강제한다고 주장하지
-않는다. 원본이 바뀌면 의존하는 템플릿만 pending이 되므로 다른 템플릿
-쓰기는 계속 가능하며, shared authority 변경이나 불일치는 볼트 전체를
-fail-closed 한다.
-
-선택한 폴더의 원본이 바뀌면 호스트에 처음 표시할 알림은 정확히
-`템플릿에 변경이 있습니다`이며, 동작은 정확히 `확인하기`와 `나중에`다.
-처음 알림에는 템플릿 이름·hash·change class를 표시하지 않는다.
-`나중에`는 host-only로 server를 호출하지 않고 interview ledger도 바꾸지
-않는다. `확인하기`는 MCP `write { op: "template", mode: "interview-next" }`로
-선형 resumable interview를 시작한다. 서버가 반환한 다음 질문을 따라
-진행하고 영향 없는 confirmed answer는 보존한다. 모든 필요한 질문 뒤에는
-정확한 최종 digest를 보여주고 사용자가 승인한 경우에만
-`mode: "commit-contracts"`로 `.oms` control만 publish한다. self-approve하지
-않는다. `status`와 search는 계속 읽기 전용이며 boot instruction이 stale한
-long-lived host도 반환된 `templateNotice`를 표시해야 한다.
-
-정확한 CLI review 흐름은 다음과 같다.
+권위 모델은 [아키텍처](./docs/architecture.md), 볼트 파일은 [컨벤션](./docs/conventions.md), leaf 목록은 [CLI 맵](./docs/cli-map.md)에 있다.
 
-```text
-oms template review
-oms template answer <question-id> --answer <JSON> --census-digest <digest> --ledger-digest <digest|null>
-oms template commit --census-digest <digest> --ledger-digest <digest|null> --dry-run
-oms template commit --census-digest <digest> --ledger-digest <digest|null> --yes --approved-digest <digest>
-```
-
-answer는 서버가 반환한 question과 CAS 값을 사용한다. commit은 같은 CAS
-값과 기존 dry-run 또는 yes/approved-digest guard를 함께 사용한다.
+## 설정
 
-정확한 note 생성 사용법은 다음과 같다.
+`oms setup`은 `oms contract setup`과 같은 명령이다. 볼트 전체를 인터뷰해 계약을 봉인한다. 볼트 안에는 `.oms/settings.json`만 쓰고 노트는 수정하지 않는다. 대화형 터미널이 없거나 `OMS_NON_INTERACTIVE=1`이면 실행을 거부하므로 에이전트는 실행하지 않는다. 언제든 다시 실행해 재봉인할 수 있다.
 
-```text
-oms note create [template-id] --body <text>|--body-file <file> [--frontmatter <json>|--frontmatter-file <file>] [--folder <note-folder>]
+```bash
+oms setup --vault /path/to/vault
+oms contract status --vault /path/to/vault
 ```
 
-노트 생성 시 배치 우선순위는 명시적 caller folder, taxonomy default, `ask`
-순서이며, 배치가 없다고 contract review를 막지 않는다.
+`oms contract extract --template <path>`는 템플릿 하나가 선언하는 것을 값 없이 보여준다. `oms contract doctor`는 봉인, 오래된 lock, 고아 generation, 예상하지 않은 제어 파일, hook 전송 실패를 진단한다. `--fix`는 이동했거나 색인되지 않은 볼트를 다시 색인할 뿐이다. 그 밖의 깨진 봉인은 `oms setup`을 다시 실행해 복구한다. 모델 수명주기는 `oms model install|select|waive|status`로 따로 존재한다.
 
 ## CLI
 
 ```text
-oms setup                                      기존 볼트 템플릿 탐색 및 채택
-oms template scan|list|show|add|update|move|remove|default|check|regenerate-types|review|answer|commit
-oms note create|append|update|audit|backfill|get
-oms link check|suggest|apply                   노트 wikilink 점검·제안·적용
 oms bridge add|remove|status                   저장소-볼트 target bridge 관리
-oms search query|context                       명시적 query 실행 또는 구조화 context 조회
-oms index sync|embed|repair|status|clean       파생 검색 상태 관리
+oms contract setup|extract|status|doctor       볼트 계약 봉인, 조회, 진단
 oms graph build|status                         노트 그래프 생성 또는 조회
+oms hook pre                                   Claude 쓰기를 vault 계약으로 판정
 oms host install|remove|sync|status            호스트 asset과 MCP 등록 관리
-oms package check|update                       OMS 패키지 확인 또는 업데이트
+oms index sync|embed|repair|status|clean       파생 검색 상태 관리
+oms link suggest|check                         노트 wikilink 제안 또는 검사
 oms model install|select|waive|status          로컬 모델 선택 관리
+oms note audit|get                             노트를 계약으로 감사하거나 읽기
+oms package check|update                       OMS 패키지 확인 또는 업데이트
+oms search query|context                       명시적 질의 실행 또는 구조화 context 조회
 oms serve mcp|http                             stdio MCP 또는 로컬 HTTP 서버 시작
-oms hook pre|post                              pre/post-tool-use 볼트 가드 실행
-oms status                                     읽기 전용 종합 상태 표시
+oms setup                                      볼트를 인터뷰하고 계약 봉인
+oms status                                     읽기 전용 통합 상태 표시
 ```
 
-`oh-my-second-brain`은 전체 명령이고 `oms`는 짧은 별칭이다.
+`oh-my-second-brain`이 전체 명령이고 `oms`는 짧은 별칭이다. 이 14개 family, 6개 스킬, 5개 MCP 도구는 서로 다른 집합이다. leaf 목록은 [CLI 맵](./docs/cli-map.md)에 있다.
 
 ### 도움말 계약
 
-인식된 모든 명령은 `--help`와 `-h`를 받아들이며, exit 0으로 종료하고
-부작용을 수행하지 않는다. 알 수 없는 명령에 `--help`를 함께 주면 exit 1로 종료한다.
-
-`oms search query <text>`는 lexical-only다. `--vec`, `--hyde`는 각각의
-typed channel을 선택하고, `--expand`는 G004 expansion을 명시적으로
-켜며, `--max-queries`는 1부터 32까지의 정수만 받는다. `--rerank`도
-opt-in이다. `oms search context`는 별도의 구조화 context 표면이다.
-Embedding은 명시적으로 `oms index embed`를 사용하며 sync와 repair는
-서로 다른 index mode다. `oms index status --view status|collections|contexts`는
-세 읽기 전용 view를 모두 보존하고, `oms index clean`은 제거 가능한 파생
-상태를 정리한다.
-
-Vector 검색에는 검증된 로컬 embedding capability가 필요하다. 선택 경로는
-완전한 `OMS_EMBEDDING_PROVIDER`/`OMS_EMBEDDING_MODEL` 쌍, vault의
-`.oms/models.json`과 검증된 설치 receipt, 또는 setup-installed default다.
-HyDE에는 resolved generate capability가, reranking에는 resolved rerank
-capability가 필요하다. 각각의 완전한 환경변수 쌍은
-`OMS_GENERATE_PROVIDER`/`OMS_GENERATE_MODEL`과
-`OMS_RERANK_PROVIDER`/`OMS_RERANK_MODEL`이다. 누락되거나 불완전하거나
-설치되지 않은 선택은 크게 실패한다. G004
-expansion은 명시적으로 사용할 수 있는 기능이며, 교체·parity·outperformance를
-주장하지 않는다.
-Setup에서는 로컬 검증 acquisition 정책 하나를 선택한다:
-`--models-default`, `--models-descriptor <path>`, `--models-no-default`.
+인식되는 모든 명령은 `--help`와 `-h`를 받으며, exit 0으로 끝나고 부작용이 없다. 알 수 없는 명령에 `--help`를 붙이면 exit 1이다.
+
+일반 `oms search query <text>`는 lexical 전용이다. `--vec`와 `--hyde`는 각 채널을 선택하고, `--expand`는 G004 확장을 명시적으로 켜며, `--max-queries`는 1부터 32까지의 정수를 받고, `--rerank`는 opt-in이다. `oms search context`는 별도의 구조화 context 표면이다. embedding은 `oms index embed`이고 sync와 repair는 서로 다른 index 모드다. `oms index status --view status|collections|contexts`는 세 가지 읽기 전용 view를 유지하고, `oms index clean`은 제거 가능한 파생 상태를 지운다.
+
+lexical, vector, HyDE, typed-axis 질의는 계약을 통과하지 못할 노트도 계속 포함한다. 계약이 없거나 손상되어도 검색은 멈추지 않는다. vector 검색에는 완전한 `OMS_EMBEDDING_PROVIDER`/`OMS_EMBEDDING_MODEL` 쌍이 필요하다. HyDE에는 `OMS_GENERATE_PROVIDER`/`OMS_GENERATE_MODEL`도 필요하다. reranking에는 `OMS_RERANK_PROVIDER`/`OMS_RERANK_MODEL`이 필요하다. 없거나 불완전하거나 설치되지 않은 선택은 크게 실패한다. G004 확장은 명시적으로 쓸 수 있는 기능이며 대체·동등·우월을 주장하지 않는다.
+
+`oms note audit`는 기존 노트를 봉인에 비추어 판정하고 `{path, field, kind}` 항목을 보고한다. 노트를 다시 쓰지 않는다. create, append, update, backfill은 폐기된 노트 작업이다. link apply는 작업이 아니다. 폐기된 작업을 위한 노트 렌더러나 호환 경로는 없다.
 
 ## MCP 도구
 
-`oms serve mcp`는 정확히 다섯 개의 공개 도구를 노출한다:
+`oms serve mcp`는 정확히 다섯 개의 공개 도구를 노출한다.
 
 `write` · `search` · `link` · `status` · `doctor`
 
-일곱 스킬(`write`, `search`, `link`, `distill`, `status`, `doctor`, `template`)은 워크플로 안내이며 MCP 도구와 같은 집합이 아니다. 세부 기능은 다섯 도구의 `op` 값으로 제공한다.
-
-쓰기는 하나의 `ResolvedTemplate`을 해석해 create, append, update를 수행한다. 템플릿 변경, projection 재생성, 한 노트 정체성 backfill은 검증된 target과 명시적 승인 digest가 필요하다. `status`와 모든 검색 동작은 읽기 전용이다.
+6개 스킬(`distill`, `doctor`, `link`, `search`, `status`, `write`)은 호스트 workflow다. `distill`은 도구가 없다.
 
-템플릿 contract review는 `oms_write`의 `op: "template"`에서 정확히
-`interview-next`, `interview-answer`, `commit-contracts` mode를 사용한다.
-정확한 CLI 대응은 `oms template review`, `oms template answer`,
-`oms template commit`이다. answer는 서버가 반환한 question, request, CAS
-field를 그대로 사용하며 parameter 이름을 만들지 않는다. 질문이 0개면
-곧바로 최종 확인으로 간다.
+다섯 도구는 스킬의 부분집합이며, 두 집합 모두 14개 CLI family와 다르다. 세부 기능은 다섯 도구 아래의 `op` 값으로 남는다. 봉인에는 MCP 작업도 스킬도 없다.
 
-일반 lexical 검색은 projection과 독립적이다. 템플릿·선언 필드·폴더·링크 축은 쓰기와 같은 projection을 사용하며 누락·stale 상태를 크게 실패시킨다. 관리 템플릿 원본은 검색 대상에서 제외한다. Vector/HyDE는 provider와 model이 모두 설정되지 않으면 가짜 대체 없이 실패한다.
+`write {path, content, template?}`는 노트 전체를 판정해 허용될 때만 저장한다. `template`은 선택 사항이며 노트가 따르는 봉인된 템플릿을 가리킨다. `status`와 모든 search 작업은 읽기 전용이다. `doctor` 도구는 봉인을 검증하고 노트를 감사하며 명시적인 index 유지보수를 실행한다. 노트를 backfill하지 않는다. 볼트 안에서 Claude의 기본 Write, Edit, MultiEdit, NotebookEdit는 `oms hook pre`를 통해 같은 판정자에 도달한다. Codex와 Hermes에는 쓰기 hook이 없으므로 MCP `write`로 쓴 노트만 판정된다.
 
 ## 설치
 
@@ -148,21 +79,12 @@ npm install -g oh-my-second-brain
 oms host install --runtime all --vault /path/to/vault --yes
 ```
 
-Gajae-Code에서는 npm 패키지를 marketplace plugin으로 설치한다: `gjc plugin install oms@oms`. GJC는 패키지 루트의 `skills/` convention path에서 일곱 OMS skill을 발견한다.
+Gajae-Code에서는 npm 패키지를 marketplace plugin으로 설치한다: `gjc plugin install oms@oms`. GJC는 패키지 루트의 `skills/` 관례 경로에서 여섯 OMS 스킬을 찾는다.
 
-호스트 설치는 canonical 볼트를
-`${XDG_CONFIG_HOME:-~/.config}/oms/vault.json`에 기록하고 각 관리형
-등록에 `oms serve mcp --vault /path/to/vault`를 넣는다.
-`oms host install|remove|sync|status`만 이 서명된 포인터로 호스트 통합을
-관리한다.
-`oms package update`는 패키지만 업데이트하고 호스트를 암묵적으로
-동기화하지 않는다. `oms host sync`는 별도로 실행한다.
+호스트 설치는 정식 볼트를 `${XDG_CONFIG_HOME:-~/.config}/oms/vault.json`에 기록하고, 관리하는 각 호스트 항목에 `oms serve mcp --vault /path/to/vault`를 새긴다. `oms host install|remove|sync|status`는 그 서명된 pointer를 호스트 통합 유지보수에만 쓴다. `oms package update`는 패키지를 업데이트하지만 호스트를 암묵적으로 sync하지 않는다. `oms host sync`를 따로 실행한다.
 
-런타임 쓰기·검색 target 해석은 호스트 관리 포인터를 읽지 않는다.
-우선순위는 명시적 target, 로컬 볼트 control, bridge, `OMS_VAULT`, 그리고
-안전한 읽기 전용 fallback으로서의 cwd 순서다. 변경 작업은 cwd fallback을
-사용할 수 없다.
+runtime target 해석은 호스트 유지보수 pointer를 읽지 않는다. 우선순위는 명시적 target, 로컬 볼트 제어 파일, bridge, `OMS_VAULT`, 그리고 안전한 읽기 전용 fallback으로서의 현재 디렉터리다. 봉인, 노트 쓰기, 파생 상태 repair는 그 fallback을 쓸 수 없다.
 
-`OMS_VAULT`는 명시적·로컬·bridge target이 없을 때 사용하는 지원 환경변수 fallback이다.
+`OMS_VAULT`는 명시적·로컬·bridge target이 없을 때 지원되는 환경 변수 fallback이다.
 
-자세한 내용은 [설치](./docs/install.md), [아키텍처](./docs/architecture.md), [컨벤션](./docs/conventions.md), [검증된 target](./docs/verified-target.md)을 참고한다.
+[설치](./docs/install.md), [아키텍처](./docs/architecture.md), [컨벤션](./docs/conventions.md), [CLI 맵](./docs/cli-map.md), [호스트 asset](./docs/adapters.md), [검증 대상](./docs/verified-target.md)을 참고한다.