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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.8.4",
+  "version": "0.9.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.9.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,15 @@
 # Assets Changelog
 
-Skills, agents, and ontology data changes belong here.
+Skills, agents, templates, and host guidance changes belong here.
 
 ## [Unreleased]
 
+## [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,13 @@ Changes to the `oms` command surface belong here.
 
 ## [Unreleased]
 
+## [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,15 @@ Domain logic changes belong here.
 
 ## [Unreleased]
 
+## [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,14 @@ MCP server tools and resources belong here.
 
 ## [Unreleased]
 
+## [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,12 @@ Per-host adapter and installer changes belong here.
 
 ## [Unreleased]
 
+## [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,16 @@ 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.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,45 @@
 # 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 semantic   네이티브 Markdown lexical/vector 검색 관리
 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`는 짧은 별칭이다.
 
 ## MCP 도구
 
@@ -89,47 +47,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,45 @@
 # 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 semantic   Manage native Markdown lexical/vector retrieval
 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.
 
 ## MCP tools
 
@@ -89,47 +47,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).

package/assets/claude/CLAUDE.md

@@ -1,25 +1,21 @@
-# Oh My Second Brain Convention Fragment
+# Oh My Second Brain — Claude Code
 
-<!-- Append this block to your project's CLAUDE.md to activate Oh My Second Brain conventions in Claude Code. -->
+This vault is governed by user-owned template conventions in `.oms/`.
 
-## Vault Convention (Oh My Second Brain)
+Before vault work:
+- Treat actual Obsidian `.md` templates as the note-shape and body source of truth.
+- Treat `.obsidian/types.json` as read-only property-type authority.
+- Read the user-owned ontology from `.oms/template-policy.json` for note/field meaning and policy, and `.oms/taxonomy.yaml` for folder/link meaning and placement.
+- Never hand-edit derived `.oms/types.json`; use doctor diagnosis and an approved regeneration.
+- People and agents follow the same stable `templateId` rules.
 
-This vault is governed by Oh My Second Brain conventions stored in `.oms/`.
-All knowledge capture and retrieval must follow the declared semantic convention.
+Writes:
+- Use `/write` and MCP `oms_write`; never host Write/Edit for vault notes or managed templates.
+- Notes use `op: "note"` with a stable template ID.
+- Template changes use `op: "template"`: dry-run first, then apply only with the exact reviewed `approvalDigest`.
 
-**Before working with vault notes:**
-- Run `oms doctor` to validate existing notes against the convention (exits 0, non-blocking).
-- Read `.oms/taxonomy.yaml` to understand which folders hold which concepts.
-- Read `.oms/concepts/*.yaml` to understand field requirements and lenses.
+Retrieval:
+- Use `/search`; discover identities with `op: "templates"`.
+- Filter with template, declared field, folder, and link axes. Plain lexical search remains read-only and projection-independent.
 
-**When writing vault notes:**
-- Use the `/write` skill. Call MCP `oms_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 `oms_write` again.
-
-**When retrieving knowledge:**
-- Use the `/search` skill.
-- 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.
-
-**Doctor is advisory. Write is not.**
-`oms doctor` always exits 0. MCP `oms_write` rejects contract violations.
+`status` is observational. `doctor` owns explicit diagnosis and repairs. The seven installed skills are write, search, link, distill, status, doctor, and tool-less template authoring.

package/assets/codex/AGENTS.md

@@ -1,16 +1,21 @@
 # Oh My Second Brain Convention Shim — Codex
 
-<!-- Append this block to your project's AGENTS.md to activate Oh My Second Brain conventions in Codex (oh-my-codex). -->
+<!-- Append this block to a project's AGENTS.md to activate Oh My Second Brain conventions in Codex. -->
 
-## Vault Convention (Oh My Second Brain)
+## Vault Convention
 
-This vault is governed by Oh My Second Brain conventions stored in `.oms/`.
+The vault is governed by user-owned template conventions in `.oms/`.
 
-**Before working with vault notes:**
-- Run `oms doctor` to validate notes against the convention (exits 0, non-blocking).
-- Read `.oms/taxonomy.yaml` and `.oms/concepts/*.yaml` for folder and field declarations.
+- Actual Obsidian `.md` templates own note shape and body scaffolding.
+- `.obsidian/types.json` is read-only type authority.
+- The user-owned ontology remains active: `.oms/template-policy.json` records note/field meaning and policy; `.oms/taxonomy.yaml` records folder/link meaning and placement.
+- `.oms/types.json` is derived; never hand-edit it.
+- Humans and agents use the same stable `templateId` rules.
 
-**Write:** Use `$oms-write`. Call MCP `oms_write`. Do not use host Write/Edit for vault `.md` files.
-**Retrieve:** Use the `$oms-search` skill with declared lenses.
+**Write:** Use `$oms-write` and MCP `oms_write`, never host Write/Edit for vault notes or managed templates. Notes use `op: "note"`. Template changes use `op: "template"`, first as a dry-run and then only with the exact reviewed `approvalDigest`.
 
-> **v0 native install:** `oms install --runtime codex` installs Codex rules, the `$oms-write`, `$oms-search`, `$oms-link`, `$oms-distill`, `$oms-status`, and `$oms-doctor` skills, and a managed Codex MCP config. Use Oh My Second Brain MCP tools for vault operations and CLI commands for lifecycle.
+**Retrieve:** Use `$oms-search`; discover stable IDs with `op: "templates"`, then use template, declared field, folder, and link axes.
+
+**Maintain:** `$oms-status` is read-only. `$oms-doctor` diagnoses and performs explicit repairs.
+
+`oms install --runtime codex` installs seven skills: `$oms-write`, `$oms-search`, `$oms-link`, `$oms-distill`, `$oms-status`, `$oms-doctor`, and tool-less `$oms-template`, plus managed MCP configuration.

package/assets/codex/rules/oms.md

@@ -1,25 +1,24 @@
 # Oh My Second Brain for Codex
 
-Use Oh My Second Brain when the user asks to set up, validate, capture into, retrieve from, or inspect an Obsidian/Markdown vault governed by `vault/.oms/`.
+Use Oh My Second Brain for an Obsidian/Markdown vault governed by user-owned template controls in `.oms/`.
 
 ## Core rule
 
-Oh My Second Brain is a convention harness, not a content generator. The user owns the ontology in `vault/.oms/`; agents must use the declared folder axis, frontmatter/property axes, wikilinks, and retrieval lenses before reading or writing notes.
+Actual Obsidian Markdown templates own note shape and body scaffolding. The user-owned ontology remains active: template policy records note/field meaning and policy, while taxonomy records folder/link meaning and placement. `.obsidian/types.json` is read-only type authority; `.oms/types.json` is derived and must never be hand-edited.
 
 ## Command mapping
 
-| User intent | Preferred Oh My Second Brain surface |
+| User intent | Preferred surface |
 |---|---|
-| adopt a vault | `oms setup --vault <path>` |
+| inspect and adopt templates | `oms setup --vault <path> --dry-run`, then `--yes --approved-digest <digest>` |
 | install host integration | `oms install --runtime codex --vault <path> --yes` |
-| uninstall host integration | `oms uninstall --runtime codex --yes` |
-| validate notes | `$oms-doctor` or `oms doctor --vault <path>` |
-| write a vault note | use `$oms-write` / MCP `oms_write` (`create`, `append`, or `update`) |
-| retrieve knowledge | use `$oms-search` / MCP `oms_search`, loading full notes only when needed |
+| diagnose or repair | `$oms-doctor` or `oms doctor --vault <path>` |
+| write a note | `$oms-write` / MCP `oms_write` with a stable `templateId` |
+| retrieve knowledge | `$oms-search` / MCP `oms_search`; discover IDs with `op: "templates"` |
 
 ## Safety
 
-- Never delete vault notes or `vault/.oms/` during uninstall.
-- Capture must stay inside the configured vault and target Markdown files only.
-- If required frontmatter is missing, ask for it; do not invent user-owned ontology values.
-- Route ambiguous captures to inbox when the ontology cannot decide.
+- Never delete vault notes or `.oms/` during uninstall.
+- Never use direct file tools for vault notes or managed templates.
+- Never invent required values or self-approve a repair digest.
+- `status` and search are read-only; mutation requires a verified target.