@skill-map/cli 0.68.0 → 0.68.1

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

@@ -6,9 +6,12 @@ actual project: a tiny personal **portfolio website**, fully static, served by a
 ~15-line Express server, plus the `.agents/skills/` **harness** that maintains
 it. skill-map maps the harness (the `.md` assets and how they reference each
 other); the site itself is plain HTML the harness produces (the daily loop, Part
-3, runs and ships it). This lens authors only **skills** and **markdown notes**,
-and they connect by **markdown references** (`[text](path)`). `pace: per-step`,
-`preflight: portfolio-init`. Shared conventions live in `_core.md`. Narrate with
+2, runs and ships it). This lens authors only **skills** and **markdown notes**,
+and they connect by **markdown references** (`[text](path)`). This part runs end
+to end: it boots the project and grows its harness members (the `kickoff` to
+`real-kinds` chapters), then wires them into a connected graph (the `check-links`
+to `confidence` chapters). `pace: per-step`, `preflight: portfolio-init`. Shared
+conventions live in `_core.md`. Narrate with
 `<provider_dir>` = `.agents/skills`.
 
 The orchestrator's `portfolio-init` pre-flight (backstage, silent) has already
@@ -94,7 +97,7 @@ Tell the tester:
 
 > I added the first real member of your harness: a skill called `content-editor`
 > (its job is to write the site's pages). A new `skill` node appeared on the map.
-> Right now it stands alone; in the next part we wire it to the handbook and the
+> Right now it stands alone; later in this part we wire it to the handbook and the
 > style guide.
 >
 > 💡 Tip: I create these harness files for you. If you'd like to see what's
@@ -135,6 +138,148 @@ Tell the tester:
 >
 > See the skill and the docs in the map?
 
-Wait for confirmation. Mark `real-kinds`: done. Last chapter of the part: apply
+Wait for confirmation. Mark `real-kinds`: done.
+
+## Chapter `check-links` - The link checker (~3 min)
+
+**Context**: the harness needs a guard that runs before publishing, a skill that
+checks the site's internal links resolve before it ships. We only create the
+`skill` node here; the `publish` skill in the next chapter is what calls it.
+
+Lay the `check-links` skill (content lives in `fixtures-data/`). Backstage
+(silent):
+
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay harness --only "__PROVIDER__/skills/check-links/SKILL.md" --provider <provider> --lang <lang>
+```
+
+Tell the tester:
+
+> So I added that guard: a skill called `check-links`. A new `skill` node
+> appeared on the **Map**, alone for now; the next chapter gives it a caller.
+>
+> See the new skill node?
+
+Wait for confirmation. Mark `check-links`: done.
+
+## Chapter `publish` - The publish skill (~4 min)
+
+**Context**: the chapter where the graph comes alive. The `publish` skill ties
+three pieces together in one body: it points at the link checker, at the content
+editor, and at the deploy runbook. On this lens all three are **markdown
+references**, so three reference arrows light up from a single new node.
+
+Tell the tester to create the file themselves (Inviolable rule #2). Render the
+block as a **top-level fenced code block** at column 0, NOT inside the `> `
+blockquote, so the frontmatter fences (`---`) land on column 0 (indented fences
+never parse, and `sm check` then warns `frontmatter-malformed`).
+
+> Create `<provider_dir>/publish/SKILL.md` with exactly this content (the first
+> line is `---`, nothing before it):
+
+```markdown
+---
+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.
+---
+
+# publish
+
+The one skill you run when the site is ready to go out.
+
+## Steps
+1. Run the [check-links](../check-links/SKILL.md) skill on the pages in public/. If it reports broken links, stop and fix them first.
+2. If a page needs a content fix, hand the change to [content-editor](../content-editor/SKILL.md).
+3. Follow the [deploy runbook](../../../docs/DEPLOY.md): regenerate pages, run the link check, start the server.
+```
+
+Continue the tester message:
+
+> Save it. Watch the **Map**: **three** new arrows light up at once from the new
+> `publish` node, all of them `references` (the open standard's one connector),
+> each landing on a real file:
+>
+> - `publish -> check-links` (the `[check-links](../check-links/SKILL.md)` link)
+> - `publish -> content-editor` (the `[content-editor](../content-editor/SKILL.md)` link)
+> - `publish -> docs/DEPLOY.md` (the `[deploy runbook](../../../docs/DEPLOY.md)` link)
+>
+> One node, three connectors, all references. On a vendor lens (claude/codex) the
+> first two would be a `/`-invoke and an `@`-mention; the open standard wires
+> everything with file links, and that is all this lens emits. The harness is
+> starting to look like a real graph.
+>
+> 💡 Tip: to tidy the layout, click **Re-arrange layout** in the map toolbar.
+>
+> Did the three arrows appear?
+
+Wait for confirmation. You MAY `Read` the file to verify the `---` fences are
+flush at column 0 (if `sm check` flags `frontmatter-malformed`, the fences got
+indented on paste, re-align every line flush left). Mark `publish`: done.
+
+## Chapter `links` - The handbook becomes the hub (~4 min)
+
+**Context**: the handbook (`AGENTS.md`) has been a lonely node since the start of
+this part. Here it becomes the hub: two bullets point it at the content editor
+and the publish skill. We also give the content editor a reference to the style guide it follows.
+
+Apply both edits (content lives in `fixtures-data/`). The first appends two hub
+bullets (markdown links) to `AGENTS.md`; the second adds the style-guide
+reference to the content-editor skill. Backstage (silent):
+
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js edit agents-hub --provider <provider> --lang <lang>
+node .claude/skills/sm-tutorial/scripts/fixtures.js edit content-editor-style --provider <provider> --lang <lang>
+```
+
+Tell the tester:
+
+> Two edits, and the **Map** fills in. Your handbook (`AGENTS.md`) is now the hub:
+> it points at the content editor and at the publish skill. And the content
+> editor now reaches the style guide it follows. New arrows, all `references`:
+>
+> - `AGENTS.md -> content-editor` (a `[content-editor](...)` link)
+> - `AGENTS.md -> publish` (a `[publish](...)` link)
+> - `content-editor -> docs/STYLE.md` (a `[style guide](...)` link)
+>
+> The whole harness is wired end to end now: the handbook reaches the work, the
+> work reaches the docs, and `publish` pulls the publish flow together, every
+> connection a markdown reference, the one link the open standard documents.
+>
+> Did the new arrows light up?
+
+Wait for confirmation. You MAY `Read` the two files to verify. Mark `links`: done.
+
+## Chapter `confidence` - How sure is each link (~3 min)
+
+No file edits, pure observation.
+
+Tell the tester:
+
+> Last beat of this part: how sure is skill-map about each connection? It records
+> a **confidence** for every link and draws it as opacity: a link that resolves
+> to a real file is solid (**1.00**), one that does not lands fainter, so a glance
+> at the **Map** separates solid wiring from problem links.
+>
+> Open the Inspector for the `publish` node (click it). Scroll to the
+> **Connections** panel and read the **Outgoing** rows. Each shows the link kind
+> (`references`, the only kind here) and a confidence badge, every one reads
+> **1.00**, because each link lands on a file that exists on disk.
+>
+> Your whole harness reads solid because every link resolves. So what does a link
+> that does NOT resolve look like? You met one in the prologue: the
+> `demo-guideline` link had no `.md`, so it pointed at a path that did not exist,
+> skill-map drew no arrow and flagged it as a **broken reference**, confidence
+> knocked to **0.50**. Adding `.md` turned it into a link that landed on the real
+> file, and it drew a solid arrow at **1.00**.
+>
+> **IMPORTANT:** why does confidence matter? It mirrors how an agent resolves a
+> reference, a deterministic name-and-path lookup, no guessing. That is cheaper
+> and does not fail, the same reason a clean, well-named harness is worth keeping.
+>
+> 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 (name the part by its title, route back to the menu; do NOT lead
 into the next part from here).

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

@@ -1,4 +1,4 @@
-# Part 5: The CLI in depth - step library
+# Part 4: 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.
 

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

@@ -1,4 +1,4 @@
-# Part 3: The daily loop (step library, `daily-loop`)
+# Part 2: The daily loop (step library, `daily-loop`)
 
 The campaign's payoff and finale fused into one part: the tester operates the
 harness they built the way they would on any normal day, **for real**. Three
@@ -62,9 +62,9 @@ broken-reference markers, and confidence live.
 ## Chapter `setup` - Make it yours and bring it up (~5 min)
 
 **Context**: the harness is wired (you built it in the earlier parts). Now you
-put it to work on a real day. First, make the site yours and give it a look you
-would not be embarrassed to share, then serve it and open it in the browser, the
-early payoff before the daily loop fills it with pages. The honest beat: the HTML
+put it to work on a real day. First, make the site yours, about whatever you
+like, then serve it and open it in the browser, the early payoff before the
+daily loop fills it with pages. The honest beat: the HTML
 and CSS are Layer 2 (the harness's output); skill-map maps the harness (Layer 1,
 the `.md` files), so the site landing on disk does NOT move the graph, and that
 is correct, not a bug. The tester runs the serve commands themselves (one of the
@@ -72,10 +72,11 @@ few non-`sm` beats); guide them, do not run them.
 
 **Preparation**:
 
-1. Ask the tester, in one short exchange: what the site should be called (their
-   name or a title) and one line about what it is for. Keep it light; if they do
-   not care, offer defaults ("My Portfolio" / "Small, sturdy things on the
-   web"). Persist both with
+1. Ask the tester the two questions straight, with no "before we build, let's
+   make it yours" lead-in: what the site should be called (their name or a
+   title) and one line about what it is for. Keep it light; if they do not care,
+   offer defaults ("My Portfolio" / "Small, sturdy things on the web"). Persist
+   both with
    `node .claude/skills/sm-tutorial/scripts/state.js set-identity --name "<name>" --tagline "<tagline>"`
    (it writes `tester.site_identity` into `tutorial-state.json`).
 2. Backstage, `Write` `public/style.css` exactly as below (Layer 2, ignored by
@@ -208,12 +209,6 @@ node server.js
 > Open `http://localhost:3000`: there is your site, named after you, with a
 > clean layout. Click **About** and back to **Home**.
 >
-> Now glance at the Map: it did not move. Everything you watched grow on the
-> canvas is your harness, the `.md` files and how they reference each other
-> (Layer 1). The pages and the stylesheet are Layer 2, what the harness
-> produces, and skill-map maps the harness, not its output. Two layers, one
-> project.
->
 > Does the site load and look clean?
 
 Wait for confirmation. If `node server.js` reports `Cannot find module
@@ -224,11 +219,6 @@ project root and Node is on PATH. Mark `setup`: done. Auto-advance to
 
 ## Chapter `add-page` - Add a page with your agent (~4 min)
 
-**Context**: the daily move. You want a new page, so you ask your
-`content-editor` to write it. This is the first time it runs **for real** (no
-more playing the agent). It reads `docs/STYLE.md` and the shared stylesheet and
-writes a new page into `public/`. The graph does not move (HTML is Layer 2).
-
 **Preparation**: none until the tester asks.
 
 Tell the tester:
@@ -269,14 +259,18 @@ Wait for confirmation. Mark `add-page`: done. Auto-advance to `broken-ref`.
 
 ## Chapter `broken-ref` - A rename breaks a link (~4 min)
 
-**Context**: real reorganizing breaks things, and this is where skill-map earns
-its keep. You rename a doc, and a link that pointed at the old name goes stale.
-skill-map catches it the moment you re-scan.
+**Context**: the daily safety net, and where skill-map earns its keep: rename and
+move things freely, and skill-map shows you exactly what you forgot to update
+before it ships broken.
 
 **Preparation**: none (the tester drives). Everything here is watched live on
 the Map; no `sm` commands.
 
-Tell the tester to rename the deploy runbook (their file):
+Tell the tester to free the third terminal, then rename the deploy runbook
+themselves (their file):
+
+> In your **third terminal** (the one running `node server.js`), press
+> **Ctrl+C** to stop the site server, then rename the deploy runbook there:
 
 ```bash
 mv docs/DEPLOY.md docs/DEPLOYMENT.md
@@ -293,9 +287,7 @@ mv docs/DEPLOY.md docs/DEPLOYMENT.md
 > point the deploy-runbook link at `docs/DEPLOYMENT.md` (the new name). Save.
 >
 > Watch the **Map** again: the arrow snaps back, solid, and the red marker
-> clears, all live, no command to run. That is the daily safety net: rename and
-> move things freely, and skill-map shows you exactly what you forgot to update
-> before it ships broken.
+> clears, all live, no command to run.
 >
 > Did the broken marker appear and then clear?
 
@@ -305,10 +297,6 @@ done. Auto-advance to `reserved`.
 
 ## Chapter `reserved` - A reserved name collides (~2 min)
 
-**Context**: you add a quick command to scaffold new pages and, without
-thinking, name it `init`, a name Claude Code already owns for its own slash
-command. skill-map warns you before the runtime silently ignores your file.
-
 **Preparation**: `Write` `.claude/commands/init.md`:
 ```markdown
 ---
@@ -333,14 +321,12 @@ The watcher picks up the new command. Tell the tester:
 > Rename it to `new-page`: first rename the file `.claude/commands/init.md` to
 > `.claude/commands/new-page.md`. Then open it in your text editor / IDE and, at
 > the top, where the frontmatter says `name: init`, change it to
-> `name: new-page`; also change the H1 to `# new-page` (a command's H1 stays a
-> plain title, never `# /new-page`). Save.
+> `name: new-page`. Save.
 >
 > Watch the **Map** again: the warning clears and the node is now `new-page`,
-> all live. Notice what cleared it: changing the **name** (`frontmatter.name`),
-> not just the filename, the reserved check looks at the command's name, which
-> is why the warning said to rename "the file or `frontmatter.name`". Now
-> `new-page` is yours and the runtime will actually run it.
+> all live. What cleared it was changing `frontmatter.name` (not just the
+> filename), the reserved check looks at the name. Now `new-page` is yours and
+> the runtime will run it.
 >
 > Did the warning clear after the rename?
 
@@ -352,12 +338,6 @@ Wait for confirmation. Mark `reserved`: done. Auto-advance to `publish`.
 
 ## Chapter `publish` - Ship it: run /publish for real (~4 min)
 
-**Context**: the harness is not a picture, it is a set of instructions, and
-`/publish` ties them together. You run it **for real** now: it invokes the link
-checker over your pages, briefs the `content-editor` if anything needs a fix,
-then follows the deploy runbook. This is the same Layer 1 / Layer 2 split, the
-pages are output, so the Map stays put while the pipeline runs.
-
 **Preparation**: make sure the pages exist (`index`, `about`, `projects` from the
 earlier chapters; lay any that are missing from the templates in `setup`). When the tester asks to publish, **execute the publish flow for real**
 by following `.claude/commands/publish.md`: run the `check-links` logic over
@@ -370,7 +350,9 @@ Tell the tester:
 > The site is ready. Tell me to publish (or type `/publish`) and I'll run your
 > publish command for real: I follow its steps, run the link check across your
 > pages, fix anything through the `content-editor`, and walk the deploy runbook,
-> exactly what the command says to do.
+> exactly what the command says to do. (You can read the command's content
+> anytime by clicking the `publish` node on the Map, then opening its **Body**
+> section.)
 
 After running the flow, report what actually happened (keep the promises
 conditional on the real result):
@@ -385,9 +367,6 @@ conditional on the real result):
 >   regenerate the pages (done), run the link check (done), start the server
 >   (next chapter).
 >
