@skill-map/cli 0.68.0 → 0.69.0

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

@@ -155,11 +155,8 @@ Tell the tester:
 > the link finds the real file and draws a solid arrow. Same kind of
 > note, one `.md` apart: one resolves, the other does not.
 >
-> One word on solidity: skill-map draws each connector's **confidence**
-> as opacity. Both drawn arrows are fully solid (1.00) because each
-> lands on a real file; the broken one would read 0.50 (a penalty, not
-> "half sure") and is not drawn at all. The exact per-link numbers live
-> in the inspector, next chapter.
+> 💡 Tip: if the nodes are crowded, the map toolbar has a **Re-arrange
+> layout** button that tidies things up.
 >
 > Confirm when you see the two arrows plus the broken-reference marker
 > on the hub. If an arrow is missing, refresh the browser and let me
@@ -175,9 +172,6 @@ by hand in `edit-link`). If an arrow is missing, do not advance. Mark
 The canvas only draws the resolved arrows; the full per-link breakdown,
 including the broken one, lives in the Inspector. Open it on the hub.
 
-> 💡 Tip: if the nodes are crowded, the map toolbar has a **Re-arrange
-> layout** button that tidies things up.
->
 > 🆕 Open the Inspector for **Demo TODO list** (click the node). Find
 > the **Connections** section: **Outgoing** and **Incoming**.
 > Demo TODO list lists **3 links** under Outgoing (the canvas drew two
@@ -192,6 +186,10 @@ including the broken one, lives in the Inspector. Open it on the hub.
 > Open `demo-guideline` and it shows **0**: the broken link never landed
 > on it. Three outgoing links on the hub, but only two reach a node.
 >
+> 💡 Tip: skill-map draws each connector's **confidence** as opacity.
+> Both drawn arrows are solid (1.00) because each lands on a real file;
+> the broken one is flagged instead of drawn.
+>
 > Let me know when you see it.
 
 Mark `inspector`: done.
@@ -250,17 +248,19 @@ each ends with its own confirmation. Do NOT prepend an intro line to a block.
 > Tell me when the tree is open.
 
 > At the top of the sidebar there's a search box (placeholder
-> `Search…`). Type `guideline`. Watch both halves: the tree narrows to
-> the two guideline nodes and the **Map** drops every node except those
-> two. The search matches a node's name, path, or description, and
-> filters live, no Enter needed.
+> `Search…`). Type `guideline`. Watch the tree narrow to the two
+> guideline nodes. The search matches a node's name, path, or
+> description, and filters live, 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 four nodes come back, in both the tree and the
-> Map. Confirm you saw it filter and then restore.
+> Now clear the box. All four 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 (tooltip "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 (tooltip "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-skill`, `demo-guideline2`). That's how you focus on
@@ -271,8 +271,9 @@ each ends with its own confirmation. Do NOT prepend an intro line to a block.
 > four nodes return.
 >
 > 💡 Tip: the map-icon button next to the search box controls whether
-> the search also filters the **Map** (on by default). Click it to
-> filter only the files list, leaving the map in place.
+> the search also filters the **Map** (off by default, which is why the
+> map stayed put while only the tree narrowed). Click it on if you want
+> a search to filter the map too.
 >
 > Did the map isolate and then restore?
 
@@ -314,7 +315,7 @@ host-dependent rendering rule. Per Inviolable rule #2, the agent does NOT touch
 ├── .agents/skills/
 │   ├── demo-skill/SKILL.md
 │   └── sm-tutorial/SKILL.md   ← the tutorial you loaded
-├── .skill-map/              ← project DB + settings (managed)
+├── .skill-map/              ← project DB + settings
 ├── .skillmapignore          ← the file we're about to edit
 └── notes/
     ├── todo.md

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

@@ -1,4 +1,4 @@
-# Part 1 (basic track): The project from zero (step library, `kickoff-*` ids)
+# Part 1 (basic track): The harness from zero (step library, `kickoff-*` ids)
 
 The campaign turns real here for the **basic track** (the open-standard family:
 `agent-skills`, `antigravity`). After the abstract prologue, the tester starts an
@@ -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 3: The CLI for you and your agent - 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
@@ -31,7 +31,7 @@ kind of those two nodes changes. Per chapter:
 - `broken-ref`: the deploy link that breaks lives in the `publish` SKILL; fix it
   in `.agents/skills/publish/SKILL.md` (not a `.claude/commands/` file).
 - `reserved`: Codex has no command, so create a SKILL with a reserved name
-  instead, `Write` `.agents/skills/config/SKILL.md` named `config` (it shadows
+  instead, `Write` `.agents/skills/model/SKILL.md` named `model` (it shadows
   the open-standard `COMMONS_RESERVED_NAMES`); clear it by renaming the folder +
   `frontmatter.name` to `new-page`, exactly like the basic track's `reserved`
   chapter, on a skill.
@@ -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:
@@ -259,6 +249,9 @@ the `> ` blockquote, do NOT drop the bar when you personalise it.
 > output; the harness on the canvas is Layer 1. Your nodes are not a diagram,
 > they are runnable, and you just ran one.
 >
+> If the new page is not showing, refresh the browser with F5, the site does
+> not reload on its own.
+>
 > See the new page on the site, and the Map unchanged?
 
 Wait for confirmation. Mark `add-page`: done. Auto-advance to `broken-ref`.
@@ -269,14 +262,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 +290,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,42 +300,36 @@ 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`:
+**Preparation**: `Write` `.claude/commands/model.md`:
 ```markdown
 ---
-name: init
+name: model
 description: |
   Scaffolds a new empty page in public/ from the shared template.
 ---
 
-# init
+# model
 
 Creates a blank page so you can start writing.
 ```
 
 The watcher picks up the new command. Tell the tester:
 
-> I added a command named `init`. Watch the **Map**: the new `init` command node
+> I added a command named `model`. Watch the **Map**: the new `model` command node
 > appears, but flagged with a **warning** marker. Open its inspector: it reads
-> `name-reserved`, `init` shadows one of Claude Code's own slash commands (like
+> `name-reserved`, `model` shadows one of Claude Code's own slash commands (like
 > `/help`, `/clear`, `/config`), so the runtime would silently ignore your file,
 > it never runs. The fix is a name the runtime does not own.
 >
