@skill-map/cli 0.53.4 → 0.53.6

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)
 
@@ -145,7 +147,7 @@ every other `<cwd>` mention.
 >    output, and I verify.
 > 2. **A second terminal**: open it now (new window or tab), then run
 >    the command below so it's anchored **exactly to this folder**.
->    That's where you copy and paste every `sm` command.
+>    That's where you copy and paste every command I give you to run.
 
 ```bash
 cd <cwd>
@@ -195,12 +197,13 @@ the files the prologue's own chapters lay as taught steps, exactly this
 set: `<provider_dir>/agents/demo-agent.md`,
 `<provider_dir>/skills/demo-skill/`,
 `<provider_dir>/commands/demo-command.md`, `notes/todo.md`,
-`notes/demo-guideline.md`, `notes/private-credentials.md`. This is the
+`notes/demo-guideline.md`, `notes/demo-guideline2.md`,
+`notes/private-credentials.md`. This is the
 single source for that list. Four entry points delete exactly this set
 when the prologue ran first in the dir: `portfolio-init`, the campaign
-`seed` fast-forward, and `backstage-init` (Part 7), each so the part's
+`seed` fast-forward, and `backstage-init` (Part 6), each so the part's
 own fixture starts from a clean slate, plus start-over (§Menu, resume,
-wrap-up). Part 8 `cli` is the inverse
+wrap-up). Part 7 `cli` is the inverse
 consumer: its `prologue-built` seed *lays* this fixture (the
 connector-chapter subset, without `notes/private-credentials.md`)
 instead of deleting it, see `fixtures.md` §Seed snapshots. Keep the list
@@ -332,7 +335,7 @@ When a part begins, honour its `preflight` from the manifest:
   `preflight: seed` to fast-forward into them directly, see the `seed`
   case below; `portfolio-init` is just Part 1's flavour of that,
   handling the Part 0 to Part 1 transition.)
-- **`backstage-init`** (Part 7 `extend`): the part teaches plugins on
+- **`backstage-init`** (Part 6 `extend`): the part teaches plugins on
   its own **master fixture**, distinct from both the demo and the
   portfolio, so on entry make the master fixture the only one on disk.
   Silently, with no narration: (1) clear whatever prior-part fixture is
@@ -352,10 +355,10 @@ When a part begins, honour its `preflight` from the manifest:
   `Write` the part's fixture (read `references/fixtures.md` for the
   verbatim `master-agent` / `master-skill` / `notes/ideas` files; skip
   kinds the provider doesn't claim). If nothing needed clearing and the
-  dir was already initialised with the master fixture in place (Part 7
+  dir was already initialised with the master fixture in place (Part 6
   re-entry), that is fine: skip the init and just ensure the fixture
   files are present.
-- **`seed: prologue-built`** (Part 8 `cli`): the part reads the **Part 0
+- **`seed: prologue-built`** (Part 7 `cli`): the part reads the **Part 0
   demo fixture**, NOT the cumulative portfolio, so on entry make that
   fixture the one on disk. Read the state, then:
   - Demo fixture already present (the tester came straight from the
@@ -374,7 +377,15 @@ When a part begins, honour its `preflight` from the manifest:
   On entry, read the state file:
   - If every predecessor campaign part up the `prereq` chain is `done`
     → reuse the accumulated state; an `sm scan` to refresh is enough,
-    nothing to lay.
+    nothing to lay. **`mcp` is the exception**: it is ordered last,
+    after `extend` (Part 6) and `cli` (Part 7), which both replace the
+    portfolio on disk with their own master / demo fixture, so its
+    accumulated state cannot be trusted to still be the portfolio.
+    `mcp` therefore ALWAYS re-lays its `harness-connected` snapshot on
+    entry (clearing a master / demo fixture first if one is present,
+    the same clears the `backstage-init` and `prologue-built` cases
+    do), then `sm init` if `.skill-map/` is missing and `sm scan`,
+    exactly like the fast-forward branch below.
   - Else → **fast-forward, silently** (backstage, do not narrate the
     plumbing): first, if the prologue ran first in this dir, clear the
     full Part 0 demo fixture set (§Fixture and state templates) so the
@@ -413,7 +424,7 @@ All three are specified in `_core.md`:
   the **numbered start menu** (Part 0 is option 1, the recommended
   first pick); the menu (the ToC from `_manifest.yml`, numbered,
   completed parts ticked, `planned` parts hidden, `prereq` gating only
-  seedless parts, none today since Part 8 `cli` now self-seeds) is the
+  seedless parts, none today since Part 7 `cli` now self-seeds) is the
   entry point on the first
   invocation and after every part closes / on resume. Render it with
   the format in `_core.md` §Menu format.
@@ -421,7 +432,7 @@ All three are specified in `_core.md`:
   wipe list is whatever the tester's parts actually created:
   `tutorial-state.yml`, `findings.md`, `.skillmapignore`,
   `.skill-map/`, the full Part 0 demo fixture set (§Fixture and state
-  templates), the Part 7 fixture if `extend` ran
+  templates), the Part 6 fixture if `extend` ran
   (`<provider_dir>/agents/master-agent.md`,
   `<provider_dir>/skills/master-skill/`, `notes/ideas.md`,
   `.skill-map/plugins/`), `link-validation/` if the CLI part ran,

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.
@@ -293,11 +318,11 @@ For every chapter:
   §Menu format).
 - **Which parts to list**: parts in `order`, `status: active` only
   (`planned` parts are hidden). A part with a `seed` (the campaign
-  parts plus Part 8 `cli`) is always shown, even out of order, its
+  parts plus Part 7 `cli`) is always shown, even out of order, its
   `preflight: seed` fast-forwards the project into it (SKILL.md
   §Entering a part). A part with a `prereq` but NO `seed` would be
   shown only once its `prereq` is `done`; no active part is in that
-  state today (Part 8 `cli` used to be, now it self-seeds).
+  state today (Part 7 `cli` used to be, now it self-seeds).
 - **After the tester picks**: walk that part; when it ends, run
   §Closing a part (a tester-facing close, then this menu).
 - **Adding content** is data-only: a new chapter in a part (or a new
@@ -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

@@ -51,7 +51,7 @@ parts:
       - id: ignore          ; title: "Silence a file via .skillmapignore"  ; est_min: 2
 
   - id: extend
-    order: 7
+    order: 6
     title: "Extend skill-map for the site"
     # Spans three chapter libraries; dispatch by chapter-id prefix:
     #   settings-*  -> part-settings.md
@@ -81,7 +81,7 @@ parts:
       - id: authoring-6-upgrade      ; title: "Try `sm plugins upgrade`" ; est_min: 2
 
   - id: cli
-    order: 8
+    order: 7
     title: "The CLI in depth"
     step_file: part-cli.md
     pace: auto-advance
@@ -142,12 +142,13 @@ parts:
     prereq: connect-harness
     status: active
     chapters:
-      - id: generate ; title: "The agent generates the HTML in public/" ; est_min: 3
-      - id: serve    ; title: "node server.js: your portfolio, live next to the graph" ; est_min: 3
+      - id: generate    ; title: "The agent generates the HTML in public/" ; est_min: 3
+      - id: serve       ; title: "node server.js: your portfolio, live next to the graph" ; est_min: 3
+      - id: editor-live ; title: "Let the content-editor agent write a posts page (optional)" ; est_min: 3
 
   - id: maintain
     order: 4
-    title: "Maintain the site"
+    title: "Maintain the harness"
     step_file: part-maintain.md
     pace: auto-advance
     preflight: seed
@@ -157,14 +158,13 @@ parts:
     chapters:
       - id: broken-ref   ; title: "A ref breaks (you rename DEPLOY.md)" ; est_min: 3
       - id: analyzers    ; title: "The analyzer catalogue (what sm check catches)" ; est_min: 3
-      - id: orphans      ; title: "Orphans (sm orphans)" ; est_min: 2
+      - id: orphans      ; title: "Orphans (a page nobody links to)" ; est_min: 2
       - id: reserved     ; title: "Reserved names" ; est_min: 2
       - id: sidecar      ; title: "Annotations .sm and consent" ; est_min: 3
-      - id: versions     ; title: "Versions: sm bump and history" ; est_min: 2
 
   - id: mcp
-    order: 5
-    title: "MCP"            # a chapter apart, just before the finale
+    order: 8
+    title: "MCP"            # standalone appendix, ordered last; ALWAYS re-seeds harness-connected (extend/cli wipe the portfolio before it)
     step_file: part-mcp.md
     pace: auto-advance
     preflight: seed
@@ -175,7 +175,7 @@ parts:
       - id: mcp-node ; title: "content-editor declares an MCP tool; the mcp:// node appears" ; est_min: 3
 
   - id: live-site
-    order: 6
+    order: 5
     title: "Ship the site (the full publish pipeline)"  # the finale / climax
     step_file: part-live-site.md
     pace: auto-advance

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

@@ -1,7 +1,7 @@
 # Fixture templates
 
 Fixtures the orchestrator lays for the auto-fixtured parts. Two full
-templates live here: the **master fixture** (Part 7, "Extend
+templates live here: the **master fixture** (Part 6, "Extend
 skill-map", `backstage-init`) right below, and the **portfolio
 fixture** (Part 1, "The project from zero", `portfolio-init`) at the
 end of this file. The **Part 0 demo fixture** is not templated here:
@@ -18,7 +18,7 @@ context for. Holds for every command fixture wherever it is defined
 (today: the prologue `demo-command`, the `publish` command, and the
 `reserved` chapter's `init`).
 
-## Master fixture (Part 7): layout (per provider)
+## Master fixture (Part 6): layout (per provider)
 
 Per §Provider detection in `SKILL.md`, the `<provider_dir>`
 placeholder resolves to `.claude/` or `.agents/skills/` depending
@@ -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
@@ -146,7 +130,7 @@ Per finding:
 Laid backstage before the tester's `sm init` in Part 1. The Express
 skeleton (`server.js`, `package.json`, `public/index.html`) is plain
 scaffolding, not `.md`, so the scan ignores it; it makes the project
-real and runnable (Part 3 runs it, Part 6 ships it). The one boot node is the
+real and runnable (Part 3 runs it, Part 5 ships it). The one boot node is the
 handbook `AGENTS.md`. On `agent-skills` / Antigravity (no `agent`
 kind) the harness still works: the agent member is created as a skill
 in a later chapter.
@@ -224,7 +208,7 @@ Append to the universal `.skillmapignore` (written in pre-flight, see
 ## Seed snapshots (for `preflight: seed`)
 
 When the orchestrator enters a seedable part out of order (the campaign
-parts when their predecessors are not `done`, or Part 8 `cli` when the
+parts when their predecessors are not `done`, or Part 7 `cli` when the
 demo fixture is not the one on disk), it fast-forwards the project by
 laying the snapshot below, then `sm init` (if `.skill-map/` is missing) +
 `sm scan`. These are **checklists, not content**: each row names a file
@@ -259,16 +243,16 @@ Everything in `harness-built`, PLUS the Part 2 wiring:
 After laying a campaign snapshot the map matches the state a tester would
 have at the END of the part just before the one being entered.
 
-### Seed snapshot: `prologue-built` (Part 8 `cli`)
+### Seed snapshot: `prologue-built` (Part 7 `cli`)
 
 NOT cumulative and NOT the portfolio: this is the **Part 0 demo
-fixture**, the five standalone demo nodes with `notes/todo` wired as the
+fixture**, the six standalone demo nodes with `notes/todo` wired as the
 hub, the clean state (`✓ No issues`) at the end of the prologue's
-connector chapters. Part 8 only reads it. Because it is a different
+connector chapters. Part 7 only reads it. Because it is a different
 fixture from the portfolio, entry first resets any portfolio on disk
 (see SKILL.md §Entering a part, the `cli` case).
 
 1. `<provider_dir>/agents/demo-agent.md`  <-  SKILL.md §Fixture and state templates. (The `.skillmapignore` is universal, already on disk from pre-flight; the snapshot does not lay it.)
-2. `<provider_dir>/skills/demo-skill/SKILL.md`, `<provider_dir>/commands/demo-command.md`, `notes/todo.md`, `notes/demo-guideline.md`  <-  part-fundamentals.md, chapter `kinds`.
-3. EDIT `notes/todo.md`: wire the hub bullets pointing at the four other nodes  <-  part-fundamentals.md, chapter `connectors`.
+2. `<provider_dir>/skills/demo-skill/SKILL.md`, `<provider_dir>/commands/demo-command.md`, `notes/todo.md`, `notes/demo-guideline.md`, `notes/demo-guideline2.md`  <-  part-fundamentals.md, chapter `kinds`.
+3. EDIT `notes/todo.md`: wire the hub bullets pointing at the five other nodes  <-  part-fundamentals.md, chapter `connectors`.
 

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

@@ -1,6 +1,6 @@
-# Part 7 (c): Extend skill-map - build plugins (step library, `authoring-*` ids)
+# Part 6 (c): Extend skill-map - build plugins (step library, `authoring-*` ids)
 
-Step bodies for the plugin-authoring chapters of Part 7.
+Step bodies for the plugin-authoring chapters of Part 6.
 The SKILL.md orchestrator dispatches each `authoring-*` chapter id
 here; `settings-*` ids it dispatches to `part-settings.md`.
 

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

@@ -1,4 +1,4 @@
-# Part 8: The CLI in depth - step library
+# Part 7: The CLI in depth - step library
 
 The deep-dive into the rest of the CLI: browsing verbs, ASCII graph + export, broken-ref issues, the `.sm` annotation consent prompt, and validating links to folders outside the scan scope. `pace: auto-advance` (walk straight into the next chapter's Announcement once one is marked done) and `preflight: seed` with the `prologue-built` snapshot: it self-seeds its own copy of the Part 0 demo fixture, so it works even if the campaign already replaced that fixture with the portfolio (see SKILL.md §Entering a part, the `cli` case). Shared conventions (tone, provider detection / substitution, the `> ` rendering rule, the per-step cycle) live in `_core.md`; do not restate them here.
 
@@ -13,7 +13,7 @@ sm show .claude/skills/demo-skill/SKILL.md
 sm check
 ```
 
