@skill-map/cli 0.69.0 → 0.71.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

@@ -21,9 +21,8 @@ Two numbering systems coexist; keep them apart:
 - **Internal (authoring only)**: the `order` field in `_manifest.yml`
   and the `# Part N` file headers, 0-based (Part 0 the prologue …
   Part 3 the CLI deep-dive, Part 4 the Extend dev section; `mcp` at Part 5 is parked / hidden). Use it
-  in `**Context**:` blocks and author
-  notes; NEVER say it to the tester, it is off by one from what they
-  see.
+  in author notes; NEVER say it to the tester, it is off by one from
+  what they see.
 - **Tester-facing (`S.N`)**: every part is a **section** numbered by
   its 1-based position in the menu (section `1` is the prologue), and
   every chapter inside it carries a `section.chapter` number like a
@@ -160,9 +159,9 @@ documented exceptions to "all prose is quoted" are the plain
 with `> `, keep that prefix verbatim (Claude mode). Do NOT strip
 `> ` on short intro lines, do NOT merge adjacent blockquote
 paragraphs into plain prose. The source already encodes which lines
-are tester-facing (`> `-prefixed) vs agent-only (plain prose in
-`**Context**:` blocks, `Expected:` lines, `Mark <chapter-id>: done`
-markers, "Walk the tester through …" meta instructions). Render the
+are tester-facing (`> `-prefixed) vs agent-only (plain prose,
+`Expected:` lines, `Mark <chapter-id>: done` markers, "Walk the
+tester through …" meta instructions). Render the
 first kind quoted, the second kind never.
 
 ### Language mirroring + fixture content
@@ -178,6 +177,15 @@ first kind quoted, the second kind never.
   English regardless**: file paths and filenames, frontmatter keys,
   node identifiers, link target paths inside `[...]( ... )`, code
   snippets, fenced blocks, anything the kernel parses structurally.
+- **Copyable blocks are byte-exact**: when you render a fenced block
+  the tester copies verbatim (a `SKILL.md` / command body, a config
+  snippet), reproduce it line for line, preserving every line break,
+  indentation level, and tab. NEVER soft-wrap a long line, and in
+  particular NEVER let a newline fall inside a markdown link: the
+  `[text](path)` token, above all the `(path)` half, must stay on one
+  physical line. A break inside the path (`(../content-` then a newline
+  then `editor/SKILL.md)`) splits it, the link stops resolving, and no
+  arrow is drawn.
 - **No em dashes** in tester-facing prose: prefer a comma or
   parentheses (project-wide style).
 
@@ -259,8 +267,8 @@ 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    |
-| `antigravity`  | `.agents/skills/`                         | skill, markdown                | `/` invokes, refs              | `.agent/workflows/`| beta             | basic   |
+| `codex`        | `.codex/agents/*.toml` + `.agents/skills/`| agent (TOML), skill, markdown  | `$` invokes, `@` file-refs, refs| `.codex/`         | beta             | rich    |
+| `antigravity`  | `.agents/skills/` + `.agent/workflows/`   | skill, workflow, markdown      | `/` invokes, `@` file-refs, refs | `.agent/workflows/`| beta             | basic   |
 | `agent-skills` | `.agents/skills/`                         | skill, markdown                | refs only                      | `.agents/`         | stable (default) | basic   |
 
 `core/markdown` classifies every orphan `.md` under whatever lens is
@@ -269,19 +277,30 @@ 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**
+  built on `skill` + `markdown` and wired with **markdown references**
   (`[text](path)`), the one connection the Agent Skills standard
-  documents. No `@`. `/` invocation is an Antigravity-only bonus, it is
-  NOT part of the neutral standard, so under the `agent-skills` lens only
-  references form.
+  documents. They diverge on what Antigravity bolts on top of the
+  standard: `agent-skills` is the pure subset (skill + markdown,
+  references only, no `@`), while `antigravity` adds its OWN `workflow`
+  kind (`.agent/workflows/*.md`), `/`-invocation (the slash resolves to
+  both skills and workflows), and `@`-file references (a file-shaped
+  `@path` token, the same file-picker grammar Codex uses, distinct from
+  Claude's `@`-agent-mention). That slash, the `workflow` kind, and the
+  `@`-file refs are Antigravity-only, NOT part of the neutral standard,
+  so under the `agent-skills` lens only markdown references form.
 
 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 +315,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 +347,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.)
@@ -379,15 +412,8 @@ For every chapter:
    the chapter inside that part, resetting per part (§Numbering), so
    section 5's third chapter announces as `Capítulo 5.3`. The title
    comes from the chapter's `title` in `_manifest.yml` (translated per
-   §Tone), not the internal id. When the source has a `**Context**:`
-   field, follow the announcement with one tester-facing sentence of
-   context, and render it **under the `> ` bar as the opening line of
-   the SAME blockquote as the chapter's instructions** (Claude variant:
-   put `>` on the blank line between the context and the instructions
-   so they read as one continuous separator bar, never two stacked
-   blocks; the context line is tester-facing, so it is never plain
-   prose). When the source has no `**Context**:` field, announce the
-   title alone.
+   §Tone), not the internal id. Announce the title alone, then go
+   straight into the chapter's instructions.
 2. **Preparation** (if applicable): create or modify the fixture
    files the chapter calls for (silently, per §Silence).
 3. **The tester's part**: the command block(s) and instructions,