-> And the Map did not move while the pipeline ran: the pages are Layer 2 output;
-> the harness on the canvas is Layer 1, and that is what skill-map maps.
->
 > As you saw in the lines just above, I did not report anything odd: the link
 > check came back clean and `/publish` is wired correctly across your pages.
 > Shall we continue?
@@ -396,46 +375,35 @@ Wait for confirmation. Mark `publish`: done. Auto-advance to `stability`.
 
 ## Chapter `stability` - Set a node's stability (and the `.sm` sidecar) (~3 min)
 
-**Context**: real maintenance includes marking how mature each piece is. skill-map
-lets you tag a node's **stability** (`experimental` / `stable` / `deprecated`)
-from the inspector. That is skill-map's own metadata, so it lands in a co-located
-**`.sm` sidecar** next to the file (the vendor file stays untouched), and the
-first `.sm` write asks for your consent. Good moment now that the site shipped:
-mark the handbook as the stable core it is.
-
 **Preparation**: none for a first-time tester. (If re-entering a dir where the
 sidecar already exists, reset consent first with `rm -f AGENTS.sm
 .skill-map/settings.local.json` so the consent prompt shows again.)
 
 Tell the tester:
 
-> Your harness shipped, so let's mark the handbook as the **stable** core it is.
-> Open the Inspector for the `AGENTS` node (click it on the **Map**) and find the
-> **stability** action (the action button in the inspector). Click it and pick
-> `stable` from the list.
+> Your harness shipped, so let's set its **stability**. Open the Inspector for
+> the `AGENTS` node (click it on the **Map**) and click the **Set stability**
+> button. Pick any of `experimental` / `stable` / `deprecated` from the list.
 >
 > The first time skill-map writes its own metadata it asks for **consent**:
