oh-my-second-brain 0.1.5 → 0.1.7

package/adapters/README.md

@@ -43,7 +43,7 @@ adapters/<host>/
 
 ### claude-code (REAL installable v0)
 
-Release contract: the npm tarball must include `adapters/claude-code/` because `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz setup --install-claude` prints a packaged adapter path for `claude plugin install`.
+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[] }`
@@ -80,11 +80,11 @@ contract validation, retrieve, graph/status, and gated capture 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/capture tools:
+The MCP server currently exposes status/read/cache/retrieve/capture tools:
 `oms_graph_status`, `oms_graph_build`, `oms_list_concepts`,
-`oms_retrieve_by_axis`, `oms_lazy_load_note`, `oms_validate_contract`,
-`oms_capture_prepare`, and `oms_capture_commit`.
-Capture commit is gated by path-safety, vault-confinement, and contract validation. The CLI (`npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz setup`, `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install`, `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz uninstall`, `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor`) remains the real surface for lifecycle commands.
+`oms_retrieve_context`, `oms_retrieve_by_axis`, `oms_lazy_load_note`,
+`oms_validate_contract`, `oms_capture_prepare`, and `oms_capture_commit`.
+Capture commit 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.
 
 ---
 
@@ -93,6 +93,6 @@ Capture commit is gated by path-safety, vault-confinement, and contract validati
 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 `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz <verb>` (for lifecycle) or call the MCP server (for capture/retrieve).
+4. Write skill wrappers that shell out to `oms <verb>` (for lifecycle) or call the MCP server (for capture/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/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Oh My Second Brain convention layer for Obsidian vaults \u2014 capture, retrieve, and validate knowledge under a declared semantic convention.",
   "author": {
     "name": "gobeumsu"

package/adapters/claude-code/CLAUDE.md

@@ -8,7 +8,7 @@ This vault is governed by Oh My Second Brain conventions stored in `.oms/`.
 All knowledge capture and retrieval must follow the declared semantic convention.
 
 **Before working with vault notes:**
-- Run `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor` to validate existing notes against the convention (exits 0, non-blocking).
+- Run `oms doctor` to validate existing notes against the convention (exits 0, non-blocking).
 - Read `.oms/taxonomy.yaml` to understand which folders hold which concepts.
 - Read `.oms/concepts/*.yaml` to understand field requirements and lenses.
 
@@ -23,4 +23,4 @@ All knowledge capture and retrieval must follow the declared semantic convention
 - Return only the fields the lens specifies — do not dump full frontmatter.
 
 **Convention violations are warnings, not errors (v0).**
-`npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor` always exits 0. Fix violations incrementally.
+`oms doctor` always exits 0. Fix violations incrementally.

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

@@ -27,7 +27,7 @@ after prepare returns `ready` or the user has supplied missing fields.
 5. If required fields are missing, ask for them; do not write.
 6. If placement is ambiguous, route to inbox.
 7. Commit only through `oms_capture_commit` (`create` or `append`).
-8. Shell out: `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor` (non-blocking, exits 0) to confirm the note is clean.
+8. Shell out: `oms doctor` (non-blocking, exits 0) to confirm the note is clean.
 
 ## Example
 

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

@@ -1,6 +1,6 @@
 ---
 name: oms-define
-description: Grow the vault convention by adding a metadata field to a concept. Entry point is npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz define (roadmap).
+description: Grow the vault convention by adding a metadata field to a concept. Entry point is oms define (roadmap).
 ---
 
 # Skill: oms-define (Claude Code)
@@ -19,7 +19,7 @@ Each frontmatter key is a unit of convention with a declared `intent`, type, and
 Intended to shell out to:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz define
+oms define
 ```
 
 **Roadmap note:** The `oms define` interactive runtime is not yet implemented in v0.
@@ -34,7 +34,7 @@ Today this skill guides you through the same steps manually (agent-guided).
 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 `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor` to validate existing notes against the updated schema.
+8. Run `oms doctor` to validate existing notes against the updated schema.
 
 ## YAML snippet to append
 
@@ -48,4 +48,4 @@ fields:
 
 ## When the runtime ships
 
-`npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz define` will run the same Q&A interactively and write the YAML for you.
+`oms define` will run the same Q&A interactively and write the YAML for you.

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

@@ -1,6 +1,6 @@
 ---
 name: oms-doctor
-description: Validate vault notes against the Oh My Second Brain convention by running npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor.
+description: Validate vault notes against the Oh My Second Brain convention by running oms doctor.
 ---
 
 # Skill: oms-doctor (Claude Code)
@@ -19,7 +19,7 @@ This skill is **REAL in v0** — it shells out to the fully-implemented CLI.
 Shells out to:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor [--vault <path>]
+oms doctor [--vault <path>]
 ```
 
 The CLI will:
@@ -39,7 +39,7 @@ The CLI will:
 ## Example
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor --vault ~/Documents/MyVault
+oms doctor --vault ~/Documents/MyVault
 ```
 
 ## Sample output

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

@@ -18,21 +18,25 @@ Surface the right notes and fields for a given purpose using the vault's declare
 Conceptually shells out to:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz retrieve
+oms retrieve
 ```
 
-**Runtime note:** Retrieval is available through MCP tools (`oms_retrieve_by_axis`
-and `oms_lazy_load_note`). This skill still guides the agent on intent and
-output shaping.
+**Runtime note:** Retrieval is available through MCP tools. Prefer
+`oms_retrieve_context` for live graph + qmd context retrieval, then
+`oms_lazy_load_note` after selecting candidate notes. `oms_retrieve_by_axis`
+remains available for legacy cache-backed axis retrieval.
 
 ## 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. Scan notes in the candidate concept/folder set.
-5. For each note, return the retrieval-view fields and lazy-load body only when needed.
-6. Return results grouped by concept/folder with retrieval-view frontmatter.
+4. Call MCP `oms_retrieve_context` with the best available axes and query.
+5. Use default `qmdScope: "global"` for broad semantic search; use
+   `qmdScope: "graph"` only when qmd must stay inside the selected graph
+   candidates.
+6. For each note, return the retrieval-view fields and lazy-load body only when needed.
+7. Return results grouped by concept/folder with retrieval-view frontmatter.
 
 ## Example
 
@@ -51,5 +55,6 @@ Purpose: "Synthesize my transformer papers"
 
 ## Runtime
 
-Use MCP `oms_retrieve_by_axis` for axis-first narrowing and optional lexical
-ranking. Use MCP `oms_lazy_load_note` only after selecting candidate notes.
+Use MCP `oms_retrieve_context` for live graph/qmd retrieval. 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,6 +1,6 @@
 ---
 name: oms-setup
-description: Adopt an existing Obsidian vault into the Oh My Second Brain convention by running npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz setup.
+description: Adopt an existing Obsidian vault into the Oh My Second Brain convention by running oms setup.
 ---
 
 # Skill: oms-setup (Claude Code)
@@ -19,8 +19,8 @@ This skill is **REAL in v0** — it shells out to the fully-implemented CLI.
 Shells out to:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz setup [--vault <path>] [--yes] [--install-claude]
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install [--runtime <auto|all|claude|codex|hermes>] [--vault <path>] [--dry-run] [--execute] [--yes]
+oms setup [--vault <path>] [--yes] [--install-claude]
+oms install [--runtime <auto|all|claude|codex|hermes>] [--vault <path>] [--dry-run] [--execute] [--yes]
 ```
 
 The CLI will:
@@ -43,19 +43,19 @@ The CLI will:
 
 ```bash
 # Interactive (recommended first run):
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz setup --vault ~/Documents/MyVault
+oms setup --vault ~/Documents/MyVault
 
 # Non-interactive (CI / scripted):
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz setup --vault ~/Documents/MyVault --yes
+oms setup --vault ~/Documents/MyVault --yes
 
 # Preview all host adapter installs:
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install --runtime all --vault ~/Documents/MyVault --dry-run
+oms install --runtime all --vault ~/Documents/MyVault --dry-run
 
 # Install all host adapter/MCP registrations:
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install --runtime all --vault ~/Documents/MyVault --yes
+oms install --runtime all --vault ~/Documents/MyVault --yes
 
 # Also run external host CLIs where available:
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install --runtime claude --vault ~/Documents/MyVault --yes --execute
+oms install --runtime claude --vault ~/Documents/MyVault --yes --execute
 ```
 
 ## After setup
@@ -65,7 +65,8 @@ 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 MCP command starts
-the status/read/cache/capture runtime (`oms_graph_status`, `oms_graph_build`,
-`oms_list_concepts`, `oms_retrieve_by_axis`, `oms_lazy_load_note`,
-`oms_validate_contract`, `oms_capture_prepare`, `oms_capture_commit`).
+the status/read/cache/retrieve/capture runtime (`oms_graph_status`, `oms_graph_build`,
+`oms_list_concepts`, `oms_retrieve_context`, `oms_retrieve_by_axis`,
+`oms_lazy_load_note`, `oms_validate_contract`, `oms_capture_prepare`,
+`oms_capture_commit`).
 Capture commit is gated by path-safety and contract validation.

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

@@ -1,6 +1,6 @@
 ---
 name: oms-uninstall
-description: Remove Oh My Second Brain host adapter and MCP registrations by running npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz uninstall.
+description: Remove Oh My Second Brain host adapter and MCP registrations by running oms uninstall.
 ---
 
 # Skill: oms-uninstall (Claude Code)
@@ -18,17 +18,17 @@ Remove Oh My Second Brain host registrations and adapter files. This does **not*
 Shells out to:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz uninstall [--runtime <all|claude|codex|hermes>] [--dry-run] [--execute] [--yes]
+oms uninstall [--runtime <all|claude|codex|hermes>] [--dry-run] [--execute] [--yes]
 ```
 
 ## Recommended flow
 
 ```bash
 # Preview first:
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz uninstall --runtime all --dry-run
+oms uninstall --runtime all --dry-run
 
 # Remove Oh My Second Brain host registrations:
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz uninstall --runtime all --yes
+oms uninstall --runtime all --yes
 ```
 
 Use `--execute` only when you want Oh My Second Brain to call external host CLIs such as `claude mcp remove oms` or `claude plugin uninstall oms`.

package/adapters/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Oh My Second Brain convention layer for Obsidian vaults \u2014 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/",

package/adapters/codex/.mcp.json

@@ -1,10 +1,8 @@
 {
   "mcpServers": {
     "oms": {
-      "command": "npx",
+      "command": "oms",
       "args": [
-        "-y",
-        "https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz",
         "mcp",
         "--vault",
         "."

package/adapters/codex/AGENTS.md

@@ -7,7 +7,7 @@
 This vault is governed by Oh My Second Brain conventions stored in `.oms/`.
 
 **Before working with vault notes:**
-- Run `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor` to validate notes against the convention (exits 0, non-blocking).
+- 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.
 
 **Capture:** Use `$oms-capture` skill or follow the librarian persona.

package/adapters/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 `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz setup --vault <path>` |
-| install host integration | `$oms-install` or `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install --runtime codex --vault <path> --yes` |
-| uninstall host integration | `$oms-uninstall` or `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz uninstall --runtime codex --yes` |
-| validate notes | `$oms-doctor` or `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor --vault <path>` |
+| 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` |
+| validate notes | `$oms-doctor` or `oms doctor --vault <path>` |
 | capture knowledge | use MCP `oms_capture_prepare` then `oms_capture_commit` |
-| retrieve knowledge | use MCP `oms_retrieve_by_axis`, then `oms_lazy_load_note` only when needed |
+| retrieve knowledge | use MCP `oms_retrieve_context`, then `oms_lazy_load_note` only when needed |
 
 ## Safety
 

package/adapters/codex/skills/oms-doctor/SKILL.md

@@ -8,7 +8,7 @@ description: Validate vault notes against the active Oh My Second Brain ontology
 Run:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor --vault <vault>
+oms doctor --vault <vault>
 ```
 
 The command is advisory in v0 and exits 0 even when warnings are found.

package/adapters/codex/skills/oms-install/SKILL.md

@@ -8,7 +8,7 @@ description: Install Oh My Second Brain Codex/Hermes/Claude host adapters and MC
 Use for host lifecycle installation.
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install --runtime <auto|all|claude|codex|hermes> --vault <vault> --yes
+oms install --runtime <auto|all|claude|codex|hermes> --vault <vault> --yes
 ```
 
 For Codex, this installs:

package/adapters/codex/skills/oms-retrieve/SKILL.md

@@ -5,6 +5,14 @@ description: Retrieve vault knowledge axis-first using folders, frontmatter, wik
 
 # oms-retrieve
 
-Use `oms_retrieve_by_axis` first. Narrow by concept/folder/property/value/wikilink before lexical query. Use `oms_lazy_load_note` only after selecting candidate notes.
+Use `oms_retrieve_context` first for natural-language retrieval. It combines live
+frontmatter/folder/wikilink graph context with optional qmd lexical/vector
+candidates and does not require a warm graph cache. Pass declared
+concept/folder/property/value/wikilink axes when the user's intent gives them.
+
+Use `qmdScope: "global"` when the user asks broad semantic search across the
+vault, and `qmdScope: "graph"` when qmd candidates must stay inside the selected
+OMS graph candidates. Use `oms_retrieve_by_axis` only for legacy axis-first
+cache retrieval. Use `oms_lazy_load_note` only after selecting candidate notes.
 
 Return lens-shaped fields where possible; do not dump full note bodies unless the user asks or the retrieval task needs body evidence.

package/adapters/codex/skills/oms-setup/SKILL.md

@@ -10,13 +10,13 @@ Use when the user wants to initialize Oh My Second Brain for a vault.
 Run:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz setup --vault <vault> --yes
+oms setup --vault <vault> --yes
 ```
 
 Then, when host registration is desired:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install --runtime codex --vault <vault> --yes
+oms install --runtime codex --vault <vault> --yes
 ```
 
 Do not modify vault notes during setup. Oh My Second Brain writes only `vault/.oms/taxonomy.yaml` and `vault/.oms/concepts/`.

package/adapters/codex/skills/oms-uninstall/SKILL.md

@@ -8,13 +8,13 @@ description: Remove Oh My Second Brain host adapter files and MCP registration w
 Preview first:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz uninstall --runtime all --dry-run
+oms uninstall --runtime all --dry-run
 ```
 
 Remove host registrations:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz uninstall --runtime all --yes
+oms uninstall --runtime all --yes
 ```
 
 Never delete vault notes or `vault/.oms/` as part of host uninstall.

package/adapters/hermes/SOUL.md

@@ -7,12 +7,12 @@
 This vault is governed by Oh My Second Brain conventions stored in `.oms/`.
 
 **Before working with vault notes:**
-- Run `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor` to validate notes against the convention (exits 0, non-blocking).
+- Run `oms doctor` to validate notes against the convention (exits 0, non-blocking).
 - Read `.oms/taxonomy.yaml` for folder-to-concept bindings.
 - Read `.oms/concepts/*.yaml` for field declarations and lenses.
 
 **Capture:** Follow the librarian persona — resolve concept, resolve folder from taxonomy,
-construct required frontmatter, write note, then run `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor`.
+construct required frontmatter, write note, then run `oms doctor`.
 
 **Retrieve:** Follow the retriever persona — identify purpose, match lens, project lens fields only.
 

package/adapters/hermes/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "oms",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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/"

package/adapters/hermes/skills/doctor/SKILL.md

@@ -8,7 +8,7 @@ description: Validate vault notes against the active Oh My Second Brain ontology
 Run:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor --vault <vault>
+oms doctor --vault <vault>
 ```
 
 The command is advisory in v0 and exits 0 even when warnings are found.

package/adapters/hermes/skills/install/SKILL.md

@@ -8,7 +8,7 @@ description: Install Oh My Second Brain Codex/Hermes/Claude host adapters and MC
 Use for host lifecycle installation.
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install --runtime <auto|all|claude|codex|hermes> --vault <vault> --yes
+oms install --runtime <auto|all|claude|codex|hermes> --vault <vault> --yes
 ```
 
 For Codex, this installs:

package/adapters/hermes/skills/retrieve/SKILL.md

@@ -5,6 +5,14 @@ description: Retrieve vault knowledge axis-first using folders, frontmatter, wik
 
 # oms-retrieve
 
-Use `oms_retrieve_by_axis` first. Narrow by concept/folder/property/value/wikilink before lexical query. Use `oms_lazy_load_note` only after selecting candidate notes.
+Use `oms_retrieve_context` first for natural-language retrieval. It combines live
+frontmatter/folder/wikilink graph context with optional qmd lexical/vector
+candidates and does not require a warm graph cache. Pass declared
+concept/folder/property/value/wikilink axes when the user's intent gives them.
+
+Use `qmdScope: "global"` when the user asks broad semantic search across the
+vault, and `qmdScope: "graph"` when qmd candidates must stay inside the selected
+OMS graph candidates. Use `oms_retrieve_by_axis` only for legacy axis-first
+cache retrieval. Use `oms_lazy_load_note` only after selecting candidate notes.
 
 Return lens-shaped fields where possible; do not dump full note bodies unless the user asks or the retrieval task needs body evidence.

package/adapters/hermes/skills/setup/SKILL.md

@@ -10,13 +10,13 @@ Use when the user wants to initialize Oh My Second Brain for a vault.
 Run:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz setup --vault <vault> --yes
+oms setup --vault <vault> --yes
 ```
 
 Then, when host registration is desired:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install --runtime codex --vault <vault> --yes
+oms install --runtime codex --vault <vault> --yes
 ```
 
 Do not modify vault notes during setup. Oh My Second Brain writes only `vault/.oms/taxonomy.yaml` and `vault/.oms/concepts/`.

package/adapters/hermes/skills/uninstall/SKILL.md

@@ -8,13 +8,13 @@ description: Remove Oh My Second Brain host adapter files and MCP registration w
 Preview first:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz uninstall --runtime all --dry-run
+oms uninstall --runtime all --dry-run
 ```
 
 Remove host registrations:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz uninstall --runtime all --yes
+oms uninstall --runtime all --yes
 ```
 
 Never delete vault notes or `vault/.oms/` as part of host uninstall.

package/core/agents/librarian.md

@@ -21,7 +21,7 @@ It reads the convention first, then acts.
 2. **Folder resolution** — look up the correct target folder from `vault/.oms/taxonomy.yaml` based on the matched concept.
 3. **Frontmatter construction** — fill every `required: true` field; fill known optional fields; leave undeclared fields untouched.
 4. **Note creation** — write the file at the resolved path; use the concept's naming convention (default: `YYYY-MM-DD-<slug>.md`).
-5. **Post-capture validation** — run `npx oms doctor` (non-blocking) to confirm the new note is clean.
+5. **Post-capture validation** — run `npx oh-my-second-brain doctor` (non-blocking) to confirm the new note is clean.
 
 ## Decision rules
 

package/core/skills/capture/SKILL.md

@@ -18,14 +18,16 @@ The librarian persona governs this action.
    - Fill optional fields where values are known.
    - Leave undeclared (extra) frontmatter fields untouched (`additionalProperties: preserve`).
 5. Write the note body after the frontmatter block.
-6. Run `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor` (non-blocking, exits 0) to confirm the new note passes field validation.
+6. Run `oms doctor` (non-blocking, exits 0) to confirm the new note passes field validation.
 
-## Conceptual shell-out (roadmap — NOT wired in v0)
+## Engine
 
-The runtime automation described above is **agent-guidance only in v0**.
-No capture engine exists yet; the agent follows these steps manually.
-When the MCP server is wired (`src/mcp/server.ts` → real), `capture` will call
-the `capture` MCP tool directly.
+The capture engine is implemented in `src/capture/safe.ts` and exposed via two MCP tools:
+
+- **`oms_capture_prepare`** — resolves the target path and constructs the proposed frontmatter/body without writing anything. Call this first to let the agent review the proposed note before committing.
+- **`oms_capture_commit`** — writes the file to disk. Gated by vault confinement: rejects writes that are outside the vault, to non-`.md` files, or into the `.oms/` config directory. Frontmatter violations are warn-only and do not block the commit.
+
+The recommended agent flow is to call `oms_capture_prepare`, review the result, then call `oms_capture_commit` to finalize.
 
 ## Example agent steps
 
@@ -40,7 +42,7 @@ User: "Save this paper: 'Attention Is All You Need', arxiv.org/abs/1706.03762"
      source-url: "https://arxiv.org/abs/1706.03762"
      captured-at: "2026-05-31"
 5. write note body
-6. npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor  ← verify (exits 0, non-blocking)
+6. oms doctor  ← verify (exits 0, non-blocking)
 ```
 
 ## Persona

package/core/skills/define/SKILL.md

@@ -12,7 +12,7 @@ type, and optional rules (`required`, `normalize`, `immutable`).
 ## Entry point
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz define
+oms define
 ```
 
 This is the intended user-facing command (roadmap: interactive runtime not built yet).
@@ -27,7 +27,7 @@ Use `define` as **agent-guided convention editing** until the interactive runtim
 4. Ask: **type** (`string` | `string[]` | `date` | `url` | `boolean`), **required** (yes/no).
 5. Optionally ask: `normalize` (e.g. `lowercase`), `immutable` (lock after creation).
 6. Open `vault/.oms/concepts/<concept>.yaml` and append the new field entry.
-7. Run `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor` to validate existing notes against the updated schema (exits 0).
+7. Run `oms doctor` to validate existing notes against the updated schema (exits 0).
 
 ## Convention YAML shape (one field entry)
 

package/core/skills/doctor/SKILL.md

@@ -11,7 +11,7 @@ This skill is **REAL in v0** — the CLI command is fully implemented.
 ## Shell-out
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor [--vault <path>]
+oms doctor [--vault <path>]
 ```
 
 - `--vault <path>` — path to your Obsidian vault root (default: current directory).
@@ -40,7 +40,7 @@ Undeclared frontmatter fields are **never** reported as violations
 
 ## Recommended usage
 
-Run `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor` after:
+Run `oms doctor` after:
 - Any `oms setup` run
 - Adding a new field via `oms define`
 - Bulk-editing notes

package/core/skills/retrieve/SKILL.md

@@ -32,12 +32,24 @@ lenses:
 
 The retrieval skill reads these declarations from `vault/.oms/concepts/*.yaml`.
 
-## Conceptual shell-out (roadmap — NOT wired in v0)
+## Engine
 
-The runtime automation described above is **agent-guidance only in v0**.
-No retrieval engine exists yet; the agent follows these steps manually.
-When the MCP server is wired (`src/mcp/server.ts` → real), `retrieve` will call
-the `retrieve` MCP tool directly.
+Use MCP `oms_retrieve_context` first for natural-language retrieval. It combines:
+
+- live folder/frontmatter/wikilink graph exploration without requiring a warm cache
+- taxonomy-axis seeds from concept, folder, property, value, or wikilink inputs
+- graph neighbors through shared frontmatter values, wikilinks, and backlinks
+- optional qmd lexical/vector candidates when the local `qmd` CLI is available
+
+Use `qmdScope: "global"` for broad semantic search across the vault. Use
+`qmdScope: "graph"` when qmd candidates must stay inside the selected OMS graph
+candidates. The qmd provider is fail-soft: retrieval must still return OMS graph
+hits when qmd is unavailable or disabled.
+
+Use the older MCP tools only for narrower follow-up steps:
+
+- **`oms_retrieve_by_axis`** — legacy cache-backed axis retrieval by concept, folder, property, value, or wikilink.
+- **`oms_lazy_load_note`** — fetches the full body of a single selected note on demand, avoiding loading all note bodies upfront.
 
 ## Example agent steps
 

package/core/skills/setup/SKILL.md

@@ -11,7 +11,7 @@ This skill is **REAL in v0** — the CLI command is fully implemented.
 ## Shell-out
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz setup [--vault <path>] [--yes]
+oms setup [--vault <path>] [--yes]
 ```
 
 - `--vault <path>` — path to your Obsidian vault root (default: current directory).
@@ -27,7 +27,7 @@ npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.t
 6. Copies the shipped default concepts into `vault/.oms/concepts/`.
 
 After setup, the vault is governed by Oh My Second Brain conventions.
-Run `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor` at any time to validate existing notes.
+Run `oms doctor` at any time to validate existing notes.
 
 ## What setup does NOT do
 
@@ -40,5 +40,5 @@ Run `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.
 Run the `doctor` skill to check your notes against the convention:
 
 ```bash
-npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor [--vault <path>]
+oms doctor [--vault <path>]
 ```