oh-my-second-brain 0.8.4 → 0.10.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.8.4",
+      "version": "0.10.0",
       "author": {
         "name": "gobeumsu",
         "email": "gobeumsu@gmail.com"
@@ -37,5 +37,5 @@
       ]
     }
   ],
-  "version": "0.8.4"
+  "version": "0.10.0"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.8.4",
+  "version": "0.10.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults — capture, retrieve, and validate knowledge under a declared semantic convention.",
   "author": {
     "name": "gobeumsu"
@@ -20,6 +20,7 @@
     "./assets/skills/link/",
     "./assets/skills/search/",
     "./assets/skills/status/",
+    "./assets/skills/template/",
     "./assets/skills/write/"
   ]
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.8.4",
+  "version": "0.10.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults — Codex native rules, skills, and MCP adapter.",
   "_note": "oms install writes Codex MCP config, installs ~/.codex/rules/oms.md, and installs ~/.codex/skills/oms-*.",
   "skills": "./assets/skills/",

package/CHANGELOG-assets.md

@@ -1,9 +1,21 @@
 # Assets Changelog
 
-Skills, agents, and ontology data changes belong here.
+Skills, agents, templates, and host guidance changes belong here.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-01
+
+### Changed
+
+- **The `/search` skill now documents an explicit `strategy` in `oms_search` calls with `op: "query"`.** Its frontmatter is unchanged.
+
+## [0.9.0] - 2026-08-31
+
+### Changed
+
+- **The seven shared skills, including the tool-less template authoring workflow, now teach stable template IDs, derived axes, explicit repair approval, and template/ontology coexistence.** Claude, Codex, and Hermes guidance separates template-owned shape from user-owned note/field/folder/link meaning. It no longer describes `concept` identity, personas, retrieval lenses, hand-edited projection state, or bundled note-type defaults.
+
 ## [0.8.4] - 2026-08-30
 
 ## [0.8.3] - 2026-08-29

package/CHANGELOG-cli.md

@@ -4,6 +4,26 @@ Changes to the `oms` command surface belong here.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-01
+
+### Breaking
+
+- **OMS now has one search taxonomy.** `oms semantic` and the old top-level collection, context, cleanup, and HTTP aliases are removed; use `oms search`, `oms doc get|multi-get`, `oms embed`, and `oms serve`. `oms index` contains exactly `sync|status|cleanup|collections|contexts`; embedding remains the compact top-level `oms embed` command.
+- **Setup model options have changed.** `--embedding-*` is replaced by `--models-default`, `--models-descriptor`, and `--models-no-default`.
+- **The embedding runtime is local-only.** The former Upstage provider path is removed; configured model identities must resolve to verified local GGUF artifacts.
+
+### Added
+
+- **Search now uses an explicit closed qmd-v2.8.3 expansion strategy.** `--max-queries` is strict, reranking is opt-in, and local model-set descriptors are supported.
+- **`oms serve` exposes only the canonical HTTP endpoints.** `/health`, `/search`, `/get`, and `/multi-get` remain; no query alias or second MCP tool surface is advertised.
+
+## [0.9.0] - 2026-08-31
+
+### Changed
+
+- **`setup`, `doctor`, `audit`, and `linkify` now expose the template contract directly.** Setup uses dry-run plus `--approved-digest`, doctor reports template/projection health and renames the report cap to `--max-per-template`, audit fails closed against resolved template identities, and linkify uses the same stable identities as write/search. Retired Concept authoring and `--suggest-fields` are no longer accepted.
+- **Host lifecycle commands now maintain a strict signed XDG vault pointer.** `install`, `update`, public `reconcile`, and `uninstall` compare-and-swap host stamps without affecting runtime vault resolution; `--template-folder` is also bound into setup discovery and its approval digest.
+
 ## [0.8.4] - 2026-08-30
 
 ## [0.8.3] - 2026-08-29

package/CHANGELOG-kernel.md

