@skill-map/spec 0.13.1 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Spec changelog
 
+## 0.14.1
+
+### Patch Changes
+
+- 34d57db: Doc-only fix to remove a misleading reading of "built-in kinds" in the Node schema and one test, plus a small batch of internal CLI refactors and tightened null checks. No external surface change.
+
+  Spec / docs:
+
+  - `spec/schemas/node.schema.json` — the top-level `description` previously read "built-in kinds today are skill, agent, command, hook, note", which suggested those kinds were a kernel-level concept. They are not — the kernel treats `kind` as an open string, and the five names are emitted by the **built-in Claude Provider**. Re-worded to attribute the catalog to the Claude Provider, matching the wording already used on the `kind` field, in `spec/README.md`, in `src/kernel/types.ts`, and in `src/kernel/adapters/sqlite/schema.ts`.
+  - `src/test/extractor-applicable-kinds.test.ts` — three comments tightened from "built-in kind" to "built-in Claude Provider kind" for consistency.
+
+  Internal CLI refactors (no behaviour change):
+
+  - `src/cli/commands/config.ts` — extracted an `isPlainObject` predicate (replaces the duplicated `!!v && typeof v === 'object' && !Array.isArray(v)` check inside `enumerateConfigPaths`) and a `safeGetAtPath` helper that wraps `getAtPath` + `ForbiddenSegmentError` handling so each read verb's `run()` no longer repeats the try/catch + instanceof shape.
+  - `src/cli/commands/db.ts` — pulled the SQL number serialiser into `formatSqlNumber` (NaN / ±Infinity collapse to NULL) so `formatSqlValue` reads as a flat dispatcher.
+  - `src/cli/util/parse-error.ts` — moved the verb-scoped error formatting (incl. the missing-positionals special case) into a `formatVerbScopedError` helper so the top-level dispatcher in `formatParseError` stays flat. Removed the now-stale "dispatcher pattern" eslint-disable comment.
+  - `src/kernel/adapters/sqlite/scan-load.ts` — tightened `parseJsonObject` / `parseJsonArray` null checks from `s == null` to `s === null || s === undefined` to remove the implicit-coercion pattern flagged by lint.
+
+  No contract change (no field/type/required edits). `spec/index.json` regenerated.
+
+## 0.14.0
+
+### Minor Changes
+
+- 8f2a66d: Bare `sm` defaults to `sm serve` instead of printing help
+
+  `sm` invoked with no arguments now starts the Web UI server when a
+  `.skill-map/` project exists in the current working directory
+  (equivalent to `sm serve`). When no project is found, it prints a
+  one-line hint pointing to `sm init` and `sm --help` on stderr and
+  exits with code `2`. `sm --help` and `sm -h` continue to print
+  top-level help — help is now reserved for explicit flags.
+
+  **Spec change** (`spec/cli-contract.md` §Binary): the prior wording —
+  _"`sm`, `sm --help`, `sm -h` MUST all print top-level help"_ — is
+  replaced by two separate clauses. Help invocation requires `--help` or
+  `-h`; bare invocation routes to the server with the hint-and-exit
+  fallback when no project exists.
+
+  **CLI change** (`src/cli/entry.ts`): empty argv is intercepted before
+  Clipanion sees it. If `defaultProjectDbPath(cwd)` exists, the args
+  are rewritten to `['serve']`. Otherwise the hint is printed via the
+  `tx()` i18n shim and the process exits `2`. `RootHelpCommand` no
+  longer carries `Command.Default`; it remains the handler for `--help`
+  and `-h` only.
+
+  **Why pre-1.0 minor instead of major**: `spec/` and `src/` are both
+  in `0.Y.Z`. Per `spec/versioning.md` §Pre-1.0, breaking changes ship
+  as minor bumps until the deliberate 1.0 stabilization. The conformance
+  suite required no updates (no case asserted bare-sm = help).
+
 ## 0.13.1
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # skill-map spec
 
-The **skill-map specification** defines a vendor-neutral standard for mapping, inspecting, and managing collections of interrelated Markdown files — skills, agents, commands, hooks, and notes that compose AI-agent ecosystems (Claude Code, Codex, Gemini, Obsidian vaults, docs sites, and any future platform).
+The **skill-map specification** defines a vendor-neutral standard for mapping, inspecting, and managing collections of interrelated Markdown files — skills, agents, commands, hooks, and notes that compose AI-agent ecosystems (Claude Code, Codex, Gemini, docs sites, and any future platform).
 
 This document is the **source of truth**. The reference implementation under `../src/` conforms to this spec. Third parties can build alternative implementations (any language, any UI, any CLI) using only `spec/`, without reading the reference source.
 
