oh-my-second-brain 0.1.5

package/dist/ontology/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Oh My Second Brain convention format — the semantic ontology, adapted from ouroboros.
+ *
+ * A vault's convention is declarative data the user owns (lives in `vault/.oms/`).
+ * Oh My Second Brain ships defaults in `core/ontology/` and enforces whatever the user declares.
+ *
+ * The format is deliberately semantic, not structural: every concept and folder
+ * carries a declared `intent` so a host agent reads *why* knowledge lives somewhere,
+ * not just *where*. "The folder itself is information."
+ */
+/** Supported scalar/collection kinds for a frontmatter field. */
+export type FieldType = "string" | "url" | "date" | "list" | "number" | "boolean";
+/** Optional normalization applied to a field value before/at validation. */
+export type Normalize = "kebab" | "lower" | "trim";
+/**
+ * One frontmatter key, modeled on ouroboros's `OntologyField`.
+ * Each field is itself a unit of convention — users grow a convention field-by-field.
+ */
+export interface OntologyField {
+    /** The frontmatter key name. */
+    name: string;
+    /** Value kind. */
+    type: FieldType;
+    /** Whether the key must be present and non-empty. Defaults to false. */
+    required?: boolean;
+    /** Semantic intent: what this field is FOR (ouroboros `description`). */
+    intent: string;
+    /** Optional value normalization for list/string fields. */
+    normalize?: Normalize;
+    /** If true, the field must not change once written (advisory in v0). */
+    immutable?: boolean;
+}
+/**
+ * A pre-declared, named retrieval view — NOT a query filter.
+ * Mirrors ouroboros's `OntologyLens`: a concept declares which fields matter
+ * for which retrieval purpose (e.g. `synthesis`, `audit`).
+ */
+export interface OntologyLens {
+    name: string;
+    /** When this lens should be activated during retrieval. */
+    intent: string;
+    /** Subset of the concept's field names surfaced by this lens. */
+    fields: string[];
+}
+/** A note-type carrying explicit intent, its fields, lenses, and folder binding. */
+export interface Concept {
+    /** Concept identifier (e.g. `literature`). */
+    concept: string;
+    /** What this knowledge is FOR. */
+    intent: string;
+    /** Folder this concept is bound to (relative to vault root). */
+    folder: string;
+    fields: OntologyField[];
+    lenses?: OntologyLens[];
+}
+/** Per-folder declaration: a folder is information, so it declares its intent. */
+export interface FolderBinding {
+    /** Why this folder exists / what kind of knowledge it holds. */
+    intent: string;
+    /** Concept name(s) bound here, or null when not yet assigned (e.g. `inbox`). */
+    concept: string | string[] | null;
+}
+/** Folder ↔ concept map with per-folder intent. */
+export interface Taxonomy {
+    version: number;
+    folders: Record<string, FolderBinding>;
+}
+/** A fully loaded convention: the taxonomy plus every concept, keyed by name. */
+export interface Ontology {
+    taxonomy: Taxonomy;
+    concepts: Map<string, Concept>;
+}

package/dist/ontology/types.js

