@skill-map/cli 0.16.5 → 0.17.0

package/dist/cli.js

@@ -660,129 +660,187 @@ var skill_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
   $id: "https://skill-map.dev/providers/claude/v1/frontmatter/skill.schema.json",
   title: "FrontmatterSkill",
-  description: "Frontmatter shape for nodes classified as `skill` by the Claude Provider. Extends the spec's universal `frontmatter/base.schema.json` via $ref-by-$id. Kind-specific fields: `inputs`, `outputs`. Stability: experimental \u2014 the parameter shape may tighten once summarizer needs emerge. Owned by the Claude Provider; relocated from `spec/schemas/frontmatter/` in spec 0.8.0 (Phase 3 of plug-in model overhaul).",
+  description: "Frontmatter shape for nodes classified as `skill` by the Claude Provider. Today identical to `command` \u2014 both extend the shared `skill-base.schema.json` per Anthropic's documented merger (https://code.claude.com/docs/en/skills.md \u2014 \"Custom commands have been merged into skills\"). The two are kept SPLIT (not aliased) because skill-map's registry differentiates them in `IProviderKind.ui` (separate label / icon / color) and `defaultRefreshAction`. Splitting also reserves room for future divergence when one kind diverges from the other. No skill-only fields today; `additionalProperties: true` so the file is ready for them.",
   allOf: [
-    { $ref: "https://skill-map.dev/spec/v0/frontmatter/base.schema.json" }
+    { $ref: "https://skill-map.dev/providers/claude/v1/frontmatter/skill-base.schema.json" }
   ],
   type: "object",
   additionalProperties: true,
-  properties: {
-    inputs: {
-      type: "array",
-      description: "Declared inputs for this skill. Optional structured. Stability: experimental.",
-      items: { $ref: "#/$defs/Parameter" }
-    },
-    outputs: {
-      type: "array",
-      description: "Declared outputs. Optional structured. Stability: experimental.",
-      items: { $ref: "#/$defs/Parameter" }
-    }
-  },
-  $defs: {
-    Parameter: {
-      type: "object",
-      required: ["name"],
-      additionalProperties: true,
-      properties: {
-        name: { type: "string", minLength: 1 },
-        type: { type: "string", description: "Free-form type hint (e.g. `string`, `integer`, `path`, `glob`)." },
-        description: { type: "string" },
-        required: { type: "boolean", default: false },
-        default: { description: "Any JSON value, or a templated string." }
-      }
-    }
-  }
+  properties: {}
 };
 
