@skill-map/cli 0.67.0 → 0.68.1

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

@@ -2,6 +2,13 @@
 
 The live-UI prologue: the tester runs `sm init`, opens the browser, and watches the map update in real time as files are written and edited. `pace: per-step` (one chapter per exchange; the chapter's own confirmation advances to the next, NO separate "¿seguimos?"), `preflight: taught-init` (the tester runs `sm init` as the first taught step, not pre-flight), and the chapters lay the basics fixture progressively, one node at a time. Shared conventions (tone, provider detection / substitution, the `> ` rendering rule, the per-step cycle) live in `_core.md`; do not restate them here.
 
+**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.
+- `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/`.
+
 ## Chapter `init` - Your first node (~2 min)
 
 Agent background (do NOT render this as a separate context paragraph; the tester-facing version is folded into the message below): `sm init` creates a hidden `.skill-map/` folder in the cwd holding the database where skill-map stores what it learns about the project, and runs an initial scan (mandatory first step). Typing `sm` alone (no arguments) in an initialised dir then starts the UI server with the watcher built in (it is just an alias of `sm serve` with all defaults; the moment you need any flag you write `sm serve --flag ...` explicitly). One process, one terminal: it boots the server, scans the `.md` files, detects changes, and pushes events over WebSocket to the live UI. The next chapters all run against this same `sm` session, you boot it here and keep it alive through the `ignore` chapter.
@@ -38,7 +45,7 @@ Wait for confirmation. Mark `init`: done.
 
 Leave the browser open and the terminal with `sm` running. You create five more nodes **without any cross-fixture links** yet, pure standalone nodes, so the tester sees five new nodes pop in. Three new **kinds** show up in this step (skill, command, markdown); the last two files are sibling `markdown` notes (`demo-guideline`, `demo-guideline2`) the hub in the `connectors` chapter reaches two ways, a bare mention that resolves to nothing (which lands as a broken reference, no arrow drawn) and the same handle plus `.md` that resolves to a real file (a solid arrow).
 
-Lay these five files in one go (their content + translation live in `fixtures-data/`). The script resolves `__PROVIDER__` and auto-skips kinds the provider does not claim (`agent-skills` / Antigravity: both `demo-agent` and `demo-command` fold away, only the skill + the three markdown notes remain), so read the actual node count from the summary's `nodeCount`. Backstage (silent):
+Lay these five files in one go (their content + translation live in `fixtures-data/`). The script resolves `__PROVIDER__` to the claude layout (this is the rich track). Backstage (silent):
 
 ```
 node .claude/skills/sm-tutorial/scripts/fixtures.js lay prologue --only "__PROVIDER__/skills/demo-skill/SKILL.md,__PROVIDER__/commands/demo-command.md,notes/todo.md,notes/demo-guideline.md,notes/demo-guideline2.md" --provider <provider> --lang <lang>
@@ -109,7 +116,7 @@ You edit `notes/todo.md` so it becomes the **hub** that points to each of the ot
 
 Five bullets, three kinds: `invokes` and `mentions` each appear twice, `references` once. The last two bullets are the resolution lesson: a bare `@demo-guideline` mention (which resolves to no agent, so it lands as a broken reference and draws no arrow) next to `@demo-guideline2.md`, the same handle shape plus a `.md` extension that points at a real sibling file (so it resolves and draws a solid arrow). Two separate nodes, one broken and one resolved. Five bullets but only four arrows on the canvas.
 
-Apply the hub bullets (their content + translation live in `fixtures-data/`). The edit appends after the `# Pending` heading; the script drops any bullet whose target kind the provider does not claim (on `agent-skills` / Antigravity there is no agent and no command → the `@demo-agent` and `/demo-command` bullets fold away; the two guideline bullets stay, so the resolution contrast, broken mention 0.50 (no arrow drawn) vs resolved reference 1.00 (solid arrow), is intact on those providers too). Backstage (silent):
+Apply the hub bullets (their content + translation live in `fixtures-data/`). The edit appends after the `# Pending` heading. Backstage (silent):
 
 ```
 node .claude/skills/sm-tutorial/scripts/fixtures.js edit todo-connectors --provider <provider> --lang <lang>
@@ -145,14 +152,10 @@ Tell the tester:
 > (That is also why `@demo-agent` drew fine: an `@name` mention
 > resolves when an agent by that name really exists.)
 >
-> One word on solidity: skill-map draws each connector's
-> **confidence** as opacity, and every arrow you see here is fully
-> solid (1.00) because each one lands on a real node. The faint,
-> partial case shows up later in the campaign; for now the rule is
-> simple, a reference
-> that resolves draws a solid arrow, a reference that points at
-> nothing is not drawn at all and gets flagged instead. The exact
-> per-link numbers live in the inspector, next chapter.
+> 💡 Tip: if all these changes left the nodes crowded together, the
+> map toolbar has a **Re-arrange layout** button: it tidies the
+> layout so everything reads better. If you've moved nodes by hand it
+> asks for confirmation first, otherwise it just re-arranges.
 >
 > Confirm when you see the four arrows plus the broken-reference
 > marker on the hub. If an arrow is missing, refresh the browser and
@@ -164,12 +167,6 @@ Expected: four drawn arrows plus one `core/reference-broken` error on `notes/tod
 
 The canvas only draws the resolved arrows; the full per-link breakdown, including the broken one that never drew, lives in the Inspector. Open it on the hub so the tester registers the surface before the `edit-link` chapter changes topology.
 
-> 💡 Tip: if all these changes left the nodes crowded together, the
-> map toolbar has a **Re-arrange layout** button (tooltip "Re-arrange
-> the visible nodes"): it tidies the layout so everything reads
-> better. If you've moved nodes by hand it asks for confirmation
-> first, otherwise it just re-arranges.
->
 > 🆕 Open the Inspector for **Demo TODO list** (click the node on
 > the map). Find the **Connections** section: it has two sections,
 > **Outgoing** and **Incoming**.
@@ -180,7 +177,7 @@ The canvas only draws the resolved arrows; the full per-link breakdown, includin
 > confidence: the numeric value. Here you'll see the contrast, the
 > `references` to `demo-guideline2` reads `1.00` (resolved), while the
 > `mentions` to `demo-guideline` reads `0.50` and is marked broken,
-> that 0.5 is the broken-reference penalty, not a "halfway sure".
+> that 0.5 is the broken-reference penalty, not "half sure".
 >
 > Now open the Inspector for a couple of the nodes to read their
 > Incoming count. The four resolved nodes (`demo-agent`,
@@ -189,6 +186,11 @@ The canvas only draws the resolved arrows; the full per-link breakdown, includin
 > mention never landed on it, so nothing points in. Five outgoing
 > links on the hub, but only four of them reach a node.
 >
+> 💡 Tip: skill-map draws each connector's **confidence** as opacity.
+> Every arrow here is solid (1.00) because it lands on a real node; a
+> reference that points at nothing is flagged instead of drawn. The
+> fainter, partial case shows up later in the campaign.
+>
 > Let me know when you see it.
 
 Mark `inspector`: done.
@@ -223,14 +225,12 @@ Once they confirm, the second edit fixes the broken reference. Tell the tester:
 >
 > Confirm when the new arrow is in and the red marker is gone.
 
-You verify by reading `notes/todo.md` to confirm both edits landed (the `@demo-agent` bullet gone, `@demo-guideline` now `@demo-guideline.md`); the prologue's broken reference is now resolved. (On `agent-skills`, where the `@demo-agent` bullet was never created in the `connectors` chapter, ask the tester to remove the only bullet they did add for the first edit; the `.md` fix on `@demo-guideline` is identical.) Once they confirm, leave the server running, the next chapter reuses it. Mark `edit-link`: done.
+You verify by reading `notes/todo.md` to confirm both edits landed (the `@demo-agent` bullet gone, `@demo-guideline` now `@demo-guideline.md`); the prologue's broken reference is now resolved. Once they confirm, leave the server running, the next chapter reuses it. Mark `edit-link`: done.
 
 ## 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.
 
-Per §Provider detection, on `agent-skills` / Antigravity the fixture has fewer nodes (`demo-skill` plus the two `notes/` files), so swap the node names below for ones that exist in that set; the gestures are identical.
-
 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.
@@ -247,18 +247,20 @@ action itself.
 > Tell me when the tree is open.
 
 > At the top of that sidebar there's a search box (placeholder
-> `Search…`). Type `guideline`. Watch both halves at once: the tree
-> narrows down to the two guideline nodes (`demo-guideline` and
-> `demo-guideline2`) and the **Map** drops every node except those
-> two. The search matches a node's name, path,
-> or description, and filters live as you type, no Enter needed.
+> `Search…`). Type `guideline`. Watch the tree narrow down to the
+> two guideline nodes (`demo-guideline` and `demo-guideline2`). The
+> search matches a node's name, path, or description, and filters
+> live as you type, no Enter needed. The **Map** stays put: by
+> default the search filters only the files list, not the map (the
+> tip below changes that).
 >
-> Now clear the box. All six nodes come back, in both the tree and
-> the Map. Confirm you saw it filter and then restore.
+> Now clear the box. All six nodes come back in the tree. Confirm you
+> saw it filter and then restore.
 
-> Last one. In the tree, find the **Demo TODO list** row: at its
-> right edge there's a small **sitemap** icon (its tooltip reads
-> "Isolate this node and its direct links on the map"). Click it.
+> Last one. In the tree, find the `notes/todo` row (the **Demo TODO
+> list** hub, the tree labels rows by file name): at its right edge
+> there's a small **sitemap** icon (its tooltip reads "Isolate this
+> node and its direct links on the map"). Click it.
 >
 > The Map collapses to **Demo TODO list** plus only the nodes it
 > draws an arrow to (`demo-command`, `demo-skill`,
@@ -271,10 +273,9 @@ action itself.
 >
 > 💡 Tip: remember the search box from a moment ago? The map-icon
 > button right next to it controls whether the search also filters
-> the **Map**. It's on by default, that's why the **Map** narrowed
-> along with the tree when you searched `guideline`. Click it to
-> switch to filtering only the files list, leaving the map's layout
-> in place.
+> the **Map**. It's off by default, which is why the **Map** stayed
+> put while only the tree narrowed when you searched `guideline`.
+> Click it on if you want a search to filter the map too.
 >
 > Did the map isolate and then restore?
 

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

@@ -27,12 +27,9 @@ 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.
 
-**Preparation**: `Edit` `<provider_dir>/agents/content-editor.md`
-(substitute `<provider_dir>` per `_core.md`; on `agent-skills` /
-Antigravity the editor is a `skill` instead, edit that file's
-frontmatter the same way). Do NOT rewrite the file. Change only the
-`tools:` line in the frontmatter so the MCP tool joins the existing
-two:
+**Preparation**: `Edit` `.claude/agents/content-editor.md`. Do NOT
+rewrite the file. Change only the `tools:` line in the frontmatter so
+the MCP tool joins the existing two:
 
 ```yaml
 tools: [Read, Write, mcp__images__search]

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

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

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

@@ -5,9 +5,13 @@ starts an actual project: a tiny personal **portfolio website**,
 fully static, served by a ~15-line Express server, plus the
 `.claude/` **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).
-`pace: per-step`, `preflight: portfolio-init`. Shared
-conventions live in `_core.md`.
+is plain HTML the harness produces (the daily loop, Part 2, runs and ships it).
+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, a link checker, a publish command, the handbook turned
+hub, and a close-up on connector confidence (the `check-links` to
+`confidence` chapters). `pace: per-step`, `preflight: portfolio-init`.
+Shared conventions live in `_core.md`.
 
 The orchestrator's `portfolio-init` pre-flight (backstage, silent)
 has already laid the bare project skeleton before the tester runs
@@ -16,6 +20,27 @@ which are `.md`, so the scan ignores them), the portfolio
 `.skillmapignore`, and the handbook `AGENTS.md` (the one boot node).
 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.
+- `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
+  guide from the start (baked into `developer_instructions`), so lay
+  `docs/STYLE.md` together with it (`fixtures.js lay portfolio --only
+  "__PROVIDER__/agents/content-editor.md,docs/STYLE.md" --provider codex …`,
+  the `--only` matches the TOML overlay by node id) so the
+  `content-editor -> docs/STYLE.md` arrow resolves immediately instead of
+  showing a transient broken-reference.
+- `real-kinds`: Codex's kinds are `agent` (TOML) + `skill` + `markdown`, there is
+  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.
+- `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
@@ -28,14 +53,13 @@ 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.** This
-project has a root `AGENTS.md` (the `codex`/Codex marker) sitting next
-to the `.claude/` folder (the `claude` marker, where the tutorial skill
-itself lives). `codex` is **experimental** (ships disabled), though, so auto-detect
-ignores its marker and `sm init` resolves the lens to `claude`
-silently, exactly like the prologue: only `claude` is selectable today,
-so there is no ambiguity and no prompt. Do not promise the tester a
-lens prompt here.
+**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.
 
 ```bash
 sm init
@@ -49,9 +73,8 @@ Tell the tester:
 > `.claude/` folder is the **harness** (the helpers that maintain the
 > site). skill-map maps that harness.
 >
-> Run `sm init`, it auto-detects the `claude` lens (this is a Claude
-> project; the other lenses are experimental). Then run `sm` to boot the
-> live UI.
+> Run `sm init`, it auto-detects the `claude` lens from the `.claude/`
+> folder. Then run `sm` to boot the live UI.
 >
 > Open the URL `sm` printed. You'll see **one node**: `AGENTS.md`,
 > the project's handbook (the operating manual for the site).
@@ -89,8 +112,7 @@ then render it in the fenced block the tester copies:
 > as a file pointer (the same `@name.md` reference you met in the
 > prologue), and since the handbook is right there
 > the link resolves with full confidence. It tells anyone (and
-> skill-map) that `CLAUDE.md` defers to the handbook. This is exactly
-> how this tool's own repo is wired.
+> skill-map) that `CLAUDE.md` defers to the handbook.
 >
 > Did the connector light up?
 