-> Rename it to `new-page`: first rename the file `.claude/commands/init.md` to
+> Rename it to `new-page`: first rename the file `.claude/commands/model.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.
+> the top, where the frontmatter says `name: model`, change it to
+> `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,90 +341,115 @@ 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.
+**Context**: the publish flow only earns its keep when something is actually
+wrong, so first you plant a real bug in the site, then watch `/publish` catch and
+fix it for real.
 
 **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
-every `.html` under `public/` (does each internal `href` resolve to a file that
-exists?); if any link is broken, brief the `content-editor` to fix it and
-re-run the check; then walk the deploy runbook steps. Do not role-play it.
+earlier chapters; lay any that are missing from the templates in `setup`).
 
-Tell the tester:
+This chapter has two beats: the tester breaks a link in the HTML first, then runs
+`/publish` so the skill catches the break. The split is required, the publish run
+cannot demonstrate the catch until the break is in place.
+
+**Beat 1, plant the bug (the tester breaks the HTML, their file).** Tell the
+tester:
+
+> Before we ship, let's break something on purpose. Open `public/index.html` in
+> your editor and find the **About** link in the top nav:
+>
+> ```html
+> <a href="/about.html">About</a>
+> ```
+>
+> Change the target to a typo that points at a page that does not exist, then
+> save:
+>
+> ```html
+> <a href="/abuot.html">About</a>
+> ```
+>
+> Now watch the **Map**. Nothing happens: no arrow moves, no red marker. Back in
+> the `broken-ref` chapter, breaking a link between your `.md` files lit up the
+> graph the instant you saved. This break is invisible to it, and that is
+> correct: skill-map maps your **harness** (the `.md` files, Layer 1), not the
+> HTML pages it produces (Layer 2, your `public/` folder, which is even in
+> `.skillmapignore`). A broken link inside your actual site never shows on the
+> graph. The one thing that catches it is your `check-links` skill, which is
+> exactly what `/publish` runs as its first step.
+>
+> Saved the typo, and the Map stayed unchanged?
+
+Wait for confirmation. The Map MUST stay unchanged; if a marker appeared they
+edited a `.md` by mistake, point them back at `public/index.html`.
 
-> 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.
+**Beat 2, run /publish for real.** Tell the tester:
 
-After running the flow, report what actually happened (keep the promises
-conditional on the real result):
+> Now ship it. Tell me to publish (or type `/publish`) and I'll run your publish
+> command for real, exactly as written. (You can read the command anytime by
+> clicking the `publish` node on the Map, then opening its **Body** section.)
+
+When the tester asks to publish, **execute the publish flow for real** by
+following `.claude/commands/publish.md`: run the `check-links` logic over every
+`.html` under `public/` (does each internal `href` resolve to a file that
+exists?), which now finds the planted typo; per step 2, brief the
+`content-editor` to fix it (point the link back at `/about.html`), re-run the
+check until it is clean, then walk the deploy runbook. Do not role-play it;
+`Read` `public/index.html` before and after the fix so the report is honest.
+
+After running the flow, report what actually happened:
 
 > Here is what just ran, for real:
 >
 > - **check-links** walked every page under `public/` and followed each internal
->   link. Result: 0 broken links. (Had it found one, the next step would have
->   briefed `content-editor` to fix it, then re-checked, that is what step 2 is
->   for.)
+>   link. It caught **1 broken link**: `/abuot.html` on `index.html`, the typo
+>   you planted. The graph never flagged it, but the skill did, because the skill
+>   reads your real pages.
+> - **step 2 kicked in**: I briefed your `content-editor` to fix it. It pointed
+>   the link back at `/about.html`, and a re-run of **check-links** came back
+>   clean: 0 broken links.
 > - the **deploy runbook** (`docs/DEPLOYMENT.md`) lists the ship steps:
->   regenerate the pages (done), run the link check (done), start the server
->   (next chapter).
+>   regenerate the pages (done), run the link check (done, now clean), 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?
+> That is the whole point of the harness: you broke the site, the graph stayed
+> quiet because the HTML is its output and not its map, and your own publish
+> command caught the break and fixed it before it shipped. Shall we continue?
 
-Wait for confirmation. Mark `publish`: done. Auto-advance to `stability`.
+Wait for confirmation. The site MUST be clean again (the typo fixed) before
+`golive`. 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 +465,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 +480,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