-> confirm it in the dialog that pops up. Two things happen at once: a `stable`
-> badge appears on the `AGENTS` node, and skill-map creates a **`.sm` sidecar**
-> (`AGENTS.sm`) right next to the handbook to hold that metadata, your `AGENTS.md`
-> itself is never touched. Your consent is remembered for the project, so it
-> will not ask again.
+> confirm it in the dialog that pops up. Two things happen at once: a stability
+> badge for the stage you picked appears on the `AGENTS` node, and skill-map
+> creates a **`.sm` sidecar file** (`AGENTS.sm`) right next to the handbook to
+> hold that metadata, your `AGENTS.md` itself is never touched. Your consent is
+> remembered for the project, so it will not ask again.
 >
 > That sidecar is where skill-map keeps what it knows about a node that does not
-> belong in the vendor file (stability, version, tags). You just wrote your first
-> one, by clicking, no command needed.
+> belong in the vendor file (stability, version, tags).
 >
-> See the `stable` badge on the handbook?
+> See the new stability badge on the handbook?
 
 Wait for confirmation. Mark `stability`: done. Auto-advance to `golive`.
 
-## Chapter `golive` - Your portfolio, live next to the graph (~3 min)
+## Chapter `golive` - Your website, live next to the graph (~3 min)
 
