oh-my-second-brain 0.2.0 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "oms",
+  "description": "Oh My Second Brain: a host-agnostic, user-owned convention layer for Obsidian and plain-markdown knowledge vaults.",
+  "owner": {
+    "name": "gobeumsu",
+    "email": "gobeumsu@gmail.com"
+  },
+  "plugins": [
+    {
+      "name": "oms",
+      "description": "Oh My Second Brain convention layer for Obsidian vaults — capture, retrieve, and validate knowledge under a declared semantic convention.",
+      "version": "0.3.0",
+      "author": {
+        "name": "gobeumsu",
+        "email": "gobeumsu@gmail.com"
+      },
+      "source": "./",
+      "category": "productivity",
+      "homepage": "https://github.com/GoBeromsu/oh-my-second-brain#readme",
+      "repository": "https://github.com/GoBeromsu/oh-my-second-brain",
+      "license": "MIT",
+      "keywords": [
+        "obsidian",
+        "knowledge-base",
+        "mcp",
+        "frontmatter",
+        "markdown",
+        "claude-code"
+      ],
+      "tags": [
+        "obsidian",
+        "knowledge-management",
+        "convention",
+        "frontmatter",
+        "vault"
+      ]
+    }
+  ],
+  "version": "0.3.0"
+}

package/{adapters/claude-code/.claude-plugin → .claude-plugin}/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults — capture, retrieve, and validate knowledge under a declared semantic convention.",
   "author": {
     "name": "gobeumsu"
@@ -15,12 +15,11 @@
     "vault"
   ],
   "skills": [
-    "./skills/setup/",
-    "./skills/doctor/",
-    "./skills/define/",
-    "./skills/write/",
-    "./skills/retrieve/",
-    "./skills/uninstall/",
-    "./skills/update/"
+    "./assets/skills/distill/",
+    "./assets/skills/doctor/",
+    "./assets/skills/link/",
+    "./assets/skills/search/",
+    "./assets/skills/status/",
+    "./assets/skills/write/"
   ]
 }

package/{adapters/codex/.codex-plugin → .codex-plugin}/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "oms",
-  "version": "0.2.0",
-  "description": "Oh My Second Brain convention layer for Obsidian vaults \u2014 Codex native rules, skills, and MCP adapter.",
+  "version": "0.3.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": "./skills/",
-  "mcpServers": "./.mcp.json"
+  "skills": "./assets/skills/",
+  "mcpServers": "./.mcp.codex.json"
 }

package/ACKNOWLEDGMENTS.md

