@skill-map/cli 0.53.3 → 0.53.5

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

@@ -145,7 +145,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>
@@ -160,9 +160,19 @@ cd <cwd>
 ### 5. Write the universal files and show the menu
 
 Pre-flight does NOT pre-lay any part's fixture and does NOT auto-enter
-a part. It writes only the two files every part needs, then routes to
-the menu:
-
+a part. It writes only the universal files every part needs, then
+routes to the menu:
+
+- `.skillmapignore` (block below). Universal, not a part fixture:
+  every part scans, and every part needs the tutorial's own machinery
+  kept out of the map (this skill's `.claude/skills/sm-tutorial/` dir,
+  `findings.md`, `tutorial-state.yml`, the CLI part's
+  `link-validation/`, and so on). Writing it here, once, before any
+  `sm init`, is what guarantees no part-entry can forget it on a
+  direct jump from the menu. `sm init` only writes `.skillmapignore`
+  when it is absent, so the tester's later `sm init` leaves this one
+  intact. Parts that need more append their own lines on entry (the
+  portfolio's `node_modules/` and `public/`).
 - `findings.md` (block below).
 - `tutorial-state.yml` (template below; it starts with `parts: {}`,
   empty, a part's entry is added the first time the tester picks it).
@@ -171,14 +181,31 @@ Then **route** per §Routing + menu in `_core.md`: render the **start
 menu** (numbered, Part 0 the prologue as option 1, the recommended
 first pick). The tester picks a part by number; that part's own
 `preflight` (see §Entering a part) lays its fixture when it begins.
-Part 0's demo fixture (the `demo-agent` + the demo `.skillmapignore`,
-blocks below) is laid by its `taught-init` entry, not here.
+Part 0's demo fixture (the `demo-agent` block below) is laid by its
+`taught-init` entry, not here.
 
 ## Fixture and state templates
 
-The `findings.md` and `tutorial-state.yml` here are universal (written
-in pre-flight); the `demo-agent.md` + the demo `.skillmapignore` are
-Part 0's fixture (laid by its `taught-init` entry).
+The `.skillmapignore`, `findings.md`, and `tutorial-state.yml` here are
+universal (written in pre-flight); the `demo-agent.md` is Part 0's
+fixture (laid by its `taught-init` entry).
+
+The **full Part 0 demo fixture** is the boot `demo-agent.md` above plus
+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/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 6), each so the part's
+own fixture starts from a clean slate, plus start-over (§Menu, resume,
+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
+here in sync if a prologue chapter adds or drops a demo file.
 
 `<provider_dir>/agents/demo-agent.md`:
 ```markdown
@@ -284,60 +311,96 @@ When a part begins, honour its `preflight` from the manifest:
 
 - **`taught-init`** (Part 0): silently, before the tester's `sm init`
   in the `init` chapter, `Write` the demo fixture (the
-  `<provider_dir>/agents/demo-agent.md` boot node + the demo
-  `.skillmapignore`, both in the §Fixture blocks above), substituting
-  `<provider_dir>` per detection. Write `.skillmapignore` BEFORE the
-  tester runs `sm init` so the first scan never sees the tutorial's
-  own files (`sm init` only writes that file when absent). The tester
-  runs `sm init` themselves in the first chapter.
+  `<provider_dir>/agents/demo-agent.md` boot node, in the §Fixture
+  blocks above), substituting `<provider_dir>` per detection. The
+  universal `.skillmapignore` is already on disk from pre-flight, so
+  the first scan never sees the tutorial's own files; nothing to lay
+  here for it. The tester runs `sm init` themselves in the first
+  chapter (`sm init` only writes `.skillmapignore` when absent, so it
+  leaves the pre-flight one intact).
 - **`portfolio-init`** (Part 1 `project-kickoff`): the campaign's
   real project begins. Backstage, before the tester's `sm init` in
   the `kickoff` chapter: (1) if the prologue ran first in this dir,
-  clear its demo fixture so the map starts clean, delete ONLY the
-  Part 0 fixture files (`<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`) plus the
+  clear its demo fixture so the map starts clean, delete ONLY the full
+  Part 0 demo fixture set (§Fixture and state templates) plus the
   stale `.skill-map/` DB (a fresh `sm init` rebuilds it), never the
   tester's own files; (2) `Write` the portfolio fixture from
   `references/fixtures.md` (the Express skeleton + the handbook
-  `AGENTS.md`); (3) ensure `.skillmapignore` carries the portfolio
-  additions (`node_modules/`, `public/`). The tester runs `sm init`
+  `AGENTS.md`); (3) append the portfolio additions (`node_modules/`,
+  `public/`) to the universal `.skillmapignore` pre-flight already
+  wrote (its tutorial internals are already there). The tester runs `sm init`
   themselves in the first chapter. (The later campaign parts use
   `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`): silently, with no
-  narration: run `sm init --no-scan` from the cwd, then `Edit` the
-  freshly created `.skillmapignore` to append the tutorial's
-  internal entries (the `sm-tutorial.md` / `findings.md` /
-  `tutorial-state.yml` / skill-dir block above), then `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 `sm init --no-scan` fails because
-  the dir was already initialised by an earlier part, that is fine:
-  the DB already exists, skip the init and just ensure the fixture
+- **`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
+  present so the master map starts clean (never the tester's own files;
+  the universal `.skillmapignore` stays):
+  - Part 0 demo fixture present (the tester came from the prologue) →
+    delete the full Part 0 demo fixture set (§Fixture and state
+    templates);
+  - portfolio fixture present instead (the tester ran the campaign) →
+    delete everything `portfolio-init` and the campaign chapters lay
+    (see `fixtures.md` §Portfolio fixture + §Seed snapshots);
+  - in either of those cases also drop the stale `.skill-map/` DB so a
+    fresh init rebuilds it.
+  (2) run `sm init --no-scan` from the cwd (the universal
+  `.skillmapignore` from pre-flight is already on disk, so init leaves
+  it intact and the tutorial's own files stay out of the scan); (3)
+  `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 6
+  re-entry), that is fine: skip the init and just ensure the fixture
   files are present.