-**Context**: the climax. Serve the finished multi-page site and click through it,
-ending with the running portfolio on one side and the full harness graph on the
-other. One of the few chapters where the tester runs non-`sm` commands
-themselves; guide them, do not run it for them. `npm install` is idempotent, so
-it is safe whether or not they ran it in `setup`.
+One of the few chapters where the tester runs non-`sm` commands themselves;
+guide them, do not run it for them. `npm install` is idempotent, so it is safe
+whether or not they ran it in `setup`.
 
 **Preparation**: none. `server.js` / `package.json` exist from the kickoff; the
 pages exist from the earlier chapters.
@@ -451,7 +419,7 @@ node server.js
 > Open `http://localhost:3000` and click through Home, About, and Projects, the
 > pages your harness produced and shipped through the publish flow you just ran.
 >
-> Now take it in at once. On one side, your real running portfolio, named after
+> Now take it in at once. On one side, your real running website, named after
 > you, that you could deploy as-is. On the other, the skill-map graph of the
 > harness that built it: the handbook, the content-editor, the style guide, the
 > publish command, the link checker, the deploy runbook, all wired together. You
@@ -466,7 +434,7 @@ Wait for confirmation. The tester runs the commands; do not run them. If
 server with Ctrl+C and apply the ports edge case.
 
 This is the campaign finale. Congratulate them plainly: they went from an empty