@@ -99,9 +121,7 @@ Wait for confirmation. Mark `manual`: done.
 ## Chapter `first-agent` - The first harness agent (~2 min)
 
 Lay the first harness agent (its content + translation live in
-`fixtures-data/`). The script resolves `__PROVIDER__`; on
-`agent-skills` / Antigravity, which has no `agent` kind, adjust the
-prose to the skill the set lays there. Backstage (silent):
+`fixtures-data/`). Backstage (silent):
 
 ```
 node .claude/skills/sm-tutorial/scripts/fixtures.js lay portfolio --only "__PROVIDER__/agents/content-editor.md" --provider <provider> --lang <lang>
@@ -111,8 +131,8 @@ Tell the tester:
 
 > I added the first real member of your harness: an agent called
 > `content-editor` (its job is to write the site's pages). A new
-> `agent` node appeared on the map. Right now it stands alone; in the
-> next part we wire it to the handbook and the style guide.
+> `agent` node appeared on the map. 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 inside, open `<provider_dir>/agents/content-editor.md` in your
@@ -147,14 +167,166 @@ Tell the tester:
 > - **agent**: `content-editor` (does work on your behalf).
 > - **markdown**: `AGENTS.md`, `CLAUDE.md`, the two docs (plain notes
 >   and manuals).
-> - **skill** and **command**: you add these (the link checker and
->   the publish command) in a later part.
+> - **skill** and **command**: you add these later in this part (the
+>   link checker and the publish command).
 >
 > Your handbook now has a real harness around it: a `content-editor`
 > agent plus its docs, all on the map.
 >
 > See the agent and the docs in the map?
 
-Wait for confirmation. Mark `real-kinds`: done. Last chapter of the
-part: apply §Closing a part (the close names the part by its title and
-routes back to the menu; do NOT lead into the next part from here).
+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):
+
+```
+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 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.
+
+> Create `.claude/commands/publish.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 command you run when the site is ready to go out.
+
+## Steps
+1. Run /check-links on the pages in public/. If it reports broken links, stop and fix them first.
+2. If a page needs a content fix, brief @content-editor with the change.
+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, and each one is a different colour
+> because each one is a different kind of link:
+>
+> - `publish -> check-links` (kind: `invokes`), from the `/check-links`
+>   token in the body.
+> - `publish -> content-editor` (kind: `mentions`), from the
+>   `@content-editor` token.
+> - `publish -> docs/DEPLOY.md` (kind: `references`), from the
+>   `[deploy runbook](../../docs/DEPLOY.md)` markdown link.
+>
+> One node, three connectors, three link kinds. The harness is
+> starting to look like a real graph.
+>
+> 💡 Tip: to tidy every node into a clean layout, click the
+> **Re-arrange layout** button in the map toolbar. Handy whenever the
+> graph starts to look crowded.
+>
+> Did the three arrows appear?
+
+Wait for confirmation. You MAY use `Read` on the file afterwards to verify it landed, in particular that the opening and closing `---` are flush at column 0. If a later `sm check` flags `frontmatter-malformed` on `publish.md`, the fences got indented on paste: have the tester re-align every line flush left (strip the leading spaces so `---` is at column 0), then the next scan reads it clean. 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: 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):
+
+```
+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
+> command. And the content editor now reaches the style guide it
+> follows. New arrows:
+>
+> - `AGENTS.md -> content-editor` (kind: `mentions`), from `@content-editor`.
+> - `AGENTS.md -> /publish` (kind: `invokes`), from `/publish`.
+> - `content-editor -> docs/STYLE.md` (kind: `references`), from the
+>   `[style guide](../../docs/STYLE.md)` markdown link.
+>
+> Here is the whole recap of the three link kinds, one per syntax:
+>
+> - an `@handle` token is always a **mention**.
+> - a `/slash` token is always an **invoke**.
+> - a `[text](path.md)` markdown link is always a **reference**.
+>
+> The kind comes purely from how you wrote it. Your harness is wired
+> end to end now: the handbook reaches the work, the work reaches the
+> docs, and `/publish` pulls the whole publish flow together.
+>
+> Did the new arrows light up?
+
+Wait for confirmation. You MAY use `Read` on the two files afterwards to verify the edits landed before moving on. Mark `links`: done.
+
+## Chapter `confidence` - How sure is each link (~3 min)
+
+No file edits in this chapter, pure observation on the graph the tester just built.
+
+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 node is solid (**1.00**), a link that
+> does not lands fainter, so a glance at the **Map** separates the
+> solid wiring from the problem links.
+>
+> Open the Inspector for the `publish` node (click it on the **Map**).
+> Scroll down to the **Connections** panel and read the **Outgoing**
+> rows. Each row shows the link kind and a confidence badge, and here
+> every one reads **1.00**:
+>
+> - `publish -> docs/DEPLOY.md` (`references`) is a markdown link to a
+>   file that exists on disk, so skill-map is certain.
+> - `publish -> content-editor` (`mentions`) resolves to the real
+>   content-editor agent, and `publish -> check-links` (`invokes`)
+>   resolves to the real check-links skill, so both are certain too.
+>
+> Your whole harness reads solid because every link lands on a real
+> node, that is what a clean, fully wired graph looks like. So what
+> does a link that does NOT resolve look like? You met one back in the
+> prologue: `@demo-guideline` was a reference skill-map could not
+> resolve, it had nothing to land on, so skill-map drew no arrow and
+> flagged it as a **broken reference**, its confidence knocked down to
+> **0.50** by the broken penalty. The fix was one character: adding
+> `.md` (`@demo-guideline.md`) turned it into a file reference to the
+> real `demo-guideline.md`, and it drew a solid arrow at **1.00**.
+>
+> **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.
+>
+> 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 (the close names the part by its title and routes back to the menu; do NOT lead into the next part from here).

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

