@skill-map/cli 0.68.0 → 0.69.0

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

@@ -53,11 +53,11 @@ parts:
       - id: init            ; title: "Your first node (sm init, sm, the UI)" ; est_min: 2
       - id: kinds           ; title: "The other kinds appear"               ; est_min: 1
       - id: first-edit      ; title: "Your first edit (the watcher reacts)" ; est_min: 1
-      - id: connectors      ; title: "The connectors light up"             ; est_min: 2
+      - id: connectors      ; title: "The connectors light up"             ; est_min: 1
       - id: inspector       ; title: "The inspector and connections"       ; est_min: 1
-      - id: edit-link       ; title: "Edit a link, the topology changes"   ; est_min: 3
-      - id: workspace       ; title: "Navigate the workspace (files, search, isolate)" ; est_min: 2
-      - id: ignore          ; title: "Silence a file via .skillmapignore"  ; est_min: 2
+      - id: edit-link       ; title: "Edit a link, the topology changes"   ; est_min: 2
+      - id: workspace       ; title: "Navigate the workspace (files, search, isolate)" ; est_min: 1
+      - id: ignore          ; title: "Silence a file via .skillmapignore"  ; est_min: 1
 
   - id: basic-fundamentals
     order: 0
@@ -72,15 +72,15 @@ parts:
       - id: init            ; title: "Your first node (sm init, sm, the UI)" ; est_min: 2
       - id: kinds           ; title: "Skills and notes appear"             ; est_min: 1
       - id: first-edit      ; title: "Your first edit (the watcher reacts)" ; est_min: 1
-      - id: connectors      ; title: "Connect with references (markdown links)" ; est_min: 2
+      - id: connectors      ; title: "Connect with references (markdown links)" ; est_min: 1
       - id: inspector       ; title: "The inspector and connections"       ; est_min: 1
-      - id: edit-link       ; title: "Edit a link, the topology changes"   ; est_min: 3
-      - id: workspace       ; title: "Navigate the workspace (files, search, isolate)" ; est_min: 2
-      - id: ignore          ; title: "Silence a file via .skillmapignore"  ; est_min: 2
+      - id: edit-link       ; title: "Edit a link, the topology changes"   ; est_min: 2
+      - id: workspace       ; title: "Navigate the workspace (files, search, isolate)" ; est_min: 1
+      - id: ignore          ; title: "Silence a file via .skillmapignore"  ; est_min: 1
 
   - id: extend
     order: 4
-    title: "Extend skill-map for the site"
+    title: "Extend skill-map with plugins"
     # Spans three chapter libraries; dispatch by chapter-id prefix:
     #   settings-*  -> part-settings.md
     #   tour-*      -> part-plugins.md
@@ -97,10 +97,10 @@ parts:
     chapters:
       - id: settings-1-layers        ; title: "The config layers and `sm config list`" ; est_min: 3
       - id: settings-2-resolve       ; title: "Read, resolve, and set a value with `sm config`" ; est_min: 3
-      - id: settings-3-lens          ; title: "The active provider lens (`activeProvider`)" ; est_min: 4
-      - id: tour-1-intro             ; title: "How plugins work" ; est_min: 4
-      - id: tour-2-kinds             ; title: "The six extension kinds" ; est_min: 5
-      - id: tour-3-explore           ; title: "Explore one extension up close" ; est_min: 4
+      - id: settings-3-lens          ; title: "The active provider lens (`activeProvider`)" ; est_min: 3
+      - id: tour-1-intro             ; title: "How plugins work" ; est_min: 3
+      - id: tour-2-kinds             ; title: "The six extension kinds" ; est_min: 4
+      - id: tour-3-explore           ; title: "Explore one extension up close" ; est_min: 3
       - id: authoring-1-scaffold     ; title: "`sm plugins create extractor demo-highlight`" ; est_min: 2
       - id: authoring-2-anatomy      ; title: "Tour the scaffold (plugin.json + stubs + README)" ; est_min: 3
       - id: authoring-3-edit-setting ; title: "Edit a setting (string-list) and observe it in the UI" ; est_min: 3