-// built-in-plugins/providers/claude/schemas/agent.schema.json
-var agent_schema_default = {
+// built-in-plugins/providers/claude/schemas/skill-base.schema.json
+var skill_base_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://skill-map.dev/providers/claude/v1/frontmatter/agent.schema.json",
-  title: "FrontmatterAgent",
-  description: "Frontmatter shape for nodes classified as `agent` by the Claude Provider. Extends the spec's universal `frontmatter/base.schema.json` via $ref-by-$id. Kind-specific field: `model`. The `tools` and `allowedTools` fields live on the spec base and apply here unchanged. Color, when needed, lives in `metadata.color` (inherited from base). Owned by the Claude Provider; relocated from `spec/schemas/frontmatter/` in spec 0.8.0 (Phase 3 of plug-in model overhaul).",
+  $id: "https://skill-map.dev/providers/claude/v1/frontmatter/skill-base.schema.json",
+  title: "FrontmatterSkillBase",
+  description: 'Shared frontmatter base for `skill` and `command` nodes per Anthropic\'s documented merger (https://code.claude.com/docs/en/skills.md \u2014 "Custom commands have been merged into skills"). Both kinds carry the same vendor frontmatter today; skill-map keeps them as distinct `IProviderKind`s in the registry (different UI presentation, different `defaultRefreshAction`) but extends the same base via `allOf` + `$ref` so the field catalog is single-sourced. Field naming is reproduced verbatim from Anthropic \u2014 a deliberate mix of kebab-case (`argument-hint`, `disable-model-invocation`, `user-invocable`, `allowed-tools`), snake_case (`when_to_use`), and camelCase. `additionalProperties: true` so future Anthropic additions flow through unchanged until this schema catches up.',
   allOf: [
     { $ref: "https://skill-map.dev/spec/v0/frontmatter/base.schema.json" }
   ],
   type: "object",
   additionalProperties: true,
   properties: {
+    when_to_use: {
+      type: "string",
+      description: "When the host SHOULD activate this skill / command. Appended to `description` for autocomplete; counts toward the 1,536-character description cap."
+    },
+    "argument-hint": {
+      type: "string",
+      description: "Autocomplete hint shown when the user types a leading `/`, e.g. `[issue-number]`."
+    },
+    arguments: {
+      oneOf: [
+        { type: "string" },
+        { type: "array", items: { type: "string" } }
+      ],
+      description: "Named positional arguments for `$name` substitution in the skill body. String form for one argument, array for several."
+    },
+    "disable-model-invocation": {
+      type: "boolean",
+      description: "When true, the model cannot invoke this skill autonomously \u2014 only the user can trigger it via the `/` menu."
+    },
+    "user-invocable": {
+      type: "boolean",
+      description: "When false, this skill is hidden from the user's `/` menu (still invocable by the model unless `disable-model-invocation` is also set)."
+    },
+    "allowed-tools": {
+      oneOf: [
+        { type: "string" },
+        { type: "array", items: { type: "string" } }
+      ],
+      description: "Tools pre-approved for this skill (no per-use permission prompt). Argument-scoped patterns supported (`Bash(git add *)`)."
+    },
     model: {
       type: "string",
-      description: "Model identifier for this agent (e.g. `sonnet`, `opus`, `haiku`, or a full `claude-*` id). Free-form string; Providers MAY validate against a platform-specific enum."
+      description: "Model alias (`sonnet`, `opus`, `haiku`), full Claude id, or the literal `inherit` to defer to the parent session's model."
+    },
+    effort: {
+      type: "string",
+      enum: ["low", "medium", "high", "xhigh", "max"],
+      description: "Effort budget for reasoning. Higher levels allocate more thinking time."
+    },
+    context: {
+      type: "string",
+      enum: ["fork"],
+      description: "Execution context. `fork` is the only documented value today (runs the skill in a subagent so the main session's context is preserved)."
+    },
+    agent: {
+      type: "string",
+      description: "Subagent type when `context: fork`. Built-ins include `Explore`, `Plan`, `general-purpose`; custom agent types resolve against the host's agent registry."
+    },
+    hooks: {
+      type: "object",
+      description: "Lifecycle hooks declared inline on this skill / command. Shape is platform-defined; preserved as an opaque object. `once: true` is honored ONLY here (not at the agent level). Note: Anthropic's `hooks` is NOT a separate node kind \u2014 it lives here, as a sub-object of skill frontmatter, or in `settings.json` (see https://code.claude.com/docs/en/hooks.md)."
+    },
+    paths: {
+      oneOf: [
+        { type: "string" },
+        { type: "array", items: { type: "string" } }
+      ],
+      description: "Glob patterns limiting auto-activation. The skill auto-activates only when the user is editing files matching one of these globs."
+    },
+    shell: {
+      type: "string",
+      enum: ["bash", "powershell"],
+      description: "Shell flavor for any embedded shell snippets. Default: `bash`."
     }
   }
 };
 
