@skill-map/cli 0.69.0 → 0.71.0

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

@@ -23,20 +23,84 @@ what the tester names their portfolio. Persist the answer with
 antigravity) walks its own `basic-daily` part. **Codex deltas** (when
 `tutorial.provider == codex`): the `content-editor` is a TOML agent at
 `.codex/agents/content-editor.toml`, and Codex has no `command` kind, so
-`publish` is a **skill** at `.agents/skills/publish/SKILL.md`. The `@`/`/`
-connectors all resolve on Codex, so every beat lands the same; only the path /
-kind of those two nodes changes. Per chapter:
-
-- `add-page`: invoke the `content-editor` TOML agent via the Task tool (same flow).
+`publish` is a **skill** at `.agents/skills/publish/SKILL.md`. The CONNECTOR
+GRAMMAR differs: Codex invokes a skill with `$` (not `/`, a Codex built-in
+command) and `@` is a file picker (not an agent mention), so `$publish` /
+`$check-links` invoke and the `content-editor` agent is referenced by a
+markdown link to its `.toml`. Per chapter:
+
+- `add-page` (Codex: the tester runs the agent for real in a fresh Codex).
+  Codex loads its agents only at startup and has no live reload (`/agent`
+  just switches existing threads), and the `content-editor` was created
+  mid-tutorial, so it is not invocable in any running session. Do NOT invoke
+  it via the Task tool and do NOT tell the tester to "reload". Instead hand
+  the run to the tester in a fresh Codex so they watch their own agent work,
+  reusing the **third terminal** (the one running `node server.js`); `sm`
+  stays up in the second terminal so the "Map unchanged" beat still lands.
+  Skip the claude `add-page` body and run this flow. First ask what page
+  they want:
+
+  > Your turn to delegate, for real, and the page is yours: tell me what to
+  > add, about anything you like, your projects, your talks, a reading list,
+  > whatever fits your site.
+
+  When they answer, guide them, dropping the topic they chose into the
+  `<your topic>` placeholder below:
+
+  > Your `content-editor` is a real Codex agent
+  > (`.codex/agents/content-editor.toml`). Heads up, this is a Codex
+  > limitation: Codex reads its agents only when it boots and has no way to
+  > reload them mid-session, so an agent you just created is not available
+  > until you start Codex again. That is why we run it in a fresh Codex now,
+  > and you get to watch it work. In your **third terminal** (the one running
+  > `node server.js`), stop the site with `Ctrl+C`, then start Codex in the
+  > same folder:
+
+  ```bash
+  codex
+  ```
+
+  > Once it is up, ask it for the page you chose, in your own words, for
+  > example:
+
+  ```text
+  Use the content-editor agent to add a page about <your topic>.
+  ```
+
+  > Watch it run: it writes your new page under `public/` for real, the way
+  > it would on a normal day. When it finishes, exit Codex (`Ctrl+D`), bring the
+  > site back up with `node server.js`, and refresh
+  > `http://localhost:3000`. Your new page is there, in the same style.
+  >
+  > Now glance at the **Map** (still running in your second terminal): same
+  > nodes as before, nothing new. The page is Layer 2 output; the harness on
+  > the canvas is Layer 1. Your nodes are not a diagram, they are runnable,
+  > and you just ran one.
+  >
+  > See the new page on the site, and the Map unchanged?
+
+  Wait for confirmation, then mark `add-page` done. If the tester's Codex
+  goes off-script (writes a `.md`, touches the harness, or the page lands
+  wrong), help them steer it, or as a last resort act as the `content-editor`
+  yourself following its rules + `docs/STYLE.md` so the beat still lands.
 - `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/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.
-- `publish`: run the `publish` SKILL's steps for real (same `/check-links` +
-  `@content-editor` + deploy runbook).
+- `reserved` (Codex: SKIP this chapter, it cannot be reproduced). The reserved-
+  name collision is a claude `/`-command beat: a user `/model` COMMAND shadows
+  Codex's own built-in `/model`. On Codex skills are `$`-invoked, a namespace
+  disjoint from the `/` built-in commands, so a skill named like a built-in
+  (`model`) never collides and skill-map flags nothing, there is no beat to
+  show. Do NOT write a `model` skill, do NOT narrate a (non-)warning, do NOT
+  make a beat of it. Silently `state.js mark daily-loop reserved skipped` and go
+  from `broken-ref` straight to `publish`. Keep the numbering it already has:
+  it is position-based, so `publish` stays 3.5, `stability` 3.6, `golive` 3.7
+  (do NOT renumber); the tester simply never sees a 3.4 on Codex.
+- `publish`: run the `publish` SKILL's steps for real (`$check-links` invokes
+  the link checker, the `content-editor` markdown-link reference, the deploy
+  runbook).
+- `golive`: when you name the harness pieces on the graph, say the **publish
+  skill**, not "the publish command" (Codex has no command kind); everything
+  else is identical.
 
 **Real-execution contract (read once).** When invoking the `content-editor` via
 the Task tool, instruct it explicitly to write ONLY `.html` files under
@@ -61,15 +125,6 @@ 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, 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
-few non-`sm` beats); guide them, do not run them.
-
 **Preparation**:
 
 1. Ask the tester the two questions straight, with no "before we build, let's
@@ -262,10 +317,6 @@ Wait for confirmation. Mark `add-page`: done. Auto-advance to `broken-ref`.
 
 ## Chapter `broken-ref` - A rename breaks a link (~4 min)
 
-**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.
 
@@ -341,10 +392,6 @@ 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`).
 