@@ -108,8 +108,8 @@ parts:
       - id: authoring-5-doctor-author ; title: "Catch a manifest mistake with `sm plugins doctor`" ; est_min: 2
 
   - id: cli
-    order: 5
-    title: "The CLI in depth"
+    order: 3
+    title: "The CLI for you and your agent"
     step_file: part-cli.md
     pace: auto-advance
     preflight: seed            # self-seeds the Part 0 demo fixture
@@ -118,11 +118,11 @@ parts:
     track: both                # CLI verbs are lens-agnostic; prose notes lens-specific node counts
     status: active
     chapters:
-      - id: browse           ; title: "list / show / check" ; est_min: 3
-      - id: graph-export     ; title: "graph / export (query, formatters)" ; est_min: 3
-      - id: issues           ; title: "Issues and broken refs (--analyzers, --json)" ; est_min: 3
+      - id: browse           ; title: "list / show / check" ; est_min: 2
+      - id: graph-export     ; title: "graph / export (query, formatters)" ; est_min: 2
+      - id: issues           ; title: "Issues and broken refs (--analyzers, --json)" ; est_min: 2
       - id: annotations      ; title: "Annotations and the .sm consent prompt" ; est_min: 3
-      - id: reference-paths  ; title: "Validate links to folders outside the scan scope" ; est_min: 4
+      - id: reference-paths  ; title: "Validate links to folders outside the scan scope" ; est_min: 3
 
   # ----- the portfolio campaign (the spine's real project) -----
   # Each part builds on the prior one's accumulated harness. Run in
@@ -133,7 +133,7 @@ parts:
 
   - id: project-kickoff
     order: 1
-    title: "The project from zero"
+    title: "The harness from zero"
     step_file: part-project-kickoff.md
     pace: per-step
     preflight: portfolio-init   # lays the Express skeleton + AGENTS.md; clears the prologue demo fixture if present
@@ -144,43 +144,31 @@ parts:
       - id: kickoff     ; title: "Start the portfolio (sm init on the real skeleton)" ; est_min: 2
       - id: manual      ; title: "The handbook (AGENTS.md) and CLAUDE.md" ; est_min: 2
       - id: first-agent ; title: "The first harness agent (content-editor)" ; est_min: 2
-      - id: real-kinds  ; title: "The real kinds in context" ; est_min: 2
-
-  - id: connect-harness
-    order: 2
-    title: "Connect the harness"
-    step_file: part-connect-harness.md
-    pace: auto-advance
-    preflight: seed
-    seed: harness-built     # fast-forward to here if project-kickoff is not done
-    prereq: project-kickoff
-    track: rich             # /publish command + @mentions; basic track connects via references
-    status: active
-    chapters:
-      - id: check-links ; title: "The check-links skill" ; est_min: 2
-      - id: publish     ; title: "The /publish command invokes the skill" ; est_min: 3
-      - id: links       ; title: "Mentions (@) and references between assets" ; est_min: 3
+      - id: real-kinds  ; title: "The real kinds in context" ; est_min: 1
+      - id: check-links ; title: "The check-links skill" ; est_min: 1
+      - id: publish     ; title: "The /publish command invokes the skill" ; est_min: 2
+      - id: links       ; title: "Mentions (@) and references between assets" ; est_min: 2
       - id: confidence  ; title: "Connector confidence (opacity = certainty)" ; est_min: 2
 
   - id: daily-loop
-    order: 3
+    order: 2
     title: "The daily loop (add, improve, publish)"   # the campaign finale
     step_file: part-daily-loop.md
     pace: auto-advance
     preflight: seed
-    seed: harness-connected   # fast-forward to here if the earlier parts are not done
-    prereq: connect-harness
+    seed: harness-connected   # fast-forward to here if project-kickoff is not done
+    prereq: project-kickoff
     fixture: portfolio        # reuses the wired harness; lays the pretty site (style.css + pages) as taught steps
     track: rich               # agent-driven page add + reserved command; basic track has its own counterpart
     status: active
     chapters:
-      - id: setup            ; title: "Make it yours and bring it up" ; est_min: 5
-      - id: add-page         ; title: "Add a page with your agent" ; est_min: 4
-      - id: broken-ref       ; title: "A rename breaks a link" ; est_min: 4
+      - id: setup            ; title: "Make it yours and bring it up" ; est_min: 4
+      - id: add-page         ; title: "Add a page with your agent" ; est_min: 3
+      - id: broken-ref       ; title: "A rename breaks a link" ; est_min: 3
       - id: reserved         ; title: "A reserved name collides" ; est_min: 2
-      - id: publish          ; title: "Ship it: run /publish for real" ; est_min: 4
+      - id: publish          ; title: "Ship it: run /publish for real" ; est_min: 3
       - id: stability        ; title: "Set a node's stability (and the `.sm` sidecar)" ; est_min: 3
-      - id: golive           ; title: "Your portfolio, live next to the graph" ; est_min: 3
+      - id: golive           ; title: "Your website, live next to the graph" ; est_min: 3
 
   # ----- the basic-track campaign (open-standard family: agent-skills / antigravity) -----
   # Mirrors the rich campaign arc with skill + markdown only, connected by
@@ -189,7 +177,7 @@ parts:
 
   - id: basic-kickoff
     order: 1
-    title: "The project from zero"
+    title: "The harness from zero"
     step_file: part-basic-kickoff.md
     pace: per-step
     preflight: portfolio-init
@@ -201,52 +189,40 @@ parts:
       - id: manual       ; title: "The handbook (AGENTS.md) and an entry pointer" ; est_min: 2
       - id: first-skill  ; title: "The first harness skill (content-editor)" ; est_min: 2
       - id: real-kinds   ; title: "The kinds in context" ; est_min: 2
-
-  - id: basic-connect
-    order: 2
-    title: "Connect the harness"
-    step_file: part-basic-connect.md
-    pace: auto-advance
-    preflight: seed
-    seed: harness-built
-    prereq: basic-kickoff
-    track: basic
-    status: active
-    chapters:
-      - id: check-links ; title: "The link checker" ; est_min: 3
-      - id: publish     ; title: "The publish skill references the harness" ; est_min: 4
-      - id: links       ; title: "The handbook becomes the hub (references)" ; est_min: 4
-      - id: confidence  ; title: "Connector confidence (opacity = certainty)" ; est_min: 3
+      - id: check-links ; title: "The link checker" ; est_min: 2
+      - id: publish     ; title: "The publish skill references the harness" ; est_min: 3
+      - id: links       ; title: "The handbook becomes the hub (references)" ; est_min: 3
+      - id: confidence  ; title: "Connector confidence (opacity = certainty)" ; est_min: 2
 
   - id: basic-daily
-    order: 3
+    order: 2
     title: "The daily loop (add, improve, publish)"
     step_file: part-basic-daily.md
     pace: auto-advance
     preflight: seed
     seed: harness-connected
-    prereq: basic-connect
+    prereq: basic-kickoff
     fixture: portfolio
     track: basic
     status: active
     chapters:
-      - id: setup       ; title: "Make it yours and bring it up" ; est_min: 5
-      - id: add-page    ; title: "Add a page with your skill" ; est_min: 4
-      - id: broken-ref  ; title: "A rename breaks a link" ; est_min: 4
+      - id: setup       ; title: "Make it yours and bring it up" ; est_min: 4
+      - id: add-page    ; title: "Add a page with your skill" ; est_min: 3
+      - id: broken-ref  ; title: "A rename breaks a link" ; est_min: 3
       - id: reserved    ; title: "A reserved name collides" ; est_min: 2
-      - id: publish     ; title: "Ship it: run the publish skill for real" ; est_min: 4
+      - id: publish     ; title: "Ship it: run the publish skill for real" ; est_min: 3
       - id: stability   ; title: "Set a node's stability (and the `.sm` sidecar)" ; est_min: 3