-Expected: you see the 5 fixture nodes listed with their kind: `demo-skill` (skill), `demo-agent` (agent), `demo-command` (command), `notes/todo` (`markdown`, the catch-all per the `kinds` chapter), and `notes/demo-guideline` (`markdown` as well, the target of the hub's `references` link). `check` reads the persisted `scan_issues` table, it does NOT re-walk the filesystem. The fixture is clean (the connector / inspector chapters captured the latest state before Ctrl+C), so the verb prints `✓ No issues`. We will plant one in the `issues` chapter and watch the rule catch it after a fresh `sm scan`.
+Expected: you see the 6 fixture nodes listed with their kind: `demo-skill` (skill), `demo-agent` (agent), `demo-command` (command), `notes/todo` (`markdown`, the catch-all per the `kinds` chapter), and the two guideline notes `notes/demo-guideline` and `notes/demo-guideline2` (both `markdown`, the hub's confidence pair: a faint `mentions` at 0.50 and a resolved `references` at 1.00). `check` reads the persisted `scan_issues` table, it does NOT re-walk the filesystem. The fixture is clean (the connector / inspector chapters captured the latest state before Ctrl+C), so the verb prints `✓ No issues`. We will plant one in the `issues` chapter and watch the rule catch it after a fresh `sm scan`.
 
 Mark `browse`: done.
 
@@ -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,9 +46,9 @@ 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:
+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:
+> Create `.claude/commands/publish.md` with exactly this content (the first line is `---`, nothing before it):
 
 ```markdown
 ---
@@ -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
@@ -99,6 +84,12 @@ Continue the tester message:
 > One node, three connectors, three link kinds. The harness is
 > starting to look like a real graph.
 >
+> 💡 Tip: to tidy every node into a clean layout, click the
+> **Re-arrange layout** button in the map toolbar (tooltip
+> "Re-arrange the visible nodes"). Handy whenever the graph starts to
+> look crowded. If you've dragged nodes by hand it asks for
+> confirmation first, otherwise it just re-arranges.
+>
 > Did the three arrows appear?
 
 Wait for confirmation. You MAY use `Read` on the file afterwards to verify it landed. Mark `publish`: done.
@@ -150,34 +141,43 @@ Wait for confirmation. You MAY use `Read` on the two files afterwards to verify
 
 ## Chapter `confidence` - How sure is each link (~3 min)
 
-**Context**: the connectors do not all look equally solid, and that is on purpose. Skill-map estimates how sure it is of every connection and shows that as opacity. Here we open the Inspector on a real harness node and read the per-link confidence numbers, mirroring the prologue's connectors beat but on the portfolio.
+**Context**: skill-map estimates how sure it is of every connection and shows that as opacity. In this harness every link resolves to a real node, so they all read solid (1.00); the faint, low-confidence case is the one the tester met in the prologue (the bare `@demo-guideline` mention that had nothing to resolve to). Here we open the Inspector on a real harness node, read the all-solid numbers, and point back to that prologue contrast. Mirrors the prologue's connectors beat on the portfolio.
 
 No file edits in this chapter, pure observation on the graph the tester just built.
 
 Tell the tester:
 
 > Last beat of this part: how sure is skill-map about each connection?
-> Look closely at the **Map** and you'll notice the arrows are not all
-> equally solid. The more confident skill-map is that a link is real,
-> the more solid the arrow; the less sure, the more translucent.
+> It estimates a **confidence** for every link and draws it as opacity:
+> the surer a connection is real, the more solid the arrow; the less
+> sure, the more translucent.
 >
 > Open the Inspector for the `publish` node (click it on the **Map**).
 > Scroll down to the **Connections** panel and read the **Outgoing**
-> rows. Each row shows the link kind and a confidence badge:
+> rows. Each row shows the link kind and a confidence badge, and here
+> every one reads **1.00**:
+>
+> - `publish -> docs/DEPLOY.md` (`references`) is a markdown link to a
+>   file that exists on disk, so skill-map is certain.
+> - `publish -> content-editor` (`mentions`) resolves to the real
+>   content-editor agent, and `publish -> check-links` (`invokes`)
+>   resolves to the real check-links skill, so both are certain too.
 >
-> - `publish -> docs/DEPLOY.md` (`references`) reads **1.00** and looks
->   solid: it is a markdown link to a file that really exists on disk,
->   so skill-map is certain.
-> - `publish -> content-editor` (`mentions`) and `publish ->
->   check-links` (`invokes`) read high too, because each `@handle` and
->   `/slash` token resolves cleanly to a node that exists in your
->   harness.
+> Your whole harness reads solid because every link lands on a real
+> node, that is what a clean, fully wired graph looks like. So what
+> does a *low*-confidence connector look like? You saw one back in the
+> prologue: `@demo-guideline` was a bare `@`-mention pointing at a
+> note, and a bare `@handle` only firmly resolves to an agent, so it
+> had nothing to land on and stayed a soft guess at **0.50**, drawn
+> translucent. The fix there was one character: `@demo-guideline2.md`,
+> the same handle plus a `.md`, resolved to the real file and jumped to
+> **1.00**.
 >
 > The number is the certainty, and the opacity on the canvas is just
 > that number drawn as transparency: a glance at the **Map** tells you
 > which connections are rock solid and which are skill-map's best
 > guess.
 >
-> Do you see the confidence badges in the Inspector?
+> Do you see every badge reading 1.00 in the Inspector?
 
 Wait for confirmation. Mark `confidence`: done. Last chapter of the part: apply §Closing a part (the close names the part by its title and routes back to the menu; do NOT lead into the next part from here).