@skill-map/cli 0.20.1 → 0.21.0

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

@@ -413,6 +413,10 @@ long_steps:
     verbs: ["sm plugins list", "sm plugins show",
             "sm plugins doctor", "sm plugins enable",
             "sm plugins disable"]
+  - id: "9-annotations"
+    title: "Annotations and the .sm consent prompt"
+    status: "pending"
+    verbs: ["sm sidecar annotate"]
 findings_file: "./findings.md"
 ```
 
@@ -613,8 +617,12 @@ Create these four files (with `Write`), exactly in this order:
    target file. Connectors land in the next sub-step.
    ```
 
-3. `.claude/hooks/demo-hook.md` (kind: hook — **don't skip this
-   one**, fields differ on purpose):
+3. `.claude/hooks/demo-hook.md` — **don't skip this one**, the
+   fields differ on purpose so the body reads like a real hook
+   manifest. The CLI classifies it as `kind: markdown` today
+   (the catch-all kind for `.md` files outside the
+   skill / agent / command folders); a dedicated `hook` kind
+   is on the roadmap:
    ```markdown
    ---
    name: demo-hook
@@ -634,7 +642,9 @@ Create these four files (with `Write`), exactly in this order:
    wired into the rest of the fixture next.
    ```
 
-4. `notes/todo.md` (kind: note):
+4. `notes/todo.md` — also classified as `kind: markdown` today
+   (same catch-all as the hook above; a dedicated `note` kind
+   is on the roadmap):
    ```markdown
    ---
    name: Demo TODO list
@@ -943,27 +953,38 @@ the server.
 sm list
 sm list --kind skill
 sm list --kind agent
+sm list --kind markdown
 sm show .claude/skills/demo-skill/SKILL.md
 sm check
 ```
 
-Expected: you see the 5 fixture nodes listed with their kind;
-`check` runs the deterministic rules and reports a clean fixture
-(no issues at this point — we will plant one in step 7 and watch
-the rule catch it).
+Expected: you see the 5 fixture nodes listed with their kind:
+`demo-skill` (skill), `demo-agent` (agent), `demo-command`
+(command), and `demo-hook` + `notes/todo` (both `markdown` —
+the catch-all per Step 2.2). `check` reads the persisted
+`scan_issues` table — it does NOT re-walk the filesystem. The
+fixture is clean (the watcher in Step 2 captured the latest
+state before Ctrl+C), so the verb prints `✓ No issues`. We will
+plant one in Step 7 and watch the rule catch it after a fresh
+`sm scan`.
 
 ### Step 6 — ASCII: graph + export (~3 min)
 
 ```bash
 sm graph
-sm graph --root .claude/skills/demo-skill/SKILL.md
 sm export --format md > export.md
-sm export --format json --kind note > export-notes.json
+sm export "kind=markdown" --format json > export-markdown.json
+sm export "path=notes/**" --format json > export-notes.json
 ls -la export.*
 ```
 
-`graph` draws an ASCII tree. `export` filters and serialises to md
-or json.
+`graph` draws an ASCII tree of the whole persisted scan (no
+`--root` flag — graph is whole-graph today). `export` takes a
+positional query (`kind=…`, `path=…`, `has=issues`, comma-OR
+within a key, AND across keys) and a `--format` of `md` or
+`json`. The `path=` glob uses POSIX semantics (`*` is one
+segment, `**` spans segments) so `path=notes/**` cleanly
+captures the notes folder regardless of the catch-all kind.
 
 ### Step 7 — Issues: broken refs (~3 min)
 
@@ -980,7 +1001,14 @@ Ask the tester to **append one bullet** to `notes/todo.md`:
 
 `./missing-page.md` deliberately doesn't exist. Save the file.
 
+The watcher was stopped at the end of Step 4, so the persisted
+`scan_issues` table still reflects the pre-edit state. `sm check`
+reads from that table without re-walking, so a bare `sm check`
+right now would still print `✓ No issues`. Run `sm scan` first
+to refresh the snapshot:
+
 ```bash
+sm scan
 sm check
 sm check --analyzers broken-ref
 sm check --json
@@ -1033,6 +1061,57 @@ all Claude-kind extraction during the window.
 If `plugins list` shows zero entries (depends on the build), tell
 the tester no plugins are installed yet and offer to skip.
 
+### Step 9 — Annotations and the `.sm` consent prompt (~3 min)
+
+**Context**: skill-map keeps a small **companion file** (extension
+`.sm`) next to each `.md` to track its version, history, and tags.
+The first time skill-map wants to write one in a new project it asks
+for your consent — it never touches your filesystem without
+permission. After you say yes, the choice persists per-checkout
+(gitignored) and the prompt never appears again.
+
+We'll demonstrate by creating an empty annotation scaffold for
+`notes/todo.md`.
+
+```bash
+sm sidecar annotate notes/todo.md
+```
+
+Expected: a short explanation paragraph appears in the terminal,
+followed by a `[Y/n]` prompt (capital Y = default Yes — you can just
+hit Enter). After accepting, `notes/todo.sm` appears next to
+`notes/todo.md` carrying an `identity:` block plus an empty
+`annotations: {}` block, and `.skill-map/settings.local.json` now
+contains `{ "allowEditSmFiles": true }`.
+
+```bash
+cat notes/todo.sm
+cat .skill-map/settings.local.json
+```
+
+**Why the prompt?** The choice is **per-user, per-project** — stored
+in the gitignored `settings.local.json` so each contributor consents
+independently and nothing about the choice travels via the repo. On a
+CI / non-interactive session, pass `--yes` to grant up-front.
+
+**Try this**: delete `notes/todo.sm` and re-run the command — this
+time it goes through silently because the flag is already set:
+
+```bash
+rm notes/todo.sm
+sm sidecar annotate notes/todo.md
+```
+
+Expected: same scaffold reappears, no prompt.
+
+> **Heads up about scope** (mention only if the tester asks):
+>
+> - `sm sidecar annotate` is the scaffold verb (creates a fresh `.sm`).
+> - `sm bump <node>` is the day-to-day verb that increments the
+>   sidecar's version and refreshes its hashes — same consent gate.
+> - `sm sidecar refresh <node>` is the hash-only update (no version
+>   bump).
+
 ---
 
 ## Final wrap-up
@@ -1060,7 +1139,7 @@ template:
 - **Depth reached**: <basic | full>
 - **Tester**: level <N> (if applicable)
 - **Tutorial directory**: <cwd>
-- **Steps completed**: N / 3 demo + X / 5 deep-dive (if applicable)
+- **Steps completed**: N / 3 demo + X / 6 deep-dive (if applicable)
 - **Steps skipped**: Y (if applicable)
 - **Total time**: ~<computed from timestamps>
 
@@ -1100,8 +1179,8 @@ the cwd, start like this (do NOT repeat pre-flight from scratch):
 > I see you already started the tutorial.
 >
 > You're at step <N> of 3 (or "you've already completed the demo
-> (steps 1-3) and you're on step <M> of 5 of the deep-dive (steps
-> 4-8)", depending on the yaml state).
+> (steps 1-3) and you're on step <M> of 6 of the deep-dive (steps
+> 4-9)", depending on the yaml state).
 >
 > 1. **Continue** from where you left off
 > 2. **Start over** — wipes all the tutorial content in this dir