@@ -0,0 +1,12 @@
+/**
+ * Oh My Second Brain convention format — the semantic ontology, adapted from ouroboros.
+ *
+ * A vault's convention is declarative data the user owns (lives in `vault/.oms/`).
+ * Oh My Second Brain ships defaults in `core/ontology/` and enforces whatever the user declares.
+ *
+ * The format is deliberately semantic, not structural: every concept and folder
+ * carries a declared `intent` so a host agent reads *why* knowledge lives somewhere,
+ * not just *where*. "The folder itself is information."
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/ontology/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/ontology/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/docs/install.md

@@ -0,0 +1,115 @@
+# 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 all install an `oms` host surface for Oh My Second Brain backed by the same MCP capture/retrieve runtime.
+
+## Prerequisites
+
+- Node.js 18 or newer.
+- `npm` on `PATH`.
+- An Obsidian vault, or any folder of Markdown notes.
+- Optional host CLIs: `claude`, `codex`, `hermes`.
+
+## One-line install
+
+Until npm publishing is unblocked, the installer installs the GitHub release tarball asset by default:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/GoBeromsu/oms/main/scripts/install.sh | bash
+```
+
+Useful overrides:
+
+```bash
+# Pick one host instead of auto-detection.
+curl -fsSL https://raw.githubusercontent.com/GoBeromsu/oms/main/scripts/install.sh | bash -s -- --runtime claude
+
+# Install every host adapter and point Oh My Second Brain at a specific vault.
+curl -fsSL https://raw.githubusercontent.com/GoBeromsu/oms/main/scripts/install.sh | bash -s -- --runtime all --vault /path/to/vault
+
+# Also execute external host CLIs where available, e.g. claude plugin/mcp commands.
+curl -fsSL https://raw.githubusercontent.com/GoBeromsu/oms/main/scripts/install.sh | bash -s -- --runtime all --vault /path/to/vault --execute
+```
+
+Environment knobs:
+
+| Variable | Meaning |
+| --- | --- |
+| `OMS_PACKAGE_SPEC` | npm package spec or tarball URL to install globally |
+| `OMS_INSTALL_RUNTIME` | `auto`, `all`, `claude`, `codex`, or `hermes` |
+| `OMS_VAULT` | vault path used for MCP registration |
+| `OMS_EXECUTE_EXTERNAL=1` | allow host CLI commands such as `claude plugin install` |
+
+## CLI install
+
+From a checkout or installed package:
+
+```bash
+npm ci
+npm run build
+npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install --runtime all --vault /path/to/vault --dry-run
+npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz install --runtime all --vault /path/to/vault --yes
+```
+
+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.
+
+## What install writes
+
+| Host | Install behavior |
+| --- | --- |
+| Claude Code | Upserts `~/.claude/mcp.json` entry for `oms`; prints Claude plugin/MCP commands; with `--execute`, runs `claude plugin install` and `claude mcp add` when the CLI is available. |
+| 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`. |
+| Hermes | Installs `~/.hermes/skills/knowledge-management/oms/`, copies adapter files to `~/.hermes/adapters/oms`, and writes `mcp_servers.oms` in `~/.hermes/config.yaml`. |
+
+All host writes are namespaced under `oms` and are reversible with `oms uninstall`.
+
+## Legacy setup flow
+
+`setup` still adopts a vault into the Oh My Second Brain ontology and can print the Claude Code plan:
+
+```bash
+npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz setup --vault /path/to/vault --yes --install-claude
+```
+
+Typical printed commands look like:
+
+```bash
+claude plugin install /path/to/oms/adapters/claude-code
+claude mcp add oms -- npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz mcp --vault /path/to/vault
+```
+
+## Uninstall
+
+Preview first:
+
+```bash
+oms uninstall --runtime all --dry-run
+```
+
+Remove host registrations and adapter files:
+
+```bash
+oms uninstall --runtime all --yes
+```
+
+One-line uninstall:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/GoBeromsu/oms/main/scripts/uninstall.sh | bash -s -- --yes
+```
+
+The uninstaller removes Oh My Second Brain host registrations and adapter files. It does **not** remove vault notes or `vault/.oms/` ontology data. Pass `--keep-package` to the shell uninstaller if you want to keep the globally installed package.
+
+## Verify the install
+
+```bash
+npx -y https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz doctor --vault /path/to/vault
+oms install --runtime all --vault /path/to/vault --dry-run
+claude plugin validate adapters/claude-code
+```
+
+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, axis retrieval, lazy note loading, contract validation, and gated capture tools.

package/docs/release.md

@@ -0,0 +1,91 @@
+# Release Oh My Second Brain
+
+Oh My Second Brain releases are npm-first and Claude Code validated. The release process must prove the published tarball works, not merely the repository checkout.
+
+## Release contract
+
+The npm package root is the runtime asset root. A releasable tarball must include:
+
+- `dist/cli/oms.js`
+- `dist/mcp/server.js`
+- `core/ontology/taxonomy.yaml`
+- `core/ontology/concepts/`
+- `adapters/claude-code/.claude-plugin/plugin.json`
+- every Claude adapter `skills/*/SKILL.md`
+- `docs/install.md`
+- `docs/release.md`
+- `scripts/install.sh`
+- `scripts/uninstall.sh`
+
+Codex and Hermes adapter files are packaged as host-native skill/rule bundles plus MCP registrations; release notes must describe the exact installed paths and avoid claiming behavior beyond the shipped skills and MCP tools.
+
+## Local release gate
+
+Run this before tagging or publishing:
+
+```bash
+npm run release:check
+```
+
+`release:check` runs:
+
+1. `npm run lint`
+2. `npm run build`
+3. `npm test`
+4. `npm run audit`
+5. `npm run release:pack`
+6. `npm run release:artifact-smoke`
+7. `npm run release:plugin`
+
+`release:pack` inspects `npm pack --dry-run --json` and fails if required runtime assets are missing. `release:artifact-smoke` creates a real tarball, unpacks it into a temp directory, installs production dependencies there, and runs setup, host install dry-run, and MCP smoke from the extracted package root.
+
+## Claude plugin validation
+
+Preferred validation:
+
+```bash
+claude plugin validate adapters/claude-code
+```
+
+If a release environment cannot run the Claude CLI, publishing is blocked unless an explicit validation attestation is provided through `OMS_PLUGIN_VALIDATION_ATTESTATION`.
+
+Required attestation fields:
+
+```json
+{
+  "actor": "person-or-bot",
+  "timestamp": "2026-06-02T00:00:00Z",
+  "command": "claude plugin validate adapters/claude-code",
+  "pluginPath": "adapters/claude-code",
+  "claudeVersion": "optional version string",
+  "exitCode": 0,
+  "warnings": ["optional warning text"],
+  "artifact": "optional log path or URL"
+}
+```
+
+## GitHub release workflow
+
+The v0 release workflow is **manual dispatch only** so the operator must provide the Claude plugin validation attestation explicitly when the GitHub runner cannot run Claude Code itself. It is credential-gated and uses npm provenance:
+
+- It runs only through `workflow_dispatch`.
+- It requires `plugin_validation_attestation` input.
+- It runs the full release gate before publish.
+- It requires `NPM_TOKEN`.
+- It requires `id-token: write` for provenance.
+- It refuses to publish `0.0.0`; bump to a real semver first.
+- It runs `npm publish --provenance --access public` only in the publish job.
+- It blocks publish if Claude plugin validation was skipped without attestation.
+
+## Version and package-name preflight
+
+Before the first public release:
+
+1. Verify that the scoped `oms` npm package name is available to the publisher.
+2. Bump `package.json` to a real semver release.
+3. Keep `adapters/claude-code/.claude-plugin/plugin.json` version in sync with `package.json` unless a future ADR deliberately splits package/plugin versioning.
+4. Confirm release notes list Codex rules/skills and Hermes skill-bundle install paths, plus the MCP registration files that make capture/retrieve tools available.
+
+## Rollback posture
+
+Do not rely on npm unpublish as a normal rollback path. Prefer publishing a fixed patch release and documenting any broken version in release notes.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "oh-my-second-brain",
+  "version": "0.1.5",
+  "description": "Oh My Second Brain: a host-agnostic, user-owned convention layer for Obsidian and plain-markdown knowledge vaults.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "oms": "dist/cli/oms.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "core",
+    "adapters",
+    "docs/install.md",
+    "docs/release.md",
+    "scripts/install.sh",
+    "scripts/uninstall.sh"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "audit": "npm audit --omit=dev",
+    "release:pack": "node scripts/release-pack.mjs",
+    "release:setup-smoke": "node scripts/release-artifact-smoke.mjs --setup-only",
+    "release:mcp-smoke": "node scripts/release-artifact-smoke.mjs --mcp-only",
+    "release:artifact-smoke": "node scripts/release-artifact-smoke.mjs",
+    "release:plugin": "node scripts/release-plugin.mjs",
+    "release:check": "npm run lint && npm run build && npm test && npm run audit && npm run release:pack && npm run release:artifact-smoke && npm run release:plugin"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GoBeromsu/oms.git"
+  },
+  "homepage": "https://github.com/GoBeromsu/oms#readme",
+  "bugs": {
+    "url": "https://github.com/GoBeromsu/oms/issues"
+  },
+  "keywords": [
+    "obsidian",
+    "knowledge-base",
+    "mcp",
+    "frontmatter",
+    "markdown",
+    "claude-code"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/install.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Oh My Second Brain installer — installs the package and registers host adapters.
+# Usage: curl -fsSL https://raw.githubusercontent.com/GoBeromsu/oms/main/scripts/install.sh | bash
+set -euo pipefail
+
+PACKAGE_SPEC="${OMS_PACKAGE_SPEC:-https://github.com/GoBeromsu/oms/releases/download/oms-v0.1.5/oms-0.1.5.tgz}"
+RUNTIME="${OMS_INSTALL_RUNTIME:-auto}"
+VAULT="${OMS_VAULT:-$PWD}"
+EXECUTE="${OMS_EXECUTE_EXTERNAL:-0}"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --runtime) RUNTIME="${2:-}"; shift 2 ;;
+    --runtime=*) RUNTIME="${1#--runtime=}"; shift ;;
+    --vault) VAULT="${2:-}"; shift 2 ;;
+    --vault=*) VAULT="${1#--vault=}"; shift ;;
+    --package) PACKAGE_SPEC="${2:-}"; shift 2 ;;
+    --package=*) PACKAGE_SPEC="${1#--package=}"; shift ;;
+    --execute) EXECUTE=1; shift ;;
+    *) shift ;;
+  esac
+done
+
+if ! command -v npm >/dev/null 2>&1; then
+  echo "Error: npm is required to install Oh My Second Brain." >&2
+  exit 1
+fi
+
+echo "Oh My Second Brain Installer"
+echo "  package: $PACKAGE_SPEC"
+echo "  runtime: $RUNTIME"
+echo "  vault:   $VAULT"
+echo
+
+npm install -g "$PACKAGE_SPEC"
+
+ARGS=(install --runtime "$RUNTIME" --vault "$VAULT" --yes)
+if [ "$EXECUTE" = "1" ]; then
+  ARGS+=(--execute)
+fi
+
+if command -v oms >/dev/null 2>&1; then
+  oms "${ARGS[@]}"
+else
+  oms "${ARGS[@]}"
+fi
+
+echo
+echo "Oh My Second Brain install complete. Run: oms doctor --vault \"$VAULT\""

package/scripts/uninstall.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Oh My Second Brain uninstaller — removes host adapter registrations and optionally the package.
+# Usage: curl -fsSL https://raw.githubusercontent.com/GoBeromsu/oms/main/scripts/uninstall.sh | bash
+set -euo pipefail
+
+RUNTIME="${OMS_UNINSTALL_RUNTIME:-all}"
+VAULT="${OMS_VAULT:-$PWD}"
+REMOVE_PACKAGE="${OMS_REMOVE_PACKAGE:-1}"
+EXECUTE="${OMS_EXECUTE_EXTERNAL:-0}"
+YES="${OMS_UNINSTALL_CONFIRM:-0}"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --runtime) RUNTIME="${2:-}"; shift 2 ;;
+    --runtime=*) RUNTIME="${1#--runtime=}"; shift ;;
+    --vault) VAULT="${2:-}"; shift 2 ;;
+    --vault=*) VAULT="${1#--vault=}"; shift ;;
+    --keep-package) REMOVE_PACKAGE=0; shift ;;
+    --execute) EXECUTE=1; shift ;;
+    -y|--yes) YES=1; shift ;;
+    *) shift ;;
+  esac
+done
+
+if [ "$YES" != "1" ]; then
+  if [ -t 0 ]; then
+    printf 'Remove Oh My Second Brain host registrations for runtime=%s? (y/N) ' "$RUNTIME"
+    read -r REPLY
+  elif [ -c /dev/tty ]; then
+    printf 'Remove Oh My Second Brain host registrations for runtime=%s? (y/N) ' "$RUNTIME" >&2
+    read -r REPLY < /dev/tty
+  else
+    echo "Non-interactive uninstall requires --yes or OMS_UNINSTALL_CONFIRM=1." >&2
+    exit 1
+  fi
+  case "$REPLY" in
+    y|Y|yes|YES) ;;
+    *) echo "Cancelled."; exit 0 ;;
+  esac
+fi
+
+ARGS=(uninstall --runtime "$RUNTIME" --vault "$VAULT" --yes)
+if [ "$EXECUTE" = "1" ]; then
+  ARGS+=(--execute)
+fi
+
+if command -v oms >/dev/null 2>&1; then
+  oms "${ARGS[@]}"
+else
+  echo "oms binary not found; skipping host deregistration." >&2
+fi
+
+if [ "$REMOVE_PACKAGE" = "1" ] && command -v npm >/dev/null 2>&1; then
+  npm uninstall -g oms || true
+fi
+
+echo "Oh My Second Brain uninstall complete. Vault content was not removed."