@@ -434,12 +481,17 @@ Tell the tester:
 > 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 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.
+> creates a **`.sm` sidecar file** right next to the handbook, named after it
+> (`AGENTS.md` becomes `AGENTS.sm` in the same folder), 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).
+> What is a **sidecar**? A sibling file that lives in the same folder as the
+> node it describes and is committed to the same repository, so it travels with
+> the `.md` wherever it goes. skill-map keeps what it learns about a node
+> (stability, version, tags) there ON PURPOSE: that is the tool's bookkeeping,
+> not your content, so it stays OUT of your source markdown. Your `.md` files
+> stay clean and authored by you, never polluted by skill-map.
 >
 > See the new stability badge on the handbook?
 
@@ -447,23 +499,25 @@ Wait for confirmation. Mark `stability`: done. Auto-advance to `golive`.
 
 ## Chapter `golive` - Your website, live next to the graph (~3 min)
 
-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`.
+The site is already serving from `add-page` (the tester brought `node server.js`
+back up in their third terminal after their agent wrote its page), so for most
+testers the finale is just opening it, not restarting anything. Only if they
+closed that terminal do they bring it back with the block below; guide them, do
+not run it for them. `npm install` is idempotent if they do restart.
 
 **Preparation**: none. `server.js` / `package.json` exist from the kickoff; the
 pages exist from the earlier chapters.
 
+> Last step, the fun one. Your site is still serving from earlier in your third
+> terminal, so just open `http://localhost:3000` and click through Home, About,
+> and the page you added, the pages your harness produced and shipped through the
+> publish flow you just ran. (If you closed that terminal, bring it back up first
+> with the commands below.)
+
 ```bash
 npm install
 node server.js
 ```
-
-> Last step, the fun one. `npm install` confirms the one small library is there,
-> and `node server.js` starts the server (`Listening on http://localhost:3000`).
->
-> 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 website, named after
 > you, that you could deploy as-is. On the other, the skill-map graph of the

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