package/dist/cli/tutorial/sm-tutorial/references/_manifest.yml

@@ -170,10 +170,10 @@ parts:
       - id: stability        ; title: "Set a node's stability (and the `.sm` sidecar)" ; est_min: 3
       - id: golive           ; title: "Your website, live next to the graph" ; est_min: 3
 
-  # ----- the basic-track campaign (open-standard family: agent-skills / antigravity) -----
+  # ----- the basic-track campaign (the Agent Skills open standard; vendors like Antigravity build on it) -----
   # Mirrors the rich campaign arc with skill + markdown only, connected by
   # markdown references. Same fixtures (portfolio / harness) laid under the
-  # basic provider, which renders the agent/command nodes as skills.
+  # `agent-skills` lens, which renders the agent/command nodes as skills.
 
   - id: basic-kickoff
     order: 1

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

@@ -21,13 +21,6 @@ gone, re-invoke the tutorial from an empty dir") and stop.
 
 ## Step `authoring-1-scaffold` - `sm plugins create extractor demo-highlight` (~2 min)
 
-**Context**: We're building `demo-highlight`: a tiny extractor
-that scans each node's body for the keywords `TODO` and `FIXME`
-and shows the count as a chip on the node card. The scaffolder
-emits a working version of it; over the next steps we'll tweak
-its setting, move the chip to a different slot, and break the
-manifest on purpose to see the diagnostic catch it.
-
 > Let's scaffold it with `sm plugins create`:
 
 ```bash

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

@@ -34,11 +34,6 @@ has NO `sm scan` / `sm check` steps: the watcher re-scans on every save.
 
 ## Chapter `setup` - Make it yours and bring it up (~5 min)
 
-**Context**: the harness is wired. Now put it to work on a real day. First make
-the site yours, about whatever you like, then serve it. The HTML and
-CSS are Layer 2 (the harness's output); skill-map maps the harness (Layer 1, the
-`.md` files), so the site landing on disk does NOT move the graph.
-
 **Preparation**:
 1. Ask the tester the two questions straight, with no "before we build, let's
    make it yours" lead-in: what the site should be called and one line about what
@@ -114,10 +109,6 @@ Wait for confirmation. Mark `add-page`: done. Auto-advance to `broken-ref`.
 
 ## Chapter `broken-ref` - A rename breaks a link (~4 min)
 
-**Context**: the daily safety net, and where skill-map earns its keep: rename and
-move things freely, and skill-map shows you exactly what you forgot to update
-before it ships broken.
-
 **Preparation**: none (the tester drives). Everything is watched live.
 
 Tell the tester to free the third terminal, then rename the deploy runbook
@@ -165,21 +156,18 @@ 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`.
 
@@ -189,10 +177,6 @@ Wait for confirmation. Mark `reserved`: done. Auto-advance to `publish`.
 
 ## Chapter `publish` - Ship it: run the publish skill 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 the publish skill
-catch and fix it for real.
-
 **Preparation**: make sure the pages exist (`index`, `about`, `projects`).
 
 This chapter has two beats: the tester breaks a link in the HTML first, then runs

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