@@ -4,6 +4,22 @@ Domain logic changes belong here.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-01
+
+### Changed
+
+- **The kernel now manages model lifecycle explicitly and carries active-template taxonomy context through the canonical engine search path.** It reports unavailable capabilities honestly instead of silently claiming support.
+- **Local model execution now has one strict lifecycle.** Vault model selection outranks setup defaults, GGUF contexts wait for admitted work before disposal, cross-encoder reranking receives bounded note content rather than filenames, and the inconsistent Upstage branch is removed.
+
+## [0.9.0] - 2026-08-31
+
+### Changed
+
+- **The domain kernel now keeps template shape and ontology meaning separate end to end.** Vault-resident Markdown templates own frontmatter/body shape; template policy carries note/field `intent`, naming, and defaults; taxonomy carries folder/link `intent` and placement; and Obsidian owns property types. They resolve into one signed projection shared by write, graph, link, search, setup, migration, diagnosis, and repair. Field intent is retained on search axes and folder intent is exposed through the derived `folder-ontology` axis. Legacy `concept` identity, bundled ontology runtime loaders, old capture APIs, writable projection contracts, graph cache, and fallback behavior were removed; managed template sources stay outside note indexes and embeddings.
+- **Template migration and repair are guarded transactions.** Setup discovers existing templates and publishes only after an explicit approval digest; projection regeneration, template mutation, relocation/reclassification, and one-note identity backfill use verified targets, compare-and-swap expectations, and read-back postcondition receipts.
+- **Migration now preserves legacy meaning while cutting over synchronously.** URL formats, enum/immutable field semantics, retrieval views, legacy type/allowed-value/axis contracts, unknown extensions, string/list/null taxonomy cardinality, raw source bytes, and provenance survive translation; one-to-many legacy routes materialize deterministic stable template clones. Unmarked managed-folder notes block activation. Durable checksummed plans can resume after interruption, invalid markers fail closed, taxonomy owns placement, and unbound templates route to the safe `Inbox/` fallback rather than their source folder.
+- **Template rendering uses one exact source layout and instant.** `{{date}}` and `{{time}}` render as UTC `YYYY-MM-DD` and `HH:mm`, title-dependent templates require a non-empty title, only a standalone content-marker line is replaced, and BOM/EOL/final-newline semantics flow from the resolved source.
+
 ## [0.8.4] - 2026-08-30
 
 ## [0.8.3] - 2026-08-29

package/CHANGELOG-mcp.md

@@ -4,6 +4,20 @@ MCP server tools and resources belong here.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-01
+
+### Changed
+
+- **`oms_search` query now accepts the closed `strategy`, `maxQueries`, `rerank`, and `candidateLimit` controls.** Query budgets are strict integers, expansion is not advertised on context retrieval, and these controls remain on the existing tool; no additional public search tool was added.
+
+## [0.9.0] - 2026-08-31
+
+### Changed
+
+- **The five-tool MCP surface now uses stable templates for every note-shaped operation.** `oms_write` has strict create/append/update branches: create derives placement from `templateId`, while append/update resolve the persisted note identity; guarded template operations remain on the same tool. `oms_search` advertises template/field/folder/link axes; `oms_status` reports projection signatures; and `oms_doctor` adds template diagnosis, approved projection regeneration, and exact one-note backfill without adding public tools.
+- **Graph, link, and search paths share one resolved convention.** Typed retrieval omits and reports unresolved note identities instead of failing the whole index, stale projections fail loudly, managed template sources are excluded, and every advertised search operation remains byte-identical read-only.
+- **Doctor and template mutation use exact public operations and durable recovery.** Doctor exposes `validate`, `regenerate-types`, and `backfill-defaults`; interrupted template transactions resume by persisted transaction ID and the original approved digest instead of reconstructing mutable caller state.
+
 ## [0.8.4] - 2026-08-30
 
 ## [0.8.3] - 2026-08-29

package/CHANGELOG-vendors.md

@@ -4,6 +4,14 @@ Per-host adapter and installer changes belong here.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-01
+
+## [0.9.0] - 2026-08-31
+
+### Changed
+
+- **Claude, Codex, and Hermes host guidance and hooks now describe the template/ontology coexistence contract.** Templates own note shape, user-owned policy/taxonomy intent owns meaning, taxonomy owns placement, and Obsidian owns types. A signed XDG host-maintenance pointer lets install, update, public reconcile, and uninstall compare-and-swap every managed MCP/hook vault stamp while remaining completely outside runtime target resolution. Claude post-write checks resolve templates without rebuilding caches.
+
 ## [0.8.4] - 2026-08-30
 
 ## [0.8.3] - 2026-08-29

package/CHANGELOG.md