-- **`reuse`** (Part 8 `cli`): assumes the prologue fixture and
-  `.skill-map/` already exist; nothing to lay. The menu offers Part 8
-  only once its `prereq` (`fundamentals`) is done, so the state is
-  there. If `.skill-map/` is somehow missing, point the tester back to
-  the prologue rather than re-initialising mid-part.
+- **`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
+    prologue) → just `sm scan`, nothing to lay.
+  - **Portfolio** fixture present instead (the tester ran the campaign)
+    → clear it first (the inverse of `portfolio-init`: delete the
+    portfolio fixture, everything `portfolio-init` and the campaign
+    chapters lay, see `fixtures.md` §Portfolio fixture + §Seed snapshots,
+    plus the stale `.skill-map/` DB; never the tester's own files), then
+    lay the `prologue-built` snapshot from `fixtures.md` (§Seed
+    snapshots), `sm init`, `sm scan`.
+  - Nothing there → lay the snapshot, `sm init`, `sm scan`.
 - **`seed`** (the campaign parts `connect-harness` / `run-harness` /
   `maintain` / `mcp` / `live-site`): the part builds on the accumulating portfolio
   harness, but the tester may have jumped straight here from the menu.
   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): lay the part's `seed` snapshot from
+    plumbing): first, if the prologue ran first in this dir, clear the
+    full Part 0 demo fixture set (§Fixture and state templates) so the
+    seeded campaign map does not carry the prologue's demo nodes (the
+    `sm scan` below reconciles the removed files out of the DB). Then
+    lay the part's `seed` snapshot from
     `references/fixtures.md` (§Seed snapshots) by following its
     checklist, copy each file's canonical content from the chapter the
     row names, apply the `EDIT` rows on top, substituting
     `<provider_dir>` and skipping provider-unsupported kinds per
-    `_core.md`. Then run `sm init` if `.skill-map/` is missing, then
-    `sm scan` so the map reflects the seeded harness. Mark the skipped
+    `_core.md`. The snapshot's `.skillmapignore` additions
+    (`node_modules/`, `public/`) are appended to the universal
+    `.skillmapignore` pre-flight already wrote, so the tutorial's own
+    `.claude/skills/sm-tutorial/` files stay out of the scan even on a
+    direct jump here. Then run `sm init` if `.skill-map/` is missing
+    (it will not overwrite that `.skillmapignore`), then `sm scan` so
+    the map reflects the seeded harness. Mark the skipped
     predecessor campaign parts `skipped` in the state (they stay in the
     menu for later). Then emit exactly ONE tester-facing line:
 
@@ -359,18 +422,15 @@ 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
-  the parts that have no `seed`) is the entry point on the first
+  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.
 - **Resume / restart**: §Resume / restart. On start-over, the exact
   wipe list is whatever the tester's parts actually created:
   `tutorial-state.yml`, `findings.md`, `.skillmapignore`,
-  `.skill-map/`, the Part 0 fixture
-  (`<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`), the
-  Part 7 fixture if `extend` ran
+  `.skill-map/`, the full Part 0 demo fixture set (§Fixture and state
+  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

@@ -149,9 +149,10 @@ first kind quoted, the second kind never.
    pre-flight only (both silent, no narration):
    - `sm version` ONCE to verify the install.
    - `sm init --no-scan` ONCE for parts whose manifest entry is
-     `preflight: backstage-init`, to provision `.skill-map/` and the
-     bundled `.skillmapignore` BEFORE any scan, so you can append the
-     tutorial's internal entries before the scanner sees the fixture.
+     `preflight: backstage-init`, to provision `.skill-map/` BEFORE
+     any scan. The universal `.skillmapignore` written in pre-flight
+     already keeps the tutorial's own files out, so there is nothing
+     to append here.
    Parts with `preflight: taught-init` (e.g. Part 0) do NOT run
    `sm init` in pre-flight, the tester runs it as the first taught
    step. You also DO NOT run `sm plugins create` on their behalf;
@@ -162,10 +163,10 @@ first kind quoted, the second kind never.
    `Read` files to verify what the tester modified. Everything else
    the tester runs.
 2. **Configuration files have two-mode access.**
-   - **Backstage setup (you DO edit)**: appending the tutorial's
-     internal entries to `.skillmapignore` right after a backstage
-     `sm init --no-scan`; writing the state file; writing fixture
-     `.md` files.
+   - **Backstage setup (you DO edit)**: writing the universal
+     `.skillmapignore` in pre-flight and appending a part's own
+     additions on entry (the portfolio's `node_modules/` / `public/`);
+     writing the state file; writing fixture `.md` files.
    - **Teach moment (you DO NOT edit)**: any change to
      `.skill-map/settings.json`, `.skill-map/settings.local.json`,
      `.skillmapignore`, or `.gitignore` that is part of a chapter
@@ -292,10 +293,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) 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` (Part 8 `cli`) is shown only once
-  its `prereq` is `done`.
+  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 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

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