-      - id: golive      ; title: "Your portfolio, live next to the graph" ; est_min: 3
+      - id: golive      ; title: "Your website, live next to the graph" ; est_min: 3
 
   # ----- parked: MCP returns later as its own iteration (body kept in part-mcp.md) -----
   - id: mcp
-    order: 6
+    order: 5
     title: "MCP"
     step_file: part-mcp.md
     pace: auto-advance
     preflight: seed
     seed: harness-connected
-    prereq: connect-harness
+    prereq: project-kickoff
     track: rich               # MCP tool declaration sits on an agent/command body
     status: planned           # temporarily disabled, hidden from the menu. Body exists; re-enable when MCP returns.
     chapters:

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

@@ -38,10 +38,10 @@ fixtures-data/
 |---|---|---|
 | `universal` | `.skillmapignore`, `findings.md` | pre-flight |
 | `prologue` | the seven Part 0 demo nodes | Part 0 (progressive, `--only`), `prologue-built` seed |
-| `portfolio` | Express skeleton, handbook, `content-editor`, `docs/STYLE` + `DEPLOY` | Part 1 (`--only` boot, chapters lay the rest), `harness-*` seeds |
-| `harness` | `check-links` skill, `publish` command | Part 2 chapters, `harness-connected` seed |
+| `portfolio` | Express skeleton, handbook, `content-editor`, `docs/STYLE` + `DEPLOY` | Part 1 (`--only` boot, chapters lay the rest), `harness-connected` seed |
+| `harness` | `check-links` skill, `publish` command | Part 1 connect chapters, `harness-connected` seed |
 | `master` | `master-agent`, `master-skill`, `notes/ideas` | Part 4 `backstage-init` |
-| `cli-external` | `link-validation/hijoA` + `hijoB` | Part 5 `reference-paths` |
+| `cli-external` | `link-validation/hijoA` + `hijoB` | Part 3 `reference-paths` |
 
 ## Edits (append fragments)
 
@@ -62,9 +62,8 @@ entered out of order.
 
 | Seed | Lays | Edits | Drops |
 |---|---|---|---|
-| `prologue-built` (Part 5) | `prologue` | `todo-connectors` | `notes/private-credentials.md` |
-| `harness-built` (Part 2) | `portfolio` | , | , |
-| `harness-connected` (Part 3) | `portfolio` + `harness` | `agents-hub`, `content-editor-style` | , |
+| `prologue-built` (Part 3) | `prologue` | `todo-connectors` | `notes/private-credentials.md` |
+| `harness-connected` (Part 2) | `portfolio` + `harness` | `agents-hub`, `content-editor-style` | , |
 
 ## Footprints (what `clear` and `wipe` remove)
 

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

@@ -41,6 +41,7 @@ Created /<cwd>/.skill-map/plugins/demo-highlight
 Next:
   - Edit extractors/demo-highlight-extractor/index.js
   - Run sm plugins doctor to confirm it loads
