oh-my-second-brain 0.2.0 → 0.3.0

package/docs/adapters.md

@@ -0,0 +1,15 @@
+# Host Asset Contract
+
+Oh My Second Brain keeps shared skills in `assets/skills/` and host-specific runtime assets in explicit directories under `assets/`. There is no adapter bundle directory.
+
+| Host | Manifest/config | Host assets | Installation destination |
+|---|---|---|---|
+| Claude Code | Root `.claude-plugin/plugin.json` and `.mcp.json` | `assets/claude/CLAUDE.md`, `assets/claude/hooks/` | Plugin root; guard hooks are installed through `~/.claude/settings.json`. |
+| Codex | Root `.codex-plugin/plugin.json` and `.mcp.codex.json` | `assets/codex/AGENTS.md`, `assets/codex/rules/oms.md` | `~/.codex/plugins/oms/AGENTS.md`, `~/.codex/rules/oms.md`, and `~/.codex/skills/oms-*`. |
+| Hermes | `assets/hermes-manifest.json` | `assets/hermes/SOUL.md`, `assets/hermes/README.md` | `~/.hermes/adapters/oms/`, `~/.hermes/skills/knowledge-management/oms/`, and `~/.hermes/config.yaml`. |
+
+Claude's manifest retains its explicit skill array; Codex's manifest retains its single shared skill-directory declaration. Both resolve `./assets/skills/` inside the repository-root plugin.
+
+The MCP server is started with `oms mcp`. Claude uses `.mcp.json`, Codex uses `.mcp.codex.json`, and Hermes receives its registration in `~/.hermes/config.yaml`.
+
+To add a host, add a clearly named `assets/<host>/` directory for host-only files, preserve shared skills in `assets/skills/`, declare every shipped path in the harness registry, and keep installer destinations explicit.

package/docs/install.md

@@ -1,6 +1,6 @@
 # Install Oh My Second Brain
 
-Oh My Second Brain v0 is distributed as one npm/GitHub-release package that contains the CLI/runtime, the default ontology, host adapter assets, host-native skill/rule bundles, and shell installers. Claude Code, Codex, and Hermes install Oh My Second Brain host surfaces backed by the same MCP write/retrieve runtime. Legacy runtime IDs remain `oms` for compatibility.
+Oh My Second Brain v0 is distributed as one npm/GitHub-release package that contains the CLI/runtime, the default ontology, root host assets, host-native skill/rule bundles, and shell installers. Claude Code, Codex, and Hermes install Oh My Second Brain host surfaces backed by the same MCP runtime. Legacy runtime IDs remain `oms` for compatibility.
 
 ## Prerequisites
 
@@ -56,14 +56,14 @@ Runtime selection follows the Ouroboros pattern:
 1. Explicit `--runtime` wins.
 2. `auto` detects `claude`, `codex`, and `hermes` on `PATH`.
 3. If nothing is detected, `auto` defaults to Claude Code for conservative first-run behavior; use `--runtime all` to install every host surface.
-4. `all` installs every known adapter surface.
+4. `all` installs every known host surface.
 
 ## What install writes
 
 | Host | Install behavior |
 | --- | --- |
 | Claude Code | Installs the plugin-owned `.mcp.json` surface; removes stale `oms` registrations across local/project/user scopes; with `--execute`, adds the OMS marketplace and installs `oms@oms` through it, falling back to the local plugin path when the marketplace flow can't complete. |
-| Codex | Installs `~/.codex/rules/oms.md`, `~/.codex/skills/oms-*`, copies adapter files to `~/.codex/plugins/oms`, and writes a managed `[mcp_servers.oms]` block plus `OMS_AGENT_RUNTIME=codex` env in `~/.codex/config.toml`. |
+| Codex | Installs `~/.codex/rules/oms.md`, `~/.codex/skills/oms-*`, installs guidance to `~/.codex/plugins/oms`, and writes a managed `[mcp_servers.oms]` block plus `OMS_AGENT_RUNTIME=codex` env in `~/.codex/config.toml`. |
 | Hermes | Installs `~/.hermes/skills/knowledge-management/oms/`, copies adapter files to `~/.hermes/adapters/oms`, and writes `mcp_servers.oms` in `~/.hermes/config.yaml`. |
 
 Host writes keep the legacy `oms` namespace for backward-compatible MCP/skill IDs and are reversible with `oh-my-second-brain uninstall` (or the `oms` alias). Each runtime is installed independently: if one host fails, the others still complete.