@@ -15,11 +15,12 @@
 #   step_files   list form when a part spans several files; dispatch
 #                by chapter-id prefix.
 #   pace         per-step | auto-advance  (see _core.md per-step cycle).
-#   preflight    taught-init | backstage-init | portfolio-init | seed |
-#                reuse  (see _core.md rule #1 + SKILL.md §Entering a part).
-#   seed         which cumulative snapshot to fast-forward to when this
-#                part is entered out of order (see fixtures.md §Seed
-#                snapshot:*). Campaign parts only.
+#   preflight    taught-init | backstage-init | portfolio-init | seed
+#                (see _core.md rule #1 + SKILL.md §Entering a part).
+#   seed         which snapshot to fast-forward to when this part is
+#                entered out of order (see fixtures.md §Seed snapshot:*).
+#                Campaign parts use a cumulative portfolio snapshot;
+#                Part 8 `cli` uses the standalone `prologue-built` demo.
 #   prereq       recommended predecessor. Gates the menu ONLY for a part
 #                with NO `seed`; a seedable part is always shown (its
 #                seed bridges the gap, predecessors get marked `skipped`).
@@ -50,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
@@ -80,12 +81,13 @@ 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
-    preflight: reuse           # reuses the fundamentals fixture + DB
-    prereq: fundamentals       # menu offers this only after Part 0
+    preflight: seed            # self-seeds the Part 0 demo fixture
+    seed: prologue-built       # the prologue demo fixture (not the cumulative portfolio)
+    prereq: fundamentals       # recommended predecessor; cli self-seeds, so it is always shown
     status: active
     chapters:
       - id: browse           ; title: "list / show / check" ; est_min: 3
@@ -140,8 +142,9 @@ 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
@@ -155,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
@@ -173,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,12 +1,24 @@
 # Fixture templates
 
-Fixtures the orchestrator lays for the auto-fixtured parts. Two sets
-today: the **master fixture** (Part 7, "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.
-Read the set for the part being entered.
-
-## Master fixture (Part 7): layout (per provider)
+Fixtures the orchestrator lays for the auto-fixtured parts. Two full
+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:
+its content lives in `SKILL.md` (§Fixture and state templates) and
+`part-fundamentals.md`, and the `prologue-built` seed snapshot below
+just points at those. Read the set for the part being entered.
+
+**Authoring note (command fixtures).** A `command` node's H1 is a plain
+title (`# publish`), never the slash form (`# /publish`). The `slash`
+extractor reads a `/name` token anywhere in the body, the H1 included,
+as an `invoke`, so `# /publish` makes the command invoke itself and
+`sm check` emits a spurious `core/link-self-loop` the tester has no
+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 6): layout (per provider)
 
 Per §Provider detection in `SKILL.md`, the `<provider_dir>`
 placeholder resolves to `.claude/` or `.agents/skills/` depending