@@ -4,10 +4,13 @@ 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`.
+- `init`: the boot node `demo-agent` is a **TOML agent** at `.codex/agents/demo-agent.toml`. `sm init` resolves the `codex` lens with no prompt (the `.codex/` marker outranks the shared `.agents/` open default), so the commands stay `sm init` then `sm`, exactly like claude.
 - `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/`.
+- `connectors`: the hub wires its nodes with the CODEX grammar, NOT claude's `/`+`@`-mention (the `todo-connectors` codex overlay lays the right bullets automatically; you only narrate the shapes). The two skill bullets INVOKE with `$` (`$demo-command`, `$demo-skill`); the agent bullet is a markdown-link reference to the agent file (`[demo-agent](../.codex/agents/demo-agent.toml)`, since Codex cannot `@`-mention an agent); `@demo-guideline2.md` is a file reference (Codex's `@` is a file picker). The bare `@demo-guideline` (no extension) forms NO edge on Codex (`@` points at a FILE, not a name), so the hub shows **four resolved arrows and NO broken-reference marker** (claude's fifth, broken bullet does not exist here). `Expected`: four drawn arrows, zero issues.
+- `inspector` (Codex): the hub lists **four** outgoing links, all resolved at `1.00`, and zero incoming. There is no `0.50` broken row (the bare `@demo-guideline` formed nothing); adapt the claude "five links, one broken" wording to "four links, all resolved".
+- `edit-link` (Codex): the tester turns the inert bare `@demo-guideline` into a file reference by adding `.md` (`@demo-guideline.md`), and the new arrow appears live. Same muscle memory as claude ("add `.md`"), but the Codex lesson is "`@` needs a filename to be a file reference, a bare `@handle` is just text".
+- `workspace` / `ignore`: identical; only the directory tree shows `.codex/agents/` + `.agents/skills/` instead of `.claude/`.
 
 ## Chapter `init` - Your first node (~2 min)
 
@@ -197,8 +200,6 @@ Mark `inspector`: done.
 
 ## Chapter `edit-link` - Edit a link, the topology changes (~3 min)
 
-**Context**: the `first-edit` chapter had the tester edit a scalar (`description`) and watch the inspector card refresh. This chapter raises the bar: edit Markdown links and watch the MAP TOPOLOGY change both ways, a connector disappears when you remove a link, and a new one appears (clearing the broken-reference error) when you fix the unresolved one.
-
 The server has been live since the `init` chapter, leave it running; this chapter and the next two (the workspace tour, then `.skillmapignore`) reuse it.
 
 > Your turn. Edit `notes/todo.md` with your editor of choice and
@@ -229,8 +230,6 @@ You verify by reading `notes/todo.md` to confirm both edits landed (the `@demo-a
 
 ## Chapter `workspace` - Navigate the workspace (files, search, isolate) (~2 min)
 
-**Context**: you've built the graph and understood it; this beat is about *moving around* it. The workspace has two halves: the **Map** you've been working in, and a **Files** panel, a folder tree of every node. You'll open that tree and filter it with the search box. The same `sm` session you booted back in the `init` chapter is still running.
-
 Walk the three tester actions below one at a time (open the Files
 panel, then search, then isolate); each ends with its own
 confirmation, so present one and wait for the tester before the next.
@@ -251,8 +250,12 @@ action itself.
 > 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).
+> default the search filters only the files list, not the map.
+>
+> 💡 Tip: the map-icon button right next to the search box controls
+> whether the search also filters the **Map**. It's 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.
 >
 > Now clear the box. All six nodes come back in the tree. Confirm you
 > saw it filter and then restore.
@@ -271,12 +274,6 @@ action itself.
 > the Map: there's a **Show all** button (an eye icon). Click it and
 > all six nodes return.
 >
-> 💡 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 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?
 
 Leave the server running, the next chapter (`.skillmapignore`) is the last one that uses it. Mark `workspace`: done.

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

@@ -12,20 +12,10 @@ only. Shared conventions live in `_core.md`.
 
 ## Chapter `mcp-node` - The agent reaches for an MCP tool (~3 min)
 
-**Context**: until now every node on the map has been a file you can
-open. This chapter introduces a node that is NOT a file: an MCP
-server the `content-editor` agent calls. MCP (Model Context
-Protocol) is the standard way an agent reaches an external tool, and
-Claude names those tools `mcp__<server>__<tool>` in an agent's
-frontmatter. When the agent declares it uses `mcp__images__search`
-(an image-search tool, so it can find art for the pages), skill-map's
-`core/mcp-tools` extractor reads that declaration and draws a
-virtual `mcp://images` node plus a `references` link from
-content-editor to it. The link confidence is around 0.85 (high, but
-not the 1.00 of a markdown link to a real file, because the target is
-an external service, not a file on disk). If several harness members
-named the same server, skill-map would draw a single shared
-`mcp://images` node, not one per caller.
+Agent note (not narrated, the demo only adds one tool so it never
+manifests here): if several harness members named the same MCP
+server, skill-map draws ONE shared `mcp://images` node, not one per
+caller.
 
 **Preparation**: `Edit` `.claude/agents/content-editor.md`. Do NOT
 rewrite the file. Change only the `tools:` line in the frontmatter so

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

