oh-my-second-brain 0.1.5

package/adapters/README.md

@@ -0,0 +1,98 @@
+# Adapter Contract
+
+## Principle
+
+Oh My Second Brain's **core** (ontology loading, convention validation, graph/search runtime targets, and MCP server once implemented) 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 `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`.
+
+- **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**: none in v0 (hook format is `hooks/hooks.json` multi-script array — roadmap).
+- **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 uses a unified `codex-native-hook.mjs` instead of `hooks.json`.
+  - 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 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:
+`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.
+
+---
+
+## 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 `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).
+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

@@ -0,0 +1,24 @@
+{
+  "name": "oms",
+  "version": "0.1.5",
+  "description": "Oh My Second Brain convention layer for Obsidian vaults \u2014 capture, retrieve, and validate knowledge under a declared semantic convention.",
+  "author": {
+    "name": "gobeumsu"
+  },
+  "license": "MIT",
+  "keywords": [
+    "obsidian",
+    "knowledge-base",
+    "convention",
+    "frontmatter",
+    "vault"
+  ],
+  "skills": [
+    "./skills/setup/",
+    "./skills/doctor/",
+    "./skills/define/",
+    "./skills/capture/",
+    "./skills/retrieve/",
+    "./skills/uninstall/"
+  ]
+}

package/adapters/claude-code/CLAUDE.md

@@ -0,0 +1,26 @@
+# Oh My Second Brain Convention Fragment
+
+<!-- Append this block to your project's CLAUDE.md to activate Oh My Second Brain conventions in Claude Code. -->
+
+## Vault Convention (Oh My Second Brain)
+
+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).
+- Read `.oms/taxonomy.yaml` to understand which folders hold which concepts.
+- Read `.oms/concepts/*.yaml` to understand field requirements and lenses.
+
+**When capturing new knowledge:**
+- Use the `/oms-capture` skill or follow the librarian persona (`core/agents/librarian.md`).
+- Every note must carry the required frontmatter fields for its concept.
+- Place notes in the folder declared in the taxonomy — do not invent new folders without updating `.oms/taxonomy.yaml`.
+
+**When retrieving knowledge:**
+- Use the `/oms-retrieve` skill or follow the retriever persona (`core/agents/retriever.md`).
+- Apply the concept's declared lens for the retrieval purpose (synthesis, audit, etc.).
+- Return only the fields the lens specifies — do not dump full frontmatter.
+
+**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.

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

@@ -0,0 +1,50 @@
+---
+name: oms-capture
+description: Capture knowledge into the vault under the Oh My Second Brain convention using gated MCP prepare/commit tools.
+---
+
+# Skill: oms-capture (Claude Code)
+
+Place a piece of knowledge into the vault with correct frontmatter and folder placement.
+
+## Invocation
+
+```
+/oms-capture
+```
+
+## What this skill does
+
+Uses MCP `oms_capture_prepare` first. Only call MCP `oms_capture_commit`
+after prepare returns `ready` or the user has supplied missing fields.
+
+## Agent-guided steps (v0)
+
+1. Identify the **concept** that fits the incoming knowledge (check `vault/.oms/concepts/`).
+2. Resolve the **target folder** from `vault/.oms/taxonomy.yaml`.
+3. Generate a filename: `YYYY-MM-DD-<slug>.md`.
+4. Construct frontmatter — fill `required: true` fields; preserve any extra 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.
+
+## Example
+
+```
+Input: "Attention Is All You Need", https://arxiv.org/abs/1706.03762
+
+→ concept:  literature
+→ folder:   vault/references/
+→ file:     vault/references/2017-06-12-attention-is-all-you-need.md
+→ frontmatter:
+    title: "Attention Is All You Need"
+    source-url: "https://arxiv.org/abs/1706.03762"
+    captured-at: "2026-05-31"
+```
+
+## Runtime
+
+`oms_capture_prepare` preserves route-to-inbox and ask-missing-fields behavior.
+`oms_capture_commit` refuses unsafe paths, `.oms/` internals, non-markdown
+targets, and frontmatter that violates the resolved concept contract.

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

@@ -0,0 +1,51 @@
+---
+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).
+---
+
+# 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
+npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz 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 `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.
+
+## YAML snippet to append
+
+```yaml
+fields:
+  - name: thesis
+    type: string
+    required: false
+    intent: "The central claim this source makes"
+```
+
+## 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.

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

@@ -0,0 +1,58 @@
+---
+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.
+---
+
+# 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
+npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz 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
+npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz 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/retrieve/SKILL.md

@@ -0,0 +1,55 @@
+---
+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
+npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz 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.
+
+## 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.
+
+## 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_by_axis` for axis-first narrowing and optional lexical
+ranking. Use MCP `oms_lazy_load_note` only after selecting candidate notes.

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

@@ -0,0 +1,71 @@
+---
+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.
+---
+
+# 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
+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]
+```
+
+The CLI will:
+1. Scan your vault's existing top-level folders (does NOT impose a structure).
+2. Interactively ask the `intent` for each folder (use `--yes` to skip prompts).
+3. Write `vault/.oms/taxonomy.yaml` and copy default concept schemas.
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--vault <path>` | Path to your Obsidian vault root (default: current directory) |
+| `--yes` | Non-interactive: accept all defaults, no prompts |
+| `--install-claude` | Legacy setup-only dry-run that prints Claude Code plugin install and MCP registration commands. |
+| `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):
+npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz 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
+
+# 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
+
+# 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
+
+# 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
+```
+
+## 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 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`).
+Capture commit is gated by path-safety and contract validation.

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