@@ -31,7 +31,7 @@ These are implementation decisions. The reference impl picks them (see [`../AGEN
 - **Machine-readable**: all domain shapes are JSON Schemas. Validate from any language that has a JSON Schema validator.
 - **Human-readable**: prose documents for each subsystem, with examples.
 - **Independently versioned**: spec `v1.0.0` can be implemented by CLI `v0.3.2`. See [`versioning.md`](./versioning.md).
-- **Platform-neutral**: no platform (Claude Code, Obsidian, …) is privileged. Each is expressed as an adapter extension.
+- **Platform-neutral**: no platform is privileged. Each is expressed as an adapter extension.
 - **Conformance-tested**: every conforming implementation passes the suite under [`conformance/`](./conformance/README.md). Pass/fail is binary.
 
 ## Naming conventions

package/cli-contract.md

@@ -8,7 +8,8 @@ Normative description of the `sm` CLI surface: verbs, flags, exit codes, machine
 
 - Primary: `sm`.
 - Long alias: `skill-map`. MUST resolve to the same binary. A symlink, shim, or alias in `bin` field of `package.json` is acceptable.
-- Help invocation: `sm`, `sm --help`, `sm -h` MUST all print top-level help and exit with code 0.
+- Help invocation: `sm --help` and `sm -h` MUST print top-level help and exit with code 0.
+- Bare invocation: `sm` with no arguments starts the Web UI server (equivalent to `sm serve`) when a `.skill-map/` project is initialized in the current working directory. When no project is found in the cwd, it MUST print a one-line hint to stderr pointing the user to `sm init` and `sm --help`, then exit with code `2`.
 
 ---
 
@@ -103,6 +104,19 @@ Flags: `--no-scan` (skip the first scan), `--force` (rewrite an existing config)
 
 Exit: 0 on success, 2 on failure.
 
+#### `sm guide`
+
+Materialize the interactive tester guide as `sm-guide.md` in the current working directory. Companion to the `sm-guide` Claude Code skill: a tester drops into an empty directory, runs `sm guide` to seed the guide source, then opens Claude Code there and triggers the skill (which reads the file as its onboarding payload).
+
+- Writes `<cwd>/sm-guide.md` (single file, top-level — no subdirectory).
+- Content is the canonical `SKILL.md` shipped with the implementation. Any conforming implementation MUST embed an equivalent guide source (the prose itself is informative; what is normative is that `sm guide` produces a single readable file at `<cwd>/sm-guide.md` that a Claude Code skill can consume).
+- Does NOT require an initialized project — runs in any directory, including empty ones, and never reads or writes `.skill-map/`.
+- Is NOT scope-aware: `-g` is accepted (inherited global flag) but has no effect; the file is always written under the cwd.
+
+Flags: `--force` (overwrite an existing `sm-guide.md` without prompting).
+
+Exit: `0` on success; `2` if `<cwd>/sm-guide.md` already exists and `--force` was not passed (operational error — refusing to clobber); `2` on any I/O failure.
+
 #### `sm version`
 
 Prints version matrix:

package/conformance/coverage.md

@@ -1,6 +1,6 @@
 # Conformance coverage
 
-Authoritative map of JSON Schemas in [`../schemas/`](../schemas/) to the conformance cases that exercise them. Every schema MUST have at least one case before spec v1.0.0 ships — missing case → missing release ([`../../AGENTS.md`](../../AGENTS.md) §Rules for AI agents editing spec/).
+Authoritative map of JSON Schemas in [`../schemas/`](../schemas/) to the conformance cases that exercise them. Every schema MUST have at least one case before spec v1.0.0 ships — missing case → missing release ([`../../context/spec.md`](../../context/spec.md) §Rules for AI agents editing spec/).
 
 This file is hand-maintained. A CI check before spec release compares the schema inventory against this table and fails if any schema lacks a case.
 

package/index.json

@@ -166,18 +166,18 @@
       }
     ]
   },
-  "specPackageVersion": "0.13.1",
+  "specPackageVersion": "0.14.1",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "e99ca15631aa9ce6392612d055379d5cb2f2757df2008c8c184acc059a4178c3",
-      "README.md": "bd30780525e75379eaeb5f8a903bdc601daf3862f3ec69dffc96c437e8d476fc",
+      "CHANGELOG.md": "4581c812b7314799af60df5c4d87f8f8ef7eeeff86a5436838f77b058e93a327",
+      "README.md": "97fd3079092182c677669c25f44e08b0f6579faaa3406d8cb5a884e37e9eef97",
       "architecture.md": "c14e69faa7ce7f657d6a2790762daaea8a5ff350375de8c254cd870b5494b896",
-      "cli-contract.md": "1aa9349ef1a8db94236a8057ed77dd2802b561eec382451be9a2afdbbbdc6f91",
+      "cli-contract.md": "0000fa2079a5dd2c44317612969bafbd6dab0a5031389a3ba0e9157377a1d36e",
       "conformance/README.md": "5f94a6ac637b7c992fcd7e53d32eed1b8887eeef05eb6ca3b5ec8a0b5045cd21",
       "conformance/cases/kernel-empty-boot.json": "ad4bbe9d637537625025c8bdb61285b1433568a2544b1ce0248f304ccff8c350",
       "conformance/cases/plugin-missing-ui-rejected.json": "c6ce8f62a430d662aea33dec8ebf6493be6455037be3114e0d93d0eb57777287",
-      "conformance/coverage.md": "a06b650c5b5684aec9b508181b3e091bf1aaa0cb45a0f8e76fdfb8f2a9c7b9a7",
+      "conformance/coverage.md": "35bac01af3a922ce580deb1f83fc890c668d3d3cf93747f5097340a09303eb43",
       "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/plugin.json": "4d78af6f12faa9d131e2a19f1dbb8f250baacc525978f3a8c858932b95da4ff6",
       "conformance/fixtures/plugin-missing-ui/.skill-map/plugins/bad-provider/provider.js": "da40b134d70f8bc8175cfa9c380ecb55d26b2240c8b467f22f3fcfab750c8747",
       "conformance/fixtures/plugin-missing-ui/notes/example.md": "55767f0aa1b6774546a99f28c58e7b732aa9cfa5dfce8d0326470f7f622f577e",
@@ -204,7 +204,7 @@
       "schemas/issue.schema.json": "40f6f8abadcce0fd8eac9df27ffcc20b2fc9fda6970142ddb8e7e56b1760b9b1",
       "schemas/job.schema.json": "ffbdd51c54b487c44eb57fabd07f624ac1030c14ef69b46933c154092853a84c",
       "schemas/link.schema.json": "0a95a24849a38b9ef5bad5361519a9f9e012b5bc3001289fad29d0851fceff6b",
-      "schemas/node.schema.json": "f9a0cc5d5a7f581915719e91ae401e46a82688e0865fd3a2eb64bd42798a6b2b",
+      "schemas/node.schema.json": "646f2b2c266b5bf1c61b9933c6defdb05565db044a766c4c575c0dcd1e68df57",
       "schemas/plugins-registry.schema.json": "5ca1d4970ae64f064f05c237a649d9f82d5edbeb7c121ec50cb4aaca13f4bc51",
       "schemas/project-config.schema.json": "4f5b1ce01446d78ebf524d11c36e0a3ae101e69008c922a2b3f53fccfd1cb87f",
       "schemas/report-base.schema.json": "a1021e9a59b4df9f99cd92454d797e88469766e7d49f52d231c4645ffdfdad8f",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skill-map/spec",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "JSON Schemas, prose contracts, and conformance suite for the skill-map specification.",
   "license": "MIT",
   "type": "module",

package/schemas/node.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://skill-map.dev/spec/v0/node.schema.json",
   "title": "Node",
-  "description": "A single markdown file in the graph. Identified by its relative path from the scope root. The `kind` is whatever the classifying Provider declares; built-in kinds today are `skill`, `agent`, `command`, `hook`, `note`, but external Providers (Cursor, Obsidian, …) MAY emit their own.",
+  "description": "A single markdown file in the graph. Identified by its relative path from the scope root. The `kind` is whatever the classifying Provider declares — open by design; the **built-in Claude Provider** emits `skill` / `agent` / `command` / `hook` / `note` today, but external Providers (Cursor, Obsidian, …) MAY emit their own.",
   "type": "object",
   "required": ["path", "kind", "provider", "bodyHash", "frontmatterHash", "bytes", "linksOutCount", "linksInCount", "externalRefsCount"],
   "additionalProperties": false,