oh-my-second-brain 0.1.5

package/adapters/hermes/SOUL.md

@@ -0,0 +1,19 @@
+# Oh My Second Brain Convention Shim — Hermes
+
+<!-- Add this as a context file in your Hermes session to activate Oh My Second Brain conventions. -->
+
+## 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` 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`.
+
+**Retrieve:** Follow the retriever persona — identify purpose, match lens, project lens fields only.
+
+> **v0 native install:** `oms install --runtime hermes` installs a Hermes skill bundle and registers Oh My Second Brain MCP in `~/.hermes/config.yaml`. Use Oh My Second Brain MCP tools for capture/retrieve and CLI commands for lifecycle.

package/adapters/hermes/manifest.json

@@ -0,0 +1,7 @@
+{
+  "name": "oms",
+  "version": "0.1.5",
+  "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/capture/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: 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/hermes/skills/doctor/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: 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/hermes/skills/install/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: 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/hermes/skills/retrieve/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: 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/hermes/skills/setup/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: 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/hermes/skills/uninstall/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: 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/core/AGENTS.md

@@ -0,0 +1,110 @@
+# Oh My Second Brain Vault Convention — SSOT for Host Agents
+
+This file is the authoritative reference a host agent (Claude Code, Codex, Hermes, or any
+other) reads when working inside a vault managed by Oh My Second Brain. It explains the convention model so
+the agent understands *why* knowledge is organized the way it is — not just *where*.
+
+---
+
+## What is a Convention?
+
+An Oh My Second Brain **convention** is declarative semantic data the **user owns**. It lives in
+`vault/.oms/` (copied there by `oms setup`; Oh My Second Brain ships the defaults in `core/ontology/`).
+The user edits it freely. Oh My Second Brain enforces whatever is declared — it does not impose structure.
+
+The convention has four building blocks:
+
+---
+
+## 1. Concept
+
+A **concept** is a note-type. Each concept carries:
+
+| Field    | Purpose |
+|----------|---------|
+| `concept` | Identifier (e.g. `literature`). |
+| `intent`  | One sentence: *what this knowledge is FOR.* |
+| `folder`  | The vault folder where notes of this type live. |
+| `fields`  | List of frontmatter keys the concept declares. |
+| `lenses`  | Named retrieval views (optional). |
+
+> "The folder itself is information — every folder declares its intent."
+> Rather than pattern-matching a directory listing, a host agent reads the declared `intent`
+> to understand *why* knowledge lives in a given folder.
+
+---
+
+## 2. Field
+
+A **field** is one frontmatter key — the smallest unit of convention. Each field declares:
+
+| Property   | Meaning |
+|------------|---------|
+| `name`     | The frontmatter key (kebab-case, e.g. `source-url`). |
+| `type`     | One of `string`, `url`, `date`, `list`, `number`, `boolean`. |
+| `required` | Whether the key must be present and non-empty. |
+| `intent`   | Semantic purpose: *what this field is FOR.* |
+| `normalize` | Optional: `kebab`, `lower`, or `trim` — applied at validation. |
+| `immutable` | Advisory: once written, should not change (v0: no-op, forward-compat). |
+
+Users grow their convention field-by-field. There is no mandatory field list.
+
+---
+
+## 3. Lens
+
+A **lens** is a pre-declared, named retrieval view. It is NOT a query filter — it is a
+concept's declaration of which fields matter for a specific retrieval purpose.
+
+Example: a `synthesis` lens on `literature` surfaces `title` and `source-url`, because those
+are the fields needed when synthesizing across references. A host agent uses the active lens
+to know which frontmatter to surface during retrieval.
+
+---
+
+## 4. Taxonomy
+
+The **taxonomy** binds folders to concepts and gives each folder a declared `intent`.
+
+```yaml
+version: 1
+folders:
+  references:
+    intent: "Processed external sources the user has read and synthesized."
+    concept: literature
+  inbox:
+    intent: "Unprocessed captures awaiting triage."
+    concept: inbox
+```
+
+A folder may bind to one concept, multiple concepts (list), or `null` (not yet assigned).
+
+---
+
+## Enforcement Posture
+
+| Setting | Value | Meaning |
+|---------|-------|---------|
+| `onViolation` | `warn` | Violations are logged but never block writes (v0 is non-blocking). |
+| `additionalProperties` | `preserve` | Frontmatter keys not declared in the concept are left untouched. |
+
+Oh My Second Brain enforces what the user declared; it does not touch anything else.
+
+---
+
+## User Ownership
+
+1. `oms setup` scans the vault's existing top-level folders and creates `vault/.oms/`.
+2. It copies shipped default concepts into `vault/.oms/concepts/` and writes
+   `vault/.oms/taxonomy.yaml` — seeded with the user's real folders.
+3. The user fills in `intent` values and adds or removes fields/lenses freely.
+4. Oh My Second Brain never imposes a folder structure; it adopts what already exists.
+
+---
+
+## Quick Reference for Host Agents
+
+- To understand a note: look up its folder in the taxonomy → read the `concept.intent`.
+- To validate frontmatter: load the concept's `fields`; check `required` + `type`.
+- To retrieve knowledge: apply the relevant `lens` to surface the fields that matter.
+- When in doubt, preserve: `additionalProperties: preserve` means unknown keys are safe.

package/core/agents/librarian.md

@@ -0,0 +1,43 @@
+---
+name: librarian
+description: Places incoming knowledge correctly in the vault, filling frontmatter per the declared concept.
+---
+
+# Agent Persona: Librarian
+
+The librarian places knowledge into the vault with precision.
+Every note lands in the right folder, carries the right frontmatter, and respects the declared convention.
+
+## Governing principle
+
+> "A note without declared intent is noise. A note with correct frontmatter is a first-class citizen."
+
+The librarian never improvises a folder or invents a field.
+It reads the convention first, then acts.
+
+## Responsibilities
+
+1. **Concept identification** — match incoming knowledge to a declared concept (`literature`, `inbox`, etc.) by comparing content and purpose against each concept's `intent`.
+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.
+
+## Decision rules
+
+| Situation | Action |
+|-----------|--------|
+| Concept is ambiguous | Default to `inbox` and note ambiguity in a `status: needs-review` field |
+| Required field value is unknown | Use a sentinel `"UNKNOWN"` string and flag it; never omit the key |
+| Folder does not exist in taxonomy | Capture to `inbox/`; surface the missing taxonomy entry to the user |
+| User provides extra context fields | Preserve them (`additionalProperties: preserve`) |
+
+## Interaction style
+
+- Ask only for information that is truly missing for required fields.
+- Propose the target folder and concept before writing — let the user confirm once.
+- After writing, show the frontmatter block so the user can see what was committed.
+
+## Skill
+
+Invoke via the `capture` skill: `core/skills/capture/SKILL.md`.

package/core/agents/retriever.md

@@ -0,0 +1,62 @@
+---
+name: retriever
+description: Surfaces the right knowledge fields from the vault for a declared retrieval purpose using lenses.
+---
+
+# Agent Persona: Retriever
+
+The retriever surfaces knowledge through the vault's declared lenses (인출).
+It never dumps raw notes — it filters to the fields that matter for the stated purpose.
+
+## Governing principle
+
+> "Retrieval is not search. It is projection: show exactly the fields this purpose requires, nothing more."
+
+The retriever reads lens declarations first, then scans notes,
+then returns only the lens-selected fields.
+
+## Responsibilities
+
+1. **Purpose identification** — clarify the user's retrieval goal (synthesize, audit, plan, review, etc.).
+2. **Lens matching** — find the declared lens on the relevant concept whose `intent` best matches the purpose.
+3. **Field projection** — for each matching note, return only the fields listed in the lens; discard the rest.
+4. **Grouping** — present results grouped by concept/folder for orientation.
+5. **Citation** — always include `source-url` (or equivalent) when the concept carries it, even if the lens does not explicitly list it.
+
+## Lens resolution algorithm
+
+```
+1. Parse user purpose → keyword(s)
+2. For each concept in vault/.oms/concepts/*.yaml:
+     for each lens in concept.lenses:
+       score = semantic_overlap(purpose, lens.intent)
+3. Select lens with highest score
+4. Collect all notes in concept's folder
+5. Project each note's frontmatter to lens.fields
+6. Return projected results
+```
+
+In v0, step 2 is agent judgment (no runtime engine). The retriever reads the YAML manually.
+
+## Output format
+
+```markdown
+## [Concept: literature] — Lens: synthesis
+
+| title | thesis | source-url |
+|-------|--------|------------|
+| Attention Is All You Need | Self-attention replaces recurrence | https://arxiv.org/abs/1706.03762 |
+```
+
+## Decision rules
+
+| Situation | Action |
+|-----------|--------|
+| No matching lens | Fall back to all `required: true` fields |
+| Note missing a lens field | Show `—` for that cell; do not skip the note |
+| Multiple concepts match purpose | Return results from all matching concepts, grouped |
+| No notes in concept folder | Report "0 notes found under `<folder>/`" |
+
+## Skill
+
+Invoke via the `retrieve` skill: `core/skills/retrieve/SKILL.md`.

package/core/ontology/concepts/inbox.yaml

@@ -0,0 +1,4 @@
+concept: inbox
+intent: "Unprocessed capture awaiting triage; no required structure yet."
+folder: inbox
+fields: []

package/core/ontology/concepts/literature.yaml

@@ -0,0 +1,27 @@
+concept: literature
+intent: "A processed reference: an external source the user has read and synthesized."
+folder: references
+fields:
+  - name: title
+    type: string
+    required: true
+    intent: "The title of the referenced work."
+  - name: source-url
+    type: url
+    required: true
+    intent: "The canonical URL where the source can be found."
+  - name: author
+    type: list
+    required: false
+    intent: "One or more authors of the referenced work."
+  - name: tags
+    type: list
+    required: false
+    intent: "Topical tags for retrieval and clustering."
+    normalize: kebab
+lenses:
+  - name: synthesis
+    intent: "Surface the minimal fields needed when synthesizing across references."
+    fields:
+      - title
+      - source-url

package/core/ontology/taxonomy.yaml

@@ -0,0 +1,11 @@
+version: 1
+folders:
+  references:
+    intent: "Processed external sources the user has read and synthesized."
+    concept: literature
+  notes:
+    intent: "Unprocessed or loosely structured notes awaiting triage or development."
+    concept: inbox
+  inbox:
+    intent: "Raw unprocessed captures awaiting triage; nothing required yet."
+    concept: inbox

package/core/skills/capture/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: capture
+description: Capture knowledge into the vault under the declared Oh My Second Brain convention.
+---
+
+# Skill: capture
+
+Place a piece of knowledge into the vault according to the Oh My Second Brain convention.
+The librarian persona governs this action.
+
+## What this skill does
+
+1. Determine the **concept** that best fits the incoming knowledge (literature, inbox, note, etc.).
+2. Resolve the **target folder** from `vault/.oms/taxonomy.yaml` — the folder whose declared `intent` matches this knowledge type.
+3. Generate a filename that follows the concept's naming rules (default: `YYYY-MM-DD-<slugified-title>.md`).
+4. Construct frontmatter from the concept's declared fields:
+   - Fill every `required: true` field.
+   - 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.
+
+## Conceptual shell-out (roadmap — NOT wired in v0)
+
+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.
+
+## Example agent steps
+
+```
+User: "Save this paper: 'Attention Is All You Need', arxiv.org/abs/1706.03762"
+
+1. concept = literature  (matches folder: references/)
+2. folder  = vault/references/
+3. file    = vault/references/2017-06-12-attention-is-all-you-need.md
+4. frontmatter:
+     title: "Attention Is All You Need"
+     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)
+```
+
+## Persona
+
+Use the **librarian** agent persona for this skill (`core/agents/librarian.md`).

package/core/skills/define/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: define
+description: Grow the vault convention by adding or editing a metadata field on a concept.
+---
+
+# Skill: define
+
+Extend your Oh My Second Brain convention field-by-field.
+Each frontmatter key is a **unit of convention**: it carries a declared `intent`,
+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
+```
+
+This is the intended user-facing command (roadmap: interactive runtime not built yet).
+In v0, `setup` and `doctor` are the REAL CLI commands today.
+Use `define` as **agent-guided convention editing** until the interactive runtime ships.
+
+## What this skill does (agent-guided, v0)
+
+1. Ask the user: which **concept** are they extending? (e.g. `literature`, `inbox`)
+2. Ask: what is the new **field name**? (snake-case, e.g. `thesis`)
+3. Ask: what is this field's **intent** — why does this knowledge live here?
+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).
+
+## Convention YAML shape (one field entry)
+
+```yaml
+fields:
+  - name: thesis
+    type: string
+    required: false
+    intent: "The central claim this source makes"
+```
+
+## Growing lenses
+
+After adding a field, consider whether it belongs in an existing lens (`synthesis`, `audit`)
+or warrants a new lens. Edit the `lenses:` block in the same concept YAML.
+
+## Where the convention lives
+
+All convention data is **user-owned** at `vault/.oms/`:
+```
+vault/.oms/
+  concepts/
+    literature.yaml
+    inbox.yaml
+  taxonomy.yaml
+```
+
+Oh My Second Brain ships defaults (from `core/ontology/`); `oms setup` copies them into the vault.
+The user then edits them at will — Oh My Second Brain only enforces, never overwrites.

package/core/skills/doctor/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: doctor
+description: Validate vault notes against the Oh My Second Brain convention and report violations (REAL today).
+---
+
+# Skill: doctor
+
+Check every note in your vault against its declared concept schema.
+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>]
+```
+
+- `--vault <path>` — path to your Obsidian vault root (default: current directory).
+- Always **exits 0** in v0 (non-blocking; `onViolation: warn`).
+
+## What the command does
+
+1. Loads `vault/.oms/` and `vault/.oms/taxonomy.yaml`.
+2. Walks every `.md` note in the vault.
+3. For each note, resolves its **concept** from the taxonomy folder binding.
+4. Calls `validateFrontmatter(frontmatter, concept)` and collects `Violation[]`.
+5. Prints a per-note summary of violations (field, rule, message).
+6. Prints total counts: notes checked, violations found.
+7. Exits 0 regardless of violation count (v0 is advisory only).
+
+## Violation rules
+
+| Rule | Description |
+|------|-------------|
+| `required` | A field declared `required: true` is missing from the note's frontmatter |
+| `type` | The field value does not match the declared type |
+| `immutable` | Field changed after initial set — **suppressed in v0** (no baseline available) |
+
+Undeclared frontmatter fields are **never** reported as violations
+(`additionalProperties: preserve`).
+
+## Recommended usage
+
+Run `npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor` after:
+- Any `oms setup` run
+- Adding a new field via `oms define`
+- Bulk-editing notes
+
+Integrate into CI by adding `npx oms doctor --vault ./vault` to your workflow.
+It will never fail the build in v0.

package/core/skills/retrieve/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: retrieve
+description: Retrieve knowledge from the vault through declared Oh My Second Brain lenses (인출).
+---
+
+# Skill: retrieve
+
+Surface the right notes and fields for a given purpose using the vault's
+declared retrieval lenses.
+
+## What this skill does
+
+1. Identify the **retrieval purpose** from the user's request (e.g. "synthesize this topic", "audit my sources").
+2. Match the purpose to a declared **lens** (e.g. `synthesis`, `audit`) on the relevant concept.
+3. For each matching note, return only the fields listed in that lens — not all frontmatter.
+4. Present results grouped by concept/folder with lens-filtered frontmatter.
+
+## Lenses (인출 뷰)
+
+A lens is a pre-declared named retrieval view, not a query filter.
+Each concept declares which fields matter for which purpose:
+
+```yaml
+lenses:
+  - name: synthesis
+    intent: "Surface what was argued and where to find it"
+    fields: [title, thesis, source-url]
+  - name: audit
+    intent: "Check provenance and capture date"
+    fields: [title, source-url, captured-at]
+```
+
+The retrieval skill reads these declarations from `vault/.oms/concepts/*.yaml`.
+
+## Conceptual shell-out (roadmap — NOT wired in v0)
+
+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.
+
+## Example agent steps
+
+```
+User: "Synthesize my literature notes on transformers"
+
+1. purpose  = synthesis
+2. concept  = literature  →  lens = synthesis  →  fields = [title, thesis, source-url]
+3. scan     = vault/references/*.md
+4. for each note: extract only those three frontmatter fields
+5. return a grouped summary with citations
+```
+
+## Persona
+
+Use the **retriever** agent persona for this skill (`core/agents/retriever.md`).

package/core/skills/setup/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: setup
+description: Adopt an existing Obsidian vault into the Oh My Second Brain convention (REAL today).
+---
+
+# Skill: setup
+
+Adopt your existing vault into the Oh My Second Brain convention.
+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]
+```
+
+- `--vault <path>` — path to your Obsidian vault root (default: current directory).
+- `--yes` / `OMS_NON_INTERACTIVE=1` — bypass all prompts and accept defaults (for CI / non-TTY).
+
+## What the command does
+
+1. Resolves the vault root (from `--vault` or `cwd`).
+2. Scans existing **top-level folders** in the vault (does NOT impose a structure).
+3. For each folder, asks its `intent` (why this knowledge lives here), pre-filling a humanized default.
+4. Asks which shipped concept binds to this folder (`literature`, `inbox`, or none).
+5. Writes `vault/.oms/taxonomy.yaml` (with `version: 0`).
+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.
+
+## What setup does NOT do
+
+- Does NOT rename, move, or delete any existing notes.
+- Does NOT impose a new folder structure.
+- Does NOT modify existing frontmatter.
+
+## After setup
+
+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>]
+```