@@ -122,8 +122,8 @@ Setup does not modify vault notes. It writes `.oms/taxonomy.yaml`, preserves exi
 Typical printed commands look like:
 
 ```bash
-claude plugin install /path/to/oh-my-second-brain/adapters/claude-code
-# MCP is declared by the installed plugin in adapters/claude-code/.mcp.json.
+claude plugin install /path/to/oh-my-second-brain
+# MCP is declared by the installed plugin in .mcp.json.
 ```
 
 ## Uninstall
@@ -165,7 +165,7 @@ oh-my-second-brain linkify --vault /path/to/vault --folder notes
 oh-my-second-brain linkify --vault /path/to/vault --apply --yes
 ```
 
-Hosts can do the same note by note through the `oms_link_suggest` (read-only) and `oms_link_apply` (writes accepted candidates) MCP tools. Nothing is linked behind your back: new notes are composed already linked, and existing notes change only when you ask.
+Hosts can do the same note by note through `oms_link`: its `suggest` operation is read-only and its `apply` operation writes accepted candidates. Nothing is linked behind your back: new notes are composed already linked, and existing notes change only when you ask.
 
 ## Verify the install
 
@@ -173,11 +173,10 @@ Hosts can do the same note by note through the `oms_link_suggest` (read-only) an
 oh-my-second-brain doctor --vault /path/to/vault
 oh-my-second-brain semantic sync --vault /path/to/vault --collection vault
 oh-my-second-brain semantic query "what should I retrieve?" --vault /path/to/vault
-oh-my-second-brain semantic context add vault "Prefer durable notes with reusable evidence." --vault /path/to/vault
-oh-my-second-brain semantic ls vault --vault /path/to/vault
-oh-my-second-brain semantic doctor --vault /path/to/vault
+oh-my-second-brain semantic context list --vault /path/to/vault
+oh-my-second-brain semantic status --vault /path/to/vault
 oh-my-second-brain install --runtime all --vault /path/to/vault --dry-run
-claude plugin validate adapters/claude-code
+claude plugin validate .
 ```
 
-Inside a host runtime, verify the MCP server by listing MCP tools or asking for Oh My Second Brain graph/status. The server exposes status, graph build, context retrieval, native OMS semantic-index sync, qmd-compatible semantic query/status aliases, `qmd://` document resources, semantic document rehydration, axis retrieval, lazy note loading, contract validation, and gated write tools. OMS does not require the `qmd` binary; `oms semantic doctor` now reports the built-in SQLite/FTS/vector backend and optional GGUF model path diagnostics.
+Inside a host runtime, verify the MCP server by listing its five tools: `oms_write`, `oms_search`, `oms_link`, `oms_status`, and `oms_doctor`. `oms_search` provides retrieval operations, `oms_status` is read-only health/statistics, and `oms_doctor` provides diagnosis or repair operations. OMS does not require the `qmd` binary; `oms semantic status` reports semantic-engine availability.

package/package.json