@@ -6,10 +6,36 @@ This aggregate changelog contains changes that span multiple layers.
 - [CLI changelog](./CHANGELOG-cli.md) — the `oms` command surface
 - [MCP changelog](./CHANGELOG-mcp.md) — MCP server tools and resources
 - [Vendors changelog](./CHANGELOG-vendors.md) — per-host adapters and installers
-- [Assets changelog](./CHANGELOG-assets.md) — skills, agents, and ontology data
+- [Assets changelog](./CHANGELOG-assets.md) — skills, agents, templates, and host guidance
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-01
+
+### Breaking
+
+- **OMS now has one search taxonomy.** `oms semantic` and the old top-level collection, context, cleanup, and HTTP aliases are removed; use `oms search`, `oms doc get|multi-get`, `oms embed`, and `oms serve`. `oms index` contains exactly `sync|status|cleanup|collections|contexts`; embedding remains the compact top-level `oms embed` command.
+- **Setup model options have changed.** `--embedding-*` is replaced by `--models-default`, `--models-descriptor`, and `--models-no-default`.
+- **The embedding runtime is local-only.** The former Upstage provider path is removed; configured model identities must resolve to verified local GGUF artifacts.
+
+### Added
+
+- **Search now uses an explicit closed qmd-v2.8.3 expansion strategy.** `--max-queries` is strict, reranking is opt-in, and local model-set descriptors are supported.
+- **`oms serve` exposes only `/health`, `/search`, `/get`, and `/multi-get`.** It does not add a query alias or a second MCP tool surface.
+
+### Changed
+
+- **The kernel makes model lifecycle and capability availability explicit.** The canonical engine path carries active-template taxonomy context into search rather than silently claiming unavailable capabilities.
+- **Model-bearing work is lifecycle-safe and content-aware.** Vault selection outranks setup defaults, GGUF disposal waits for admitted work, and reranking scores bounded note content instead of filenames.
+- **MCP search accepts `strategy`, `maxQueries`, `rerank`, and `candidateLimit` through the existing `oms_search` tool.** No additional public search tool was added.
+- **The `/search` skill now calls `oms_search` with `op: "query"` and an explicit strategy.** Its frontmatter is unchanged.
+
+## [0.9.0] - 2026-08-31
+
+### Changed
+
+- **Oh My Second Brain now derives one write/search contract from templates and a coexisting user-owned ontology.** Vault Markdown templates own frontmatter/body shape; template policy owns note/field meaning, naming, and defaults; taxonomy owns folder/link meaning and placement; and Obsidian owns property types. The synchronized kernel, CLI, MCP, host, skill, setup, migration, diagnosis, and documentation cutover removes only the former `concept` note identity and bundled runtime authority. Stable template identities, inherited base defaults, managed-source exclusion, verified repair transactions, and host pointer reconciliation now work consistently across all supported environments.
+
 ## [0.8.4] - 2026-08-30
 
 ### Documentation

package/README.ko.md

@@ -1,87 +1,68 @@
 # Oh My Second Brain
 
-> Obsidian 및 일반 마크다운 지식 볼트를 위한, 호스트에 종속되지 않고 사용자가 소유하는 컨벤션 레이어.
+Oh My Second Brain(`oms`)은 기존 Obsidian/Markdown 볼트를 노트 소유권을 빼앗지 않고 AI 호스트에 연결한다. 볼트는 계속 평범한 Markdown이다.
 
-[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)
+- 볼트에 실제로 존재하는 Obsidian `.md` 템플릿이 관리 노트의 frontmatter 형태와 본문 골격을 소유한다.
+- 각 템플릿은 경로·digest와 독립적인 안정적 `templateId`를 가지며, 볼트 전체의 `BaseContract` 하나를 상속한다.
+- `.obsidian/types.json`은 읽기 전용 타입 권위다.
+- 사용자 소유 온톨로지는 계속 활성 상태다. `.oms/template-policy.json`은 노트·필드 의미와 필수값, 형식, 허용값, 기본값, 이름 규칙, 정체성, 바인딩을 기록한다.
+- `.oms/taxonomy.yaml`은 폴더·링크 의미와 배치를 소유하며, 작성된 폴더 의미는 `folder-ontology` 검색 축으로 노출된다.
+- `.oms/types.json`은 쓰기·검색용 검증된 파생 projection이다. 직접 편집하지 않는다.
 