@@ -23,10 +23,6 @@ restore the files.") and stop.
 
 ## Step `tour-1-intro` - how plugins work (~4 min)
 
-**Context**: A short tour of what a plugin is, how it groups
-extensions, and a peek at the five plugins that ship
-pre-installed.
-
 > Plugins are how skill-map gets extended. A **plugin** is the
 > deployable unit: one directory with a `plugin.json` manifest and
 > the extension code. It groups one or more **extensions**, the
@@ -130,10 +126,6 @@ Mark `tour-2-kinds: done`.
 
 ## Step `tour-3-explore` - explore one extension up close (~4 min)
 
-**Context**: Drill into a single extension to see its detail,
-run the diagnostic, then toggle one off and back on so you see
-the change persists.
-
 > Pick one extension and look at its details. We'll use
 > `core/external-url-counter`, an extractor that counts how many
 > external URLs each node body contains:

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

@@ -22,9 +22,11 @@ The chapters grow the harness from there.
 
 **Codex deltas (rich track).** When `tutorial.provider == codex`:
 
-- `kickoff` / `manual`: identical. A `.codex/` project resolves the `codex`
-  lens; `CLAUDE.md`'s `@AGENTS.md` reference resolves the same (Codex has the
-  `@`-directive). `AGENTS.md` is still the one boot node.
+- `kickoff` / `manual`: identical flow (`sm init` then `sm`, no lens
+  prompt, `.codex/` outranks the shared `.agents/` home). `CLAUDE.md`'s
+  `@AGENTS.md` reference resolves the same (it carries `.md`, so Codex reads
+  `@AGENTS.md` as a FILE reference, Codex's `@` is a file picker, not an agent
+  mention). `AGENTS.md` is still the one boot node.
 - `first-agent`: the `content-editor` is a **TOML agent** at
   `.codex/agents/content-editor.toml`, not a `.claude/agents/*.md` file; point
   the tester at the `.toml` if they want to peek. Its body references the style
@@ -38,28 +40,24 @@ 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); 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.
+- `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 uses the CODEX grammar (`$check-links` invokes the link checker; a markdown link references `content-editor`; the deploy runbook is a markdown reference), so the three connectors still light up, just `$`/file-ref instead of `/`+`@`-mention. 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)
 
-**Context**: same `sm init` the tester learned in the prologue, but
-now on a real project. The map will show the project's harness, not
-throwaway demo nodes.
-
 If the prologue (`fundamentals`) ran first in this directory, the
 demo fixture (`demo-agent`, `demo-skill`, `notes/…`) is still on
 disk. The orchestrator's `portfolio-init` already cleared it during
 pre-flight, so the tester sees only the portfolio. If anything demo
 lingers, mention it once and move on.
 
-**Context (agent, do not narrate the plumbing): the lens.** The skill
-was scaffolded under `.claude/` (the `claude` marker, where the tutorial
-skill itself lives), so `sm init` auto-detects the `claude` lens with no
-prompt. The root `AGENTS.md` is the vendor-neutral handbook, NOT a lens
-marker, so it never forces an ambiguous prompt. (This is the rich track;
-a Codex project resolves the `codex` lens the same way from its
-`.codex/` marker.) Do not promise the tester a lens prompt here.
+**Context (agent, do not narrate the plumbing): the lens.** `sm init`
+auto-detects the lens with no prompt: claude from its lone `.claude/`
+marker, codex from `.codex/` (which outranks the shared `.agents/` open
+default, so the extra `.agents/skills/` skill home does NOT trigger an
+ambiguous prompt). The root `AGENTS.md` is the vendor-neutral handbook,
+NOT a lens marker, so it never forces a prompt either. Do not promise the
+tester a lens prompt here.
 
 ```bash
 sm init