+  - Run sm plugins trust demo-highlight to let its code run (project-local plugins are untrusted until you allow them)
   - sm plugins slots list: browse slots and input-types
 ```
 
@@ -48,6 +49,28 @@ Next:
 slashes, no uppercase. `demo-highlight` is fine, `demo/highlight`
 or `Demo-Highlight` are rejected.
 
+**Trust it before it can run.** A project-local plugin you just dropped
+into `.skill-map/plugins/` is discovered but its code does NOT run until
+you trust it on this machine, a security gate so cloning a repo never
+auto-executes its plugins behind your back. The plugin is yours (you just
+wrote it), so grant trust now; the next chapters need it to run. Tell the
+tester:
+
+> One more step before your plugin can run. skill-map found it but will
+> not execute its code until you **trust** it, your local consent that
+> this code may run on your machine. It is yours, so trust it:
+
+```bash
+sm plugins trust demo-highlight
+```
+
+> Two separate ideas, on purpose: **enable** says "this plugin is part of
+> the project" (shared, lives in the config), **trust** says "I let it run
+> on this machine" (local, never travels in a commit). A scaffolded plugin
+> is enabled by default, so trusting it is all it needs to run. You can
+> revoke later with `sm plugins untrust demo-highlight`, or use the
+> per-plugin Trust control in the Settings UI.
+
 Mark `authoring-1-scaffold: done`.
 
 ## Step `authoring-2-anatomy` - tour the scaffold (~3 min)
@@ -162,12 +185,6 @@ the browser, click `notes/ideas`, and find the chip in the card's
 **left footer** (it also shows in the inspector). It reads
 `🔍 kw 3`, one match per keyword.
 
-> Heads up: editing only the fixture (`notes/ideas.md`) updates
-> live through the watcher, but it recounts with the OLD keyword
-> set, so the chip would read `🔍 kw 2`. The new `XXX` keyword
-> lives in the plugin, and the plugin is read at boot, that is why
-> restarting `sm` is the step that takes the count to 3.
-
 > Three matches. The setting flowed from the extension's `settings`
 > through `ctx.settings.keywords` into the extractor, the extractor
 > counted them, the kernel persisted the contribution, and the UI

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

@@ -1,4 +1,4 @@
-# Part 3 (basic track): The daily loop (step library, `daily-loop`)
+# Part 2 (basic track): The daily loop (step library, `daily-loop`)
 
 The campaign's payoff and finale, basic track. The tester operates the harness
 they built the way they would on any normal day, **for real**. Three acts:
@@ -35,13 +35,14 @@ has NO `sm scan` / `sm check` steps: the watcher re-scans on every save.
 ## Chapter `setup` - Make it yours and bring it up (~5 min)
 
 **Context**: the harness is wired. Now put it to work on a real day. First make
-the site yours and give it a look you would share, then serve it. The HTML and
+the site yours, about whatever you like, then serve it. 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.
 
 **Preparation**:
-1. Ask the tester, in one short exchange: what the site should be called and one
-   line about what it is for. If they do not care, offer defaults ("My Portfolio"
+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 and one line about what
+   it is for. 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>"`.
 2. Backstage, `Write` `public/style.css`, `public/index.html`, and
@@ -69,10 +70,6 @@ node server.js
 > Open `http://localhost:3000`: there is your site, named after you. Click
 > **About** and back to **Home**.
 >
-> Now glance at the Map: it did not move. What you watched grow is your harness
-> (Layer 1, the `.md` files and their references). The pages and stylesheet are
-> Layer 2, what the harness produces. Two layers, one project.
->
 > Does the site load and look clean?
 
 Wait for confirmation. If `node server.js` reports `Cannot find module
@@ -81,11 +78,6 @@ Wait for confirmation. If `node server.js` reports `Cannot find module
 
 ## Chapter `add-page` - Add a page with your skill (~4 min)
 
-**Context**: the daily move. You want a new page, so you ask your
-`content-editor` to write it, the first time it runs **for real**. 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).
-
 Tell the tester:
 
 > Your turn to delegate, the way you would on a real day. Tell me what page to
@@ -109,6 +101,9 @@ inside the `> ` blockquote):
 > 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`.
@@ -119,13 +114,17 @@ 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 the watcher re-scans.
+**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 is watched live.
 
-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
@@ -141,9 +140,7 @@ mv docs/DEPLOY.md docs/DEPLOYMENT.md
 > and 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. 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.
 >
 > Did the broken marker appear and then clear?
 
@@ -152,40 +149,35 @@ Wait for confirmation. The harness MUST be clean again before Act C. Mark
 
 ## Chapter `reserved` - A reserved name collides (~2 min)
 
-**Context**: you add a quick helper skill and, without thinking, name it
-`config`, a name the agent runtime already owns for its own built-in slash verb.
-skill-map warns you before the runtime silently ignores your skill.
-
-**Preparation**: `Write` `<provider_dir>/config/SKILL.md`:
+**Preparation**: `Write` `<provider_dir>/model/SKILL.md`:
 ```markdown
 ---
-name: config
+name: model
 description: |
   Scaffolds a new empty page in public/ from the shared template.
 ---
 
