@skill-map/cli 0.53.5 → 0.54.0

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

@@ -42,8 +42,10 @@ prefix when a part spans several files: `settings-*` →
 `part-authoring.md`).
 
 > For the tester this is a single guided session, never a course
-> catalogue. Never say "part 6", "chapter id", "the settings tour"
-> out loud. Use the friendly titles from the manifest.
+> catalogue. Refer to a chapter by its tester-facing `section.chapter`
+> number plus its friendly title (`_core.md` §Numbering); never expose
+> the internal `order` index ("Part 6", off by one from the menu), a
+> raw "chapter id", or tour jargon ("the settings tour").
 
 ## Pre-flight (run once, silent on success)
 

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

@@ -8,9 +8,32 @@ library assumes it. Do NOT restate these rules inside a part file.
 The tutorial is **one book**: an ordered sequence of **chapters
 grouped in parts**, listed in `_manifest.yml`. A chapter is the
 minimal unit (1 to a few steps). For the tester it is a single
-guided session, never a "course catalogue"; never say "part 3",
-"the settings tour", "chapter id" out loud. The menu uses friendly
-titles; once they pick, you just walk that path.
+guided session, never a "course catalogue": refer to a chapter by its
+tester-facing `section.chapter` number (§Numbering) plus its friendly
+title, never by a raw "chapter id" or tour jargon ("the settings
+tour"). The menu uses friendly titles; once they pick, you just walk
+that path.
+
+## Numbering (the `section.chapter` scheme)
+
+Two numbering systems coexist; keep them apart:
+
+- **Internal (authoring only)**: the `order` field in `_manifest.yml`
+  and the `# Part N` file headers, 0-based (Part 0 the prologue …
+  Part 8 the MCP appendix). Use it in `**Context**:` blocks and author
+  notes; NEVER say it to the tester, it is off by one from what they
+  see.
+- **Tester-facing (`S.N`)**: every part is a **section** numbered by
+  its 1-based position in the menu (section `1` is the prologue), and
+  every chapter inside it carries a `section.chapter` number like a
+  semver minor, resetting per section: section `5`'s chapters are
+  `5.1`, `5.2`, … This `S.N` form is the ONLY number you say out loud;
+  it matches the menu number the tester picked.
+
+So the third chapter of section 5 announces as `5.3`, and the
+prologue's first chapter is `1.1`. The numbers are derived at render
+time from the menu order and the chapter's position in its part,
+nothing is stored in the manifest.
 
 ## Tone
 
@@ -263,10 +286,12 @@ Never call `TaskCreate` / `TaskUpdate` (Inviolable rule #4).
 
 For every chapter:
 
-1. **Announcement**: "Capítulo N: `<title>`. ~M min." then a blank
+1. **Announcement**: "Capítulo S.N: `<title>`. ~M min." then a blank
    line, then (optionally) one sentence of context on its own
-   paragraph. `N` is the 1-based index of the chapter inside its
-   part; it resets per part. The context paragraph renders ONLY when
+   paragraph. `S` is the section number (the part's 1-based menu
+   position) and `N` is the 1-based index of the chapter inside that
+   part, resetting per part (§Numbering), so section 5's third chapter
+   announces as `Capítulo 5.3`. The context paragraph renders ONLY when
    the source has a `**Context**:` field; if omitted, announce the
    title alone. The title comes from the chapter's `title` in
    `_manifest.yml` (translated per §Tone), not the internal id.
@@ -339,7 +364,8 @@ and go straight to §Final wrap-up.
 
 Render the menu numbered and formatted (NOT a bare list), translated
 to the tester's language. A one-line intro, then per part a **bold
-numbered title line** (number + title + `(~M min)`) as plain prose,
+numbered title line** (the section number + title + `(~M min)`, that
+number is the `S` major in the chapter `S.N` scheme, §Numbering) as plain prose,
 immediately followed by a single-level `> ` blockquote one-line
 description (what the part covers, derived from its title + chapters).
 A **completed part** keeps its plain title (NO `✓` on the title line)

package/dist/cli/tutorial/sm-tutorial/references/_manifest.yml

@@ -148,7 +148,7 @@ parts:
 
   - id: maintain
     order: 4
-    title: "Maintain the site"
+    title: "Maintain the harness"
     step_file: part-maintain.md
     pace: auto-advance
     preflight: seed

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

@@ -62,8 +62,6 @@ description: |
   tools so the `core/tools-counter` extractor emits a count.
 tools: [Read, Bash, Edit]
 model: sonnet
-metadata:
-  version: "1.0.0"
 ---
 
 # master-agent
@@ -82,17 +80,6 @@ description: |
   Example skill paired with the master-agent for the advanced
   tutorial. Links to the agent so extractors and analyzers have
   something to chew on.
-inputs:
-  - name: target
-    type: path
-    description: File to process.
-    required: true
-outputs:
-  - name: report
-    type: string
-    description: Markdown summary.
-metadata:
-  version: "1.0.0"
 ---
 
 # master-skill
@@ -115,9 +102,6 @@ name: Ideas backlog
 description: |
   Free-form notes for the advanced tutorial. Demonstrates the
   catch-all markdown kind alongside the agent and skill.
-tags: [notes, master]
-metadata:
-  version: "1.0.0"
 ---
 
 # Ideas

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

@@ -63,50 +63,28 @@ sm check --json
 
 Expected: the error surfaces the dangling link from `notes/todo.md` to the non-existent `missing-page.md`. The `--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.
 
-If the tester asks about `sm orphans` vs `sm check`:
-
-- `sm check` reports broken-refs and other rule-driven issues
-  (the deterministic catalog).
-- `sm orphans` is a **different scope**: auto-rename / orphan-node
-  detection (a node whose file disappeared, or a candidate rename
-  the kernel is still unsure about). Our fixture doesn't produce
-  orphans of that kind, so `sm orphans` will print "No orphan /
-  auto-rename issues", that's expected, not a bug.
-
 Mark `issues`: done.
 
 ## Chapter `annotations` - Annotations and the .sm consent prompt (~3 min)
 
-**Context**: every `.md` skill-map tracks gets a sibling **companion file** with extension `.sm` that carries **all of the tool's metadata about that markdown, so your `.md` stays clean and uncluttered**. Version, history, tags, annotations, anything that does not belong in the human-authored body lives in the `.sm`. The `.md` is content you write for Claude or humans; the `.sm` is bookkeeping the tool writes. They are ordinary source files, committed to git like everything else, and you'll encounter them often once you start working with the project.
+**Context**: skill-map keeps each tracked `.md`'s metadata (version, history, tags, annotations) in a sibling **`.sm` companion file** so the `.md` stays clean, and the first time it writes one in a project it asks for consent (remembered in the gitignored `settings.local.json`). The Maintain part walks that consent flow in full; this chapter does not re-teach it. The CLI focus here is what Maintain does not cover: the **three sidecar verbs** and the `--yes` non-interactive switch. A tester who jumped straight here gets a one-line refresher in the demo below.
 
-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 is saved to the project's `settings.local.json` (part of your project config, gitignored) and the prompt never appears again.
-
-We'll demonstrate by creating an empty annotation scaffold for `notes/todo.md`. **Reset any prior consent state first** so the prompt actually appears (an earlier step may have flipped the flag without you noticing, in which case `sm sidecar annotate` would skip straight past the prompt and the lesson would not land):
+Create a scaffold for `notes/todo.md` so there is a `.sm` on disk to talk about. **Reset any prior consent state first** so the prompt appears (an earlier step may have flipped the flag, in which case the verb skips straight past it):
 
 ```bash
 rm -f notes/todo.sm .skill-map/settings.local.json
 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. Once accepted, the flag stays set and skill-map will never ask again on this checkout (the next `sm sidecar annotate` or `sm bump` goes through silently). On a CI / non-interactive session, pass `--yes` to grant up-front.
+Expected: a short explanation, then a `[Y/n]` prompt (capital Y = default Yes, just hit Enter). After accepting, `notes/todo.sm` appears with an `identity:` block plus an empty `annotations: {}`, and `.skill-map/settings.local.json` records `{ "allowEditSmFiles": true }` so it never asks again on this checkout (the choice is per-user, per-project, gitignored).
 
-If the tester asks about `sm bump` vs `sm sidecar annotate` vs `sm sidecar refresh`:
+The part the CLI adds on top, the three sidecar verbs (all share that same consent gate):
 
-- `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).
+- `sm sidecar annotate <node>` is the scaffold verb you just ran (creates a fresh `.sm`).
+- `sm bump <node>` is the day-to-day verb: it increments the sidecar's version and refreshes its hashes.
+- `sm sidecar refresh <node>` is the hash-only update (no version bump).
 
-If the tester ever asks about reserved names (e.g. `commands/help.md`): if they name a file after a built-in (`/help`, `/clear`, `/init`, `/agents`, `/model`, or one of the documented agent reservations like `general-purpose`), `sm check` surfaces a `reserved-name` warning. The vendor runtime ignores user-owned files that shadow its built-ins, so the warning is not a bug, it's skill-map telling the operator "Claude will never invoke this file; pick another name". Incoming links to the shadowed file resolve at confidence `0.1` instead of `1.0`, so the **Map** also visually de-emphasises them. Rename the file and the warning clears on the next scan.
+And for automation: a CI / non-interactive session has no one to answer the `[Y/n]`, so pass `--yes` to grant consent up front (`sm sidecar annotate <node> --yes`).
 
 Mark `annotations`: done.
 
@@ -131,7 +109,6 @@ name: note-with-external-link
 description: |
   Demo note that links out to a sibling project (hijoB) sitting
   next to this one. Used to teach scan.referencePaths.
-tags: [demo, link-validation]
 ---
 
 # Note with external link
@@ -147,7 +124,6 @@ description: |
   Target of the cross-folder link. Lives outside hijoA's scan
   scope on purpose: that is precisely what scan.referencePaths
   is designed to bridge.
-tags: [demo, link-validation]
 ---
 
 # External spec

package/dist/cli/tutorial/sm-tutorial/references/part-connect-harness.md

@@ -14,15 +14,6 @@ name: check-links
 description: |
   Validates the portfolio's internal links before publishing. Walks
   every generated page and reports any link whose target is missing.
-inputs:
-  - name: root
-    type: path
-    description: Folder of generated pages to check.
-    required: true
-outputs:
-  - name: report
-    type: string
-    description: List of broken links, empty when all resolve.
 ---
 
 # check-links
@@ -55,7 +46,7 @@ Wait for confirmation. Mark `check-links`: done.
 
 On `agent-skills` / Antigravity there is no `command` kind, so skip this whole chapter and fold its purpose into the prose of the next one.
 
-Tell the tester to create the file themselves (it is their project's file, Inviolable rule #2). Substitute `<provider_dir>` per `_core.md` in the path you give them. The frontmatter fence (`---`) MUST sit on column 0 with no leading spaces: present the block below exactly as written, and if the tester pastes it indented, have them strip the leading whitespace. An indented `---` does not parse as YAML, so the `publish` node would land without its `name`, `description`, or `shortcut`.
+Tell the tester to create the file themselves (it is their project's file, Inviolable rule #2). Substitute `<provider_dir>` per `_core.md` in the path you give them. The frontmatter fence (`---`) MUST sit on column 0 with no leading spaces: present the block below exactly as written, and if the tester pastes it indented, have them strip the leading whitespace. An indented `---` does not parse as YAML, so the `publish` node would land without its `name` or `description`.
 
 > Create `.claude/commands/publish.md` with exactly this content (the first line is `---`, nothing before it):
 
@@ -65,12 +56,6 @@ name: publish
 description: |
   Publishes the portfolio: runs the link check, hands off to the
   content editor for any last fixes, then follows the deploy runbook.
-shortcut: "ctrl+alt+p"
-args:
-  - name: root
-    type: path
-    description: Folder of generated pages to publish.
-    required: true
 ---
 
 # publish

package/dist/cli/tutorial/sm-tutorial/references/part-fundamentals.md

@@ -43,15 +43,6 @@ Create these five files (with `Write`), exactly in this order. Per §Provider de
    description: |
      Example skill that walks a file and returns a Markdown report.
      Showcases the `skill` kind in the demo map.
-   inputs:
-     - name: target
-       type: path
-       description: File to process.
-       required: true
-   outputs:
-     - name: report
-       type: string
-       description: Markdown summary.
    ---
 
    # demo-skill
@@ -70,20 +61,14 @@ Create these five files (with `Write`), exactly in this order. Per §Provider de
    ---
    name: demo-command
    description: |
-     Example slash-style command that wraps the demo-skill behind
-     a keyboard shortcut. Showcases the `command` kind.
-   shortcut: "ctrl+alt+d"
-   args:
-     - name: target
-       type: path
-       description: File the command will hand off to the skill.
-       required: true
+     Example slash command that wraps the demo-skill. Showcases the
+     `command` kind.
    ---
 
    # demo-command
 
-   Quick keyboard entry point for running the demo flow on a
-   target file. Connectors land in the next sub-step.
+   Quick entry point for running the demo flow on a target file.
+   Connectors land in the next sub-step.
    ```
 
 3. `notes/todo.md`, classified as `kind: markdown` today
@@ -96,7 +81,6 @@ Create these five files (with `Write`), exactly in this order. Per §Provider de
      Live list of things to review in the demo. Will become the
      hub that points to the rest of the fixture in the next
      sub-step.
-   tags: [notes, demo]
    ---
 
    # Pending
@@ -112,7 +96,6 @@ Create these five files (with `Write`), exactly in this order. Per §Provider de
      Static reference notes the rest of the demo points at. The hub
      reaches it with a bare `@`-mention, which stays a faint guess
      (0.50) because it can't resolve to a known entity.
-   tags: [notes, demo]
    ---
 
    # Demo Guideline
@@ -135,7 +118,6 @@ Create these five files (with `Write`), exactly in this order. Per §Provider de
      Sibling of demo-guideline. The hub reaches it with an
      `@`-mention that carries the `.md` extension, so the link
      resolves to this file and lands certain (1.00).
-   tags: [notes, demo]
    ---
 
    # Demo Guideline 2

package/dist/cli/tutorial/sm-tutorial/references/part-live-site.md

@@ -80,8 +80,8 @@ Tell the tester:
 >
 > **Step 2, brief the editor** (`@content-editor`). The check found
 > nothing to fix, so there is no brief to hand off this time, that is
-> the happy path. (Part 4 is where a link actually breaks and this
-> step earns its keep.)
+> the happy path. (Maintaining the harness is where a link actually
+> breaks, and that is where this step earns its keep.)
 >
 > **Step 3, follow the deploy runbook** (`docs/DEPLOY.md`). It lists:
 > generate the pages (done), run the link check (done), start the
@@ -122,7 +122,7 @@ Tell the tester:
 > Last step, the fun one. In your terminal, run these two commands:
 >
 > `npm install` downloads the one small library the server needs
-> (Express). If you already ran it in Part 3 it just confirms it is
+> (Express). If you already ran it earlier it just confirms it is
 > there. Then `node server.js` starts the server; it prints a line
 > like `Listening on http://localhost:3000`.
 >

package/dist/cli/tutorial/sm-tutorial/references/part-maintain.md

@@ -1,4 +1,4 @@
-# Part 4: Maintain the site (step library, `maintain`)
+# Part 4: Maintain the harness (step library, `maintain`)
 
 This is the upkeep part. The harness from Part 2 is wired and clean; real projects drift, links break, drafts pile up, names collide. Here the tester breaks something on purpose and fixes it, meets the analyzer catalogue that catches those problems, finds an orphan nobody links to, clears a reserved-name warning, and learns the `.sm` companion files that carry the tool's bookkeeping. `pace: auto-advance` (walk straight into the next chapter once one is marked done), `preflight: seed` (it builds on the portfolio harness from Parts 1 and 2, reusing the accumulated state when its predecessors are done, no fresh fixture of its own). Shared conventions (tone, provider detection / substitution, the `> ` rendering rule, the per-step cycle) live in `_core.md`; do not restate them here.
 
@@ -113,7 +113,7 @@ Wait for confirmation. Mark `analyzers`: done.
 
 ## Chapter `orphans` - A page nobody links to (~3 min)
 
-**Context**: a different kind of loose end. A node can be perfectly valid and still be an orphan: nothing in the harness links to it. We create a draft page that no one references; it lands on the **Map** as a floating dot, and `sm show` confirms it has no incoming links. The point is to separate three ideas the tester now has names for: orphan (nothing points at it) vs broken-ref (a link with no target) vs issue (a rule violation). Note: orphan-ness is a property of the graph (visible on the Map / inspector), there is no `sm check` analyzer for it. The separate `sm orphans` verb is unrelated, it surfaces history stranded by a rename, not unlinked pages, so do NOT use it here.
+**Context**: a different kind of loose end. A node can be perfectly valid and still be an orphan: nothing in the harness links to it. We create a draft page that no one references; it lands on the **Map** as a floating dot, and `sm show` confirms it has no incoming links. The point is to separate three ideas the tester now has names for: orphan (nothing points at it) vs broken-ref (a link with no target) vs issue (a rule violation). Note: orphan-ness is a property of the graph (visible on the Map / inspector), there is no `sm check` analyzer for it. The separate `sm orphans` verb is unrelated (it surfaces history stranded by a rename, not unlinked pages), so do NOT run it or bring it up with the tester here.
 
 `Write` `docs/draft.md` (markdown kind), a half-finished page nobody has wired up yet:
 
@@ -123,7 +123,6 @@ name: draft
 description: |
   Half-finished page nobody links to yet. Here to show what an
   orphan looks like: a valid node with no incoming connectors.
-tags: [docs, portfolio, draft]
 ---
 
 # Draft page
@@ -163,16 +162,12 @@ Tell the tester:
 > - **issue**: any rule violation `sm check` reports (broken-ref is
 >   one family; name-reserved, self-loop and the rest are others).
 >
-> An orphan is not automatically a problem (a draft you have not wired
-> up yet is fine), it is just skill-map pointing out the page is not
-> reachable from anywhere. When you link to it later, it stops being
-> an orphan.
->
-> (Heads up: there is also an `sm orphans` command, but it is a
-> different tool. It tracks history left stranded when you rename a
-> file that had tracked state, not pages with no links, so it will
-> not list `docs/draft`. Running it here prints "no orphan issues",
-> which is correct.)
+> An orphan is not automatically a problem. Sometimes it is a draft you
+> have not wired up yet; sometimes it is a node you deliberately keep on
+> its own, isolated on purpose, and that is just as valid. skill-map is
+> only pointing out that the page is not reachable from anywhere, not
+> telling you to fix it: if you link to it later it stops being an
+> orphan, and if you never do, that was your call, not an error.
 >
 > Did `docs/draft` land as a floating dot, with `sm show` confirming
 > no links in?
@@ -191,11 +186,6 @@ name: init
 description: |
   Bootstraps a fresh portfolio scaffold. Named init on purpose, to
   collide with the runtime built-in and trigger name-reserved.
-args:
-  - name: target
-    type: path
-    description: Folder to scaffold into.
-    required: true
 ---
 
 # init
@@ -280,6 +270,15 @@ sm sidecar annotate AGENTS.md
 > layer (gitignored), so each contributor consents on their own
 > checkout and the choice never travels through git.
 >
+> **Tip:** that `.sm` is also where the inspector gets a node's
+> **Metadata**. With the live `sm` still running, click the `AGENTS`
+> node on the **Map**: the inspector now shows a **Metadata** section
+> that was not there before you created the companion file. It reads
+> straight from `AGENTS.sm`, so a node with no `.sm` has no Metadata
+> section at all. For now it reads **never bumped**, because you only
+> scaffolded the file; once you start running `sm bump AGENTS.md` that
+> panel fills in **Created** and **Last bumped**.
+>
 > Did the prompt appear, and does `AGENTS.sm` exist now?
 
 Wait for confirmation. You MAY use `Read` on `AGENTS.sm` to verify it landed. Mark `sidecar`: done. Last chapter of the part: apply §Closing a part (the close names the part by its title and routes back to the menu).

package/dist/cli/tutorial/sm-tutorial/references/part-project-kickoff.md

@@ -139,7 +139,6 @@ runbook), so Part 4's maintenance beats have something to point at.
 name: style-guide
 description: |
   Writing and markup conventions every portfolio page follows.
-tags: [docs, portfolio]
 ---
 
 # Style guide
@@ -155,7 +154,6 @@ tags: [docs, portfolio]
 name: deploy-runbook
 description: |
   How the portfolio gets published once the pages are written.
-tags: [docs, portfolio]
 ---
 
 # Deploy runbook