@skill-map/cli 0.18.0 → 0.20.0

package/README.md

@@ -78,6 +78,10 @@ Exit codes follow [`spec/cli-contract.md`](../spec/cli-contract.md):
 | `4` | Nonce mismatch |
 | `5` | Resource not found |
 
+## Sidecar `.sm` files
+
+`sm bump` and `sm sidecar annotate` write a sibling `<basename>.sm` YAML next to each `.md` (same directory). Their purpose is to keep skill-map's bookkeeping — version, stability, supersession, tags, audit trail — **out of the `.md` body and frontmatter**. The `.md` stays vendor-pure (Claude Code, Codex, Cursor, …); the `.sm` is the only file skill-map writes. **`sm scan`, `sm watch`, and the live UI never create `.sm` files** — they only read existing ones; sidecars appear only when you opt in via `bump` or `annotate`. **Commit `.sm` files to git like any other source file** — don't `.gitignore` them; they carry the metadata that drives `sm check`, drift detection, and supersession graphs. Full spec: [`spec/architecture.md` §Annotation system](../spec/architecture.md#annotation-system).
+
 ## Spec
 
 This binary implements the [skill-map spec](https://www.npmjs.com/package/@skill-map/spec). The spec package ships JSON Schemas, conformance cases, and prose contracts; `skill-map` conforms to a declared range via its `specCompat`.

package/dist/cli/tutorial/sm-tutorial.md

@@ -405,7 +405,7 @@ long_steps:
   - id: "7-issues"
     title: "Issues: broken refs"
     status: "pending"
-    verbs: ["sm check", "sm check --rules broken-ref",
+    verbs: ["sm check", "sm check --analyzers broken-ref",
             "sm check --json"]
   - id: "8-plugins"
     title: "Plugins"
@@ -863,13 +863,12 @@ Mark `2-ui-live: done`.
 > UI sees it instantly. In **~10 minutes** you've already seen the
 > full flow.
 >
-> One thing worth knowing for later: alongside every `.md` skill-map
-> can write a sibling `.sm` file (same basename, different extension)
-> that holds the concrete metadata — version, stability, supersession,
-> tags, audit trail. The `.md` stays vendor-pure; the `.sm` is where
-> skill-map writes. Both travel via git like the rest of your scope.
-> You'll see them appear once you start using `sm bump` or
-> `sm sidecar annotate`.
+> ⚠️ **`.sm` files (heads-up for later)** — when skill-map needs to
+> record metadata on a node, it doesn't modify the `.md` directly;
+> it creates a sibling file with `.sm` extension (e.g. `demo-agent.sm`
+> next to `demo-agent.md`). You won't see any during this demo — they
+> only appear after `sm bump` or `sm sidecar annotate`. Commit them
+> to git like any other source file.
 >
 > If you want, **we can keep going deeper**: I'll walk you through
 > the CLI verbs and flags (`list`, `graph`, `export`, `orphans`,
@@ -983,13 +982,13 @@ Ask the tester to **append one bullet** to `notes/todo.md`:
 
 ```bash
 sm check
-sm check --rules broken-ref
+sm check --analyzers broken-ref
 sm check --json
 ```
 
 Expected: the warning surfaces the dangling link from
 `notes/todo.md` to the non-existent `missing-page.md`. The
-`--rules` filter lets you focus on a single issue type; `--json`
+`--analyzers` filter lets you focus on a single issue type; `--json`
 emits the structured payload (useful for CI / scripting). When
 done, the tester can leave the bullet in place or delete it — the
 rest of the deep-dive doesn't depend on it.