-Oh My Second Brain(`oms`)은 기존 Obsidian/마크다운 볼트를 에이전트가 읽을 수 있는 지식 베이스로 만든다. 볼트가 가진 고유한 폴더/프론트매터 컨벤션을 로드하고, 그에 맞게 노트를 검증하고, 로컬 링크 그래프를 만들고, 이 모든 것을 단일 MCP 서버를 통해 AI 코딩 호스트(Claude Code, Codex, Hermes)에 노출한다. 특정 호스트에 종속되지 않으며 노트를 다른 곳으로 옮기지도 않는다.
+제거된 것은 노트 정체성으로서의 `concept`와 번들 runtime 기본값이지, 의미 계층으로서의 온톨로지가 아니다.
 
-**컨벤션 우선, 사용자 소유**가 원칙이다. 볼트는 그대로 일반 마크다운으로 남고, 온톨로지는 사용자가 통제하는 커밋된 `.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으로:
+Setup은 기존 템플릿을 재귀 탐색하고 migration을 제안한다. 노트 타입 기본값을 번들로 강요하지 않으며 노트를 수정하지 않는다.
 
 ```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       # 적용
+oms setup --vault /path/to/vault --dry-run
+oms setup --vault /path/to/vault --yes --approved-digest <표시된-digest>
 ```
 
-전체 가이드: [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`로 되돌릴 수 있다.
+관리 템플릿 변경도 dry-run, 호출자가 검토한 정확한 digest, CAS, transaction, 사후조건 receipt를 거친다.
 
 ## CLI
 
-```
-oms setup      기존 볼트를 컨벤션으로 채택 (.oms/taxonomy.yaml 작성, 노트는 수정하지 않음)
-oms install    호스트 어댑터 + MCP 등록 설치
-oms uninstall  호스트 어댑터 + MCP 등록 제거
+```text
+oms setup      기존 볼트 템플릿 탐색 및 채택
+oms install    호스트 어댑터와 관리형 MCP 등록 설치
+oms uninstall  호스트 어댑터와 관리형 MCP 등록 제거
 oms update     패키지 업데이트 확인/적용 후 어댑터 재조정
-oms doctor     온톨로지 기준으로 노트 frontmatter 검증 (필드/컨셉별 집계)
-oms lint       볼트 링크 건강도 점검: 깨진 [[wikilink]] + 고아 노트
-oms semantic   네이티브 마크다운 시맨틱 인덱스 / 검색 / 조회
+oms reconcile  엄격한 전역 볼트 포인터로 호스트 재기록
+oms doctor     템플릿 권위와 파생 상태 진단
+oms lint       깨진 [[wikilink]]와 고아 노트 점검
+oms search <text>  일반 lexical 검색; --vec, --hyde, --expand, --max-queries 1..32, --rerank은 명시적 선택
+oms embed      색인된 노트의 임베딩 생성
+oms index sync|status|cleanup|collections|contexts
+oms doc get|multi-get
+oms serve      로컬 검색 HTTP 서버 시작
 oms mcp        stdio MCP 서버 시작
-oms hook       볼트 가드 훅 (Claude Code pre/post tool-use)
+oms hook       Claude pre/post tool-use 볼트 가드 실행
 ```
 
-`oh-my-second-brain`이 정식 명령이고, `oms`는 짧은 별칭이다.
+`oh-my-second-brain`이 전체 명령이고 `oms`는 짧은 별칭이다.
+
+`oms search <text>`는 lexical-only다. `--vec`, `--hyde`는 각각의 typed
+channel을 선택하고, `--expand`는 G004 expansion을 명시적으로 켜며,
+`--max-queries`는 1부터 32까지의 정수만 받는다. `--rerank`도 opt-in이다.
+`oms embed`가 유일한 embedding 명령이며 `oms index`에는 embedding
+subcommand가 없다.
+
+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`.
 
 ## MCP 도구
 
@@ -89,47 +70,23 @@ oms hook       볼트 가드 훅 (Claude Code pre/post tool-use)
 
 `oms_write` · `oms_search` · `oms_link` · `oms_status` · `oms_doctor`
 
-`oms_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/`를 보존하며, 노트는 절대 수정하지 않는다.
+일곱 스킬(`write`, `search`, `link`, `distill`, `status`, `doctor`, `template`)은 워크플로 안내이며 MCP 도구와 같은 집합이 아니다. 세부 기능은 다섯 도구의 `op` 값으로 제공한다.
 