-# config
+# model
 
 Creates a blank page so you can start writing.
 ```
 
 The watcher picks up the new skill. Tell the tester:
 
-> I added a skill named `config`. Watch the **Map**: the new `config` skill node
+> I added a skill named `model`. Watch the **Map**: the new `model` skill node
 > appears, but flagged with a **warning** marker. Open its inspector: it reads
-> `name-reserved`, `config` shadows one of the agent runtime's own built-in verbs
-> (like `help`, `clear`, `model`), so the runtime would silently ignore your
+> `name-reserved`, `model` shadows one of the agent runtime's own built-in verbs
+> (like `help`, `clear`, `config`), so the runtime would silently ignore your
 > skill, it never runs. The fix is a name the runtime does not own.
 >
-> Rename it to `new-page`: first rename the folder `<provider_dir>/config/` to
+> Rename it to `new-page`: first rename the folder `<provider_dir>/model/` to
 > `<provider_dir>/new-page/`. Then open `new-page/SKILL.md` and, at the top where
-> the frontmatter says `name: config`, change it to `name: new-page`; also change
-> the H1 to `# new-page`. Save.
+> 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`), which
-> for a skill must match its folder, so you rename both. Now `new-page` is yours
-> and the runtime will actually run it.
+> live. What cleared it was changing `frontmatter.name` (which for a skill must
+> match its folder, so you renamed both). Now `new-page` is yours and the runtime
+> will run it.
 >
 > Did the warning clear after the rename?
 
@@ -197,66 +189,96 @@ Wait for confirmation. Mark `reserved`: done. Auto-advance to `publish`.
 
 ## Chapter `publish` - Ship it: run the publish skill for real (~4 min)
 
-**Context**: the harness is a set of instructions, and the `publish` skill ties
-them together. You run it **for real**: it runs the link checker over your pages,
-hands off to the `content-editor` if anything needs a fix, then follows the
-deploy runbook. 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 the publish skill
+catch and fix it for real.
 
-**Preparation**: make sure the pages exist (`index`, `about`, `projects`). When
-the tester asks to publish, **execute the publish flow for real** by following
-`<provider_dir>/publish/SKILL.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, hand it to the `content-editor` and re-run; then walk the
-deploy runbook. Do not role-play it.
+**Preparation**: make sure the pages exist (`index`, `about`, `projects`).
 
-Tell the tester:
+This chapter has two beats: the tester breaks a link in the HTML first, then runs
+the publish skill so `check-links` 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 the publish skill 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 and I'll run your `publish` skill 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
-> skill says to do.
+**Beat 2, run the publish skill for real.** Tell the tester:
 
-After running the flow, report what actually happened (keep promises conditional
-on the real result):
+> Now ship it. Tell me to publish and I'll run your `publish` skill for real,
+> exactly as written. (You can read the skill 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 `<provider_dir>/publish/SKILL.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, hand it to the
+`content-editor` to fix (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 hand it
->   to `content-editor` to fix, then re-check.)
+>   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 handed it to your `content-editor` to fix. 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.
->
-> 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
+> skill 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** 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.
-
 This chapter is lens-agnostic: follow the `stability` chapter in the rich
-daily-loop (`part-daily-loop.md`) verbatim, marking the `AGENTS` handbook node
-`stable` from the inspector, confirming the consent dialog, and watching the
-`stable` badge plus the `AGENTS.sm` sidecar appear. Nothing here depends on the
+daily-loop (`part-daily-loop.md`) verbatim, setting the `AGENTS` handbook node's
+stability from the inspector, confirming the consent dialog, and watching the
+stability badge plus the `AGENTS.sm` sidecar appear. Nothing here depends on the
 lens.
 
 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. Lens-agnostic: follow the `golive` chapter in the rich daily-loop
+Lens-agnostic: follow the `golive` chapter in the rich daily-loop
 (`part-daily-loop.md`) verbatim (the serve commands and the closing congratulation
 are identical), except when you name the harness pieces on the graph, say "the
 handbook, the content-editor, the style guide, the publish skill, the link