@@ -0,0 +1,154 @@
+# ACKNOWLEDGMENTS
+
+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)
+
+## LLM-Wiki 패턴 & 구현체
+
+- https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
+- https://github.com/Astro-Han/karpathy-llm-wiki
+- https://github.com/nashsu/llm_wiki — GPL-3.0: **아이디어만 참조, 코드 미사용**
+- https://github.com/nashsu/llm_wiki_skill — 무라이선스: 개념 참조만
+- https://github.com/nvk/llm-wiki
+- https://github.com/lucasastorian/llmwiki
+- https://github.com/atomicstrata/llm-wiki-compiler
+- https://github.com/shannhk/llm-wikid
+- https://github.com/AgriciDaniel/claude-obsidian
+- https://github.com/NicholasSpisak/second-brain
+- 박제창(Dreamwalker) — https://medium.com/@aristojeff
+- @aboutcorelab — https://www.threads.com/@aboutcorelab
+- 패스트캠퍼스 — https://fastcampus.co.kr/biz_camp_llmwiki
+- MindStudio — https://www.mindstudio.ai/blog/ai-second-brain-obsidian-vault-folder-architecture
+
+## 검색 / 임베딩 엔진
+
+- https://github.com/tobi/qmd
+- gbrain — 원 repo URL 미확인 `TODO(verify)`
+- https://github.com/pgvector/pgvector
+- https://github.com/electric-sql/pglite
+
+## 그래프 접근
+
+- https://github.com/safishamsi/graphify  (후원: https://github.com/sponsors/safishamsi)
+
+## Agent Skills 생태계
+
+- https://github.com/anthropics/skills
+- https://github.com/VoltAgent/awesome-agent-skills
+- https://github.com/code-yeongyu/lazycodex — MIT, **vendored**: `programming` 스킬 직접 설치, LICENSE+저작권 고지 보존 (`~/.claude/skills/programming/`)
+- https://github.com/Yeachan-Heo/oh-my-claudecode
+- https://github.com/Yeachan-Heo/oh-my-codex
+
+---
+
+## M1 Retrieval Engine — Absorbed Patterns
+
+아래 패턴들은 M1 엔진(`src/kernel/engine/`) 구현 과정에서 아이디어/알고리즘만 흡수한 목록이다.
+**verbatim 코드 사용 없음** — 모든 구현은 독립적으로 작성되었다.
+
+| Pattern | Source | License | Note |
+|---------|--------|---------|------|
+| Adamic-Adar co-link scoring: AA(u,v) = Σ_{w∈N(u)∩N(v)} 1/log(deg(w)). Implemented by iterating each node w, enumerating pairs of its neighbours, and accumulating 1/log(deg(w)) into a canonical pair key. | [nashsu/llm_wiki](https://github.com/nashsu/llm_wiki) | GPL-3.0 | **IDEA-ONLY — zero verbatim code** |
+| Composite edge weight = weighted sum of per-tier contributions (wikilink×3.0, frontmatter×4.0, adamic-adar×1.5, type-affinity×1.0). Frontmatter relation extraction from `sources[]`/`relations[]` YAML keys. | [nashsu/llm_wiki](https://github.com/nashsu/llm_wiki) | GPL-3.0 | **IDEA-ONLY — zero verbatim code** |
+| Reciprocal Rank Fusion weight schedule: score(d) = Σ 1/(k+rank_i(d)), k=60 default calibration | [nashsu/llm_wiki](https://github.com/nashsu/llm_wiki) + MS GraphRAG technical report | GPL-3.0 (idea-only) / public algorithm | Zero verbatim code |
+| HyDE (Hypothetical Document Embeddings) — generate a hypothetical answer passage then embed it for retrieval | [nashsu/llm_wiki](https://github.com/nashsu/llm_wiki) | GPL-3.0 | **IDEA-ONLY — zero verbatim code** |
+| P-08-style two-layer retry: inner immediate retry + outer 50 ms back-off, abort on CancelToken | P-08 resilience pattern (architecture concept) | idea-only | No external code |
+| Lightweight cancel token: mutable boolean wrapped in a getter+cancel() object, threaded through every async call | gajae-code patterns | MIT | idea-only, implementation is original |
+| Lazy-load + 5-minute idle unload guard (`src/kernel/engine/embed/provider.ts`): model/contexts not initialised until first `embed()` call; a `setTimeout` resets per call; no calls for 5 min → dispose pool; next `embed()` reloads lazily. The only permitted timer (plan.md:83, R2). | [qmd (tobi)](https://github.com/tobi/qmd) | MIT | **IDEA-ONLY — zero verbatim code** |
+| Hardware-adaptive parallel embed pool (`src/kernel/engine/embed/provider.ts`): `poolSize = min(4, cpuCount-1)`, round-robin context selection across the pool, `Promise.all` parallel context init, 2-stage batch distribution. | [qmd (tobi)](https://github.com/tobi/qmd) | MIT | **IDEA-ONLY — zero verbatim code** |
+| SHA-256 chunk-level incremental diff (`src/kernel/engine/embed/sync.ts`): compute SHA-256 of each chunk text; compare with stored SHA from `EngineStore.getShas()`; skip `embed()` call when SHA matches — only changed chunks are re-embedded. | [qmd (tobi)](https://github.com/tobi/qmd) | MIT | **IDEA-ONLY — zero verbatim code** |
+
+> **⚠ License flag — gbrain**: The gbrain project was referenced for logic/architecture patterns only. The original repo URL and license are unconfirmed (`TODO(verify)`). No code was copied. Attribution will be updated once the license is confirmed.
+
+---
+
+## M2 Compile Engine — Absorbed Patterns
+
+M2 컴파일 기능의 이전 구현 과정에서 아이디어/알고리즘만 흡수한 목록이다.
+**verbatim 코드 사용 없음** — 모든 구현은 독립적으로 작성되었다.
+
+| Pattern | Source | License | Note |
+|---------|--------|---------|------|
+| SHA-incremental per-compile-unit: fingerprint materials → diff SHA → skip or recompile → persist SHA (`.llmwiki/sha-cache.json`) | bstack `terminology` skill | Self-authored | Full idea absorption |
+| 2-step Chain-of-Thought: Step 1 analysis (entity/concept/argument/contradiction/structure) → Step 2 synthesis (source summary + concept page + `[[wikilink]]`); Step 1 output is Step 2 context, always sequential | [nashsu/llm_wiki](https://github.com/nashsu/llm_wiki) | GPL-3.0 | **IDEA-ONLY — zero verbatim code** |
+| 2-phase separation: Phase A extract-all-without-writing (pure read) / Phase B generate (writes to `processed/`, never `wiki/`); A·B never overlap in one execution context | atomicstrata | License TBD | **CONCEPT-ONLY — no code** |
+| Cascade return: every compile write returns `{ affected_backlinks: string[] }` so the M3 caller schedules staleness updates | lucasastorian/llmwiki | Terminology only | **CONCEPT-ONLY — no code** |
+
+---
+
+## M4 Distill — Absorbed Patterns
+
+M4 Distill 스킬(`assets/skills/distill/`)은 standalone 흡수-분석기다.
+**verbatim 코드 사용 없음** — 패턴 시그니처는 self-authored mining 문서에서 도출했다.
+
+| Pattern | Source | License | Note |
+|---------|--------|---------|------|
+| Provider-injection seam (`AnalyzerProvider` mirrors `EmbeddingProvider`) — deterministic stub for tests, real LLM injected in production | oh-my-secondbrain M1 (self) | Internal | 코드베이스 1급 설계 패턴 |
+| Red-team pattern signatures: parallel pool, SHA-256 fingerprint, sqlite-vec store, token chunker, retry, RRF fusion, typed sub-query | [qmd (tobi)](https://github.com/tobi/qmd) | MIT | mining doc 도출, verbatim 없음 |
+| Red-team pattern signatures: 4-pass entity dedup, Leiden/Louvain community detection, grow-only build_merge, 3-tier edge confidence, pipeline-as-modules, 2-pass extraction | [graphify (Safi Shamsi)](https://github.com/safishamsi/graphify) | MIT | mining doc 도출, verbatim 없음 |
+| Clean-room mechanism (pure data spec, caller spawns subagent) + mutation-detector SHA snapshot protocol | plan.md M4 / deep-interview R13·R16 | Internal | Self-authored |
+
+---
+
+## M3 Wiki Engine — Absorbed Patterns
+
+M3 위키 컬렉션은 이전 구현에서 아이디어/알고리즘만 흡수한 목록이다.
+**verbatim 코드 사용 없음** — 모든 구현은 독립적으로 작성되었다.
+
+| Pattern | Source | License | Note |
+|---------|--------|---------|------|
+| Navigation conventions: `wiki/index.md` global catalog regenerated after every compile run; `wiki/log.md` append-only compile log (`## [YYYY-MM-DD] compile \| ConceptName`) | [Karpathy wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) | No license declared | **IDEA-ONLY — no verbatim code** |
+| Collection owner pattern: five responsibilities (namespace/identity, link-graph closure, staleness-ledger delegation, navigation delegation, processed→wiki promotion) | [Astro-Han/karpathy-llm-wiki](https://github.com/Astro-Han/karpathy-llm-wiki) | MIT | **IDEA-ONLY — no verbatim code** |
+| 3-phase hard separation: Research→Compile(sequential)→Wiki(read-only query surface); compile never writes wiki/ directly, a wiki query never triggers compile, promotion is the sole path into wiki/ | [nvk/llm-wiki](https://github.com/nvk/llm-wiki) | Apache-2.0 | **IDEA-ONLY — no verbatim code** |
+| Cascade consumption: consume `affected_backlinks` from the M2 compile result to schedule staleness flips (CLEAN→DIRTY) | [lucasastorian/llmwiki](https://github.com/lucasastorian/llmwiki) | Terminology only | **CONCEPT-ONLY — no code** |
+
+---
+
+## M5 Governance, Conventions, Setup & Adapters — Absorbed Patterns
+
+M5 거버넌스/컨벤션/셋업/어댑터 레이어 구현 과정에서 아이디어/방법론만 흡수한 목록이다.
+**verbatim 코드 사용 없음** — 모든 구현은 독립적으로 작성되었다.
+
+**Conventions / vault-lint** (`src/kernel/engine/conventions/`)
+
+| Pattern | Source | License | Note |
+|---------|--------|---------|------|
+| `validateFrontmatter()` + `parseNote()` delegated for required/type checks; wrapper adds checks 1/4/5 around them | `src/kernel/conventions/{validate,frontmatter}.ts` (self) | Self-authored | Direct import, read-only |
+| Directory-walk pattern (SKIP_DIRS + recursive readdir generator) reimplemented independently to avoid coupling to link-issue logic | `src/kernel/conventions/lint.ts` (self) | Self-authored | Pattern absorbed, not imported |
+
+**Setup interview**
+
+| Pattern | Source | License | Note |
+|---------|--------|---------|------|
+| Socratic clarity loop; ambiguity scoring `1 − mean(goal, constraint, criteria, context)`; Round-0 topology gate; Contrarian / Simplifier / Ontologist challenge modes | omc deep-interview methodology | Self-reimplemented | **METHOD-ONLY — no source code copied**; loop, scoring, gate, modes independently authored in TypeScript |
+
+**Governance skills**
+
+| Pattern | Source | License | Note |
+|---------|--------|---------|------|
+| decisions/ zone pattern — a dedicated top-level folder for structural decision artefacts | Ataraxia vault "95. Decisions" | Private vault, no external license | CONCEPT-ONLY — no verbatim content |
+| Six-field ADR structure (context/decision/consequences/status/supersedes/superseded_by) | Michael Nygard ADR template (cognitect.com/blog/2011) | No license stated | IDEA-ONLY — format reimplemented |
+| Taxonomy seeder (read engine DEFAULT → write per-vault override) + vault-confinement guard mirroring `src/kernel/capture/safe.ts` | bstack second-brain design (self) | Self-authored | Full idea absorption |
+| Append-only/immutability → SUPERSEDE-ONLY ADR update rule; architecture.md stub follows the sub-dir README (R21) convention | M3 wiki ledger (self) | Self-authored | Internal reuse, same codebase |
+
+**Governance scaffold & ontology schemas** (`.oms/governance/`, `core/ontology/schemas/`)
+
+| 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) |
+| 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 |
+
+**Shared skills** (`assets/skills/`)
+
+| Work | Source | License | Note |
+|------|--------|---------|------|
+| Shared skill source consumed by Claude, Codex, and Hermes | `assets/skills/*/SKILL.md` (self) | Self-authored | No external sources absorbed |
+
+---
+
+공개적으로 작업하고 공유해주신 위 모든 분들께 다시 한번 진심으로 감사드린다.
+새로운 흡수가 있을 때마다 이 목록을 갱신한다.

package/CHANGELOG-assets.md

@@ -0,0 +1,19 @@
+# Assets Changelog
+
+Skills, agents, and ontology data changes belong here.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-24
+
+### Fixed
+
+- Packaged host guidance names the invocations each host actually installs. Codex namespaces every skill under an `oms-` prefix, so its guidance now says `$oms-write` rather than `$write`, which would fail on a real install. A reference to `core/agents/retriever.md` was also removed: that path never shipped in the npm artifact, so it was broken for every installed user while resolving fine in the repository.
+
+### Added
+
+- `assets/skills/` is the single authored source for all six skills — `write`, `search`, `link`, `distill`, `status`, `doctor` — replacing four drifted copies. Frontmatter is restricted to `name`, `description`, `aliases`, `mcp_tool` and `mcp_args`; the five skills that declare a tool are validated against that tool's advertised schema, so a skill cannot ship arguments its tool would reject.
+
+### Removed
+
+- `skills-manifest.yaml`. It declared itself generated while no generator existed, had no consumer anywhere in the source, scripts or CI, and never shipped in the package.

package/CHANGELOG-cli.md

@@ -0,0 +1,15 @@
+# CLI Changelog
+
+Changes to the `oms` command surface belong here.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-24
+
+### Changed
+
+- An unrecognised command now exits 1 instead of printing usage and exiting 0. Silent success on a typo made a removed command indistinguishable from a working one.
+
+### Removed
+
+- The top-level qmd-compatible aliases `oms query`, `oms vsearch`, `oms get`, `oms multi-get` and `oms status` are gone, with ADR-009's D2. The canonical nested commands — `oms semantic query|status|get|multi-get|vsearch` — are unaffected and remain the supported surface.

package/CHANGELOG-kernel.md

@@ -0,0 +1,25 @@
+# Kernel Changelog
+
+Domain logic changes belong here.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-24
+
+### Fixed
+
+- Collection scoping now constrains the candidate set before result limiting. A filtered query previously ran against already-truncated results, so it could return nothing while matching in-collection documents sat below the limit.
+- Collection names are matched literally. They were interpolated into a SQL `LIKE` pattern unescaped, so `_` and `%` acted as wildcards and a request for `my_notes` also matched `myXnotes`.
+
+### Added
+
+- A `SearchBackend` seam names the retrieval capability OMS actually ships, so a second backend has something to implement against instead of reaching into the engine's own types. A request is either a plain `query` or typed `searches` sub-queries — never both — plus `limit`, `minScore`, and an `intent` field that disambiguates without itself searching. That exclusive choice is enforced at runtime as well as in the type, because a request parsed from JSON at the MCP boundary arrives unchecked.
+- A conformance suite defines what "a search backend" means. A new backend implements the interface and must pass `src/kernel/searchbackend/conformance.test.ts`; anything that can't is not a backend.
+
+### Changed
+
+- The in-repo engine is the **default** search backend. qmd is pluggable, neither default nor required, and no dependency was added or removed to make the seam exist — a third-party binary is never mandatory for a core capability.
+- A plain `query` expands to lexical search only. Expanding it to lexical + vector was tried and rejected: on a vault with no embeddings that converts a perfectly good lexical answer into a loud failure. Asking for `vec` explicitly still fails loudly with `available: false` naming `OMS_EMBEDDING_PROVIDER` and `OMS_EMBEDDING_MODEL`, which is ADR-007 behaving exactly as locked.
+- **Breaking:** every domain module now lives under `src/kernel/`, and `src/index.ts` moved with it. The package `main` and `types` are now `dist/kernel/index.js` and `dist/kernel/index.d.ts`. Importing the package by name is unaffected; anything reaching into a deep `dist/` path must update, since the package publishes no `exports` map to shield those paths.
+- **Breaking:** `retrieve/` is now `kernel/search/`, matching the `search` skill and the `oms_search` tool that already carried that name.
+- ADR-009 is superseded only in part. D2, the qmd-compatible surface as a product interface, is retired. D1, link-based `resolveEffectiveVault`, remains in force and is load-bearing for the verified-target write kernel — marking the whole ADR dead would have silently retired a live contract.

package/CHANGELOG-mcp.md

@@ -0,0 +1,26 @@
+# MCP Changelog
+
+MCP server tools and resources belong here.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-24
+
+### Changed
+
+- `oms_search` is genuinely read-only and is now annotated as such. It previously advertised `readOnlyHint: false`, and truthfully so: searching a vault with no index silently created `.oms/` and initialised an SQLite store, and the `embeddingSyncBeforeSearch` family of parameters let any caller turn a search into a write by passing a flag. Neither is possible now. This matters beyond tidiness, because MCP hosts may auto-approve tools that declare themselves read-only.
+
+  Searching an unindexed vault still returns results. Rather than refusing until you run a command, the server builds the lexical index in memory for the life of the session and answers from that, so a first search on a fresh vault behaves as it always did while leaving the vault byte-identical. Once a persistent index exists it is used as-is and a search never rewrites it; refreshing it is `oms semantic sync`'s job.
+
+  Preparing lexical or embedding data on disk is now exclusively `oms_doctor { op: "sync-embeddings" }`, which is annotated as writing and routes through the verified-target kernel. Asking for vector retrieval on a vault with no vectors still fails loudly rather than quietly degrading to lexical.
+- `oms_search` advertises `limit` (default 10), `minScore` (default 0) and `rerank` (default false). The first two are applied at the normalizer, so an options-free query is bounded rather than unlimited. `rerank` is opt-in per ADR-011: `true` reranks only when startup was given a real reranker and otherwise fails loudly with configuration guidance, rather than silently returning unreranked results as if the request had been honoured.
+
+- The public MCP surface is now five tools — `oms_write`, `oms_search`, `oms_link`, `oms_status`, `oms_doctor` — down from twenty-three. The eighteen detail tools are reachable through an `op` parameter on the tool that owns them; nothing was deleted, so no capability is lost, but any client calling a detail tool by its old name must switch to the owning tool plus `op`.
+- `oms_search` routes through the `SearchBackend` seam. A plain `query` now expands to lexical retrieval and returns results on a vault with no embedding provider, where it previously failed. Asking explicitly for vector retrieval — through a typed `vec` or `hyde` sub-search, the `vec`/`hyde` shorthands, or `mode: "vsearch"` — still fails loudly naming `OMS_EMBEDDING_PROVIDER` and `OMS_EMBEDDING_MODEL`. Lexical is a default for callers who did not choose a strategy, never a substitute for one that was asked for.
+- Supplying an explicit `mode` together with explicit `searches` is refused as contradictory rather than resolved by discarding one of them.
+- `oms_write` refuses a request that addresses the note both ways at once. `notePath` and `folder`/`filename` are alternatives; supplying both used to write one form while reporting the other's implications.
+- Every mutating `oms_doctor` repair returns a typed receipt whose postcondition the server verified by reading persisted state back. Repairs are admitted through the verified-target kernel before anything touches disk, so a `cwd`-inferred target is rejected while diagnosis still works.
+
+### Removed
+
+- The qmd-compatible aliases `query`, `get`, `multi_get` and `status`, and the `qmd://` resource, are gone. ADR-009's D2 is superseded by ADR-010; D1 remains in force.

package/CHANGELOG-vendors.md

@@ -0,0 +1,22 @@
+# Vendors Changelog
+
+Per-host adapter and installer changes belong here.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-24
+
+### Changed
+
+- Plugin roots moved to the repository root. `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json` now reference `./assets/skills/` as an in-root path, which is what makes a single authored skill source possible; each host keeps its own manifest shape and its own MCP config. Hermes is deliberately asymmetric: it has no repo plugin manifest because `~/.hermes/skills/` is its native surface, and its installer reads the same shared source.
+
+### Removed
+
+- The `adapters/` tree is gone. Its skills were four copies that had drifted to thirteen, fourteen, twelve and eleven entries; hooks, rules and guidance moved under `assets/`.
+
+## [0.1.6] - 2026-06-02
+
+### Changed
+- The project is published to npm as `oh-my-second-brain`, while `oms` stays the CLI, MCP, skill, and repo slug.
+- The installer defaults to the published npm package instead of `npx` against GitHub release URLs.
+- Host MCP registration now points at the installed `oms mcp --vault ...` command.

package/CHANGELOG.md

@@ -1,7 +1,31 @@
 # Changelog
 
+This aggregate changelog contains changes that span multiple layers.
+
+- [Kernel changelog](./CHANGELOG-kernel.md) — domain logic
+- [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
+
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-24
+
+### Breaking
+
+- **The MCP surface is five tools.** `oms_write`, `oms_search`, `oms_link`, `oms_status` and `oms_doctor` replace the previous twenty-three. The eighteen detail tools were not deleted: each is reachable through an `op` parameter on the tool that owns it, so no capability was lost. A client that calls a detail tool by its old name must switch to the owning tool plus `op`. See [CHANGELOG-mcp.md](./CHANGELOG-mcp.md) for the operation map.
+- **The qmd-compatible aliases are gone.** The `query`, `get`, `multi_get` and `status` commands and the `qmd://` resource were retired; ADR-009's D2 is superseded by ADR-010, while D1 remains in force. The canonical nested commands `oms semantic query|status|get|multi-get|vsearch` are unaffected.
+- **`oms_search` no longer accepts sync parameters.** `embeddingSyncBeforeSearch` and its siblings let a caller turn a search into a write, which is incompatible with the read-only guarantee the tool now makes. Preparing index data on disk is `oms_doctor { op: "sync-embeddings" }`, which is annotated as writing.
+
+### Changed
+
+- **`src/` is five role layers.** `kernel`, `cli`, `mcp`, `vendors` and `assets` replace twenty-one top-level entries, and `adapters/` is dissolved. The domain library is the kernel; the CLI and MCP server are thin entrypoints over it. Three import-direction, module-size and surface-parity gates enforce the boundaries, and all of them fail closed rather than passing on an empty scan.
+- **Skills exist once.** `assets/skills/` holds exactly six — `write`, `search`, `link`, `distill`, `status`, `doctor` — replacing near-duplicate copies that had drifted across four vendor trees. This works because the plugin root is the repository root, so every host manifest points at the same directory; there is no copy step and no generated manifest.
+- **`oms_search` is genuinely read-only** and is annotated as such. It previously created `.oms/` and an SQLite store on a plain search. Searching an unindexed vault still returns results, now from an index built in memory for the session, so the vault is left byte-identical. This matters because MCP hosts may auto-approve tools that declare themselves read-only.
+- The published package now ships `ACKNOWLEDGMENTS.md`, because the licence section links to it and shipping the note without its target left a dangling reference in the artifact.
+- `docs/release.md` no longer ships. It documents how to release this package, which an installed consumer cannot do; the READMEs link to the repository copy instead.
+
 ## [0.2.0] - 2026-08-19
 
 ### Added
@@ -74,13 +98,6 @@
 ### Fixed
 - Frontmatter diagnostics are tolerant: malformed frontmatter no longer blocks retrieve or build paths.
 
-## [0.1.6] - 2026-06-02
-
-### Changed
-- The project is published to npm as `oh-my-second-brain`, while `oms` stays the CLI, MCP, skill, and repo slug.
-- The installer defaults to the published npm package instead of `npx` against GitHub release URLs.
-- Host MCP registration now points at the installed `oms mcp --vault ...` command.
-
 ## [0.1.5] - 2026-06-02
 
 ### Changed

package/README.ko.md

@@ -65,7 +65,7 @@ oms install --runtime all --vault /path/to/vault --yes       # 적용
 | **codex** | `.codex-plugin/plugin.json` | `AGENTS.md` | `$` | 네이티브 스킬 + MCP |
 | **hermes** | `manifest.json` | `SOUL.md` | (MCP/tools) | 네이티브 스킬 + MCP |
 
-`oms install`은 호스트 네이티브 규칙/스킬과 관리형 `oms` MCP 등록을 작성하며, `oms uninstall`로 되돌릴 수 있다. 호스트별 상세: [adapters/README.md](./adapters/README.md).
+`oms install`은 호스트 네이티브 규칙/스킬과 관리형 `oms` MCP 등록을 작성하며, `oms uninstall`로 되돌릴 수 있다.
 
 ## CLI
 
@@ -120,7 +120,7 @@ npm test
 npm run release:check   # lint + build + test + audit + pack + artifact-smoke + plugin 검증
 ```
 
-릴리스 절차: [docs/release.md](./docs/release.md).
+릴리스 절차: [docs/release.md](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/docs/release.md).
 
 ## 라이선스
 

package/README.md

@@ -14,15 +14,15 @@ It is **convention-first and user-owned**: your vault stays plain markdown, the
 ## How it works
 
 ```
-core (written once)                       adapters (one per host)
-  ontology loading                          claude-code  .claude-plugin + CLAUDE.md   /sigil
-  convention validation         +           codex        .codex-plugin + AGENTS.md    $sigil
-  graph + semantic runtime                  hermes       manifest.json + SOUL.md      (MCP/tools)
-  MCP server (capture/retrieve/validate)
+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
 ```
 
-- **core** is host-agnostic: ontology, validation, the graph/semantic engine, and the MCP server.
-- each **adapter** absorbs exactly one host's structural differences (manifest schema, convention file, invocation sigil) — adding a host means adding an adapter directory, not touching core.
+- **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
@@ -63,17 +63,17 @@ Full guide: [docs/install.md](./docs/install.md).
 |------|----------|-----------------|-------|--------|
 | **claude-code** | `.claude-plugin/plugin.json` | `CLAUDE.md` | `/` | installable |
 | **codex** | `.codex-plugin/plugin.json` | `AGENTS.md` | `$` | native skills + MCP |
-| **hermes** | `manifest.json` | `SOUL.md` | (MCP/tools) | native skills + MCP |
+| **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: [adapters/README.md](./adapters/README.md).
+`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).
 
 ## CLI
 
 ```
 oms setup      Adopt an existing vault into the convention (writes .oms/taxonomy.yaml; never edits notes)
-oms install    Install host adapters + MCP registration
-oms uninstall  Remove host adapters + MCP registration
-oms update     Check/apply a package update, then reconcile adapters
+oms 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
@@ -85,11 +85,11 @@ oms hook       Vault guard hooks (Claude Code pre/post tool-use)
 
 ## MCP tools
 
-`oms mcp` exposes status, read, retrieve, validation, and gated write tools, including:
+`oms mcp` exposes exactly five public tools:
 
-`oms_graph_status` · `oms_graph_build` · `oms_list_concepts` · `oms_retrieve_context` · `oms_retrieve_by_axis` · `oms_sync_embeddings` · `oms_semantic_query` · `oms_get_document` · `oms_multi_get_documents` · `oms_lazy_load_note` · `oms_validate_contract` · `write`
+`oms_write` · `oms_search` · `oms_link` · `oms_status` · `oms_doctor`
 
-`write` is gated by path-safety, vault-confinement, and the kernel-owned concept contract.
+`oms_write` is gated by path-safety, vault-confinement, and the kernel-owned concept contract.
 
 ## Vault layout (`.oms/`)
 
@@ -121,7 +121,7 @@ npm test
 npm run release:check   # lint + build + test + audit + pack + artifact-smoke + plugin validate
 ```
 
-Release process: [docs/release.md](./docs/release.md).
+Release process: [docs/release.md](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/docs/release.md).
 
 ## License
 

package/{adapters/claude-code → assets/claude}/CLAUDE.md

@@ -13,13 +13,13 @@ All knowledge capture and retrieval must follow the declared semantic convention
 - Read `.oms/concepts/*.yaml` to understand field requirements and lenses.
 
 **When writing vault notes:**
-- Use the `/oms-write` skill. Call MCP `write`. Do not use host Write/Edit for vault `.md` files.
-- The kernel fills and checks frontmatter from `.oms`. `ask` or `rejected` means fix and call `write` again.
+- 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 `/oms-retrieve` skill or follow the retriever persona (`core/agents/retriever.md`).
+- 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 `write` rejects contract violations.
+`oms doctor` always exits 0. MCP `oms_write` rejects contract violations.

package/{adapters → assets}/codex/AGENTS.md

@@ -10,7 +10,7 @@ This vault is governed by Oh My Second Brain conventions stored in `.oms/`.
 - 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.
 
-**Write:** Use `$oms-write`. Call MCP `write`. Do not use host Write/Edit for vault `.md` files.
-**Retrieve:** Use `$oms-retrieve` skill or follow the retriever persona with declared lenses.
+**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.
 
-> **v0 native install:** `oms install --runtime codex` installs Codex rules, `$oms-*` skills, and a managed Codex MCP config. Use Oh My Second Brain MCP tools for write/retrieve and CLI commands for lifecycle.
+> **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.

package/{adapters → assets}/codex/rules/oms.md

@@ -10,12 +10,12 @@ Oh My Second Brain is a convention harness, not a content generator. The user ow
 
 | User intent | Preferred Oh My Second Brain surface |
 |---|---|
-| adopt a vault | `$oms-setup` or `oms setup --vault <path>` |
-| install host integration | `$oms-install` or `oms install --runtime codex --vault <path> --yes` |
-| uninstall host integration | `$oms-uninstall` or `oms uninstall --runtime codex --yes` |
+| adopt a vault | `oms setup --vault <path>` |
+| 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 `write` (`create`, `append`, or `update`) |
-| retrieve knowledge | use MCP `oms_retrieve_context`, then `oms_lazy_load_note` only when needed |
+| 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 |
 
 ## Safety
 

package/{adapters → assets}/hermes/README.md

@@ -5,6 +5,6 @@ Installed by `oms install --runtime hermes` into:
 - `~/.hermes/skills/knowledge-management/oms/`
 - `~/.hermes/config.yaml` as `mcp_servers.oms`
 
-The skill bundle mirrors Oh My Second Brain's write/retrieve/setup/doctor lifecycle and uses the Oh My Second Brain MCP server for runtime operations.
+The skill bundle contains Oh My Second Brain's `write`, `search`, `link`, `distill`, `status`, and `doctor` skills and uses the Oh My Second Brain MCP server for runtime operations.
 
 Unlike Claude Code (`claude plugin install`), Hermes exposes no native marketplace or plugin-update command, so this adapter stays OMS-managed: `oms update` reconciles it by re-running the same install path. `mcp_servers.oms` is edited surgically, leaving the rest of `~/.hermes/config.yaml` — including comments and key ordering — untouched.

package/{adapters → assets}/hermes/SOUL.md

@@ -11,8 +11,8 @@ This vault is governed by Oh My Second Brain conventions stored in `.oms/`.
 - Read `.oms/taxonomy.yaml` for folder-to-concept bindings.
 - Read `.oms/concepts/*.yaml` for field declarations and lenses.
 
-**Write:** Use the `write` skill. Call MCP `write`. Do not use host Write/Edit for vault `.md` files.
+**Write:** Use the `write` skill. Call MCP `oms_write`. Do not use host Write/Edit for vault `.md` files.
 
-**Retrieve:** Follow the retriever persona — identify purpose, match lens, project lens fields only.
+**Retrieve:** Use the `search` skill or follow the retriever persona — identify purpose, match lens, project lens fields only.
 
-> **v0 native install:** `oms install --runtime hermes` installs a Hermes skill bundle and registers Oh My Second Brain MCP in `~/.hermes/config.yaml`. Use Oh My Second Brain MCP tools for write/retrieve and CLI commands for lifecycle.
+> **v0 native install:** `oms install --runtime hermes` installs the `write`, `search`, `link`, `distill`, `status`, and `doctor` skills and registers Oh My Second Brain MCP in `~/.hermes/config.yaml`. Use Oh My Second Brain MCP tools for vault operations and CLI commands for lifecycle.

package/{adapters/hermes/manifest.json → assets/hermes-manifest.json}

@@ -1,7 +1,6 @@
 {
   "name": "oms",
-  "version": "0.2.0",
-  "description": "Oh My Second Brain convention layer for Obsidian vaults \u2014 Hermes skill bundle and MCP adapter.",
-  "_note": "oms install writes ~/.hermes/config.yaml mcp_servers.oms and installs skills under ~/.hermes/skills/knowledge-management/oms/.",
-  "skills": "./skills/"
+  "version": "0.3.0",
+  "description": "Oh My Second Brain convention layer for Obsidian vaults — Hermes skill bundle and MCP adapter.",
+  "_note": "oms install writes ~/.hermes/config.yaml mcp_servers.oms and installs skills under ~/.hermes/skills/knowledge-management/oms/."
 }

package/assets/skills/distill/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: distill
+description: Analyze a target as read-only input and return a structured absorption report.
+---
+
+# distill
+
+Analyze a repository, document, skill, or concept as inert read-only input. This is a recipe skill; it has no backing MCP engine and does not write to the vault.
+
+## Use when
+
+Use this skill to extract reusable patterns, identify risks, and preserve attribution before adopting material from a target.
+
+## Usage
+
+```text
+/distill <target-path-or-text>
+```
+
+Do not execute the target. Produce a report with exactly three sections: Patterns, Risks, and Attribution. The report is the output; write it only when explicitly requested outside this skill.