@skill-map/cli 0.68.1 → 0.70.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/config/SKILL.md` named `config` (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
@@ -249,6 +313,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 +364,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 +405,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.
 
-> 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.)
+**Beat 1, plant the bug (the tester breaks the HTML, their file).** Tell the
+tester:
 
-After running the flow, report what actually happened (keep the promises
-conditional on the real result):
+> 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.)
+
+When the tester asks to publish, **execute the publish flow for real** by
+following `.claude/commands/publish.md`: run the `check-links` logic over every
+`.html` under `public/` (does each internal `href` resolve to a file that
+exists?), which now finds the planted typo; per step 2, brief the
+`content-editor` to fix it (point the link back at `/about.html`), re-run the
+check until it is clean, then walk the deploy runbook. Do not role-play it;
+`Read` `public/index.html` before and after the fix so the report is honest.
+
+After running the flow, report what actually happened:
 
 > Here is what just ran, for real:
 >
 > - **check-links** walked every page under `public/` and followed each internal
->   link. Result: 0 broken links. (Had it found one, the next step would have
->   briefed `content-editor` to fix it, then re-checked, that is what step 2 is
->   for.)
+>   link. It caught **1 broken link**: `/abuot.html` on `index.html`, the typo
+>   you planted. The graph never flagged it, but the skill did, because the skill
+>   reads your real pages.
+> - **step 2 kicked in**: I briefed your `content-editor` to fix it. It pointed
+>   the link back at `/about.html`, and a re-run of **check-links** came back
+>   clean: 0 broken links.
 > - the **deploy runbook** (`docs/DEPLOYMENT.md`) lists the ship steps:
->   regenerate the pages (done), run the link check (done), start the server
->   (next chapter).
+>   regenerate the pages (done), run the link check (done, now clean), start the
+>   server (next chapter).
 >
-> 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)
 
@@ -388,12 +498,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?
 
@@ -401,23 +516,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`.
-- `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.
+- `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)
 
@@ -177,7 +180,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`,
@@ -251,8 +254,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 +278,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.
@@ -313,7 +314,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**,
@@ -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,7 +40,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 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)
@@ -53,13 +55,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.** 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

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`.

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