@@ -1,6 +1,6 @@
-# Part 4 (a): Extend skill-map - settings (step library, `settings-*` ids)
+# Part 3 (a): Extend skill-map - settings (step library, `settings-*` ids)
 
-Step bodies for the settings chapters of Part 4 (config layers, the
+Step bodies for the settings chapters of Part 3 (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`.
@@ -125,16 +125,19 @@ Mark `settings-2-resolve: done`.
 
 **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.
+never touches your `.md` files. (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
 > at a time, and that lens decides how each file is interpreted, so
 > the same files can read differently depending on which lens is active.
 
-> The lens auto-detects on the first scan from your project's layout
-> (a `.claude/` folder selects the `claude` lens). Scan once and check
-> where it landed:
+> The lens auto-detects on the first scan from the project's layout. A
+> marker folder selects its lens: `.claude/` → `claude`, `.codex/` →
+> `codex`, `.agent/workflows/` → `antigravity`; a project with only
+> `.agents/skills/` and no vendor marker falls back to the open-standard
+> `agent-skills` lens. Scan once and check where it landed:
 
 ```bash
 sm scan
@@ -142,17 +145,18 @@ sm config get activeProvider
 ```
 
 Expected: the scan prints a line like `Auto-detected activeProvider
-= claude from filesystem markers; persisted to
-.skill-map/settings.json`, and `get` then reports `claude`. The lens
+= <provider> from filesystem markers; persisted to
+.skill-map/settings.json`, and `get` then reports `<provider>`. The lens
 is just a key in `settings.json`, persisted like any other setting.
 
-> Other lenses exist in the engine (`codex` for Codex,
-> `agent-skills`, `antigravity`), but they are **experimental** (ship
-> disabled by default): today we demo the `claude` lens only. The idea to keep is
-> the one above, one project reads through exactly one provider at a
-> time, chosen by `activeProvider`. The lens is cheap to change later
-> because the graph is always rebuilt from your files, never the
-> other way around.
+> The other lenses are just as real: `claude` and the open-standard
+> `agent-skills` are stable; `codex` (OpenAI) and `antigravity` (Google)
+> are beta but ship enabled and auto-detect their own marker. The open
+> `agent-skills` lens is the default a project falls back to when no
+> vendor marker is present. The idea to keep: one project reads through
+> exactly one lens at a time, chosen by `activeProvider`, and it is cheap
+> to change later because the graph is always rebuilt from your files,
+> never the other way around.
 
 Mark `settings-3-lens: done`.