-## 시맨틱 검색 (선택)
+쓰기는 하나의 `ResolvedTemplate`을 해석해 create, append, update를 수행한다. 템플릿 변경, projection 재생성, 한 노트 정체성 backfill은 검증된 target과 명시적 승인 digest가 필요하다. `status`와 모든 검색 동작은 읽기 전용이다.
 
-시맨틱 검색에는 실제 임베딩 모델이 필요하다 — 프로덕션 경로에 가짜/해시 폴백은 없다(ADR-007). 가장 간단한 경로는 핀 고정된 로컬 기본 모델이다:
+일반 lexical 검색은 projection과 독립적이다. 템플릿·선언 필드·폴더·링크 축은 쓰기와 같은 projection을 사용하며 누락·stale 상태를 크게 실패시킨다. 관리 템플릿 원본은 검색 대상에서 제외한다. Vector/HyDE는 provider와 model이 모두 설정되지 않으면 가짜 대체 없이 실패한다.
 
-```bash
-oms setup --vault /path/to/vault --yes --embedding-default
-oms embed  --vault /path/to/vault
-oms semantic vsearch "무엇을 찾아야 하나?" --vault /path/to/vault
-```
-
-`--embedding-default`는 EmbeddingGemma-300M(약 318 MB)을 내려받아 핀 고정된 SHA-256으로 검증한 뒤, 볼트가 아니라 사용자 캐시 디렉터리에 설치한다. `node-llama-cpp`로 로컬 실행되므로 API 키가 필요 없고, 모델 원본 768차원을 폴딩 없이 그대로 사용한다. 이후 `oms embed`와 벡터 검색은 환경변수 없이 동작한다.
-
-의존하기 전에 알아둘 점이 하나 있다. 이 모델과 프롬프트 형식은 [qmd](https://github.com/tobi/qmd)가 기본으로 쓰는 것과 동일하지만, 이 프로젝트의 자체 검색 하네스에서 측정된 적은 한 번도 없다. 여기서의 랭킹 품질은 대안과의 측정 비교가 아니라 그 동일성에 근거한다. 그 이유와, 해당 측정이 단순히 '보류 중'이 아닌 이유는 [결정 기록](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/docs/measurements/model-default-deferral.md)에 적혀 있다.
-
-직접 고른 모델을 쓰려면 `OMS_EMBEDDING_PROVIDER`와 `OMS_EMBEDDING_MODEL`을 함께 지정한다(`gguf`에 로컬 GGUF 경로, 또는 `upstage`에 모델 id와 `UPSTAGE_API_KEY`). 둘 중 하나만 지정하면 두 변수 이름을 모두 알려주며 실패한다. 조용한 폴백은 없다.
-
-모델이 없어도 어휘 검색, 그래프 기반 검색, 컨벤션 검증은 그대로 동작한다. 벡터와 HyDE 요청만 거부되며, 그때 어떤 변수를 설정해야 하는지 알려준다.
+## 설치
 
-## 개발
+Node.js 20 이상이 필요하다.
 
 ```bash
-npm install
-npm run build
-npm test
-npm run release:check   # lint + build + test + audit + pack + artifact-smoke + plugin 검증
+npm install -g oh-my-second-brain
+oms install --runtime all --vault /path/to/vault --yes
 ```
 
-릴리스 절차: [docs/release.md](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/docs/release.md).
+호스트 설치는 canonical 볼트를 `${XDG_CONFIG_HOME:-~/.config}/oms/vault.json`에 기록하고 각 관리형 등록에 `oms mcp --vault /path/to/vault`를 넣는다. `install`, `update`, `reconcile`, `uninstall`만 이 서명된 포인터를 호스트 stamp 관리에 사용한다. 런타임 쓰기·검색 target 해석은 포인터를 읽지 않으며 명시적 target, 로컬 볼트 control, bridge, `OMS_VAULT`, 읽기 전용 cwd fallback 순서를 유지한다.
 
-## 라이선스
+`OMS_VAULT`는 명시적·로컬·bridge target이 없을 때 사용하는 지원 환경변수 fallback이다.
 
-MIT. 상위 출처 크레딧은 [ACKNOWLEDGMENTS.md](./ACKNOWLEDGMENTS.md) 참고.
+자세한 내용은 [설치](./docs/install.md), [아키텍처](./docs/architecture.md), [컨벤션](./docs/conventions.md), [검증된 target](./docs/verified-target.md)을 참고한다.

package/README.md

@@ -1,87 +1,66 @@
 # Oh My Second Brain
 
-> A host-agnostic, user-owned convention layer for Obsidian and plain-markdown knowledge vaults.
+Oh My Second Brain (`oms`) connects an existing Obsidian or Markdown vault to AI hosts without taking ownership of its notes. The vault remains plain Markdown.
 
-**English** · [한국어](./README.ko.md)
+## Template and ontology vault model
 
-[![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)
+- Actual vault-resident Obsidian `.md` templates own managed frontmatter shape and body scaffolding.
+- Each template has a stable `templateId`, independent of its path and digest, and inherits one vault-wide `BaseContract`.
+- `.obsidian/types.json` is read-only type authority.
+- The user-owned ontology remains active: `.oms/template-policy.json` records note/field meaning alongside requiredness, formats, allowed values, defaults, naming, identity, and bindings.
+- `.oms/taxonomy.yaml` records folder/link meaning and owns placement; authored folder intents are exposed through the `folder-ontology` search axis.
+- `.oms/types.json` is a validated derived write/search projection. Never hand-edit it.
 
-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.
+The retired model is `concept` as note identity and bundled runtime defaults—not ontology as semantic meaning.
 
-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.
+## Setup
 
-## How it works
-
-```
-kernel (written once)                     root host surfaces
-  ontology + convention logic                .claude-plugin/  Claude plugin manifest
-  graph + semantic runtime        +          .codex-plugin/   Codex plugin manifest
-  gated note operations                      .mcp.json         Claude MCP registration
-  CLI and MCP entry points                   .mcp.codex.json   Codex MCP registration
-```
-
-- **kernel** is host-agnostic: ontology, validation, graph/semantic logic, and note operations.
-- host-specific assets live at the package root: Claude hooks are in `assets/claude/hooks/`, Codex rules are in `assets/codex/rules/`, and Hermes metadata is `assets/hermes-manifest.json`.
-- 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:
+Setup recursively discovers existing templates and proposes migration. It ships no note-type defaults and never modifies notes.
 
 ```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
+oms setup --vault /path/to/vault --dry-run
+oms setup --vault /path/to/vault --yes --approved-digest <shown-digest>
 ```
 
-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** | `assets/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: [docs/install.md](./docs/install.md).
+Managed-template changes use the same dry-run, exact caller approval, compare-and-swap, transaction, and postcondition receipt boundary.
 
 ## CLI
 
-```
-oms setup      Adopt an existing vault into the convention (writes .oms/taxonomy.yaml; never edits notes)
-oms install    Install host assets + MCP registration
-oms uninstall  Remove host assets + MCP registration
-oms update     Check/apply a package update, then reconcile host assets
-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
+```text
+oms setup      Discover and adopt existing vault templates
+oms install    Install host adapters and managed MCP registration
+oms uninstall  Remove host adapters and managed MCP registration
+oms update     Check/apply a package update and reconcile adapters
+oms reconcile  Re-stamp hosts from the strict global vault pointer
+oms doctor     Diagnose template authority and derived state
+oms lint       Check broken [[wikilinks]] and orphan notes
+oms search <text>  Plain lexical search; --vec, --hyde, --expand, --max-queries 1..32, and --rerank are explicit
+oms embed      Generate embeddings for indexed notes
+oms index sync|status|cleanup|collections|contexts
+oms doc get|multi-get
+oms serve      Start the local search HTTP server
 oms mcp        Start the stdio MCP server
-oms hook       Vault guard hooks (Claude Code pre/post tool-use)
+oms hook       Run Claude pre/post tool-use vault guards
 ```
 
-`oh-my-second-brain` is the canonical command; `oms` is the short alias.
+`oh-my-second-brain` is the full command; `oms` is its short alias.
+
+`oms search <text>` is lexical-only. `--vec` and `--hyde` select their respective
+typed channels; `--expand` explicitly enables G004 expansion, `--max-queries`
+accepts an integer from 1 through 32, and `--rerank` is opt-in. `oms embed` is
+the sole embedding command; `oms index` has no embedding subcommand.
+
+Vector search requires a verified local embedding capability, selected by a
+complete `OMS_EMBEDDING_PROVIDER`/`OMS_EMBEDDING_MODEL` pair, the vault's
+`.oms/models.json` plus its verified installed receipt, or a setup-installed
+default. HyDE also requires a resolved generate capability; reranking requires
+a resolved rerank capability. Their complete environment pairs are
+`OMS_GENERATE_PROVIDER`/`OMS_GENERATE_MODEL` and
+`OMS_RERANK_PROVIDER`/`OMS_RERANK_MODEL`. Missing, incomplete, or uninstalled
+selections fail loudly. G004 expansion is an explicit
+available capability; it makes no replacement, parity, or outperformance claim.
+During setup, choose one local verified acquisition policy:
+`--models-default`, `--models-descriptor <path>`, or `--models-no-default`.
 
 ## MCP tools
 
@@ -89,47 +68,23 @@ oms hook       Vault guard hooks (Claude Code pre/post tool-use)
 
 `oms_write` · `oms_search` · `oms_link` · `oms_status` · `oms_doctor`
 
-`oms_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.
+The seven skills (`write`, `search`, `link`, `distill`, `status`, `doctor`, `template`) are workflow guidance, not a tool-equality list. Detail capabilities remain `op` values under the five tools.
 
-## Semantic search (optional)
+Writes resolve one `ResolvedTemplate` and support create, append, and update. Template mutation, projection regeneration, and one-note identity backfill require a verified target and explicit approval digest. `status` and every search operation are read-only.
 
-Semantic retrieval requires a real embedding model — there is no fake/hash fallback (ADR-007). The quickest path is the pinned local default:
+Plain lexical search is projection-independent. Typed template/declared-field/folder/link axes use the same projection as writes and fail loudly when it is missing or stale. Managed template sources are excluded. Vector and HyDE requests fail loudly unless both embedding provider and model are configured.
 
-```bash
-oms setup --vault /path/to/vault --yes --embedding-default
-oms embed  --vault /path/to/vault
-oms semantic vsearch "what should I retrieve?" --vault /path/to/vault
-```
-
-`--embedding-default` downloads EmbeddingGemma-300M (~318 MB), verifies it against a pinned SHA-256, and installs it under your user cache — not in the vault. It runs locally through `node-llama-cpp`, needs no API key, and embeds at the model's full 768 dimensions with no folding. After that, `oms embed` and vector search need no environment variables.
-
-One thing to know before you rely on it: this is the same model and prompt format [qmd](https://github.com/tobi/qmd) resolves by default, but it has never been measured in this project's own retrieval harness. Its ranking quality here rests on that equivalence, not on a measured comparison against alternatives. [The decision record](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/docs/measurements/model-default-deferral.md) explains why, and why the measurement is not merely pending.
-
-To choose your own model instead, set `OMS_EMBEDDING_PROVIDER` + `OMS_EMBEDDING_MODEL` (`gguf` with a local GGUF path, or `upstage` with a model id and `UPSTAGE_API_KEY`). Setting only one of the pair is an error naming both, never a silent fallback.
-
-Without any model, lexical search, graph-based retrieval, and convention validation all still work; only vector and HyDE requests are refused, and they say which variables to set.
+## Install
 
-## Development
+Node.js 20 or later is required.
 
 ```bash
-npm install
-npm run build
-npm test
-npm run release:check   # lint + build + test + audit + pack + artifact-smoke + plugin validate
+npm install -g oh-my-second-brain
+oms install --runtime all --vault /path/to/vault --yes
 ```
 
-Release process: [docs/release.md](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/docs/release.md).
+Host installation records the canonical vault in `${XDG_CONFIG_HOME:-~/.config}/oms/vault.json` and stamps `oms mcp --vault /path/to/vault` into each managed host entry. `install`, `update`, `reconcile`, and `uninstall` use that signed pointer only to maintain host stamps. Runtime write/search target resolution never reads it and keeps this precedence: explicit target, local vault controls, bridge, `OMS_VAULT`, then read-only cwd fallback.
 
-## License
+`OMS_VAULT` is the supported environment fallback when no explicit, local, or bridge target exists.
 
-MIT. See [ACKNOWLEDGMENTS.md](./ACKNOWLEDGMENTS.md) for upstream credits.
+See [installation](./docs/install.md), [architecture](./docs/architecture.md), [conventions](./docs/conventions.md), and [verified targets](./docs/verified-target.md).