@@ -1,26 +1,37 @@
 {
   "name": "oh-my-second-brain",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Oh My Second Brain: a host-agnostic, user-owned convention layer for Obsidian and plain-markdown knowledge vaults.",
   "type": "module",
   "license": "MIT",
   "bin": {
     "oh-my-second-brain": "dist/cli/oms.js",
     "oms": "dist/cli/oms.js",
-    "oms-guard": "adapters/claude-code/hooks/oms-guard.mjs",
-    "oms-post-guard": "adapters/claude-code/hooks/oms-post-guard.mjs"
+    "oms-guard": "assets/claude/hooks/oms-guard.mjs",
+    "oms-post-guard": "assets/claude/hooks/oms-post-guard.mjs"
   },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/kernel/index.js",
+  "types": "dist/kernel/index.d.ts",
   "files": [
     "dist",
-    "core",
-    "adapters",
+    "core/AGENTS.md",
+    "core/ontology",
+    ".claude-plugin",
+    ".codex-plugin",
+    ".mcp.json",
+    ".mcp.codex.json",
+    "assets",
+    "docs/adapters.md",
     "docs/install.md",
-    "docs/release.md",
     "scripts/install.sh",
     "scripts/uninstall.sh",
-    "CHANGELOG.md"
+    "ACKNOWLEDGMENTS.md",
+    "CHANGELOG.md",
+    "CHANGELOG-kernel.md",
+    "CHANGELOG-cli.md",
+    "CHANGELOG-mcp.md",
+    "CHANGELOG-vendors.md",
+    "CHANGELOG-assets.md"
   ],
   "engines": {
     "node": ">=20"
@@ -30,6 +41,7 @@
     "postbuild": "chmod +x dist/cli/oms.js",
     "lint": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
+    "check:docs": "node scripts/check-doc-mapping.mjs",
     "audit": "npm audit --omit=dev",
     "release": "node scripts/release.mjs",
     "release:pack": "node scripts/release-pack.mjs",

package/adapters/README.md

@@ -1,99 +0,0 @@
-# Adapter Contract
-
-## Principle
-
-Oh My Second Brain's **core** (ontology loading, convention validation, graph/search runtime targets, and MCP server) is written once.
-Each **adapter** absorbs exactly one host's structural differences — manifest schema,
-hook format, invocation sigil, and convention-file name — so adding a new host
-means adding one new adapter directory, not touching core.
-
-Per-host structural asymmetry is documented here, **not abstracted away**.
-The goal is legibility: when something breaks on one host, you read its adapter,
-not a shared abstraction layer.
-
----
-
-## Host Comparison Table
-
-| Host | Manifest | Convention file | Sigil | Status |
-|------|----------|----------------|-------|--------|
-| **claude-code** | `.claude-plugin/plugin.json` | `CLAUDE.md` | `/` | REAL installable v0 |
-| **codex** | `.codex-plugin/plugin.json` | `AGENTS.md` | `$` | Native skills + MCP install (v0) |
-| **hermes** | `manifest.json` | `SOUL.md` + context files | (built-in tools) | Native skills + MCP install (v0) |
-
----
-
-## Adapter Structure
-
-Each adapter lives at `adapters/<host>/` and contains:
-
-```
-adapters/<host>/
-  <manifest-dir>/
-    plugin.json       # Host-specific manifest (schema varies per host — see below)
-  skills/             # Host-specific skill wrappers/bundles
-    <verb>/
-      SKILL.md
-  CLAUDE.md           # OR AGENTS.md OR SOUL.md — convention-file shim for this host
-```
-
----
-
-## Per-Host Structural Notes
-
-### claude-code (REAL installable v0)
-
-Release contract: the npm tarball must include `adapters/claude-code/` because `oms setup --install-claude` prints a packaged adapter path for `claude plugin install`.
-
-- **Manifest**: `.claude-plugin/plugin.json`
-  - Schema: `{ name, version, description, author, license, keywords, skills: string[] }`
-  - `skills` is an **array of directory-path strings** relative to the plugin root (e.g. `"./skills/setup/"`).
-  - Each path must contain a `SKILL.md`.
-- **Convention file**: `CLAUDE.md` — append `adapters/claude-code/CLAUDE.md` to your project's `CLAUDE.md`.
-- **Sigil**: `/` (e.g. `/oms-setup`).
-- **Hooks**: `oms install --runtime claude` can upsert OMS guard entries in `~/.claude/settings.json` while preserving existing non-OMS hooks.
-- **Install**: `claude plugin install path/to/adapters/claude-code` or point Claude Code at the adapter directory.
-
-### codex (native skills + MCP install v0)
-
-- **Manifest**: `.codex-plugin/plugin.json`
-  - Schema differs from claude-code: codex declares its skill directory and MCP server manifest directly.
-  - Skills are invoked with `$` sigil instead of `/`.
-- **Convention file**: `AGENTS.md` — append `adapters/codex/AGENTS.md` to your project's `AGENTS.md`.
-- **Status**: v0 native install. `oms install --runtime codex` installs `~/.codex/rules/oms.md`, namespaced `~/.codex/skills/oms-*`, a managed `[mcp_servers.oms]` block in `~/.codex/config.toml`, and a copy of the adapter under `~/.codex/plugins/oms`.
-
-### hermes (native skills + MCP install v0)
-
-- **Manifest**: `manifest.json` (Hermes/Nous Research format — schema TBD).
-  - Hermes skills register on agentskills.io; no local manifest equivalent exists yet.
-- **Convention file**: `SOUL.md` + context files — append `adapters/hermes/SOUL.md` to your Hermes session context.
-- **Sigil**: N/A (Hermes uses built-in tools + MCP, not a `/`/`$` sigil system).
-- **Status**: v0 native install. `oms install --runtime hermes` installs the skill bundle under `~/.hermes/skills/knowledge-management/oms/`, registers `mcp_servers.oms` in `~/.hermes/config.yaml`, and keeps an adapter copy under `~/.hermes/adapters/oms`.
-
----
-
-## MCP Backbone
-
-The cross-host mechanism is an **MCP server** (`src/mcp/server.ts`) that exposes
-contract validation, retrieve, graph/status, and gated write tools.
-
-All three hosts natively support MCP (`.mcp.json` for claude-code and codex; "any MCP server" for Hermes).
-In the current repository, `src/mcp/server.ts` starts a real stdio MCP server via `oms mcp`.
-
-The MCP server currently exposes status/read/cache/retrieve/write tools:
-`oms_graph_status`, `oms_graph_build`, `oms_list_concepts`,
-`oms_retrieve_context`, `oms_sync_embeddings`, `oms_get_document`, `oms_multi_get_documents`,
-`oms_retrieve_by_axis`, `oms_lazy_load_note`,
-`oms_validate_contract`, and `write`.
-`write` is gated by path-safety, vault-confinement, and contract validation. The CLI (`oms setup`, `oms install`, `oms uninstall`, `oms doctor`) remains the real surface for lifecycle commands.
-
----
-
-## Adding a New Host
-
-1. Create `adapters/<host>/`.
-2. Write the host-specific manifest in the correct subdirectory and schema.
-3. Write the convention-file shim (`CLAUDE.md` / `AGENTS.md` / `SOUL.md` / whatever the host uses).
-4. Write skill wrappers that shell out to `oms <verb>` (for lifecycle) or call the MCP server (for write/retrieve).
-5. Document the host's structural differences in this table.
-6. Do **not** modify `core/` or add host-specific logic to shared code.

package/adapters/claude-code/skills/compile/SKILL.md

@@ -1,27 +0,0 @@
----
-name: oms-compile
-description: Agent-guided concept compile — synthesize a concept wiki page from source materials with incremental skip, provenance weighting, and cascade backlinks.
----
-
-# Skill: oms-compile (Claude Code)
-
-Synthesize a concept wiki page from source materials.
-
-## Invocation
-
-```
-/oms-compile
-```
-
-## What this skill does
-
-Thin pointer to `core/skills/compile`. There is no `oms compile` CLI.
-
-1. **Phase A** — load and grade materials; resolve backlinks (pure read).
-2. Skip rewrite if the material SHA is unchanged.
-3. **Phase B** — write the body to `processed/` only.
-4. Pass affected backlinks to the wiki skill so those pages can be marked stale.
-
-Provenance order: authored > curated > external-raw.
-Use `oms_retrieve_context` or `oms_get_document` to gather source materials.
-Delete `{dotLlmwiki}/sha-cache.json` to force a full recompile.

package/adapters/claude-code/skills/define/SKILL.md

@@ -1,51 +0,0 @@
----
-name: oms-define
-description: Grow the vault convention by adding a metadata field to a concept. Entry point is oms define (roadmap).
----
-
-# Skill: oms-define (Claude Code)
-
-Extend your vault convention field-by-field.
-Each frontmatter key is a unit of convention with a declared `intent`, type, and rules.
-
-## Invocation
-
-```
-/oms-define
-```
-
-## What this skill does
-
-Intended to shell out to:
-
-```bash
-oms define
-```
-
-**Roadmap note:** The `oms define` interactive runtime is not yet implemented in v0.
-Today this skill guides you through the same steps manually (agent-guided).
-
-## Agent-guided steps (v0)
-
-1. Identify which **concept** to extend (e.g. `literature`, `inbox`).
-2. Choose a new **field name** (snake-case, e.g. `thesis`).
-3. State the field's **intent** — why this knowledge matters.
-4. Choose **type**: `string` | `string[]` | `date` | `url` | `boolean`.
-5. Choose **required**: yes / no.
-6. Optionally set **normalize** (e.g. `lowercase`) or **immutable** (lock after creation).
-7. Append the entry to `vault/.oms/concepts/<concept>.yaml`.
-8. Run `oms doctor` to validate existing notes against the updated schema.
-
-## YAML snippet to append
-
-```yaml
-fields:
-  - name: thesis
-    type: string
-    required: false
-    intent: "The central claim this source makes"
-```
-
-## When the runtime ships
-
-`oms define` will run the same Q&A interactively and write the YAML for you.

package/adapters/claude-code/skills/distill/SKILL.md

@@ -1,28 +0,0 @@
----
-name: oms-distill
-description: Standalone meta-absorption skill — analyzes any target (repo, document, skill, concept) in a clean-room context and produces a structured absorption report with patterns, risks, and attribution.
----
-
-# Skill: oms-distill (Claude Code)
-
-Run adversarial absorption analysis on a target and produce a structured report.
-
-## Invocation
-
-```
-/oms-distill <target-path-or-text>
-```
-
-## What this skill does
-
-Thin pointer to `core/skills/distill`. Vault-agnostic — `OMS_VAULT` is NOT
-required. The target is treated as inert read-only text and is never executed.
-
-1. Load the target as inert data only.
-2. Snapshot a content hash before analysis.
-3. Run red-team analysis (read-only).
-4. Write the report: §1 Patterns, §2 Risks, §3 Attribution.
-5. Verify the hash is unchanged. Stop if anything mutated.
-6. Return the report string. Write it only if the user explicitly requests it.
-
-No vault write occurs inside distill.

package/adapters/claude-code/skills/doctor/SKILL.md

@@ -1,58 +0,0 @@
----
-name: oms-doctor
-description: Validate vault notes against the Oh My Second Brain convention by running oms doctor.
----
-
-# Skill: oms-doctor (Claude Code)
-
-Check every note in your vault against its declared concept schema.
-This skill is **REAL in v0** — it shells out to the fully-implemented CLI.
-
-## Invocation
-
-```
-/oms-doctor
-```
-
-## What this skill does
-
-Shells out to:
-
-```bash
-oms doctor [--vault <path>]
-```
-
-The CLI will:
-1. Load `vault/.oms/` and `vault/.oms/taxonomy.yaml`.
-2. Walk every `.md` note in the vault.
-3. Resolve each note's concept from the taxonomy folder binding.
-4. Validate frontmatter fields against the concept schema.
-5. Print per-note violations (field, rule, message) and total counts.
-6. **Always exits 0** — v0 is advisory only (`onViolation: warn`).
-
-## Options
-
-| Flag | Description |
-|------|-------------|
-| `--vault <path>` | Path to your Obsidian vault root (default: current directory) |
-
-## Example
-
-```bash
-oms doctor --vault ~/Documents/MyVault
-```
-
-## Sample output
-
-```
-vault/references/attention.md
-  WARN  title      required  Field "title" is required but missing
-  WARN  source-url type      Expected url, got string
-
-Checked 12 notes. 2 violations found. (exits 0)
-```
-
-## Roadmap
-
-Doctor is fully real in v0. Run it after any `oms setup`, `oms define`,
-or bulk note edit to keep your vault clean.

package/adapters/claude-code/skills/link/SKILL.md

@@ -1,87 +0,0 @@
----
-name: oms-link
-description: Two-path note-linking skill — Path A (pre-write): compose a new note body that already carries [[wikilinks]] to existing term notes; Path B (retrofit): add missing links to existing notes via oms linkify or oms_link_apply.
----
-
-# Skill: oms-link (Claude Code)
-
-Two-path skill — thin pointer to `core/skills/link`. Requires `OMS_VAULT`.
-
-## Invocation
-
-```
-/link
-```
-
-## Which path?
-
-Check **before acting**:
-- **Path A (pre-write):** you are about to write the note → learn the term
-  vocabulary first, then draft a body that already contains `[[wikilinks]]`.
-- **Path B (retrofit):** the note already exists → `oms linkify` or
-  MCP `oms_link_suggest` → `oms_link_apply`.
-
-These paths are **mutually exclusive**.
-
-## The link universe
-
-Only notes bound to the `term` concept in `vault/.oms/taxonomy.yaml` are link
-targets; their surface forms are the basename and the frontmatter `aliases`.
-`0 term note(s) available as link targets` means the vault has no term layer —
-build one with the `wiki` skill first.
-
-Three engine rules, not negotiable:
-- **Surface-anchored** — a link exists only where the term literally appears.
-- **First occurrence only** — one link per target note per body.
-- **Ambiguity is reported, never resolved** — `ambiguous: true` plus `rivalPaths`
-  means ask the user or skip the span.
-
-Frontmatter, code, existing links, headings, URLs, and tags are masked out; a
-"missing" link inside any of them is correct.
-
----
-
-## Path A — pre-write linking
-
-*(Only while drafting, so no retrofit pass is ever needed for this note.)*
-
-### Agent-guided steps
-
-1. Call MCP `oms_link_suggest` on an existing note in the same folder (or
-   `oms linkify --folder <folder>` in report mode) and read the `targetPath`
-   list — that is the vault's current term vocabulary.
-2. Draft the body with those exact surface forms, writing `[[wikilinks]]` inline
-   at the first mention of each term.
-3. Commit via MCP `write`. Host `Write`/`Edit` never touches vault `.md`.
-4. Re-check with `oms_link_suggest`; zero candidates means the draft was already
-   fully linked.
-
----
-
-## Path B — retrofit existing notes
-
-*(Only when the note is already on disk. Report first, always.)*
-
-### Batch
-
-```bash
-oms linkify --folder notes                  # report only, writes nothing
-oms linkify --folder notes --apply --yes    # rewrite in place
-```
-
-`--apply` without `--yes` refuses before reading any note and writes nothing.
-Show the report and get agreement before adding `--yes`. Writes go through the
-capture kernel, so path safety and the concept contract hold.
-
-### Single note
-
-1. `oms_link_suggest { notePath, folder? }` → candidates + `baseContentHash`.
-2. Present the candidates; drop ambiguous ones the user does not resolve.
-3. `oms_link_apply { notePath, baseContentHash, candidateIds, folder? }` — pass
-   back the same `baseContentHash` and the same `folder` scope.
-
-`oms_link_apply` refuses without writing on `note-changed`, `candidate-drift`,
-or overlapping candidates. Re-run `oms_link_suggest` for fresh offsets instead
-of retrying stale ids.
-
-After a retrofit run, run `oms doctor` (non-blocking, exits 0).

package/adapters/claude-code/skills/retrieve/SKILL.md

@@ -1,99 +0,0 @@
----
-name: oms-retrieve
-description: Retrieve knowledge from the vault through declared Oh My Second Brain retrieval views and axes (agent-guided; runtime is roadmap).
----
-
-# Skill: oms-retrieve (Claude Code)
-
-Surface the right notes and fields for a given purpose using the vault's declared retrieval axes and views (인출).
-
-## Invocation
-
-```
-/oms-retrieve
-```
-
-## What this skill does
-
-Conceptually shells out to:
-
-```bash
-oms retrieve
-```
-
-**Runtime note:** Retrieval is available through MCP tools. Prefer
-`oms_retrieve_context` for live graph + semantic context retrieval, use
-`oms_sync_embeddings` when the native semantic index must be refreshed, then
-`oms_get_document` or `oms_multi_get_documents` for selected semantic evidence
-or `oms_semantic_query`/`oms_semantic_status` for qmd-compatible follow-ups,
-and `oms_lazy_load_note` for selected vault-note bodies. `oms_retrieve_by_axis`
-remains available for legacy cache-backed axis retrieval.
-
-## Typed query interface
-
-Pass `semanticSearches` to issue typed sub-queries in a single call:
-
-| type    | behaviour                                        |
-|---------|--------------------------------------------------|
-| `lex`   | BM25 keyword search (exact terms, fast)          |
-| `vec`   | SQLite-vector semantic search (meaning-based)    |
-| `hyde`  | Hypothetical-document expansion before search    |
-
-```
-semanticSearches: [
-  { type: "lex",   query: "transformer attention" },
-  { type: "vec",   query: "self-attention replaces recurrence" },
-  { type: "hyde",  query: "a paper about attention mechanisms" }
-]
-```
-
-Use `semanticScope: "global"` (default) for vault-wide semantic search.
-Use `semanticScope: "graph"` (**gph mode**) to confine semantic candidates
-to the set already selected by the OMS graph traversal.
-
-## Agent-guided steps (v0)
-
-1. Clarify the user's **retrieval purpose** (synthesize, audit, plan, review, etc.).
-2. Narrow by declared **folder/concept/property/wikilink axes** where possible.
-3. Match the purpose to a declared **retrieval view** (`lenses` in YAML) in `vault/.oms/concepts/*.yaml`.
-4. Call MCP `oms_retrieve_context` with the best available axes and query.
-5. Choose semantic scope: `semanticScope: "global"` for broad vault-wide search;
-   `semanticScope: "graph"` (gph mode) when candidates must stay inside the
-   selected graph neighbors. Pass typed sub-queries via `semanticSearches`
-   using `lex`, `vec`, or `hyde` types as appropriate.
-   Pass `semanticMode`, `semanticIntent`, `semanticLex`, `semanticVec`,
-   `semanticHyde`, and `semanticMinScore` for additional control.
-   Set `embeddingSyncBeforeSearch: true` only when the native semantic
-   index must be refreshed before retrieval.
-6. Use `oms_sync_embeddings` for explicit update/embed sync.
-7. Use `oms_semantic_query`, `oms_semantic_status`, `oms_semantic_collections`,
-   or `oms_semantic_contexts` for qmd-compatible follow-ups on the native OMS index.
-8. Use read-only `oms_get_document` or `oms_multi_get_documents` to rehydrate
-   selected docids, paths, globs, or line ranges.
-9. For each note, return the retrieval-view fields and lazy-load body only when needed.
-10. Return results grouped by concept/folder with retrieval-view frontmatter.
-
-## Example
-
-```
-Purpose: "Synthesize my transformer papers"
-
-→ concept: literature
-→ view:    synthesis  (YAML key: lenses; fields: [title, thesis, source-url])
-→ scan:    vault/references/*.md
-→ output:
-
-| title | thesis | source-url |
-|-------|--------|------------|
-| Attention Is All You Need | Self-attention replaces recurrence | https://arxiv.org/abs/1706.03762 |
-```
-
-## Runtime
-
-Use MCP `oms_retrieve_context` for live graph/semantic retrieval. Pass typed
-sub-queries via `semanticSearches` (types: `lex`, `vec`, `hyde`).
-Use `semanticScope: "graph"` (gph mode) to confine semantic candidates to
-graph neighbors. Use MCP `oms_sync_embeddings` for native semantic-index sync.
-Use MCP `oms_get_document` or `oms_multi_get_documents` for document rehydration.
-Use MCP `oms_retrieve_by_axis` only for legacy axis-first cache retrieval.
-Use MCP `oms_lazy_load_note` only after selecting candidate notes.

package/adapters/claude-code/skills/setup/SKILL.md

@@ -1,78 +0,0 @@
----
-name: oms-setup
-description: Adopt an existing Obsidian vault into the Oh My Second Brain convention by running oms setup.
----
-
-# Skill: oms-setup (Claude Code)
-
-Adopt your Obsidian vault into the Oh My Second Brain convention.
-This skill is **REAL in v0** — it shells out to the fully-implemented CLI.
-
-## Invocation
-
-```
-/oms-setup
-```
-
-## What this skill does
-
-Shells out to:
-
-```bash
-oms setup [--vault <path>] [--yes] [--suggest-fields] [--install-claude]
-oms install [--runtime <auto|all|claude|codex|hermes>] [--vault <path>] [--dry-run] [--execute] [--yes]
-```
-
-The CLI will:
-1. Scan your vault's existing top-level folders (does NOT impose a structure).
-2. Interactively ask each folder's intent and concept binding (use `--yes` to accept defaults).
-3. Summarize observed frontmatter fields without changing notes.
-4. Optionally add selected observed fields to concept schemas with `--suggest-fields`.
-5. Ask for retrieval lenses and reject lenses that reference unknown fields.
-6. Write `vault/.oms/taxonomy.yaml` and preserve existing `vault/.oms/concepts/` files while adding missing defaults.
-
-## Options
-
-| Flag | Description |
-|------|-------------|
-| `--vault <path>` | Path to your Obsidian vault root (default: current directory) |
-| `--yes` | Non-interactive: accept all defaults, no prompts |
-| `--suggest-fields` | Merge observed note frontmatter fields into concept schemas without mutating notes. |
-| `--install-claude` | Legacy setup-only dry-run that prints the Claude Code plugin install command and plugin-owned MCP asset. |
-| `install --runtime <name>` | Install host adapter/MCP registration for `auto`, `all`, `claude`, `codex`, or `hermes`. |
-| `install --dry-run` | Preview host writes without mutating config. |
-| `install --execute` | Allow external host CLIs such as `claude plugin install` to run when available. |
-
-## Example
-
-```bash
-# Interactive (recommended first run):
-oms setup --vault ~/Documents/MyVault
-
-# Interactive setup with observed frontmatter field suggestions:
-oms setup --vault ~/Documents/MyVault --suggest-fields
-
-# Non-interactive (CI / scripted):
-oms setup --vault ~/Documents/MyVault --yes
-
-# Preview all host adapter installs:
-oms install --runtime all --vault ~/Documents/MyVault --dry-run
-
-# Install all host adapter/MCP registrations:
-oms install --runtime all --vault ~/Documents/MyVault --yes
-
-# Also run external host CLIs where available:
-oms install --runtime claude --vault ~/Documents/MyVault --yes --execute
-```
-
-## After setup
-
-Run `/oms-doctor` to validate your existing notes against the convention.
-
-## Roadmap
-
-Setup plus `oms install`/`oms uninstall` host lifecycle commands are real and release-gated by unpacked npm tarball smoke tests. The plugin-owned MCP asset starts
-the status/read/cache/retrieve/write runtime (`oms_graph_status`, `oms_graph_build`,
-`oms_list_concepts`, `oms_retrieve_context`, `oms_retrieve_by_axis`,
-`oms_lazy_load_note`, `oms_validate_contract`, `write`).
-`write` is gated by path-safety and the kernel-owned contract.