oh-my-second-brain 0.20.5 → 0.21.0

package/.claude-plugin/marketplace.json

@@ -10,15 +10,15 @@
     {
       "name": "oms",
       "description": "Oh My Second Brain convention layer for Obsidian vaults — capture, retrieve, and validate knowledge under a declared semantic convention.",
-      "version": "0.20.5",
+      "version": "0.21.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",
+      "homepage": "https://github.com/Xia-Ataraxia/oh-my-second-brain#readme",
+      "repository": "https://github.com/Xia-Ataraxia/oh-my-second-brain",
       "license": "MIT",
       "keywords": [
         "obsidian",
@@ -37,5 +37,5 @@
       ]
     }
   ],
-  "version": "0.20.5"
+  "version": "0.21.0"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.20.5",
+  "version": "0.21.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults — six shared skills and four MCP tools under a user-owned contract.",
   "author": {
     "name": "gobeumsu"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.20.5",
+  "version": "0.21.0",
   "description": "Oh My Second Brain convention layer for Obsidian vaults — Codex native rules, skills, and MCP adapter.",
   "_note": "oms setup host install writes Codex MCP config and provenance, installs ~/.codex/rules/oms.md, and installs the six shared skills under ~/.codex/skills/oms-*.",
   "skills": "./assets/skills/",

package/ACKNOWLEDGMENTS.md

@@ -4,7 +4,7 @@ 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)
+> 관리 규칙: [`docs/rules/external-attribution.md`](https://github.com/Xia-Ataraxia/oh-my-second-brain/blob/main/docs/rules/external-attribution.md)
 
 ## 계약·평가·인터뷰 설계
 

package/CHANGELOG-assets.md

@@ -4,6 +4,22 @@ Skills, agents, templates, and host guidance changes belong here.
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-10-03
+
+- **Use the selected dark library README artwork.** The English and Korean READMEs now share the finished native Blender scene with floating pages and knowledge-stars, with readable poster typography and material credits. Setup commands, safety guidance, links, and runtime behavior are unchanged.
+
+- Search and write guidance explains the existing exact-path read-before-edit flow: use the complete source and its returned revision as `ifMatch`, and reread after a stale-write rejection rather than hashing a retrieved slice.
+
+- The shipped search skill teaches optional-template observed discovery, exact typed facet selection, metadata-only zero-hit responses and the lexical-only/single-collection boundary. It distinguishes detached current-note validation from synchronization of persistent/vector indexes and warm-session speed from cold CLI calls.
+
+- **Refresh the English and Korean README presentation.** Both READMEs now share a repository-specific 3D hero and a more compact overview while preserving setup, contract, host, safety, documentation, and credit guidance. Canonical repository links now point directly to `Xia-Ataraxia/oh-my-second-brain` after the ownership transfer.
+
+## [0.20.6] - 2026-10-01
+
+- **Skills and host guidance now say that contract findings warn instead of deny.** The `write`, `distill`, and `setup` skills, the Claude, Codex, and Hermes host guidance, and the README and docs had kept saying that a note breaking the contract is denied. Since the contract became warn-first, such a note is saved with each finding as a `{field, kind}` warning and one guidance command; only a safety refusal (a path outside the vault, a control or unsafe path, unsupported input, a tampered contract) denies, and in a sealed vault a note written through MCP or `oms write` whose frontmatter does not parse may be kept as a draft. Agents reading the old wording stopped and asked after a write that had already succeeded. The README also no longer says MCP cannot seal: `interview` `op: seal` seals a proposal the owner confirmed. Run `oms setup host sync` to refresh installed host guidance.
+
+- **Docs and skills say what `--fix` and `ifMatch` do.** The README, the docs, and the `doctor` skill now say that `oms doctor contract --fix` also rebuilds an unreadable index. The architecture page no longer counts a stale `ifMatch` among the safety refusals; it is a revision precondition that writes nothing. The `write` skill says that among contract states only a tampered contract denies, the 0.19 migration guide notes that a contract finding has warned since 0.20, and the harness architecture page cites the current `status.ts` lines.
+
 ## [0.20.5] - 2026-09-30
 
 ## [0.20.4] - 2026-09-30

package/CHANGELOG-cli.md

@@ -4,6 +4,20 @@ Changes to the `oms` command surface belong here.
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-10-03
+
+- Enabled HTTP maintenance cancels immediately when shutdown is requested, even when a client leaves a request body unfinished. Connections have a bounded drain period and repeated close calls reuse one shutdown.
+
+- `oms serve mcp|http --maintenance lexical|full` explicitly enables automatic maintenance of an existing canonical index. Default startup stays unchanged; unverified targets, missing indexes and incompatible full-mode models are rejected before serving.
+
+- `oms search --observed '<JSON>'` and HTTP `/search` accept explicit current-note frontmatter filters and bounded key/value discovery. Metadata-only requests need no query text, and `-n 0`/`limit: 0` suppresses note hits while retaining discovery.
+
+- **CLI and HTTP lexical search see unsynced note edits without repairing the persistent index.** HTTP reuses a server-owned detached native FTS corpus; each CLI invocation closes its own transient corpus. Requests that race an edit return a retry instead of stale matches with new previews.
+
+## [0.20.6] - 2026-10-01
+
+- **`oms doctor contract --fix` usage says what it repairs.** The `doctor` and contract usage text said `--fix` only re-indexes a moved or unindexed vault; it also rebuilds an unreadable index, and the usage now says so. The contract usage also names `oms interview` as the command that reseals a broken seal, matching the diagnosis's `recovery` field.
+
 ## [0.20.5] - 2026-09-30
 
 ## [0.20.4] - 2026-09-30

package/CHANGELOG-kernel.md

@@ -4,6 +4,65 @@ Domain logic changes belong here.
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-10-03
+
+- Default public facet summaries now bound payload bytes as well as cardinality: at most 20 entries and 32 KiB of serialized array JSON including the two-space CLI/MCP indentation, omitting keys or values over 512 UTF-8 bytes without changing their identities. Warnings disclose retained/total counts and byte-limit omissions; complete collection aggregation, hit ranking, counts and pagination remain unchanged. This bounds the facet array, not the whole response or aggregation memory.
+
+- Temporary lexical spills and read-only snapshots retain the canonical directory's device/inode identity and recheck ownership before reuse, copying, and cleanup. Missing, replaced, symlinked, or unverifiable directories are left untouched with a bounded residue diagnostic; cleanup failures preserve the original operation error. These observations detect replacement but do not provide an atomic boundary against ongoing same-user tampering.
+
+- Observed-only frontmatter filters and discovery capture current metadata without seeding detached lexical storage or chunking Markdown. Warm requests reuse the existing parsed projection cache and private EAV backing. A later lexical or mixed query reconciles the complete canonical chunk corpus, while concurrent upgrades wait for joined metadata selectors to finish; source witnesses, cursor validation, memory budgets and read-only persistence behavior are preserved.
+
+- Detached lexical reconciliation skips clearing a document whose stored chunk set is already empty. Empty FTS deletes flush pending terms even without matching rows; avoiding them lets fresh notes share the intended bounded native batch while preserving existing-note cleanup and rollback.
+
+- Live lexical capture groups disk-backed document updates into bounded synchronous transactions. The queue owns serialized chunks and source evidence, including title/heading metadata, and flushes residual records before retrieval. Dedicated reconciliation reuses its outer rollback boundary without redundant FTS savepoints; ordinary store methods retain independent atomicity. In-memory capture still commits and checks the spill budget one document at a time.
+
+- Detached live lexical captures update each note's chunks and verified source evidence in one synchronous private transaction, reducing separate commits during cold corpus construction. A failed source publication rolls back that note's lexical changes. Persistent stores, SQLite durability settings, native ranking, memory budgets and final source validation keep their existing behavior.
+
+- Live lexical capture shares one canonical frontmatter parse between its compact metadata projection and chunk title extraction. Malformed metadata diagnostics, title fallback, raw embedding text and copied projection values keep their existing semantics; unchanged warm notes still skip parsing.
+
+- Chunking counts each line's script-aware token weight once and carries the exact weight through overlap, avoiding repeated scans of growing buffers on short-line notes. Canonical chunk text, title, heading paths, ordinals and digests remain unchanged; cold live search still captures the full corpus and performs its existing freshness checks.
+
+- Automatic maintenance ignores excluded editor housekeeping watch hints while retaining known exclusion settings and their directory replacements. Uppercase Markdown hints remain incremental, and unsafe or uncertain paths still request complete reconciliation.
+
+- Automatic full maintenance only loads an already installed native embedding backend; missing binaries fail with setup guidance instead of downloading or building llama.cpp in the background. Explicit provider callers retain their existing policy.
+
+- Explicit automatic maintenance reuses the existing index and revisioned queue with bounded scheduling, complete-scan recovery and separate conservative process ownership. Watch hints never authorize mass deletion; cancelled or superseded embedding jobs cannot commit. The feature stays off unless a server invocation enables it, and existing source/target/model checks remain authoritative.
+
+- Warm live lexical sessions keep their complete private corpus across persistent index writes, vector syncs, rebuilds, and index removal or replacement. Each query still refreshes current Markdown and validates returned sources; incomplete captures and changed or unknown vault identities retain conservative bootstrap checks. Private freshness never certifies persistent/vector synchronization, and searches still leave those stores untouched.
+- Late embedding jobs validate their captured revision and model before initializing an existing store. Preflight, schema initialization, and publication share one connection and transaction, so replaced stores and cancelled legacy migrations remain unchanged when a job is rejected.
+
+- Background embedding maintenance completes already-embedded queue entries only after checking real vector coverage, and repairs verified clean chunks whose vectors are missing. Legacy revision-less entries can be upgraded safely, preventing repeated stale retries after interrupted queue housekeeping. Pending-only paths remain visible to complete scans so excluded or deleted notes cannot strand orphaned work.
+
+- Short index writers serialize stale-lock recovery with immutable per-attempt owner records, closing a race that could temporarily move a live successor and admit another writer. All concurrent writers must use the upgraded protocol; the legacy lock remains visible but cannot fence an already-running old reclaimer. Unreadable or malformed legacy owner records now fail closed instead of being reclaimed or retried indefinitely.
+
+- Per-note write maintenance publishes lexical chunks, source evidence, and a revisioned embedding queue in one SQLite transaction. Background embedding results can commit only against the same source, chunks, model, and active owner; edits, deletions, or cancellation leave newer work intact. Explicit embedding sync also repairs missing vectors left by interrupted legacy lexical updates and retains pending work through lexical-only passes.
+
+- Observed value facets include a directly reusable, JSON-safe exact typed selection. Selecting a date, date-looking string, numeric timestamp, boolean or string now reproduces its distinct-note count within an unchanged discovery scope, without changing declared-axis or legacy comparison behavior. Exact date selectors require canonical ISO strings rather than permissive date coercion.
+- Ordinary live refresh prunes obsolete projection backing without invalidating unchanged observed-field rows. The next explicit observed query removes deleted/excluded canonical metadata and adds renamed notes through the existing authoritative snapshot reconciliation, avoiding a whole-corpus EAV rewrite while retaining cursor invalidation and current-source checks.
+
+- Live lexical projection overflow now reuses the original compact parsed document from versioned binary rows in the existing session-private axis store. Unchanged notes beyond the object-cache budget no longer require repeated body reads or YAML parsing; edits and missing/incompatible rows are recaptured, deleted/excluded rows are removed, and ordinary declared-axis/facet behavior remains unchanged. The same private spill owner bounds retained SQLite pages and cleans up failed refreshes after readers drain.
+
+- Explicit observed frontmatter queries now filter the same current-byte native FTS snapshot before candidate limits. Scalar/list predicates, bounded key/value discovery, cross-session cursors, and source-race rejection work without a sealed field declaration; existing declared axes retain their semantics. Dense observations spill the existing EAV repository to disposable session-private storage, never a new persistent index.
+
+- The existing axis-observation repository gains an in-memory observed-field query foundation: shared scalar/list and range operators, parameterized pre-limit candidate intersection, current-source reconciliation, and bounded key/value discovery with distinct-note counts and snapshot-bound cursors. Declared typed axes keep their existing behavior, and cyclic YAML lists no longer recurse forever in the EAV importer.
+
+- Hash-prefixed native document IDs resolve currently admitted Markdown paths, so new or renamed live-search hits can be opened before an explicit index sync. The reader checks current exclusions and captures confined, non-symlink source bytes without changing model/backend selection.
+
+- Live lexical sessions pin candidate capture across concurrent generation changes, drain bounded readers before failed cleanup, and release oversized cores when spill fails. Compact facet projections own their retained string storage so previews, YAML scalars, and link targets cannot pin entire raw notes behind the cache budget.
+
+- **Lexical search stays current between explicit index syncs.** A bounded, session-owned native SQLite FTS corpus refreshes changed/new notes and removes deleted or excluded notes without modifying the vault or persistent index. Native ranking, candidate limits, and complete totals are preserved; source evidence and preview-byte checks reject mid-query revision races. Missing legacy evidence is rebuilt only in the detached corpus, and oversized snapshots spill to disposable external storage.
+
+- Skip per-note filesystem alias probes when source exclusions contain no alias targets, keeping ordinary vault scans responsive without changing exclusion decisions.
+- Read-only SQLite snapshot capture now streams through one 1 MiB buffer instead of retaining two whole database/WAL images. The existing double-capture byte-digest and file-identity checks remain, opened handles are verified against the observed pathname, and failed captures close descriptors and discard their temporary files. Large indexes can be read without memory allocation proportional to multiple copies of the index.
+
+- **Persisted searches report stale source evidence instead of presenting stale matches with fresh previews.** Explicit synchronization records per-note filesystem change evidence and byte digests, including empty notes. A read-only indexed query checks that evidence before retrieval and again after reading previews; missing legacy evidence or externally changed notes return `available: false`, `indexDrift: true`, and an explicit sync command. Unchanged checks do not read note bodies, and a byte-identical touch is verified by hashing only that note. Full or collection-scoped synchronization also removes deleted or newly excluded entries in its own scope; one-file write maintenance preserves unrelated entries. This is a correctness boundary, not live indexing: a subsequent change can add read-only live refresh without weakening the evidence checks.
+- Graph and node-index construction bound concurrent note reads to 32 handles, preventing file-descriptor exhaustion on large vaults without changing the resulting projection or source signature. A failed read stops new work and drains open handles before its original error is returned.
+
+- Warm node-cache reads validate a version-5 filesystem metadata witness instead of rereading every note body. Byte-identical touches still reuse the cache through the existing content hash; real edits and projection changes remain loud. Explicit graph builds derive edges, nodes, and the content hash from the same handle-verified captured bytes and verify note membership and metadata before publishing either cache, while read-only searches leave cache state untouched. Filesystems without trustworthy high-resolution identity evidence retain full-byte validation.
+- **Writes revalidate live template sources before publishing a note.** New notes and writes naming a template carry a witness of the template-folder selector, discovered source paths, exact-byte digests and scan diagnostics. A changed observation returns retryable `WRITE_TEMPLATE_SOURCE_CHANGED` instead of saving stale scaffolding; retrying reads the current templates. Validation runs after the temporary note is staged, again before a hard-link fallback, and before keeping a draft. The target note is rechecked after source validation so concurrent user edits observed there are preserved. This is optimistic revalidation, not a multi-file transaction: changes after a source's last observation can still race publication, and the existing target check-to-rename limitations remain.
+
+## [0.20.6] - 2026-10-01
+
 ## [0.20.5] - 2026-09-30
 
 ## [0.20.4] - 2026-09-30

package/CHANGELOG-mcp.md

@@ -4,6 +4,26 @@ MCP server tools and resources belong here.
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-10-03
+
+- Default read-only MCP servers now close their resources on stdin EOF and termination signals, including disposable lexical disk files after a completed query. Previously that shutdown handler was installed only for opt-in maintenance servers, so ordinary client closure could leave scratch behind. Forced process termination may still leave an orphan directory.
+
+- Tool guidance identifies `search {path}` as the existing revision-bearing exact read for a subsequent `write.ifMatch`. A read/edit regression covers successful use and stale-revision refusal without changing response contracts.
+
+- An explicitly enabled server exposes maintenance status in doctor status, signals successful writes to its bounded update queue, and drains/cancels maintenance on shutdown. The four-tool surface and read-only search annotation stay unchanged.
+
+- Observed predicates accept `exact: {valueType, value}` and value facets return `selection` for direct reuse. Type/value mismatches are refused; exact date values are canonical ISO strings. Selection objects remain included in the existing serialized discovery-page budget.
+
+- `search` `op: query` accepts the distinct `observed: {field?, discover?}` namespace and returns bounded `observed.discovery` only on request. Metadata-only calls can use `limit: 0`; declared `axes.field` and ordinary response payloads are unchanged.
+
+- Live lexical servers retain only the detached index between requests. Reranker/model adapters remain request-owned, so changed installed-model defaults are resolved on the next request and caller-owned rerankers are never disposed.
+
+- **Repeated lexical queries reuse one read-only live snapshot per server.** Unsynced note edits are searchable immediately on the next stable request. The server no longer copies the entire persistent index once to probe existence and again to execute the same query; explicit vector operations retain their existing request-scoped validation.
+
+## [0.20.6] - 2026-10-01
+
+- **The server instructions no longer call a stale `ifMatch` a safety refusal.** They listed it beside the vault boundary and a tampered contract as something that denies `write`. A missing or stale `ifMatch` is a revision precondition: it returns `WRITE_IF_MATCH_REQUIRED` or the retryable `WRITE_TARGET_CHANGED` and writes nothing, and the safety list now also names unsupported input.
+
 ## [0.20.5] - 2026-09-30
 
 ## [0.20.4] - 2026-09-30

package/CHANGELOG-vendors.md

@@ -4,6 +4,12 @@ Per-host adapter and installer changes belong here.
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-10-03
+
+- **Claude's published marketplace fallback follows the new repository owner.** npm-installed copies now add `Xia-Ataraxia/oh-my-second-brain`, and the marketplace manifest's homepage and repository fields use the same canonical location. The marketplace and plugin names and versions are unchanged.
+
+## [0.20.6] - 2026-10-01
+
 ## [0.20.5] - 2026-09-30
 
 - **The Claude marketplace is named after the repository.** `.claude-plugin/marketplace.json` is now `oh-my-second-brain`, so the plugin id is `oms@oh-my-second-brain` for Claude Code and Gajae-Code instead of the doubled `oms@oms`; the plugin and its skills stay `oms` and `/oms:*`. To pick up the new name, run `claude plugin uninstall oms@oms` and `claude plugin marketplace remove oms`, then install again. The README now credits Gajae Code through the acknowledgements, and the Gajae-Code install command lives in the host asset guide.

package/CHANGELOG.md

@@ -10,6 +10,18 @@ This aggregate changelog contains changes that span multiple layers.
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-10-03
+
+- Release rehearsals use a read-only verification job with no OIDC grant and never invoke npm publish, including dry runs. Manual dispatch on a tag or with `rehearsal=false` cannot publish or create a GitHub Release; publication requires a verified `oms-v*` tag push in a separate privileged job. The npm trusted-publisher transfer hold still applies.
+
+- Release instructions use the canonical `oms setup host` and `oms setup package` commands and describe the six skills and four MCP tools verified by the artifact rehearsal, so operators can follow the documented upgrade steps with the current package.
+
+- Packaging and documentation checks accept npm 12's package-name-keyed `pack --json` output alongside npm 10/11 arrays. A shared strict parser rejects errors, unexpected packages, multi-package reports, and malformed file manifests instead of silently skipping checks.
+
+- **Repository metadata follows the GitHub ownership transfer.** Package, issue, installer, attribution, measurement, release-check, and release-process links now point directly at `Xia-Ataraxia/oh-my-second-brain` instead of relying on GitHub's redirect from `GoBeromsu`. The repository history, releases, tags, package name, marketplace name, versions, and author attribution are unchanged. npm trusted-publisher rebinding remains a separately approved registry action; no publish or tag is part of this migration.
+
+## [0.20.6] - 2026-10-01
+
 ## [0.20.5] - 2026-09-30
 
 ## [0.20.4] - 2026-09-30

package/README.ko.md

@@ -1,69 +1,33 @@
 <p align="center">
-  <img src="./assets/readme/hero.svg" alt="Oh My Second Brain. 흩어진 생각이 연결되는 별자리." width="100%" />
+  <img src="./assets/readme-hero.webp" alt="oh my secondbrain — 거대한 서가와 떠다니는 낱장, 서로 이어지는 지식의 별자리." width="100%" />
 </p>
 
 <h1 align="center">Oh My Second Brain</h1>
 
 <p align="center">
   <strong>흩어진 지식이, 다시 하나의 별자리로.</strong><br />
-  Obsidian, Markdown, AI 에이전트를 잇는 사용자 소유의 지식·컨벤션 레이어.
+  Obsidian · Markdown · AI 에이전트를 잇는 사용자 소유의 지식·컨벤션 레이어.
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/oh-my-second-brain"><img src="https://img.shields.io/npm/v/oh-my-second-brain?style=flat-square&amp;color=8b9daa&amp;label=npm" alt="npm 버전" /></a>
-  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%E2%89%A520-80b89b?style=flat-square" alt="Node.js 20 이상" /></a>
-  <a href="#mcp-도구와-에이전트-연결"><img src="https://img.shields.io/badge/MCP-4_tools-97a8b1?style=flat-square" alt="MCP 도구 4개" /></a>
-  <a href="https://github.com/GoBeromsu/oh-my-second-brain/blob/main/package.json"><img src="https://img.shields.io/badge/license-MIT-d7c7a8?style=flat-square" alt="패키지 라이선스 MIT" /></a>
-</p>
-
-<p align="center">
-  <a href="#빠른-시작"><strong>빠른 시작</strong></a> ·
+  <a href="#빠른-시작">빠른 시작</a> ·
   <a href="#동작-방식">동작 방식</a> ·
   <a href="#문서">문서</a> ·
-  <a href="https://github.com/GoBeromsu/oh-my-second-brain/releases">릴리스</a> ·
+  <a href="https://github.com/Xia-Ataraxia/oh-my-second-brain/releases">릴리스</a> ·
   <a href="./README.md">English</a>
 </p>
 
----
+<p align="center"><sub>Node.js ≥ 20 · MCP 도구 4개 · 공통 스킬 6개 · 패키지 라이선스 MIT</sub></p>
 
-볼트에는 이미 아이디어, 결정, 배운 것들이 쌓여 있다. **OMS는 에이전트가 그 지식을 되찾고, 내가 정한 규칙 안에서 노트를 쓰도록 돕는다.** 새 노트 형식도, 정해진 폴더 체계도, 특정 호스트로의 지식 이전도 필요 없다.
-
-Obsidian은 사령탑으로 남는다. OMS가 꺼져 있어도 노트는 사람이 읽고 고칠 수 있는 Markdown 파일이다. Claude Code, Codex, Hermes를 각 호스트의 통합 기능으로 같은 볼트에 연결할 수 있다.
+볼트에는 이미 아이디어, 결정, 배운 것들이 쌓여 있다. **OMS는 에이전트가 그 지식을 되찾고, 내가 정한 규약에 맞춰 노트를 쓰도록 돕는다.** Obsidian은 사령탑으로 남고, 노트는 OMS가 꺼져 있어도 읽고 고칠 수 있는 Markdown 파일로 남는다.
 
 ## 왜 OMS인가?
 
-<table>
-<tr>
-<td width="50%" valign="top">
-<h3>이미 아는 것을 다시 찾기</h3>
-기존 노트를 lexical 검색으로 찾는다. 필요할 때 vector, HyDE, 질의 확장, reranking을 명시적으로 선택한다.
-</td>
-<td width="50%" valign="top">
-<h3>내 볼트의 언어 그대로</h3>
-폴더와 속성의 의미는 내가 정한다. OMS가 제시하는 체계를 따르는 대신, 내 컨벤션을 기록한다.
-</td>
-</tr>
-<tr>
-<td width="50%" valign="top">
-<h3>에이전트가 공유하는 계약</h3>
-setup으로 볼트 규약을 봉인한다. 지원되는 쓰기 경로는 저장 전에 노트 전체가 그 계약에 맞는지 확인한다.
-</td>
-<td width="50%" valign="top">
-<h3>파일의 소유권은 그대로</h3>
-기존 Markdown 노트와 템플릿을 계속 쓴다. setup은 이 파일들을 다시 쓰지 않으며, 봉인된 계약은 볼트 밖에 둔다.
-</td>
-</tr>
-<tr>
-<td width="50%" valign="top">
-<h3>호스트를 넘어 연결하기</h3>
-Claude Code, Codex, Hermes의 네이티브 통합을 사용한다. MCP 도구 4개와 공통 워크플로 스킬 6개를 제공한다.
-</td>
-<td width="50%" valign="top">
-<h3>추측 대신 상태 확인</h3>
-계약 상태, 노트 규약 준수, 색인, wikilink 제안을 확인한다. 검색과 상태 조회는 읽기 전용이다.
-</td>
-</tr>
-</table>
+| 다시 찾기 | 내 규약으로 쓰기 | 계속 소유하기 |
+| :--- | :--- | :--- |
+| Lexical 검색부터 시작하고, 필요할 때 vector·HyDE·질의 확장·reranking을 선택한다. | 폴더와 속성의 의미를 직접 정한다. 지원되는 쓰기 경로에서 계약을 검사하고 결과를 알려준다. | 기존 노트와 템플릿을 유지하며 Claude Code, Codex, Hermes를 같은 볼트에 연결한다. |
+
+검색과 `oms doctor status`는 읽기 전용이다. 색인 유지보수는 명시적으로 실행한다.
 
 ## 빠른 시작
 
@@ -127,19 +91,19 @@ oms search "프로젝트 결정" --vault /path/to/vault
 | **에이전트** | 맥락을 읽고 노트를 작성하며 호스트에 맞는 워크플로를 쓴다. 보존할 가치는 사용자와 에이전트가 판단한다. |
 
 > [!IMPORTANT]
-> **쓰기 검사를 신뢰하기 전에 계약부터 설정한다.** 이 기기에 봉인이 없는 볼트는 계약 판정을 하지 않는다. 일반적인 경로·입력 보호는 그대로 적용된다. 계약을 위반하는 쓰기는 파일을 바꾸지 않는다. 쓰기 허용은 구조 준수를 뜻하며, 사실의 정확성이나 품질 승인이 아니다.
+> **쓰기 검사를 신뢰하기 전에 계약부터 설정한다.** 이 기기에 봉인이 없는 볼트는 계약 판정을 하지 않는다. 그 쓰기에는 `oms interview`를 안내하는 `contract-open` 경고가 붙고, 일반적인 경로·입력 보호는 그대로 적용된다. 계약을 어긴 쓰기는 경고와 함께 저장되고, 안전 거부, 없거나 오래된 `ifMatch`, 검증되지 않은 대상은 파일을 바꾸지 않는다. 경고 없이 허용된 쓰기는 구조 준수를 뜻하며, 사실의 정확성이나 품질 승인이 아니다.
 
 <details>
 <summary><strong>볼트 계약 자세히 보기</strong></summary>
 
 - **의미는 사용자 소유다.** 폴더와 속성 pool을 함께 인터뷰한다. 속성 이름·폴더·페르소나를 하드코딩하지 않고 Inbox fallback도 없다.
 - **볼트 안의 제어 파일은 하나다.** `.oms/settings.json`에 `version`, `vaultId`, `templateFolder`, `embedding`, `agentRepair`를 둔다. 다른 `.oms/` 항목은 무시하고 `oms doctor contract`가 예상하지 않은 제어 파일로 보고한다. `.obsidian/types.json`은 읽기 전용 관측값이며 봉인을 덮어쓰지 않는다.
-- **템플릿은 원본으로 남는다.** 템플릿은 `templateFolder`에 있으며 봉인하거나 판정하지 않는다. 새 노트는 살아 있는 템플릿으로 뼈대를 채운다. 쓰기가 이름을 준 템플릿, 없으면 basename이나 `folder:` 키가 대상 폴더와 맞는 유일한 템플릿이다. 템플릿 파일을 다시 쓰거나 복사하지 않으며, Templater·JavaScript·전용 token 언어를 해석하거나 실행하지 않는다. 쓰기는 작성 중인 노트의 기계적인 부분만 채운다. `{{title}}`·`{{date}}`·`{{time}}` 변수, 새 노트의 date·datetime 기본값, 선택한 템플릿의 frontmatter 기본값과 빠진 heading이다. 노트에 이미 있는 값이 우선한다. 필수 값을 대신 채우지는 않는다.
+- **템플릿은 원본으로 남는다.** 템플릿은 `templateFolder`에 있으며 봉인하거나 판정하지 않는다. 새 노트는 살아 있는 템플릿으로 뼈대를 채운다. 쓰기가 이름을 준 템플릿, 없으면 basename이나 `folder:` 키가 대상 폴더와 맞는 유일한 템플릿이다. 템플릿 파일을 다시 쓰거나 복사하지 않으며, Templater·JavaScript·전용 token 언어를 해석하거나 실행하지 않는다. 쓰기는 작성 중인 노트의 기계적인 부분만 채운다. `{{title}}`·`{{date}}`·`{{time}}` 변수, 새 노트의 date·datetime 기본값, 선택한 템플릿의 frontmatter 기본값과 빠진 heading이다. 노트에 이미 있는 값이 우선한다. 필수 값을 지어내지 않으며, 계약이 값을 하나로 정한 경우에만 무손실 수정으로 채우고 영수증의 `fixes`에 남긴다.
 - **이전 봉인도 읽힌다.** 새 봉인은 폴더와 속성만 저장한다. 이전 릴리스가 만든 봉인도 그대로 읽히며, `oms setup status`는 그 템플릿 제약을 `legacyTemplates` 개수로 보고할 뿐 강제하지 않는다.
-- **판정자는 하나다.** 거부 시 `{field, kind}` 위반과 안내 명령 하나만 반환한다. 규칙 값, 저장소 경로, 계약 본문은 반환하지 않는다.
-- **봉인 증거가 맞지 않으면 쓰기를 거부한다.** 이 기기의 증거가 볼트와 어긋나면 `contract-unreadable`로 거부하고 소유자가 `oms setup`을 다시 실행해야 한다. 봉인이 아예 없는 기기에서는 판정하지 않는 것과 구별한다.
+- **판정자는 하나다.** 저장된 쓰기는 계약 위반을 `{field, kind}` 경고로, 거부된 쓰기는 그 이유를 같은 형태로 반환하며, 각각 안내 명령 하나가 붙는다. 규칙 값, 저장소 경로, 계약 본문은 반환하지 않는다.
+- **변조된 봉인은 쓰기를 거부한다.** `.oms/settings.json`의 vault id가 이 기기의 봉인과 어긋나면 `contract-tampered`로 거부하고, `oms doctor contract`가 원인을 알려준다. 봉인 증거가 없거나 깨졌으면 `contract-unreadable` 경고와 함께 저장하며, 소유자가 `oms interview`로 다시 봉인할 때까지 이어진다. `oms doctor contract`가 볼트 이동이나 색인 항목의 누락·손상을 찾으면, 다시 봉인하지 않고 색인만 고치는 `oms doctor contract --fix`를 안내한다. 봉인이 아예 없는 기기에서는 판정하지 않는 것과 구별한다.
 
-[아키텍처](./docs/architecture.md), [컨벤션](./docs/conventions.md), [ADR-007](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/docs/decisions/ADR-007-vault-contract-ontology.md)을 참고한다.
+[아키텍처](./docs/architecture.md), [컨벤션](./docs/conventions.md), [ADR-007](https://github.com/Xia-Ataraxia/oh-my-second-brain/blob/main/docs/decisions/ADR-007-vault-contract-ontology.md)을 참고한다.
 
 </details>
 
@@ -152,7 +116,7 @@ oms search "프로젝트 결정" --vault /path/to/vault
 
 setup과 인터뷰는 폴더와 속성만 묻는다. `oms setup extract --template <name>`은 `templateFolder`의 템플릿이 채울 뼈대(원본 경로, `folder:` 선택자, 속성 이름, heading)를 미리 보여 준다. 템플릿을 고치면 재봉인 없이 다음 쓰기부터 반영된다.
 
-`oms doctor contract`는 봉인, 오래된 lock, 고아 generation, 예상하지 않은 제어 파일, hook 전송 실패를 진단한다. `--fix`는 이동했거나 색인되지 않은 볼트를 다시 색인할 뿐이다. 다른 봉인 문제는 `oms setup`으로 복구한다.
+`oms doctor contract`는 봉인, 오래된 lock, 고아 generation, 예상하지 않은 제어 파일, hook 전송 실패를 진단한다. `--fix`는 이동했거나 색인되지 않은 볼트를 다시 색인하거나, 읽을 수 없는 색인을 다시 만들 뿐이다. 다른 봉인 문제는 `oms interview`로 다시 봉인한다.
 
 모델 수명주기는 별도다: `oms setup model install|select|waive|status`.
 
@@ -168,12 +132,12 @@ setup과 인터뷰는 폴더와 속성만 묻는다. `oms setup extract --templa
 | :--- | :--- |
 | `write` | 노트 전체를 봉인된 계약으로 판정하고 허용된 쓰기를 저장한다. |
 | `search` | 볼트를 바꾸지 않고 노트, 구조화된 맥락, wikilink 제안을 찾는다. |
-| `interview` | 볼트 인터뷰 질문과 봉인 상태를 보여 준다. 아무것도 봉인하지 않는다. |
+| `interview` | 볼트 인터뷰를 이어 간다. 열린 질문을 보여 주고 답을 기록하며, 소유자가 확인한 제안만 봉인한다. |
 | `doctor` | 읽기 전용 `status`, 계약 진단, 노트 감사, 링크 검사, 명시적인 색인 유지보수를 수행한다. |
 
 6개 스킬은 `distill`, `doctor`, `interview`, `search`, `setup`, `write`다.
 
-`distill`과 `setup`은 대응 MCP 도구가 없는 워크플로다. 봉인에는 MCP 작업이 없고, 세부 기능은 네 도구 아래의 `op` 값으로 제공한다. 도구 annotation은 도구별로 정한다. `write`와 `doctor` 복구는 변경을 일으키고 `interview`는 보수적으로 두므로 읽기 전용으로 표시한 도구는 `search`뿐이다.
+`distill`과 `setup`은 대응 MCP 도구가 없는 워크플로다. MCP는 소유자가 확인한 제안만 `interview` `op: seal`로 봉인하고, 세부 기능은 네 도구 아래의 `op` 값으로 제공한다. 도구 annotation은 도구별로 정한다. `write`와 `doctor` 복구는 변경을 일으키고 `interview`는 보수적으로 두므로 읽기 전용으로 표시한 도구는 `search`뿐이다.
 
 | 호스트 | 통합 방식 | 쓰기 검사 |
 | :--- | :--- | :--- |
@@ -182,7 +146,7 @@ setup과 인터뷰는 폴더와 속성만 묻는다. `oms setup extract --templa
 | **Hermes** | 프로필별 스킬, 가이드, MCP | MCP `write`만 검사. 기본 쓰기 hook은 없다. |
 
 > [!NOTE]
-> Claude hook은 판정된 계약 위반을 거부하지만, hook 자체를 실행할 수 없으면 경고와 함께 쓰기를 허용한다. Codex와 Hermes의 기본 파일 쓰기는 OMS 판정자를 거치지 않는다. 파일시스템 전체를 통제하는 sandbox가 아니다.
+> Claude hook은 안전 거부(제어 경로나 안전하지 않은 경로, `~/.oms/` 접근, 지원하지 않는 입력, 변조된 계약)만 막는다. 계약 위반은 경고와 함께 쓰기를 허용하고, hook 자체를 실행할 수 없으면 쓰기를 허용하고 경고를 기록한다. Codex와 Hermes의 기본 파일 쓰기는 OMS 판정자를 거치지 않는다. 파일시스템 전체를 통제하는 sandbox가 아니다.
 
 <details>
 <summary><strong>호스트 유지보수와 볼트 선택</strong></summary>
@@ -253,13 +217,13 @@ oms hook pre                                    Claude 쓰기를 계약으로
 | [설치](./docs/install.md): 설치, setup, 모델, 제거 | [아키텍처](./docs/architecture.md): 권위와 도메인 경계 |
 | [볼트 컨벤션](./docs/conventions.md): 설정과 봉인된 계약 | [CLI 맵](./docs/cli-map.md): 명령과 MCP 작업 매핑 |
 | [호스트 통합](./docs/adapters.md): Claude Code, Codex, Hermes | [검증된 target](./docs/verified-target.md): 안전한 볼트 선택 |
-| [릴리스](https://github.com/GoBeromsu/oh-my-second-brain/releases): 배포 버전 | [변경 이력](./CHANGELOG.md): 무엇이 왜 달라졌는가 |
+| [릴리스](https://github.com/Xia-Ataraxia/oh-my-second-brain/releases): 배포 버전 | [변경 이력](./CHANGELOG.md): 무엇이 왜 달라졌는가 |
 
 ## 기여와 크레딧
 
-[기여 가이드](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/CONTRIBUTING.md)를 읽거나, 재현 가능한 문제와 구체적인 제안을 [이슈](https://github.com/GoBeromsu/oh-my-second-brain/issues)로 남길 수 있다.
+[기여 가이드](https://github.com/Xia-Ataraxia/oh-my-second-brain/blob/main/CONTRIBUTING.md)를 읽거나, 재현 가능한 문제와 구체적인 제안을 [이슈](https://github.com/Xia-Ataraxia/oh-my-second-brain/issues)로 남길 수 있다.
 
-[ACKNOWLEDGMENTS](./ACKNOWLEDGMENTS.md)는 [Ouroboros](./ACKNOWLEDGMENTS.md#ouroboros), [Gajae Code](./ACKNOWLEDGMENTS.md#gajae-code)의 deep-interview 등 설계에 영향을 준 아이디어를 기록한다. runtime 복제나 연구 결과를 뜻하지 않는다. 별자리 배너는 [beomsukoh.com](https://beomsukoh.com/)의 연결된 노트 풍경에서 착안한 자체 제작 일러스트다. 이미지는 개념을 설명하는 도식이며 제품 화면, host smoke 증거, 제품 gate 통과 결과가 아니다.
+[ACKNOWLEDGMENTS](./ACKNOWLEDGMENTS.md)는 [Ouroboros](./ACKNOWLEDGMENTS.md#ouroboros), [Gajae Code](./ACKNOWLEDGMENTS.md#gajae-code)의 deep-interview 등 설계에 영향을 준 아이디어를 기록한다. runtime 복제나 연구 결과를 뜻하지 않는다. 상단 이미지는 서가와 떠다니는 낱장, 지식의 별자리를 표현한 자체 제작 Blender 장면이다. 네이티브 렌더링, CC0 목재 텍스처, 타이포그래피 출처는 [아트워크 크레딧](./assets/readme/ARTWORK.md)에 기록했다. 개념 이미지이며 제품 화면, host smoke 증거, 제품 gate 통과 결과가 아니다.
 
 ---
 

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="./assets/readme/hero.svg" alt="Oh My Second Brain. A quiet constellation of connected thoughts." width="100%" />
+  <img src="./assets/readme-hero.webp" alt="oh my secondbrain — a towering library with floating pages and connected stars." width="100%" />
 </p>
 
 <h1 align="center">Oh My Second Brain</h1>
@@ -10,60 +10,24 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/oh-my-second-brain"><img src="https://img.shields.io/npm/v/oh-my-second-brain?style=flat-square&amp;color=8b9daa&amp;label=npm" alt="npm version" /></a>
-  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%E2%89%A520-80b89b?style=flat-square" alt="Node.js 20 or later" /></a>
-  <a href="#mcp-tools--integrations"><img src="https://img.shields.io/badge/MCP-4_tools-97a8b1?style=flat-square" alt="4 MCP tools" /></a>
-  <a href="https://github.com/GoBeromsu/oh-my-second-brain/blob/main/package.json"><img src="https://img.shields.io/badge/license-MIT-d7c7a8?style=flat-square" alt="Package license: MIT" /></a>
-</p>
-
-<p align="center">
-  <a href="#quick-start"><strong>Quick start</strong></a> ·
+  <a href="#quick-start">Quick start</a> ·
   <a href="#how-it-works">How it works</a> ·
   <a href="#documentation">Documentation</a> ·
-  <a href="https://github.com/GoBeromsu/oh-my-second-brain/releases">Releases</a> ·
-  <a href="https://github.com/GoBeromsu/oh-my-second-brain/blob/main/README.ko.md">한국어</a>
+  <a href="https://github.com/Xia-Ataraxia/oh-my-second-brain/releases">Releases</a> ·
+  <a href="https://github.com/Xia-Ataraxia/oh-my-second-brain/blob/main/README.ko.md">한국어</a>
 </p>
 
----
+<p align="center"><sub>Node.js ≥ 20 · 4 MCP tools · 6 shared skills · Package licensed MIT</sub></p>
 
-Your vault already holds ideas, decisions, and things you learned. **OMS helps your agents find that knowledge and write within the conventions you defined.** No new note format. No prescribed folder system. No handover of your knowledge to a single host.
-
-Obsidian stays the command center. Your notes stay plain Markdown, readable and editable even when OMS is not running. Connect Claude Code, Codex, or Hermes to the same vault through their host integrations.
+Your vault already holds ideas, decisions, and things you learned. **OMS helps your agents find that knowledge and write within the conventions you defined.** Obsidian stays the command center. Your notes stay plain Markdown, readable and editable even when OMS is not running.
 
 ## Why OMS?
 
-<table>
-<tr>
-<td width="50%" valign="top">
-<h3>Recall what you already know</h3>
-Search your existing notes with lexical retrieval. Choose vector, HyDE, query expansion, or reranking explicitly when you need them.
-</td>
-<td width="50%" valign="top">
-<h3>Your vault, your vocabulary</h3>
-Define the meaning of folders and properties. OMS records your conventions instead of shipping a system you have to adopt.
-</td>
-</tr>
-<tr>
-<td width="50%" valign="top">
-<h3>Give agents a shared contract</h3>
-Seal your vault conventions through setup. Supported write paths check the whole note against that contract before saving it.
-</td>
-<td width="50%" valign="top">
-<h3>Keep the files you own</h3>
-Keep using your Markdown notes and templates. Setup does not rewrite them, and the sealed contract lives outside the vault.
-</td>
-</tr>
-<tr>
-<td width="50%" valign="top">
-<h3>Connect across hosts</h3>
-Use native integrations for Claude Code, Codex, and Hermes, with four MCP tools and six shared workflow skills.
-</td>
-<td width="50%" valign="top">
-<h3>Inspect, don't guess</h3>
-Check contract state, audit notes, inspect indexes, and review wikilink suggestions. Search and `doctor status` stay read-only.
-</td>
-</tr>
-</table>
+| Recall | Write with context | Keep ownership |
+| :--- | :--- | :--- |
+| Start with lexical retrieval. Choose vector, HyDE, query expansion, or reranking when you need them. | Define what your folders and properties mean. Supported write paths check the contract and report their findings. | Keep your existing notes and templates. Connect Claude Code, Codex, and Hermes to the same vault. |
+
+Search and `oms doctor status` stay read-only. Index maintenance is explicit.
 
 ## Quick start
 
@@ -127,19 +91,19 @@ These are example requests, not captured run results. Available workflows and wr
 | **Your agent** | Reads context, composes notes, and uses the appropriate host workflow. You and the agent decide what is worth keeping. |
 
 > [!IMPORTANT]
-> **Set up the contract before relying on write checks.** A vault with no seal on this machine is not contract-judged; general path and input safeguards still apply. A contract violation leaves the file unchanged. An allowed write means structural compliance, not factual accuracy or quality approval.
+> **Set up the contract before relying on write checks.** A vault with no seal on this machine is not contract-judged: its writes carry a `contract-open` warning naming `oms interview`, and general path and input safeguards still apply. A write that breaks the contract is saved with warnings; a safety refusal, a missing or stale `ifMatch`, or an unverified target leaves the file unchanged. An allowed write with no warnings means structural compliance, not factual accuracy or quality approval.
 
 <details>
 <summary><strong>The vault contract, in detail</strong></summary>
 
 - **Meaning is user-owned.** The interview covers folders and the property pool together. OMS hardcodes no property names, folders, or personas and has no Inbox fallback.
 - **One control file inside the vault.** `.oms/settings.json` holds `version`, `vaultId`, `templateFolder`, `embedding`, and `agentRepair`. Other `.oms/` entries are ignored and reported as unexpected control files by `oms doctor contract`. `.obsidian/types.json` is a read-only observation, not an override of the seal.
-- **Templates stay yours.** Templates live in your `templateFolder` and are never sealed or judged. A new note is scaffolded from the live template: the one the write names, or else the one template whose basename or `folder:` key matches the target folder. OMS never rewrites or copies a template file, and does not parse or execute Templater, JavaScript, or a private token language. A write only fills what is mechanical in the note being written: `{{title}}`, `{{date}}` and `{{time}}` variables, date and datetime defaults on a new note, and the chosen template's frontmatter defaults and missing headings. The note's own values win. It never supplies a required value.
+- **Templates stay yours.** Templates live in your `templateFolder` and are never sealed or judged. A new note is scaffolded from the live template: the one the write names, or else the one template whose basename or `folder:` key matches the target folder. OMS never rewrites or copies a template file, and does not parse or execute Templater, JavaScript, or a private token language. A write only fills what is mechanical in the note being written: `{{title}}`, `{{date}}` and `{{time}}` variables, date and datetime defaults on a new note, and the chosen template's frontmatter defaults and missing headings. The note's own values win. It never invents a required value; only a value the contract fixes is filled, as a lossless fix listed in the receipt's `fixes`.
 - **Old seals stay readable.** A new seal stores folders and properties only. A seal made by an older release still loads; `oms setup status` counts its template constraints as `legacyTemplates`, and they are reported, never enforced.
-- **One judge, bounded feedback.** Denied writes return `{field, kind}` violations and one guidance command, not rule values, store paths, or the contract body.
-- **Mismatched seal evidence blocks writes.** When this machine's evidence no longer matches the vault, writes fail with `contract-unreadable` until the owner runs `oms setup` again. A machine with no seal is a different case: its vault is not contract-judged.
+- **One judge, bounded feedback.** A saved write returns its contract findings as `{field, kind}` warnings, and a refused write returns its reason the same way. Each of these comes with one guidance command, never rule values, store paths, or the contract body.
+- **A tampered seal blocks writes.** When the vault id in `.oms/settings.json` no longer matches this machine's seal, writes are refused as `contract-tampered`; `oms doctor contract` explains it. Missing or broken seal evidence is `contract-unreadable`: the write is saved with that warning until the owner reseals with `oms interview`. When `oms doctor contract` finds a moved vault or a missing or unreadable index entry, it names `oms doctor contract --fix`, which reindexes without resealing. A machine with no seal is a different case: its vault is not contract-judged.
 
-See [architecture](./docs/architecture.md), [conventions](./docs/conventions.md), and [ADR-007](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/docs/decisions/ADR-007-vault-contract-ontology.md).
+See [architecture](./docs/architecture.md), [conventions](./docs/conventions.md), and [ADR-007](https://github.com/Xia-Ataraxia/oh-my-second-brain/blob/main/docs/decisions/ADR-007-vault-contract-ontology.md).
 
 </details>
 
@@ -152,7 +116,7 @@ The `setup` skill asks the owner each question via `oms setup --questions` and s
 
 Setup and the interview ask about folders and properties only. `oms setup extract --template <name>` previews what a template in `templateFolder` would scaffold: its source, `folder:` selector, property names, and headings. Editing a template takes effect on the next write without a reseal.
 
-`oms doctor contract` diagnoses seal problems, stale locks, orphaned generations, unexpected control files, and hook transport failures. Its `--fix` only re-indexes a moved or unindexed vault. Other broken seals are recovered through `oms setup`.
+`oms doctor contract` diagnoses seal problems, stale locks, orphaned generations, unexpected control files, and hook transport failures. Its `--fix` only re-indexes a moved or unindexed vault, or rebuilds an unreadable index. Other broken seals are resealed with `oms interview`.
 
 Model lifecycle is separate: `oms setup model install|select|waive|status`.
 
@@ -173,7 +137,7 @@ Model lifecycle is separate: `oms setup model install|select|waive|status`.
 
 The six skills are `distill`, `doctor`, `interview`, `search`, `setup`, and `write`.
 
-`distill` and `setup` are tool-less workflows; sealing has no MCP operation. Detail capabilities use `op` values under the four tools. Tool annotations are per tool: only `search` is marked read-only, because `write` and the `doctor` repairs mutate and `interview` is kept conservative.
+`distill` and `setup` are tool-less workflows; MCP seals only through `interview` `op: seal` on a proposal the owner confirmed. Detail capabilities use `op` values under the four tools. Tool annotations are per tool: only `search` is marked read-only, because `write` and the `doctor` repairs mutate and `interview` is kept conservative.
 
 | Host | Integration | Write checks |
 | :--- | :--- | :--- |
@@ -182,7 +146,7 @@ The six skills are `distill`, `doctor`, `interview`, `search`, `setup`, and `wri
 | **Hermes** | Profile-scoped skills, guidance, and MCP | MCP `write`; no native write hook. |
 
 > [!NOTE]
-> Claude's hook rejects a judged contract violation, but allows the write with a warning if the hook itself cannot run. Native file writes in Codex and Hermes do not pass through the OMS judge. This is not a filesystem-wide sandbox.
+> Claude's hook denies a write only on a safety refusal: a control or unsafe path (including access under `~/.oms/`), unsupported input, or a tampered contract. A contract finding allows the write with a warning; a hook that cannot run allows the write and logs a warning. Native file writes in Codex and Hermes do not pass through the OMS judge. This is not a filesystem-wide sandbox.
 
 <details>
 <summary><strong>Host maintenance and vault targeting</strong></summary>
@@ -253,13 +217,13 @@ Note `create`, `append`, `update`, and `backfill` are retired operations. There
 | [Installation](./docs/install.md): install, setup, models, removal | [Architecture](./docs/architecture.md): authority and domain boundaries |
 | [Vault conventions](./docs/conventions.md): settings and sealed contracts | [CLI map](./docs/cli-map.md): command and MCP operation mapping |
 | [Host integrations](./docs/adapters.md): Claude Code, Codex, Hermes | [Verified targets](./docs/verified-target.md): safe vault resolution |
-| [Releases](https://github.com/GoBeromsu/oh-my-second-brain/releases): published versions | [Changelog](./CHANGELOG.md): what changed and why |
+| [Releases](https://github.com/Xia-Ataraxia/oh-my-second-brain/releases): published versions | [Changelog](./CHANGELOG.md): what changed and why |
 
 ## Contributing & credits
 
-Contributions are welcome. Start with the [contributing guide](https://github.com/GoBeromsu/oh-my-second-brain/blob/main/CONTRIBUTING.md), or [open an issue](https://github.com/GoBeromsu/oh-my-second-brain/issues) with a reproducible problem or a focused proposal.
+Contributions are welcome. Start with the [contributing guide](https://github.com/Xia-Ataraxia/oh-my-second-brain/blob/main/CONTRIBUTING.md), or [open an issue](https://github.com/Xia-Ataraxia/oh-my-second-brain/issues) with a reproducible problem or a focused proposal.
 
-[ACKNOWLEDGMENTS](./ACKNOWLEDGMENTS.md) records design influences, including [Ouroboros](./ACKNOWLEDGMENTS.md#ouroboros) and [Gajae Code](./ACKNOWLEDGMENTS.md#gajae-code)'s deep-interview. Those credits describe ideas, not a copied runtime or a research result. The original constellation illustration is inspired by the connected-note landscape at [beomsukoh.com](https://beomsukoh.com/). Illustrations explain concepts; they are not product screenshots, host-smoke evidence, or product-gate results.
+[ACKNOWLEDGMENTS](./ACKNOWLEDGMENTS.md) records design influences, including [Ouroboros](./ACKNOWLEDGMENTS.md#ouroboros) and [Gajae Code](./ACKNOWLEDGMENTS.md#gajae-code)'s deep-interview. Those credits describe ideas, not a copied runtime or a research result. The hero is an original Blender library scene with floating paper and knowledge-stars. [Artwork and material credits](./assets/readme/ARTWORK.md) describe its native rendering, CC0 wood texture, and typography. It is conceptual artwork, not a product screenshot, host-smoke evidence, or a product-gate result.
 
 ---