@@ -0,0 +1,34 @@
+---
+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.
+---
+
+# Skill: oms-uninstall (Claude Code)
+
+Remove Oh My Second Brain host registrations and adapter files. This does **not** delete vault notes or `vault/.oms/` ontology data.
+
+## Invocation
+
+```
+/oms-uninstall
+```
+
+## What this skill does
+
+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]
+```
+
+## 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
+
+# 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
+```
+
+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

@@ -0,0 +1,8 @@
+{
+  "name": "oms",
+  "version": "0.1.5",
+  "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/",
+  "mcpServers": "./.mcp.json"
+}

package/adapters/codex/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "oms": {
+      "command": "npx",
+      "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

@@ -0,0 +1,16 @@
+# Oh My Second Brain Convention Shim — Codex
+
+<!-- Append this block to your project's AGENTS.md to activate Oh My Second Brain conventions in Codex (oh-my-codex). -->
+
+## Vault Convention (Oh My Second Brain)
+
+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).
+- Read `.oms/taxonomy.yaml` and `.oms/concepts/*.yaml` for folder and field declarations.
+
+**Capture:** Use `$oms-capture` skill or follow the librarian persona.
+**Retrieve:** Use `$oms-retrieve` skill or follow the retriever persona with declared lenses.
+
+> **v0 native install:** `oms install --runtime codex` installs Codex rules, `$oms-*` skills, and a managed Codex MCP config. Use Oh My Second Brain MCP tools for capture/retrieve and CLI commands for lifecycle.

package/adapters/codex/rules/oms.md

@@ -0,0 +1,25 @@
+# Oh My Second Brain for Codex
+
+Use Oh My Second Brain when the user asks to set up, validate, capture into, retrieve from, or inspect an Obsidian/Markdown vault governed by `vault/.oms/`.
+
+## Core rule
+
+Oh My Second Brain is a convention harness, not a content generator. The user owns the ontology in `vault/.oms/`; agents must use the declared folder axis, frontmatter/property axes, wikilinks, and retrieval lenses before reading or writing notes.
+
+## Command mapping
+
+| 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>` |
+| 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 |
+
+## Safety
+
+- Never delete vault notes or `vault/.oms/` during uninstall.
+- Capture must stay inside the configured vault and target Markdown files only.
+- If required frontmatter is missing, ask for it; do not invent user-owned ontology values.
+- Route ambiguous captures to inbox when the ontology cannot decide.

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

@@ -0,0 +1,16 @@
+---
+name: oms-capture
+description: Capture knowledge into the vault through Oh My Second Brain's folder/frontmatter contract.
+---
+
+# oms-capture
+
+Use MCP `oms_capture_prepare` before writing. Commit only with `oms_capture_commit` after the plan is `ready` or the user provides missing fields.
+
+Rules:
+
+1. Resolve concept from the user-owned ontology.
+2. Resolve folder from `vault/.oms/taxonomy.yaml`.
+3. Fill required frontmatter; preserve additional properties.
+4. Route ambiguity to inbox.
+5. Keep writes inside the vault and Markdown-only.

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

@@ -0,0 +1,14 @@
+---
+name: oms-doctor
+description: Validate vault notes against the active Oh My Second Brain ontology.
+---
+
+# oms-doctor
+
+Run:
+
+```bash
+npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz 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

@@ -0,0 +1,19 @@
+---
+name: oms-install
+description: Install Oh My Second Brain Codex/Hermes/Claude host adapters and MCP registration.
+---
+
+# oms-install
+
+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
+```
+
+For Codex, this installs:
+
+- `~/.codex/rules/oms.md`
+- `~/.codex/skills/oms-*`
+- `~/.codex/plugins/oms`
+- managed `[mcp_servers.oms]` in `~/.codex/config.toml`

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

@@ -0,0 +1,10 @@
+---
+name: oms-retrieve
+description: Retrieve vault knowledge axis-first using folders, frontmatter, wikilinks, and declared lenses.
+---
+
+# 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.
+
+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

@@ -0,0 +1,22 @@
+---
+name: oms-setup
+description: Adopt an Obsidian markdown vault into the Oh My Second Brain convention and optionally install host MCP integration.
+---
+
+# oms-setup
+
+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
+```
+
+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
+```
+
+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

@@ -0,0 +1,20 @@
+---
+name: oms-uninstall
+description: Remove Oh My Second Brain host adapter files and MCP registration without deleting vault notes or vault ontology.
+---
+
+# oms-uninstall
+
+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
+```
+
+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
+```
+
+Never delete vault notes or `vault/.oms/` as part of host uninstall.

package/adapters/hermes/README.md

@@ -0,0 +1,8 @@
+# Oh My Second Brain Hermes Adapter
+
+Installed by `oms install --runtime hermes` into:
+
+- `~/.hermes/skills/knowledge-management/oms/`
+- `~/.hermes/config.yaml` as `mcp_servers.oms`
+
+The skill bundle mirrors Oh My Second Brain's capture/retrieve/setup/doctor lifecycle and uses the Oh My Second Brain MCP server for runtime operations.