-// built-in-plugins/providers/claude/schemas/command.schema.json
-var command_schema_default = {
+// built-in-plugins/providers/claude/schemas/agent.schema.json
+var agent_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://skill-map.dev/providers/claude/v1/frontmatter/command.schema.json",
-  title: "FrontmatterCommand",
-  description: "Frontmatter shape for nodes classified as `command` by the Claude Provider. Extends the spec's universal `frontmatter/base.schema.json` via $ref-by-$id. Kind-specific fields: `args`, `shortcut`. Owned by the Claude Provider; relocated from `spec/schemas/frontmatter/` in spec 0.8.0 (Phase 3 of plug-in model overhaul).",
+  $id: "https://skill-map.dev/providers/claude/v1/frontmatter/agent.schema.json",
+  title: "FrontmatterAgent",
+  description: "Frontmatter shape for nodes classified as `agent` by the Claude Provider. Mirrors Anthropic's documented agent frontmatter verbatim (https://code.claude.com/docs/en/agents.md): `name` and `description` come from the spec base; this schema adds the 14 vendor-specific fields. skill-map AGGREGATES the vendor spec, it does not curate it \u2014 keys are reproduced exactly as Anthropic publishes them (mix of camelCase and snake_case). `additionalProperties: true` so future Anthropic additions flow through unchanged until this schema catches up.",
   allOf: [
     { $ref: "https://skill-map.dev/spec/v0/frontmatter/base.schema.json" }
   ],
   type: "object",
   additionalProperties: true,
   properties: {
-    args: {
+    tools: {
       type: "array",
-      description: "Declared positional / named arguments for this command.",
-      items: { $ref: "#/$defs/CommandArg" }
+      description: "Allowlist of tools this agent is permitted to invoke. Argument-scoped patterns supported (e.g. `Bash(git add *)`). Free-form strings \u2014 token vocabulary is platform-specific.",
+      items: { type: "string" }
     },
-    shortcut: {
+    disallowedTools: {
+      type: "array",
+      description: "Denylist of tools this agent MUST NOT invoke. Free-form strings \u2014 token vocabulary is platform-specific.",
+      items: { type: "string" }
+    },
+    model: {
       type: "string",
-      description: "Keyboard shortcut hint. Platform-specific notation (e.g. `cmd+shift+k`, `ctrl+alt+m`). Purely advisory."
-    }
-  },
-  $defs: {
-    CommandArg: {
+      description: "Model alias (`sonnet`, `opus`, `haiku`), full Claude id (e.g. `claude-3-7-sonnet-latest`), or the literal `inherit` to defer to the parent session's model."
+    },
+    permissionMode: {
+      type: "string",
+      enum: ["default", "acceptEdits", "auto", "dontAsk", "bypassPermissions", "plan"],
+      description: "How the agent handles permission prompts. See https://code.claude.com/docs/en/agents.md."
+    },
+    maxTurns: {
+      type: "integer",
+      minimum: 1,
+      description: "Hard cap on agentic turns this agent may take in one invocation."
+    },
+    skills: {
+      type: "array",
+      description: "Skills preloaded into this agent's context. Identifiers reference skill nodes available to the host.",
+      items: { type: "string" }
+    },
+    mcpServers: {
+      type: "array",
+      description: "MCP servers this agent connects to at startup. Shape is platform-defined; preserved as opaque objects.",
+      items: { type: "object" }
+    },
+    hooks: {
       type: "object",
-      required: ["name"],
-      additionalProperties: true,
-      properties: {
-        name: { type: "string", minLength: 1 },
-        type: {
-          type: "string",
-          description: "Free-form type hint (e.g. `string`, `integer`, `path`, `boolean`, `enum:a|b|c`)."
-        },
-        required: { type: "boolean", default: false },
-        description: { type: "string" },
-        default: { description: "Any JSON value." }
-      }
+      description: "Lifecycle hooks (`PreToolUse`, `PostToolUse`, `Stop`, etc.) declared inline on the agent. Shape is platform-defined; preserved as an opaque object. Note: Anthropic's `hooks` is NOT a separate node kind \u2014 it lives here, as a sub-object of agent frontmatter, or in `settings.json` (see https://code.claude.com/docs/en/hooks.md)."
+    },
+    memory: {
+      type: "string",
+      enum: ["user", "project", "local"],
+      description: "Memory scope this agent reads from and writes to."
+    },
+    background: {
+      type: "boolean",
+      description: "When true, the agent runs as a background task (no foreground UI presence)."
+    },
+    effort: {
+      type: "string",
+      enum: ["low", "medium", "high", "xhigh", "max"],
+      description: "Effort budget for reasoning. Higher levels allocate more thinking time."
+    },
+    isolation: {
+      type: "string",
+      enum: ["worktree"],
+      description: "Isolation strategy. `worktree` is the only documented value today (runs the agent in a separate git worktree)."
+    },
+    color: {
+      type: "string",
+      enum: ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"],
+      description: "Display color for this agent in the host UI."
+    },
+    initialPrompt: {
+      type: "string",
+      description: "Auto-submitted first turn \u2014 Anthropic dispatches this as if the user had typed it on agent activation."
     }
   }
 };
 
-// built-in-plugins/providers/claude/schemas/hook.schema.json
-var hook_schema_default = {
+// built-in-plugins/providers/claude/schemas/command.schema.json
+var command_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://skill-map.dev/providers/claude/v1/frontmatter/hook.schema.json",
-  title: "FrontmatterHook",
-  description: "Frontmatter shape for nodes classified as `hook` by the Claude Provider. Extends the spec's universal `frontmatter/base.schema.json` via $ref-by-$id. Kind-specific fields: `event`, `condition`, `blocking`, `idempotent`. Owned by the Claude Provider; relocated from `spec/schemas/frontmatter/` in spec 0.8.0 (Phase 3 of plug-in model overhaul).",
+  $id: "https://skill-map.dev/providers/claude/v1/frontmatter/command.schema.json",
+  title: "FrontmatterCommand",
+  description: "Frontmatter shape for nodes classified as `command` by the Claude Provider. Today identical to `skill` per Anthropic's documented merger (https://code.claude.com/docs/en/skills.md \u2014 \"Custom commands have been merged into skills\"). Both extend the shared `skill-base.schema.json` via the same `allOf` pattern. The two are kept SPLIT (not aliased) because skill-map's registry differentiates them in `IProviderKind.ui` (separate label / icon / color) and `defaultRefreshAction`. Splitting also reserves room for future divergence. No command-only fields today; `additionalProperties: true` so the file is ready for them.",
   allOf: [
-    { $ref: "https://skill-map.dev/spec/v0/frontmatter/base.schema.json" }
+    { $ref: "https://skill-map.dev/providers/claude/v1/frontmatter/skill-base.schema.json" }
   ],
   type: "object",
   additionalProperties: true,
-  properties: {
-    event: {
-      type: "string",
-      description: "Event name this hook reacts to (e.g. `PreToolUse`, `PostToolUse`, `SubagentStop`, `SessionStart`). Platform-specific enum; Providers MAY validate."
-    },
-    condition: {
-      type: "string",
-      description: "Free-form predicate expression evaluated by the host. Syntax is platform-specific; the spec does not constrain it."
-    },
-    blocking: {
-      type: "boolean",
-      description: "When true, the host MUST wait for the hook to finish before proceeding. When false, the hook runs fire-and-forget."
-    },
-    idempotent: {
-      type: "boolean",
-      description: "Author-declared: executing twice with the same inputs produces the same result. Consumed by runners for retry and dedup."
-    }
-  }
+  properties: {}
 };
 
 // built-in-plugins/providers/claude/schemas/note.schema.json
@@ -805,7 +863,7 @@ var claudeProvider = {
   pluginId: "claude",
   kind: "provider",
   version: "1.0.0",
-  description: "Walks Claude Code scope conventions (.claude/{agents,commands,hooks,skills} + notes).",
+  description: "Walks Claude Code scope conventions (.claude/{agents,commands,skills} + notes).",
   stability: "stable",
   // The Claude Provider's content lives under `~/.claude` for the global
   // scope (and inside `.claude/` for project scope). `sm doctor` validates
@@ -857,20 +915,6 @@ var claudeProvider = {
         }
       }
     },
-    hook: {
-      schema: "./schemas/hook.schema.json",
-      schemaJson: hook_schema_default,
-      defaultRefreshAction: "claude/summarize-hook",
-      ui: {
-        label: "Hooks",
-        color: "#8b5cf6",
-        colorDark: "#a78bfa",
-        icon: {
-          kind: "svg",
-          path: "M12 2 a3 3 0 1 0 0 6 a3 3 0 1 0 0 -6 M12 8 L12 22 M5 12 H2 a10 10 0 0 0 20 0 H19"
-        }
-      }
-    },
     skill: {
       schema: "./schemas/skill.schema.json",
       schemaJson: skill_schema_default,
@@ -897,6 +941,12 @@ var claudeProvider = {
       }
     }
   },
