@skill-map/cli 0.69.0 → 0.70.0

package/dist/cli/tutorial/sm-tutorial/SKILL.md

@@ -64,9 +64,14 @@ ls -A
 ```
 
 **Items you ignore** when evaluating "empty" (internal
-infrastructure, not user content): `.claude` (skills/agents infra),
-`.tmp` (Claude Code scratch dir), `SKILL.md` / `sm-tutorial.md`
-(loose copies of this skill), `tutorial-state.json` (resume mode).
+infrastructure, not user content): the provider scaffold dirs `sm
+tutorial` drops for the active lens, `.claude`, `.codex`, `.agents`,
+`.agent` (the vendor marker plus the open-standard skill home, e.g.
+codex drops both `.codex/` and `.agents/skills/`), `.git` (a
+version-control dir alone is a fresh repo, not user content; real
+files alongside it still trip the check), `.tmp` (Claude Code
+scratch dir), `SKILL.md` / `sm-tutorial.md` (loose copies of this
+skill), `tutorial-state.json` (resume mode).
 
 The whitelist is internal; do NOT enumerate it to the tester.
 

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/agents-hub/providers/codex/en/agents-hub.md

@@ -0,0 +1,2 @@
+- When a page needs writing or fixing, brief [content-editor](.codex/agents/content-editor.toml).
+- When the site is ready to go out, run $publish.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/agents-hub/providers/codex/es/agents-hub.md

@@ -0,0 +1,2 @@
+- Cuando una página necesita escribirse o arreglarse, informa a [content-editor](.codex/agents/content-editor.toml).
+- Cuando el sitio esté listo para salir, corre $publish.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/codex/en/todo-bullet-agent.md

@@ -0,0 +1 @@
+- [ ] Brief [demo-agent](../.codex/agents/demo-agent.toml) on the rough edges.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/codex/en/todo-bullet-command.md

@@ -0,0 +1 @@
+- [ ] Run $demo-command before publishing.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/codex/en/todo-bullet-skill.md

@@ -0,0 +1 @@
+- [ ] Trigger $demo-skill when the input lands.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/codex/es/todo-bullet-agent.md

@@ -0,0 +1 @@
+- [ ] Informa a [demo-agent](../.codex/agents/demo-agent.toml) sobre los detalles pendientes.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/codex/es/todo-bullet-command.md

@@ -0,0 +1 @@
+- [ ] Ejecuta $demo-command antes de publicar.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/codex/es/todo-bullet-skill.md

@@ -0,0 +1 @@
+- [ ] Dispara $demo-skill cuando llegue la entrada.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/harness/providers/codex/en/__PROVIDER__/skills/publish/SKILL.md

@@ -10,6 +10,6 @@ description: |
 The one skill 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.
+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](../../../.codex/agents/content-editor.toml) with the change.
 3. Follow the [deploy runbook](../../../docs/DEPLOY.md): regenerate pages, run the link check, start the server.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/harness/providers/codex/es/__PROVIDER__/skills/publish/SKILL.md

@@ -11,6 +11,6 @@ description: |
 La única skill que corres cuando el sitio está listo para salir.
 
 ## Pasos
-1. Corre /check-links sobre las páginas en public/. Si reporta enlaces rotos, frena y arréglalos primero.
-2. Si una página necesita un arreglo de contenido, dale el cambio a @content-editor.
+1. Corre $check-links sobre las páginas en public/. Si reporta enlaces rotos, frena y arréglalos primero.
+2. Si una página necesita un arreglo de contenido, dale el cambio a [content-editor](../../../.codex/agents/content-editor.toml).
 3. Sigue el [runbook de despliegue](../../../docs/DEPLOY.md): regenera las páginas, corre el chequeo de enlaces, inicia el servidor.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/providers/codex/en/.codex/agents/master-agent.toml

@@ -1,6 +1,6 @@
 name = "master-agent"
 description = "Example agent used by the advanced tutorial. The target node when we exercise extractors, analyzers, and the plugin-authoring flow."
-model = "gpt-5-codex"
+model = "gpt-5.5"
 developer_instructions = """
 # master-agent
 

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/providers/codex/es/.codex/agents/master-agent.toml

@@ -1,6 +1,6 @@
 name = "master-agent"
 description = "Agente de ejemplo que usa el tutorial avanzado. Es el nodo objetivo cuando ejercitamos extractors, analyzers y el flujo de autoría de plugins."
-model = "gpt-5-codex"
+model = "gpt-5.5"
 developer_instructions = """
 # master-agent
 

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/providers/codex/en/.codex/agents/content-editor.toml

@@ -1,6 +1,6 @@
 name = "content-editor"
 description = "Writes and edits the portfolio's pages. Reads a brief, follows the style guide, and emits the HTML into public/."
-model = "gpt-5-codex"
+model = "gpt-5.5"
 developer_instructions = """
 # content-editor
 

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/providers/codex/es/.codex/agents/content-editor.toml

@@ -1,6 +1,6 @@
 name = "content-editor"
 description = "Escribe y edita las páginas del portfolio. Lee un brief, sigue la guía de estilo y emite el HTML en public/."
-model = "gpt-5-codex"
+model = "gpt-5.5"
 developer_instructions = """
 # content-editor
 

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/providers/codex/en/.codex/agents/demo-agent.toml

@@ -1,6 +1,6 @@
 name = "demo-agent"
 description = "Example agent that handles read and shell tasks. Solo node at boot; gets connected to the rest of the demo fixture during the Live UI step."
-model = "gpt-5-codex"
+model = "gpt-5.5"
 developer_instructions = """
 # demo-agent
 

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/providers/codex/es/.codex/agents/demo-agent.toml

@@ -1,6 +1,6 @@
 name = "demo-agent"
 description = "Agente de ejemplo que maneja tareas de lectura y shell. Nodo solo al arranque; se conecta al resto del fixture demo durante el paso de UI en vivo."
-model = "gpt-5-codex"
+model = "gpt-5.5"
 developer_instructions = """
 # demo-agent
 

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

@@ -259,7 +259,7 @@ A skill-map project reads its files through exactly ONE active lens
 | Provider       | Asset layout                              | Kinds                          | Connectors that form           | Marker             | Stability        | Track   |
 |----------------|-------------------------------------------|--------------------------------|--------------------------------|--------------------|------------------|---------|
 | `claude`       | `.claude/` (agents, commands, skills)     | agent, command, skill, markdown| `/` invokes, `@` mentions, refs| `.claude/`         | stable           | rich    |
-| `codex`        | `.codex/agents/*.toml` + `.agents/skills/`| agent (TOML), skill, markdown  | `/` invokes, `@` mentions, refs| `.codex/`          | beta             | rich    |
+| `codex`        | `.codex/agents/*.toml` + `.agents/skills/`| agent (TOML), skill, markdown  | `$` invokes, `@` file-refs, refs| `.codex/`         | beta             | rich    |
 | `antigravity`  | `.agents/skills/`                         | skill, markdown                | `/` invokes, refs              | `.agent/workflows/`| beta             | basic   |
 | `agent-skills` | `.agents/skills/`                         | skill, markdown                | refs only                      | `.agents/`         | stable (default) | basic   |
 
@@ -269,8 +269,11 @@ active; it is the universal base, never a selectable lens.
 **Two tracks, by capability** (the axis is "does the lens have an
 `agent` kind?"):
 
-- **rich** (`claude`, `codex`): agents + skills (+ commands on claude),
-  wired with `/` invocations and `@` mentions plus markdown references.
+- **rich** (`claude`, `codex`): agents + skills (+ commands on claude).
+  Claude wires `/` invocations and `@` mentions; Codex wires `$` invocations
+  (skills) and `@`-FILE references (Codex's `@` is a file picker, it cannot
+  mention an agent by name, and `/` is a Codex built-in command, not a skill
+  invocation). Both also use markdown references.
 - **basic** (`agent-skills`, `antigravity`): the open-standard family,
   `skill` + `markdown` only, wired with **markdown references**
   (`[text](path)`), the one connection the Agent Skills standard
@@ -280,8 +283,10 @@ active; it is the universal base, never a selectable lens.
 
 Why references and not slash on the open standard: the Agent Skills
 spec (agentskills.io) activates a skill by its `description` and
-connects files by relative markdown links; it has no `/`-invocation
-syntax. claude/codex add `/` and `@` as vendor features on top.
+connects files by relative markdown links; it has no invocation sigil.
+Vendors add their own on top: claude `/`-invokes and `@`-mentions; Codex
+`$`-invokes skills and treats `@` as a file picker (`/` is a Codex
+built-in command, not a skill invocation).
 
 **Decision logic, applied silently at pre-flight:**
 
@@ -296,14 +301,17 @@ syntax. claude/codex add `/` and `@` as vendor features on top.
      `<provider_dir> = .claude`, `track = rich`.
    - else skill under `.agents/skills/sm-tutorial/` → `provider = agent-skills`,
      `<provider_dir> = .agents/skills`, `track = basic`.
-   **Lens ambiguity for codex / antigravity**: both adopt the open
-   `.agents/skills/` layout, so their own marker (`.codex/` or
-   `.agent/workflows/`) coexists with the `agent-skills` marker (`.agents/`)
-   and a plain `sm scan --yes` reports the lens as ambiguous. For those two,
-   set it explicitly once before the first scan, `sm config set
-   activeProvider <codex|antigravity> --yes`, then the book runs unchanged
-   (the fixture engine renders the right shape: codex its TOML agents +
-   command-as-skill, antigravity reuses the `agent-skills` overlays).
+   **Lens precedence for codex / antigravity**: both adopt the open
+   `.agents/skills/` layout, so the scaffold leaves the vendor marker
+   (`.codex/` or `.agent/workflows/`) alongside the `agent-skills` marker
+   (`.agents/`). The vendor marker WINS: `sm init` resolves `codex` /
+   `antigravity` outright with no prompt (the `.agents/` open default only
+   competes when no vendor marker is present). So the codex book runs
+   exactly like claude, `sm init` then `sm`, with no lens prompt and no
+   `sm config set activeProvider` step anywhere (tester chapters or
+   backstage seeds). The fixture engine still renders the right shape:
+   codex its TOML agents + command-as-skill, antigravity reuses the
+   `agent-skills` overlays.
 2. `state.js init --provider <p>` persists `provider` plus the derived
    `track`, so a resumed session never re-detects.
 3. Render only the parts whose `track` is `tutorial.track` (or `both`).
@@ -325,31 +333,42 @@ at `.claude/skills/sm-tutorial/` (this repo is itself a Claude project);
 
 ### Rendering the rich book on Codex
 
-The rich track has two lenses, `claude` and `codex`. They teach the SAME
-lessons with the SAME connectors (`/` invocations, `@` mentions, markdown
-references all resolve on both), so the rich part bodies are written in the
-`claude` shape; when `tutorial.provider == codex`, apply these substitutions:
+The rich track has two lenses, `claude` and `codex`. They teach the same
+lessons, but Codex's CONNECTOR GRAMMAR differs from claude's (see the
+Connectors bullet below), so the rich part bodies are written in the `claude`
+shape; when `tutorial.provider == codex`, apply these substitutions:
 
 - **Agents are TOML.** A Codex agent is a single `.codex/agents/<name>.toml`
   file (the prompt lives in its `developer_instructions` field), NOT a
   `.claude/agents/<name>.md`. The fixtures lay them, so when a chapter says
   "open the agent file" point at the `.toml`; a chapter that has the tester
   read or tweak an agent works on the TOML frontmatter / `developer_instructions`.
+- **Connectors differ.** Codex invokes a skill with `$<name>` (NOT `/`, which
+  is a Codex built-in command), and `@<name>` is a FILE picker, not an agent
+  mention. So where the claude book writes `/check-links` (invoke) say
+  `$check-links`; where it writes `@content-editor` (mention an agent),
+  reference the agent's FILE instead, a markdown link `[content-editor](<rel-path>.toml)`
+  or a file-shaped `@<file>.md` / `@<file>.toml`; a bare `@<name>` (no
+  path/extension) forms NOTHING on Codex. The codex fixture overlays already
+  carry the `$`/file-ref shapes, narrate them, do not re-derive.
 - **No `command` kind.** Where the claude book authors a `command` (the
-  `/publish` command, the reserved-name chapter's `model` command), Codex uses a
-  **skill** at `.agents/skills/<name>/SKILL.md`. The body is identical (same
-  `/check-links` + `@content-editor` + deploy reference); only the kind and path
-  change. `cat <set> --file … --provider codex` already returns the Codex skill
-  body, so the create-the-file block stays a copy-paste. The reserved-name beat
-  uses a skill named with a reserved verb (Codex inherits the open-standard
-  `COMMONS_RESERVED_NAMES`, e.g. `model`), exactly like the basic track's
-  `reserved` chapter, on a skill instead of a command.
+  `/publish` command), Codex uses a **skill** at `.agents/skills/<name>/SKILL.md`.
+  The body uses the CODEX grammar (`$check-links` to invoke, a file reference to
+  `content-editor` instead of an `@`-mention, per Connectors above); the codex
+  fixture overlay already carries that shape, so the create-the-file block
+  (`cat <set> --file … --provider codex`) stays a copy-paste.
+- **No reserved skill names on Codex.** Codex `$`-invokes skills, a namespace
+  disjoint from its `/` built-in commands, so a skill named like a built-in
+  (`model`) does NOT collide with `/model` and is NOT flagged. The claude
+  `reserved` chapter (a `/model` COMMAND collides) has no Codex equivalent; the
+  daily-loop `reserved` Codex delta reframes / skips it (see that chapter).
   **Apply every substitution silently.** Use the Codex path, kind and file
   directly in the tester-facing prose, but never EXPLAIN the substitution or
   compare it to the claude shape. The Codex tester only ever sees a `skill`
   where the claude book has a command; never tell them "Codex has no `command`
-  kind", never say a node "is a command that shows as a skill", never reference
-  "the claude command". On Codex these nodes were always skills, there is
+  kind", never say a node "is a command that shows as a skill" or that it
+  "replaces" / "stands in for" / "reemplaza" a command, never append a parenthetical
+  like "(in Codex this replaces the command)", never reference "the claude command". On Codex these nodes were always skills, there is
   nothing to explain. (Same for the TOML-agent and path swaps above: point the
   tester at the real `.toml` / `.agents/` file when they interact with it, just
   do not narrate that it "would be" something else on claude.)

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

@@ -165,24 +165,29 @@ Creates a blank page so you can start writing.
 The watcher picks up the new skill. Tell the tester:
 
 > I added a skill named `model`. Watch the **Map**: the new `model` skill node
-> appears, but flagged with a **warning** marker. Open its inspector: it reads
-> `name-reserved`, `model` shadows one of the agent runtime's own built-in verbs
-> (like `help`, `clear`, `config`), so the runtime would silently ignore your
-> skill, it never runs. The fix is a name the runtime does not own.
+> appears **clean, no warning**. On the open Agent Skills standard a skill is
+> activated by its `description`, not invoked by a `/` command, so a skill name
+> can never collide with a built-in command, there are NO reserved skill names.
+> Name your skills anything you like, even after a CLI built-in like `model` or
+> `help`.
 >
-> Rename it to `new-page`: first rename the folder `<provider_dir>/model/` to
-> `<provider_dir>/new-page/`. Then open `new-page/SKILL.md` and, at the top where
-> the frontmatter says `name: model`, change it to `name: new-page`. Save.
+> The one exception is a vendor that bolts `/`-invocation onto the standard:
+> Google's Antigravity invokes skills with `/<name>`, so under the Antigravity
+> lens a skill named after one of its built-in verbs (like `goal`) WOULD be
+> flagged `name-reserved`. The neutral open standard you are on reserves nothing.
 >
-> Watch the **Map** again: the warning clears and the node is now `new-page`, all
-> live. What cleared it was changing `frontmatter.name` (which for a skill must
-> match its folder, so you renamed both). Now `new-page` is yours and the runtime
-> will run it.
->
-> Did the warning clear after the rename?
+> See the `model` node land clean, with no warning?
 
 Wait for confirmation. Mark `reserved`: done. Auto-advance to `publish`.
 
+**Antigravity delta** (`tutorial.provider == antigravity`): skills ARE
+`/`-invoked here, so a built-in verb DOES collide. Name the skill `goal` (an
+Antigravity built-in) instead of `model`, narrate the `name-reserved`
+**warning** that appears, and have the tester clear it by renaming the folder +
+`frontmatter.name` to `new-page` (the warning clears live). That collision-and-
+fix beat is the Antigravity version; `agent-skills` gets the "names are free"
+lesson above.
+
 ---
 
 **Act C - Publish**

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

@@ -251,8 +251,12 @@ each ends with its own confirmation. Do NOT prepend an intro line to a block.
 > `Search…`). Type `guideline`. Watch the tree narrow to the two
 > guideline nodes. The search matches a node's name, path, or
 > description, and filters live, no Enter needed. The **Map** stays
-> put: by default the search filters only the files list, not the map
-> (the tip below changes that).
+> put: by default the search filters only the files list, not the map.
+>
+> 💡 Tip: the map-icon button next to the search box controls whether
+> the search also filters the **Map** (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 four nodes come back in the tree. Confirm you
 > saw it filter and then restore.
@@ -270,11 +274,6 @@ each ends with its own confirmation. Do NOT prepend an intro line to a block.
 > Map: there's a **Show all** button (an eye icon). Click it and all
 > four nodes return.
 >
-> 💡 Tip: the map-icon button next to the search box controls whether
-> the search also filters the **Map** (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.
->
 > Did the map isolate and then restore?
 
 Leave the server running, the next chapter is the last that uses it. Mark

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
@@ -434,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?
 
@@ -447,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`.
+- `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)
 
@@ -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.

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,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); 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)
@@ -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/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