-directory to a real, running portfolio plus a complete map of its harness. Then
+directory to a real, running website plus a complete map of its harness. Then
 invite them to keep going on their own:
 
 > And this site is yours to keep playing with: add more pages, refine the style

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

@@ -152,14 +152,10 @@ Tell the tester:
 > (That is also why `@demo-agent` drew fine: an `@name` mention
 > resolves when an agent by that name really exists.)
 >
-> One word on solidity: skill-map draws each connector's
-> **confidence** as opacity, and every arrow you see here is fully
-> solid (1.00) because each one lands on a real node. The faint,
-> partial case shows up later in the campaign; for now the rule is
-> simple, a reference
-> that resolves draws a solid arrow, a reference that points at
-> nothing is not drawn at all and gets flagged instead. The exact
-> per-link numbers live in the inspector, next chapter.
+> 💡 Tip: if all these changes left the nodes crowded together, the
+> map toolbar has a **Re-arrange layout** button: it tidies the
+> layout so everything reads better. If you've moved nodes by hand it
+> asks for confirmation first, otherwise it just re-arranges.
 >
 > Confirm when you see the four arrows plus the broken-reference
 > marker on the hub. If an arrow is missing, refresh the browser and
@@ -171,12 +167,6 @@ Expected: four drawn arrows plus one `core/reference-broken` error on `notes/tod
 
 The canvas only draws the resolved arrows; the full per-link breakdown, including the broken one that never drew, lives in the Inspector. Open it on the hub so the tester registers the surface before the `edit-link` chapter changes topology.
 
-> 💡 Tip: if all these changes left the nodes crowded together, the
-> map toolbar has a **Re-arrange layout** button (tooltip "Re-arrange
-> the visible nodes"): it tidies the layout so everything reads
-> better. If you've moved nodes by hand it asks for confirmation
-> first, otherwise it just re-arranges.
->
 > 🆕 Open the Inspector for **Demo TODO list** (click the node on
 > the map). Find the **Connections** section: it has two sections,
 > **Outgoing** and **Incoming**.
@@ -187,7 +177,7 @@ The canvas only draws the resolved arrows; the full per-link breakdown, includin
 > confidence: the numeric value. Here you'll see the contrast, the
 > `references` to `demo-guideline2` reads `1.00` (resolved), while the
 > `mentions` to `demo-guideline` reads `0.50` and is marked broken,
-> that 0.5 is the broken-reference penalty, not a "halfway sure".
+> that 0.5 is the broken-reference penalty, not "half sure".
 >
 > Now open the Inspector for a couple of the nodes to read their
 > Incoming count. The four resolved nodes (`demo-agent`,
@@ -196,6 +186,11 @@ The canvas only draws the resolved arrows; the full per-link breakdown, includin
 > mention never landed on it, so nothing points in. Five outgoing
 > links on the hub, but only four of them reach a node.
 >
+> 💡 Tip: skill-map draws each connector's **confidence** as opacity.
+> Every arrow here is solid (1.00) because it lands on a real node; a
+> reference that points at nothing is flagged instead of drawn. The
+> fainter, partial case shows up later in the campaign.
+>
 > Let me know when you see it.
 
 Mark `inspector`: done.
@@ -252,18 +247,20 @@ action itself.
 > Tell me when the tree is open.
 
 > At the top of that sidebar there's a search box (placeholder
-> `Search…`). Type `guideline`. Watch both halves at once: the tree
-> narrows down to the two guideline nodes (`demo-guideline` and
-> `demo-guideline2`) and the **Map** drops every node except those
-> two. The search matches a node's name, path,
-> or description, and filters live as you type, no Enter needed.
+> `Search…`). Type `guideline`. Watch the tree narrow down to the
+> two guideline nodes (`demo-guideline` and `demo-guideline2`). The
+> search matches a node's name, path, or description, and filters
+> live as you type, no Enter needed. The **Map** stays put: by
+> default the search filters only the files list, not the map (the
+> tip below changes that).
 >
-> Now clear the box. All six nodes come back, in both the tree and
-> the Map. Confirm you saw it filter and then restore.
+> Now clear the box. All six nodes come back in the tree. Confirm you
+> saw it filter and then restore.
 
-> Last one. In the tree, find the **Demo TODO list** row: at its
-> right edge there's a small **sitemap** icon (its tooltip reads
-> "Isolate this node and its direct links on the map"). Click it.
+> Last one. In the tree, find the `notes/todo` row (the **Demo TODO
+> list** hub, the tree labels rows by file name): at its right edge
+> there's a small **sitemap** icon (its tooltip reads "Isolate this
+> node and its direct links on the map"). Click it.
 >
 > The Map collapses to **Demo TODO list** plus only the nodes it
 > draws an arrow to (`demo-command`, `demo-skill`,
@@ -276,10 +273,9 @@ action itself.
 >
 > 💡 Tip: remember the search box from a moment ago? The map-icon
 > button right next to it controls whether the search also filters
-> the **Map**. It's on by default, that's why the **Map** narrowed
-> along with the tree when you searched `guideline`. Click it to
-> switch to filtering only the files list, leaving the map's layout
-> in place.
+> the **Map**. It's off by default, which is why the **Map** stayed
+> put while only the tree narrowed when you searched `guideline`.
+> Click it on if you want a search to filter the map too.
 >
 > Did the map isolate and then restore?
 

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

@@ -1,4 +1,4 @@
-# Part 4 (b): Extend skill-map - plugins (step library, `tour-*` ids)
+# Part 3 (b): Extend skill-map - plugins (step library, `tour-*` ids)
 
 Guided tour of the **built-in plugins** that ship with `sm`. Three
 steps: a quick mental model of what plugins are plus a peek at