+  // Auxiliary schemas the per-kind schemas $ref by $id. AJV needs them
+  // registered via addSchema BEFORE the per-kind schemas compile, so the
+  // validator builder pre-registers them. `skill-base.schema.json` is the
+  // shared base for `skill` + `command` per Anthropic's documented merger
+  // (https://code.claude.com/docs/en/skills.md).
+  schemas: [skill_base_schema_default],
   async *walk(roots, options = {}) {
     const filter = options.ignoreFilter ?? buildIgnoreFilter();
     for (const root of roots) {
@@ -917,7 +967,6 @@ var claudeProvider = {
     const lower = path.toLowerCase();
     if (lower.startsWith(".claude/agents/")) return "agent";
     if (lower.startsWith(".claude/commands/")) return "command";
-    if (lower.startsWith(".claude/hooks/")) return "hook";
     if (lower.startsWith(".claude/skills/")) return "skill";
     return "note";
   }
@@ -1597,7 +1646,7 @@ var ASCII_FORMATTER_TEXTS = {
 
 // built-in-plugins/formatters/ascii/index.ts
 var ID10 = "ascii";
-var KIND_ORDER = ["agent", "command", "hook", "skill", "note"];
+var KIND_ORDER = ["agent", "command", "skill", "note"];
 var asciiFormatter = {
   id: ID10,
   pluginId: "core",
@@ -1809,6 +1858,7 @@ function buildProviderFrontmatterValidator(providers) {
   const baseFile = resolve3(specRoot, "schemas/frontmatter/base.schema.json");
   const baseSchema = JSON.parse(readFileSync2(baseFile, "utf8"));
   ajv.addSchema(baseSchema);
+  registerProviderAuxiliarySchemas(ajv, providers);
   const compiled = /* @__PURE__ */ new Map();
   for (const provider of providers) {
     for (const [kind, entry] of Object.entries(provider.kinds)) {
@@ -1833,6 +1883,16 @@ function formatError(err) {
   const path = err.instancePath || "(root)";
   return `${path} ${err.message ?? err.keyword}`;
 }
+function registerProviderAuxiliarySchemas(ajv, providers) {
+  for (const provider of providers) {
+    if (!provider.schemas) continue;
+    for (const aux of provider.schemas) {
+      const auxJson = aux;
+      if (typeof auxJson.$id === "string" && ajv.getSchema(auxJson.$id)) continue;
+      ajv.addSchema(aux);
+    }
+  }
+}
 function resolveSpecRoot() {
   const require2 = createRequire(import.meta.url);
   try {
@@ -6297,7 +6357,7 @@ function writeStreamSnippet(stream, header, text) {
 var CONFORMANCE_COMMANDS = [ConformanceRunCommand];
 
 // cli/commands/db.ts
-import { spawnSync as spawnSync2 } from "child_process";
+import { spawn, spawnSync as spawnSync2 } from "child_process";
 import { chmod, copyFile, mkdir, rm } from "fs/promises";
 import { dirname as dirname8, join as join9, resolve as resolve12 } from "path";
 import { DatabaseSync as DatabaseSync4 } from "node:sqlite";
@@ -6349,6 +6409,11 @@ var DB_TEXTS = {
   migrateKernelAppliedWithBackup: "kernel \xB7 Applied {{count}} migration(s) \xB7 backup: {{backupPath}}\n",
   // --- shell (system sqlite3 binary required for the interactive REPL) ---
   shellSqlite3NotFound: "sqlite3 binary not found on PATH. Install it (macOS: brew install sqlite; Debian/Ubuntu: apt install sqlite3) or use `sm db dump` for read-only inspection.\n",
+  // --- browser (system sqlitebrowser GUI required) ---------------------
+  browserRunScanFirstHint: "Run `sm scan` first (or `sm init`) to create the project DB.\n",
+  browserNotFound: "sqlitebrowser is not installed (or not on PATH).\n\nIf you want a GUI to inspect the DB, install it:\n  Debian/Ubuntu: sudo apt install -y sqlitebrowser\n  macOS:         brew install --cask db-browser-for-sqlite\n  Windows:       https://sqlitebrowser.org/dl/\n",
+  browserOpeningReadOnly: "Opening {{path}} (read-only)\n",
+  browserOpeningReadWrite: "Opening {{path}} (read-write)\n",
   // --- dump (pure node:sqlite, no external binary) ----------------------
   dumpInvalidTable: "--tables: refusing non-identifier name {{table}}. Table names must match [a-zA-Z_][a-zA-Z0-9_]*\n",
   // --- plugin migration runner -----------------------------------------
@@ -6635,6 +6700,57 @@ var DbShellCommand = class extends SmCommand {
     return result.status ?? 0;
   }
 };
+var DbBrowserCommand = class extends SmCommand {
+  static paths = [["db", "browser"]];
+  static usage = Command5.Usage({
+    category: "Database",
+    description: "Open the DB in DB Browser for SQLite (sqlitebrowser GUI).",
+    details: `
+      Default: read-only (-R), so a concurrent \`sm scan\` writer is safe.
+      Pass --rw to enable writes.
+
+      Resolution order for the DB path: positional arg > --db <path> >
+      -g/--global > project default (cwd/.skill-map/skill-map.db).
+
+      Spawns sqlitebrowser detached so the terminal stays usable. If
+      sqlitebrowser is not on PATH, a clear error points at the install
+      hint (Debian/Ubuntu: sudo apt install -y sqlitebrowser).
+    `,
+    examples: [
+      ["Open the project DB read-only", "sm db browser"],
+      ["Open the project DB read-write", "sm db browser --rw"],
+      ["Open an arbitrary DB file", "sm db browser path/to/other.db"]
+    ]
+  });
+  // GUI launch: the spawned process is detached and unref'd; we exit
+  // immediately. No `done in <…>` line — the user expects to see the
+  // GUI window, not a follow-up trailer in the terminal.
+  emitElapsed = false;
+  rw = Option5.Boolean("--rw", false, {
+    description: "Open in read-write mode. Default is read-only so a concurrent `sm scan` writer is safe."
+  });
+  positional = Option5.String({ required: false });
+  async run() {
+    const path = this.positional ? resolve12(this.positional) : resolveDbPath({ global: this.global, db: this.db, ...defaultRuntimeContext() });
+    if (!assertDbExists(path, this.context.stderr)) {
+      this.context.stderr.write(DB_TEXTS.browserRunScanFirstHint);
+      return ExitCode.NotFound;
+    }
+    const which = spawnSync2("which", ["sqlitebrowser"], { stdio: "ignore" });
+    if (which.status !== 0) {
+      this.context.stderr.write(DB_TEXTS.browserNotFound);
+      return ExitCode.Error;
+    }
+    const readOnly = !this.rw;
+    const args2 = readOnly ? ["-R", path] : [path];
+    this.context.stdout.write(
+      tx(readOnly ? DB_TEXTS.browserOpeningReadOnly : DB_TEXTS.browserOpeningReadWrite, { path })
+    );
+    const child = spawn("sqlitebrowser", args2, { detached: true, stdio: "ignore" });
+    child.unref();
+    return ExitCode.Ok;
+  }
+};
 var DbDumpCommand = class extends SmCommand {
   static paths = [["db", "dump"]];
   static usage = Command5.Usage({
@@ -6924,6 +7040,7 @@ var DB_COMMANDS = [
   DbRestoreCommand,
   DbResetCommand,
   DbShellCommand,
+  DbBrowserCommand,
   DbDumpCommand,
   DbMigrateCommand
 ];
@@ -7081,7 +7198,7 @@ var EXPORT_TEXTS = {
 };
 
 // cli/commands/export.ts
-var KIND_ORDER2 = ["agent", "command", "hook", "skill", "note"];
+var KIND_ORDER2 = ["agent", "command", "skill", "note"];
 var SUPPORTED_FORMATS = ["json", "md"];
 var DEFERRED_FORMATS = {
   mermaid: EXPORT_TEXTS.formatDeferredReasonMermaid
@@ -7097,7 +7214,7 @@ var ExportCommand = class extends SmCommand {
 
       Query syntax (v0.5.0): whitespace-separated key=value tokens; AND
       across keys, OR within comma-separated values. Keys: \`kind\`
-      (skill / agent / command / hook / note), \`has\` (issues), \`path\`
+      (skill / agent / command / note), \`has\` (issues), \`path\`
       (POSIX glob \u2014 \`*\` matches a single segment, \`**\` matches across
       segments).
 
@@ -7374,7 +7491,7 @@ import { Command as Command8, Option as Option8 } from "clipanion";
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.16.5",
+  version: "0.17.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -7421,10 +7538,13 @@ var package_default = {
   scripts: {
     build: "tsup",
     dev: "tsup --watch",
-    "dev:serve": "node ../scripts/dev-serve.js",
+    "dev:serve": "node scripts/dev-serve.js",
     typecheck: "tsc --noEmit",
     lint: "eslint .",
     "lint:fix": "eslint . --fix",
+    reference: "node scripts/build-reference.js",
+    "reference:check": "node scripts/build-reference.js --check",
+    validate: "npm run typecheck && npm run lint && npm run build && npm run test:ci && npm run reference:check",
     pretest: "tsup",
     "pretest:ci": "tsup",
     "pretest:coverage": "tsup",
@@ -7437,7 +7557,7 @@ var package_default = {
   },
   dependencies: {
     "@hono/node-server": "2.0.1",
-    "@skill-map/spec": "0.16.0",
+    "@skill-map/spec": "0.17.0",
     ajv: "8.18.0",
     "ajv-formats": "3.0.1",
     chokidar: "5.0.0",
@@ -12240,7 +12360,7 @@ function renderDeltaIssues(issues) {
 }
 
 // cli/commands/serve.ts
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 import { existsSync as existsSync18 } from "fs";
 import { Command as Command19, Option as Option19 } from "clipanion";
 
@@ -12897,24 +13017,46 @@ var PLACEHOLDER_HTML = `<!doctype html>
   </body>
 </html>
 `;
-function createStaticHandler(uiDist) {
-  if (uiDist === null) return placeholderRootMiddleware();
-  return serveStatic({ root: uiDist });
+var DEV_PLACEHOLDER_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="skill-map-mode" content="live" />
+    <title>skill-map BFF (dev)</title>
+    <style>
+      body { font-family: system-ui, sans-serif; margin: 2rem; max-width: 36rem; line-height: 1.5; }
+      code { background: #f4f4f4; padding: 0.1rem 0.3rem; border-radius: 3px; }
+      h1 { font-size: 1.4rem; }
+    </style>
+  </head>
+  <body>
+    <h1>skill-map BFF in dev mode \u2014 UI disabled</h1>
+    <p>Run <code>npm run ui:dev</code> in another terminal and visit <a href="http://localhost:4200/">http://localhost:4200/</a> for the Angular SPA.</p>
+    <p>The REST API on this port is reachable at <code>/api/health</code>.</p>
+  </body>
+</html>
+`;
+function createStaticHandler(opts) {
+  if (opts.uiDist === null) return placeholderRootMiddleware(opts.noUi === true);
+  return serveStatic({ root: opts.uiDist });
 }
-function createSpaFallback(uiDist) {
+function createSpaFallback(opts) {
+  const placeholder = opts.noUi === true ? DEV_PLACEHOLDER_HTML : PLACEHOLDER_HTML;
   return async (c, _next) => {
     if (c.req.method !== "GET" && c.req.method !== "HEAD") return c.notFound();
-    if (uiDist === null) return htmlResponse(c, PLACEHOLDER_HTML);
-    const indexPath = join13(uiDist, INDEX_HTML);
-    if (!existsSync16(indexPath)) return htmlResponse(c, PLACEHOLDER_HTML);
+    if (opts.uiDist === null) return htmlResponse(c, placeholder);
+    const indexPath = join13(opts.uiDist, INDEX_HTML);
+    if (!existsSync16(indexPath)) return htmlResponse(c, placeholder);
     return fileResponse(c, indexPath);
   };
 }
-function placeholderRootMiddleware() {
+function placeholderRootMiddleware(noUi) {
+  const html = noUi ? DEV_PLACEHOLDER_HTML : PLACEHOLDER_HTML;
   return async (c, next) => {
     if (c.req.method !== "GET" && c.req.method !== "HEAD") return next();
     if (c.req.path === "/" || c.req.path === "/index.html") {
-      return htmlResponse(c, PLACEHOLDER_HTML);
+      return htmlResponse(c, html);
     }
     return next();
   };
@@ -13018,8 +13160,8 @@ function createApp(deps) {
     throw new HTTPException5(404, { message: `Unknown API endpoint: ${c.req.path}` });
   });
   attachBroadcasterRoute(app, deps.broadcaster);
-  app.use("*", createStaticHandler(deps.options.uiDist));
-  app.get("*", createSpaFallback(deps.options.uiDist));
+  app.use("*", createStaticHandler({ uiDist: deps.options.uiDist, noUi: deps.options.noUi }));
+  app.get("*", createSpaFallback({ uiDist: deps.options.uiDist, noUi: deps.options.noUi }));
   app.notFound((c) => {
     throw new HTTPException5(404, { message: `Not found: ${c.req.path}` });
   });
@@ -13481,12 +13623,15 @@ function validateServerOptions(input) {
   if (watcherError !== null) return { ok: false, error: watcherError };
   const debounceError = validateWatcherDebounce(input.watcherDebounceMs);
   if (debounceError !== null) return { ok: false, error: debounceError };
+  const noUiError = validateNoUi(filled.noUi, filled.uiDist);
+  if (noUiError !== null) return { ok: false, error: noUiError };
   const options = {
     port: filled.port,
     host: filled.host,
     scope: filled.scope,
     dbPath: input.dbPath,
     uiDist: filled.uiDist,
+    noUi: filled.noUi,
     noBuiltIns: filled.noBuiltIns,
     noPlugins: filled.noPlugins,
     open: filled.open,
@@ -13504,6 +13649,7 @@ function applyDefaults(input) {
     host: input.host ?? DEFAULT_HOST,
     scope: input.scope ?? DEFAULT_SCOPE,
     uiDist: input.uiDist ?? null,
+    noUi: input.noUi ?? false,
     noBuiltIns: input.noBuiltIns ?? false,
     noPlugins: input.noPlugins ?? false,
     open: input.open ?? true,
@@ -13562,6 +13708,16 @@ function validateWatcherDebounce(value) {
   }
   return null;
 }
+function validateNoUi(noUi, uiDist) {
+  if (noUi && uiDist !== null) {
+    return {
+      code: "no-ui-conflicts-ui-dist",
+      message: "--no-ui and --ui-dist <path> are mutually exclusive",
+      value: uiDist
+    };
+  }
+  return null;
+}
 
 // server/paths.ts
 import { existsSync as existsSync17, statSync as statSync5 } from "fs";
@@ -13757,6 +13913,10 @@ var SERVE_TEXTS = {
   // Watcher option failures — ExitCode.Error.
   watcherRequiresPipeline: "sm serve: --no-built-ins is incompatible with the watcher (would persist empty scans on every batch). Pass --no-watcher to opt out, or drop --no-built-ins.\n",
   watcherDebounceInvalid: "sm serve: --watcher-debounce-ms must be a non-negative integer (got {{value}}).\n",
+  // --no-ui flag-validation failures — ExitCode.Error.
+  noUiConflictsUiDist: "sm serve: --no-ui and --ui-dist {{path}} are mutually exclusive (drop one).\n",
+  // --no-ui + --open is harmless but worth flagging — non-fatal stderr note.
+  noUiOpenWarning: "sm serve: warning: --open with --no-ui will open the placeholder, not the live UI; pass --no-open if running alongside `ui:dev`.\n",
   // Generic operational error — surfaced when the server itself throws
   // before the listener binds (e.g. UI bundle missing under explicit
   // --ui-dist).
@@ -13961,6 +14121,9 @@ var ServeCommand = class extends SmCommand {
   // need it). Clipanion still exposes it on the parser; the Usage
   // omission is the "hidden" contract per the 14.1 brief.
   uiDist = Option19.String("--ui-dist", { required: false, hidden: true });
+  noUi = Option19.Boolean("--no-ui", false, {
+    description: "Don't serve the Angular UI bundle. Use this when running the BFF alongside `ui:dev` (Angular dev server with HMR). The root `/` then renders an inline placeholder pointing the user at the dev server."
+  });
   noWatcher = Option19.Boolean("--no-watcher", false, {
     description: "Disable the chokidar-fed scan-and-broadcast loop. Use only for CI / read-only deployments."
   });
@@ -14001,13 +14164,28 @@ var ServeCommand = class extends SmCommand {
       );
       return ExitCode.NotFound;
     }
-    const uiDistResult = resolveUiDist(runtimeCtx, this.uiDist);
-    if (!uiDistResult.ok) {
+    if (this.noUi && this.uiDist !== void 0) {
       this.context.stderr.write(
-        tx(SERVE_TEXTS.startupFailed, { message: sanitizeForTerminal(uiDistResult.message) })
+        tx(SERVE_TEXTS.noUiConflictsUiDist, { path: sanitizeForTerminal(this.uiDist) })
       );
       return ExitCode.Error;
     }
+    let resolvedUiDist;
+    if (this.noUi) {
+      resolvedUiDist = null;
+    } else {
+      const uiDistResult = resolveUiDist(runtimeCtx, this.uiDist);
+      if (!uiDistResult.ok) {
+        this.context.stderr.write(
+          tx(SERVE_TEXTS.startupFailed, { message: sanitizeForTerminal(uiDistResult.message) })
+        );
+        return ExitCode.Error;
+      }
+      resolvedUiDist = uiDistResult.uiDist;
+    }
+    if (this.noUi && this.open) {
+      this.context.stderr.write(SERVE_TEXTS.noUiOpenWarning);
+    }
     const debounceResult = parseDebounce(this.watcherDebounceMs);
     if (!debounceResult.ok) {
       this.context.stderr.write(
@@ -14020,7 +14198,8 @@ var ServeCommand = class extends SmCommand {
     const input = {
       dbPath,
       scope,
-      uiDist: uiDistResult.uiDist,
+      uiDist: resolvedUiDist,
+      noUi: this.noUi,
       noBuiltIns: this.noBuiltIns,
       noPlugins: this.noPlugins,
       open: this.open,
@@ -14131,6 +14310,8 @@ function formatValidationError(err) {
       return tx(SERVE_TEXTS.watcherRequiresPipeline, { value: sanitizeForTerminal(err.value) });
     case "watcher-debounce-invalid":
       return tx(SERVE_TEXTS.watcherDebounceInvalid, { value: sanitizeForTerminal(err.value) });
+    case "no-ui-conflicts-ui-dist":
+      return tx(SERVE_TEXTS.noUiConflictsUiDist, { path: sanitizeForTerminal(err.value) });
     default:
       return tx(SERVE_TEXTS.startupFailed, { message: sanitizeForTerminal(err.message) });
   }
@@ -14161,7 +14342,7 @@ function tryOpenBrowser(url, stderr) {
       command = "xdg-open";
       args2 = [url];
     }
-    const child = spawn(command, args2, { detached: true, stdio: "ignore" });
+    const child = spawn2(command, args2, { detached: true, stdio: "ignore" });
     child.on("error", (err) => {
       stderr.write(
         tx(SERVE_TEXTS.openFailed, {