@skill-map/cli 0.68.1 → 0.69.0

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

@@ -101,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`.
@@ -146,30 +149,30 @@ Wait for confirmation. The harness MUST be clean again before Act C. Mark
 
 ## Chapter `reserved` - A reserved name collides (~2 min)
 
-**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`. 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. What cleared it was changing `frontmatter.name` (which for a skill must
@@ -186,37 +189,82 @@ Wait for confirmation. Mark `reserved`: done. Auto-advance to `publish`.
 
 ## Chapter `publish` - Ship it: run the publish skill for real (~4 min)
 
-**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.
+**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.
 
-Tell the tester:
+**Preparation**: make sure the pages exist (`index`, `about`, `projects`).
+
+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`.
+
+**Beat 2, run the publish skill for real.** Tell the tester:
+
+> 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.)
 
-> 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. (You can read the skill's content 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 (keep promises conditional
-on the real result):
+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).
 >
-> 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)
 

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

@@ -315,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

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

@@ -1,4 +1,4 @@
-# Part 4: 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

@@ -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.
@@ -249,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`.
@@ -297,30 +300,30 @@ done. Auto-advance to `reserved`.
 
 ## Chapter `reserved` - A reserved name collides (~2 min)
 
-**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
+> 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`,
@@ -338,40 +341,83 @@ Wait for confirmation. Mark `reserved`: done. Auto-advance to `publish`.
 
 ## Chapter `publish` - Ship it: run /publish for real (~4 min)
 
+**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`.
+
+**Beat 2, run /publish for real.** Tell the tester:
+
+> 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.)
 
-> 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. (You can read the command's content
-> 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 (keep the promises
-conditional on the real result):
+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).
 >
-> 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)
 

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

@@ -5,7 +5,7 @@ The live-UI prologue: the tester runs `sm init`, opens the browser, and watches
 **Codex deltas (rich track).** When `tutorial.provider == codex` the lay commands are unchanged (the `--only` ids match the Codex overlay), but the on-disk shapes differ; substitute in the tester-facing prose:
 
 - `init`: the boot node `demo-agent` is a **TOML agent** at `.codex/agents/demo-agent.toml`.
-- `kinds`: the node list reads `.codex/agents/demo-agent.toml` (agent), `.agents/skills/demo-command/SKILL.md` (Codex has no `command`, so this node is a **skill**), `.agents/skills/demo-skill/SKILL.md` (skill), and the `notes/*.md`. Name the kinds as agent + skill + markdown.
+- `kinds`: the node list reads `.codex/agents/demo-agent.toml` (agent), `.agents/skills/demo-command/SKILL.md` (skill), `.agents/skills/demo-skill/SKILL.md` (skill), and the `notes/*.md`. Name the kinds as agent + skill + markdown (two new kinds this step: skill + markdown). Present `demo-command` as a plain skill: do NOT tell the tester it "is a command" or narrate any command-to-skill substitution. Codex has no `command` kind, so on this track `demo-command` is simply one of the two skills, nothing to explain.
 - `first-edit`: the description to edit lives in `.codex/agents/demo-agent.toml` (the `description = "…"` TOML field, not YAML frontmatter).
 - `connectors` onward: identical, the `@`/`/` bullets resolve the same on Codex; only the `ignore` chapter's directory tree shows `.codex/agents/` + `.agents/skills/` instead of `.claude/`.
 
@@ -177,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 "half sure".
+> that 0.5 is the broken-reference penalty, it's a "half sure".
 >
 > Now open the Inspector for a couple of the nodes to read their
 > Incoming count. The four resolved nodes (`demo-agent`,
@@ -313,7 +313,7 @@ Give the tester a mental map of the folder so they know where the file lives, th
 │   └── 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-plugins.md

@@ -1,4 +1,4 @@
-# Part 3 (b): Extend skill-map - plugins (step library, `tour-*` ids)
+# Part 4 (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

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

@@ -1,4 +1,4 @@
-# Part 1: The project from zero (step library, `kickoff-*` ids)
+# Part 1: The harness from zero (step library, `kickoff-*` ids)
 
 The campaign turns real here. After the abstract prologue, the tester
 starts an actual project: a tiny personal **portfolio website**,
@@ -38,7 +38,7 @@ The chapters grow the harness from there.
   no `command`. Lay only `docs/DEPLOY.md` here (STYLE landed in `first-agent`),
   and name the kinds as agent + skill + markdown (the skill + the publish piece
   arrive later in this part as skills).
-- `publish`: Codex has no `command` kind, so the tester creates a **skill** at `.agents/skills/publish/SKILL.md` instead of `.claude/commands/publish.md`. The body is the Codex one (same `/check-links` + `@content-editor` + deploy reference); fetch it with `fixtures.js cat harness --file "__PROVIDER__/skills/publish/SKILL.md" --provider codex --lang <lang>`. Tell the tester they are creating a `skill` (one node, three connectors, same as the claude command). The fixture lays no `publish` for codex in this chapter (the tester authors it), so the `cat` is the source.
+- `publish`: Codex has no `command` kind, so the tester creates a **skill** at `.agents/skills/publish/SKILL.md` instead of `.claude/commands/publish.md`. The body is the Codex one (same `/check-links` + `@content-editor` + deploy reference); fetch it with `fixtures.js cat harness --file "__PROVIDER__/skills/publish/SKILL.md" --provider codex --lang <lang>`. Tell the tester they are creating a `skill` (one node, three connectors); present it plainly as a skill, with no mention of a command or a substitution (per _core.md §Rendering the rich book on Codex, silent substitution). The fixture lays no `publish` for codex in this chapter (the tester authors it), so the `cat` is the source.
 - `links`: the `content-editor-style` reference is baked into the Codex content-editor's TOML (`developer_instructions`) at lay time, so the `edit content-editor-style` step is a no-op on Codex, the `content-editor -> docs/STYLE.md` arrow is already drawn from earlier in this part. Run only `edit agents-hub` and narrate the two `AGENTS.md` arrows; mention the style-guide arrow as already present.
 
 ## Chapter `kickoff` - Start the portfolio (~2 min)

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

@@ -1,6 +1,6 @@
-# Part 3 (a): Extend skill-map - settings (step library, `settings-*` ids)
+# Part 4 (a): Extend skill-map - settings (step library, `settings-*` ids)
 
-Step bodies for the settings chapters of Part 3 (config layers, the
+Step bodies for the settings chapters of Part 4 (config layers, the
 `sm config` verbs, the active provider lens). The SKILL.md
 orchestrator dispatches each `settings-*` chapter id here;
 `authoring-*` ids it dispatches to `part-authoring.md`.