@@ -134,7 +146,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.
@@ -205,15 +217,16 @@ app.listen(port, () => console.log(`Portfolio live at http://localhost:${port}`)
 
 ### `.skillmapignore` additions
 
-Append to the portfolio `.skillmapignore` (on top of the tutorial
-internals from `SKILL.md`): `node_modules/` (the Express install) and
-`public/` (generated HTML, not part of the harness graph).
+Append to the universal `.skillmapignore` (written in pre-flight, see
+`SKILL.md`): `node_modules/` (the Express install) and `public/`
+(generated HTML, not part of the harness graph).
 
-## Seed snapshots (for `preflight: seed`, jumping into a campaign part)
+## Seed snapshots (for `preflight: seed`)
 
-When the orchestrator enters a campaign part out of order (its
-predecessors are not `done`), it fast-forwards the project by laying
-the snapshot below, then `sm init` (if `.skill-map/` is missing) +
+When the orchestrator enters a seedable part out of order (the campaign
+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
 and the chapter that holds its canonical content. Lay each file by
 copying the content from the named chapter (substitute `<provider_dir>`
@@ -243,6 +256,19 @@ Everything in `harness-built`, PLUS the Part 2 wiring:
 7. EDIT `AGENTS.md`: append the two hub bullets (mention `@content-editor`, invoke `/publish`)  <-  part-connect-harness.md, chapter `links`.
 8. EDIT `<provider_dir>/agents/content-editor.md`: add the `[style guide](../../docs/STYLE.md)` line  <-  part-connect-harness.md, chapter `links`.
 
-After laying a snapshot the map matches the state a tester would have at
-the END of the part just before the one being entered.
+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 7 `cli`)
+
+NOT cumulative and NOT the portfolio: this is the **Part 0 demo
+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 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`, `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`.
 
@@ -11,11 +11,11 @@ view-slot, and confirm the contribution lands in the UI.
 
 ## Precondition check
 
-Verify that `.skill-map/` exists in the cwd (pre-flight step 4 of
-the `SKILL.md` orchestrator ran `sm init --no-scan` and appended
-the master-tutorial's internal entries to `.skillmapignore`, so
-this is the expected state regardless of whether the tester ran
-the plugins chapters first). If `.skill-map/` is missing, the fixture
+Verify that `.skill-map/` exists in the cwd (the `extend` part's
+`backstage-init` preflight ran `sm init --no-scan` to provision it;
+the universal `.skillmapignore` from pre-flight keeps the tutorial's
+own files out of the scan, so this is the expected state regardless
+of whether the tester ran the plugins chapters first). If `.skill-map/` is missing, the fixture
 is corrupted: surface the mismatch ("the project bootstrap is
 gone, re-invoke the tutorial from an empty dir") and stop.
 

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

@@ -1,6 +1,6 @@
-# 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 it reuses the fundamentals fixture and DB built in Part 0 (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.
+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.
 
 ## Chapter `browse` - list / show / check (~3 min)
 
@@ -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.
 

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

@@ -1,6 +1,6 @@
 # Part 2: Connect the harness (step library, `connect-harness`)
 
-This is the wiring part. Part 1 grew a small set of standalone nodes around the handbook (the portfolio harness); here the tester turns that scatter of dots into a connected graph: a link checker, a publish command that pulls three pieces together, the handbook becoming a real hub, and a close-up on how sure skill-map is of each connection. `pace: auto-advance` (walk straight into the next chapter once one is marked done), `preflight: reuse` (it builds on the portfolio harness from Part 1, 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.
+This is the wiring part. Part 1 grew a small set of standalone nodes around the handbook (the portfolio harness); here the tester turns that scatter of dots into a connected graph: a link checker, a publish command that pulls three pieces together, the handbook becoming a real hub, and a close-up on how sure skill-map is of each connection. `pace: auto-advance` (walk straight into the next chapter once one is marked done), `preflight: seed` (it builds on the portfolio harness from Part 1, 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.
 
 ## Chapter `check-links` - The link checker (~3 min)
 
@@ -55,9 +55,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`, `description`, or `shortcut`.
 
-> 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
 ---
@@ -73,7 +73,7 @@ args:
     required: true
 ---
 
-# /publish
+# publish
 
 The one command you run when the site is ready to go out.
 
@@ -99,6 +99,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 +156,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).