@@ -1,7 +1,9 @@
 # Part 0 (basic track): The live map (prologue) - step library
 
-The live-UI prologue for the **basic track** (the open-standard family:
-`agent-skills`, `antigravity`). Same arc as the rich prologue, the tester runs
+The live-UI prologue for the **basic track**: the **Agent Skills open
+standard** (the `agent-skills` lens; vendors like Antigravity build on it and
+add their own extras, which this book does not teach). Same arc as the rich
+prologue, the tester runs
 `sm init`, opens the browser, and watches the map update in real time, but this
 lens authors only **skills** and **markdown notes**, and assets connect by
 **markdown references** (`[text](path)`), the one link the Agent Skills standard
@@ -196,11 +198,6 @@ Mark `inspector`: done.
 
 ## Chapter `edit-link` - Edit a link, the topology changes (~3 min)
 
-**Context**: `first-edit` changed a scalar and watched a card refresh. This
-chapter edits the markdown links and watches the MAP TOPOLOGY change both ways,
-a connector disappears when you remove a link, and a new one appears (clearing
-the broken-reference error) when you fix the unresolved one.
-
 The server has been live since `init`, leave it running; this chapter and the
 next two reuse it.
 
@@ -232,10 +229,6 @@ You verify by reading `notes/todo.md` (the `demo-skill` bullet gone, the
 
 ## 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**, and a **Files**
-panel (a folder tree of every node). The same `sm` session is still running.
-
 Walk the three actions one at a time (open the Files panel, search, isolate);
 each ends with its own confirmation. Do NOT prepend an intro line to a block.
 
@@ -251,8 +244,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 +267,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-basic-kickoff.md

@@ -1,7 +1,8 @@
 # Part 1 (basic track): The harness from zero (step library, `kickoff-*` ids)
 
-The campaign turns real here for the **basic track** (the open-standard family:
-`agent-skills`, `antigravity`). After the abstract prologue, the tester starts an
+The campaign turns real here for the **basic track**: the **Agent Skills open
+standard** (the `agent-skills` lens; vendors like Antigravity build on it).
+After the abstract prologue, the tester starts an
 actual project: a tiny personal **portfolio website**, fully static, served by a
 ~15-line Express server, plus the `.agents/skills/` **harness** that maintains
 it. skill-map maps the harness (the `.md` assets and how they reference each
@@ -22,9 +23,6 @@ The chapters grow the harness from there.
 
 ## Chapter `kickoff` - Start the portfolio (~2 min)
 
-**Context**: same `sm init` from the prologue, now on a real project. The map
-shows the project's harness, not throwaway demo nodes.
-
 If the prologue (`basic-fundamentals`) ran first here, `portfolio-init` already
 cleared the demo fixture during pre-flight, so the tester sees only the
 portfolio. If anything demo lingers, mention it once and move on.
@@ -59,11 +57,6 @@ Wait for confirmation. Mark `kickoff`: done.
 
 ## Chapter `manual` - The handbook and an entry pointer (~2 min)
 
-**Context**: the first connector on the real project. A project often keeps a
-short entry file that points readers (and tools) at the handbook. On this lens
-that pointer is a plain **markdown link**, the only connector the open standard
-defines, and it is the tester's first real reference here.
-
 Tell the tester to create the file themselves (their project's file, Inviolable
 rule #2):
 
@@ -110,11 +103,6 @@ Wait for confirmation. Mark `first-skill`: done.
 
 ## Chapter `real-kinds` - The kinds in context (~2 min)
 
-**Context**: the prologue showed this lens's two kinds on abstract demo nodes.
-Now name them on the real project, and add the two markdown docs the harness
-references later (the style guide and the deploy runbook), so the daily loop's
-maintenance beats have something to point at.
-
 Lay the two docs (content lives in `fixtures-data/`). Backstage (silent):
 
 ```
@@ -142,10 +130,6 @@ Wait for confirmation. Mark `real-kinds`: done.
 
 ## Chapter `check-links` - The link checker (~3 min)
 
-**Context**: the harness needs a guard that runs before publishing, a skill that
-checks the site's internal links resolve before it ships. We only create the
-`skill` node here; the `publish` skill in the next chapter is what calls it.
-
 Lay the `check-links` skill (content lives in `fixtures-data/`). Backstage
 (silent):
 
@@ -164,15 +148,14 @@ Wait for confirmation. Mark `check-links`: done.
 
 ## Chapter `publish` - The publish skill (~4 min)
 
-**Context**: the chapter where the graph comes alive. The `publish` skill ties
-three pieces together in one body: it points at the link checker, at the content
-editor, and at the deploy runbook. On this lens all three are **markdown
-references**, so three reference arrows light up from a single new node.
-
 Tell the tester to create the file themselves (Inviolable rule #2). Render the
 block as a **top-level fenced code block** at column 0, NOT inside the `> `
 blockquote, so the frontmatter fences (`---`) land on column 0 (indented fences
-never parse, and `sm check` then warns `frontmatter-malformed`).
+never parse, and `sm check` then warns `frontmatter-malformed`). Emit every line
+verbatim: never soft-wrap, and never let a newline fall inside a `[text](path)`
+link, a break inside the `(path)` splits it (`(../content-editor/SKILL.md)` must
+stay on one line) and the link stops resolving (see `_core.md` §Language
+mirroring + fixture content).
 
 > Create `<provider_dir>/publish/SKILL.md` with exactly this content (the first
 > line is `---`, nothing before it):
@@ -220,10 +203,6 @@ indented on paste, re-align every line flush left). 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: two bullets point it at the content editor
-and the publish skill. We also give the content editor a reference to the style guide it follows.
-
 Apply both edits (content lives in `fixtures-data/`). The first appends two hub
 bullets (markdown links) to `AGENTS.md`; the second adds the style-guide
 reference to the content-editor skill. Backstage (silent):
@@ -275,8 +254,10 @@ Tell the tester:
 > file, and it drew a solid arrow at **1.00**.
 >
 > **IMPORTANT:** why does confidence matter? It mirrors how an agent resolves a
-> reference, a deterministic name-and-path lookup, no guessing. That is cheaper
-> and does not fail, the same reason a clean, well-named harness is worth keeping.
+> reference, a deterministic name-and-path lookup, no guessing. A link that does
+> not resolve sends the agent guessing and retrying, which burns time and tokens;
+> a deterministic one is cheaper and does not fail, the same reason a clean,
+> well-named harness is worth keeping.
 >
 > Do you see every badge reading 1.00 in the Inspector?
 

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

@@ -67,8 +67,6 @@ Mark `issues`: done.
 
 ## Chapter `annotations` - Annotations and the .sm consent prompt (~3 min)
 
-**Context**: skill-map keeps each tracked `.md`'s metadata (version, history, tags, annotations) in a sibling **`.sm` companion file** so the `.md` stays clean, and the first time it writes one in a project it asks for consent (remembered in the gitignored `settings.local.json`). The Maintain part walks that consent flow in full; this chapter does not re-teach it. The CLI focus here is what Maintain does not cover: the **three sidecar verbs** and the `--yes` non-interactive switch. A tester who jumped straight here gets a one-line refresher in the demo below.
-
 Create a scaffold for `notes/todo.md` so there is a `.sm` on disk to talk about. **Reset any prior consent state first** so the prompt appears (an earlier step may have flipped the flag, in which case the verb skips straight past it):
 
 ```bash
@@ -90,8 +88,6 @@ Mark `annotations`: done.
 
 ## Chapter `reference-paths` - Validate links to folders outside the scan scope (~4 min)
 
-**Context**: until now the map saw only files inside the cwd. In real projects a repo often links to files in a sibling repo (a specs project, a sibling package in a monorepo). Skill-map only scans from its cwd downwards, so a link to `../sibling/file.md` shows up as broken. The fix is to declare the external folders in `scan.referencePaths`, which lets the `reference-broken` analyzer validate path-style links against those extra roots **without indexing their files as nodes**. The folders are checked, not walked as part of the map.
-
 **Setup (you, silent)**: lay the fixture under the tutorial cwd so both sub-projects are siblings of each other but children of the tutorial root (its content + translation live in `fixtures-data/`). No confirmation beat needed, the tester learns about the files in the next message. Backstage (silent):
 
 ```