@@ -88,12 +86,6 @@ Wait for confirmation. Mark `kickoff`: done.
 
 ## Chapter `manual` - The handbook (AGENTS.md) and CLAUDE.md (~2 min)
 
-**Context**: the dogfood beat. Real Claude Code projects can
-reference the generic `AGENTS.md` from their `CLAUDE.md` (this very
-repo does). That one-line pointer is a real `references` link (the
-`.md` extension makes `@AGENTS.md` a file pointer), the tester's first
-connector on the real project.
-
 Tell the tester to create the file themselves (it is their project's
 file, Inviolable rule #2). Backstage, get the content:
 `node .claude/skills/sm-tutorial/scripts/fixtures.js cat portfolio --file "CLAUDE.md" --provider <provider> --lang <lang>`,
@@ -145,11 +137,6 @@ Wait for confirmation. Mark `first-agent`: done.
 
 ## Chapter `real-kinds` - The real kinds in context (~2 min)
 
-**Context**: the prologue showed the four kinds on abstract demo
-nodes. Now name them on the real project, and add the two markdown
-docs the harness references later (the style guide and the deploy
-runbook), so the Daily Loop's maintenance beats have something to point at.
-
 Lay the two markdown docs the harness references later (their content
 + translation live in `fixtures-data/`). Backstage (silent):
 
@@ -179,8 +166,6 @@ 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` command in the next chapter is its caller.
-
 Lay the `check-links` skill (its content + translation live in
 `fixtures-data/`; this kind exists on every provider, so no skip).
 Backstage (silent):
@@ -201,9 +186,7 @@ Wait for confirmation. Mark `check-links`: done.
 
 ## Chapter `publish` - The publish command (~4 min)
 
-**Context**: this is the chapter where the graph comes alive. The `/publish` command ties three pieces together in one body: it invokes the link checker, mentions the content editor, and references the deploy runbook. Three connectors light up from a single new node, one per link syntax.
-
-Tell the tester to create the file themselves (it is their project's file, Inviolable rule #2). Substitute `<provider_dir>` per `_core.md` in the path you give them. Backstage, get the content: `node .claude/skills/sm-tutorial/scripts/fixtures.js cat harness --file "__PROVIDER__/commands/publish.md" --provider <provider> --lang <lang>`, then render it as a **top-level fenced code block**: at column 0, NOT inside the `> ` blockquote and with NO leading indentation, so the tester's copy keeps every line flush left. The frontmatter fences (`---`) MUST land on column 0. If the block is rendered (or pasted) indented, the opening and closing `---` shift off column 0, the YAML never parses, and the `publish` node loads body-only without its `name` / `description` (`sm check` then warns `frontmatter-malformed`). Present the block below exactly as written.
+Tell the tester to create the file themselves (it is their project's file, Inviolable rule #2). Substitute `<provider_dir>` per `_core.md` in the path you give them. Backstage, get the content: `node .claude/skills/sm-tutorial/scripts/fixtures.js cat harness --file "__PROVIDER__/commands/publish.md" --provider <provider> --lang <lang>`, then render it as a **top-level fenced code block**: at column 0, NOT inside the `> ` blockquote and with NO leading indentation, so the tester's copy keeps every line flush left. The frontmatter fences (`---`) MUST land on column 0. If the block is rendered (or pasted) indented, the opening and closing `---` shift off column 0, the YAML never parses, and the `publish` node loads body-only without its `name` / `description` (`sm check` then warns `frontmatter-malformed`). Present the block below exactly as written, line for line: never soft-wrap, and never let a newline fall inside a `[text](path)` link (a break inside the `(path)`, e.g. `(../../docs/DEPLOY.md)`, splits it and the link stops resolving). See `_core.md` §Language mirroring + fixture content.
 
 > Create `.claude/commands/publish.md` with exactly this content (the first line is `---`, nothing before it):
 
@@ -251,8 +234,6 @@ Wait for confirmation. You MAY use `Read` on the file afterwards to verify it la
 
 ## 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: we add two bullets so it mentions the content editor and invokes the publish command. We also give the content editor a reference to the style guide it follows. Several connectors land, and we recap the three link kinds and which syntax produced each.
-
 Apply both edits (their content + translation live in `fixtures-data/`).
 The first appends the two hub bullets to `AGENTS.md`; the second adds
 the style-guide reference line to the content-editor. Backstage (silent):
@@ -323,9 +304,10 @@ Tell the tester:
 >
 > **IMPORTANT:** why does confidence matter? It mirrors how the runtime itself
 > resolves a reference: a deterministic name-and-path lookup, no guessing
-> and no scanning the tree for a file under some other extension. That is
-> cheaper and it does not fail, so the agent spends fewer tokens and less
-> time, the same reason a clean, well-named harness is worth keeping.
+> and no scanning the tree for a file under some other extension. A link that
+> does not resolve sends the agent guessing and retrying, which burns time and
+> tokens; a deterministic one does not fail and resolves first try, the same
+> reason a clean, well-named harness is worth keeping.
 >
 > Do you see every badge reading 1.00 in the Inspector?
 

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

@@ -22,9 +22,6 @@ stop, do not try to re-init mid-chapter.
 
 ## Step `settings-1-layers` - the config layers (~3 min)
 
-**Context**: where settings live and how `sm` resolves a value
-when more than one place sets it.
-
 > `sm` resolves every setting through a stack of **layers**, each
 > one overriding the layer below it:
 >
@@ -74,9 +71,6 @@ Mark `settings-1-layers: done`.
 
 ## Step `settings-2-resolve` - read, resolve, and set a value (~3 min)
 
-**Context**: the four config verbs (`get`, `show`, `set`, `reset`)
-and how `show --source` reveals which layer won.
-
 > Read a single setting. We'll use `scan.maxNodes`, the cap on how
 > many nodes a scan walks:
 
@@ -123,10 +117,8 @@ Mark `settings-2-resolve: done`.
 
 ## Step `settings-3-lens` - the active provider lens (~2 min)
 
-**Context**: the single most consequential setting, the lens that
-decides which provider types the project's files. It auto-detects and
-never touches your `.md` files. (Agent: substitute `<provider>` with
-`tutorial.provider`, the lens this run was scaffolded for.)
+(Agent: substitute `<provider>` with `tutorial.provider`, the lens
+this run was scaffolded for.)
 
 > One setting earns its own step: the **active provider lens**. A
 > skill-map project reads its files through exactly **one** provider

package/dist/cli/tutorial/sm-tutorial/scripts/lib/paths.js

@@ -58,9 +58,10 @@ export function overlayKey(provider) {
 /**
  * Kinds whose edit fragments (the todo-connectors hub bullets, etc.) apply for
  * a provider, keyed by TRACK, not by the base-tier kinds. A rich provider links
- * to every node role even when it renders some differently, Codex's agent is a
- * TOML overlay and its command-node is a skill, but an `@agent` mention and a
- * `/command` invocation still resolve, so every bullet applies. A basic
+ * to every node role even when it renders some differently (Codex's agent is a
+ * TOML overlay and its command-node is a skill), so every hub bullet applies;
+ * the per-provider overlay then supplies the right connector grammar (claude
+ * `/`+`@`, codex `$`-invoke + `@`-file / markdown-link references). A basic
  * provider only has skill + markdown, so the agent / command bullets fold away.
  */
 export function fragmentKindsFor(provider) {
@@ -134,5 +135,5 @@ export function nodeIdForTokenPath(tokenRelPath) {
   if (codexAgent) return codexAgent[1];
   return tokenRelPath;
 }
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9a867c5a-0c61-500e-a583-7d7dd6c5ac92")}catch(e){}}();
-//# debugId=9a867c5a-0c61-500e-a583-7d7dd6c5ac92
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="54e1e331-4312-5c77-adc1-287ab9df7502")}catch(e){}}();
+//# debugId=54e1e331-4312-5c77-adc1-287ab9df7502