@skill-map/cli 0.70.0 → 0.72.0

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

@@ -276,8 +276,8 @@ the `__PROVIDER__` token and skip kinds the provider does not claim.
      `rm -rf .skill-map`.
   2. Lay the portfolio boot (Express skeleton + handbook):
      `fixtures.js lay portfolio --only "AGENTS.md,server.js,package.json,public/index.html" --provider <provider> --lang <lang>`.
-     The harness members (`CLAUDE.md`, `content-editor`, the docs) are
-     laid by their own chapters.
+     The harness members (the entry pointer, `content-editor`, the docs)
+     are laid by their own chapters.
 
   The tester runs `sm init` in the first chapter. (Later campaign
   parts use `preflight: seed`; `portfolio-init` is Part 1's flavour,

package/dist/cli/tutorial/sm-tutorial/fixtures-data/manifest.json

@@ -19,6 +19,7 @@
     "portfolio": [
       "AGENTS.md",
       "CLAUDE.md",
+      "README.md",
       "server.js",
       "package.json",
       "AGENTS.sm",

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/providers/codex/shared/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

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).
 
@@ -260,7 +268,7 @@ A skill-map project reads its files through exactly ONE active lens
 |----------------|-------------------------------------------|--------------------------------|--------------------------------|--------------------|------------------|---------|
 | `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, `@` file-refs, refs| `.codex/`         | beta             | rich    |
-| `antigravity`  | `.agents/skills/`                         | skill, markdown                | `/` invokes, refs              | `.agent/workflows/`| beta             | basic   |
+| `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
@@ -275,11 +283,17 @@ active; it is the universal base, never a selectable lens.
   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
@@ -398,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.json

@@ -289,7 +289,7 @@
         {
           "id": "reserved",
           "title": "A reserved name collides",
-          "est_min": 2
+          "est_min": 4
         },
         {
           "id": "publish",

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
@@ -209,7 +209,7 @@ parts:
       - id: setup       ; title: "Make it yours and bring it up" ; est_min: 4
       - id: add-page    ; title: "Add a page with your skill" ; est_min: 3
       - id: broken-ref  ; title: "A rename breaks a link" ; est_min: 3
-      - id: reserved    ; title: "A reserved name collides" ; est_min: 2
+      - id: reserved    ; title: "A reserved name collides" ; est_min: 4
       - id: publish     ; title: "Ship it: run the publish skill for real" ; est_min: 3
       - 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

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

@@ -12,8 +12,11 @@ model; the per-chapter invocations live in each `part-*.md`.
 fixtures-data/
   manifest.json                 sets, footprints, edits, seeds, providerToken, langs
   sets/<set>/
-    shared/                     lang-invariant files (code: server.js, package.json, CLAUDE.md)
+    shared/                     lang-invariant files (code: server.js, package.json)
     en/  es/                    one tree per language (files with translatable prose)
+    providers/<provider>/       per-lens overlay (shared/ + en/ es/); e.g. the root
+                                entry pointer is CLAUDE.md on claude/codex,
+                                README.md on agent-skills/antigravity
   edits/<edit-id>/
     en/  es/                    append fragments (one file per fragment)
 ```

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
@@ -147,7 +138,7 @@ mv docs/DEPLOY.md docs/DEPLOYMENT.md
 Wait for confirmation. The harness MUST be clean again before Act C. Mark
 `broken-ref`: done. Auto-advance to `reserved`.
 
-## Chapter `reserved` - A reserved name collides (~2 min)
+## Chapter `reserved` - A reserved name collides (~4 min)
 
 **Preparation**: `Write` `<provider_dir>/model/SKILL.md`:
 ```markdown
@@ -178,15 +169,51 @@ The watcher picks up the new skill. Tell the tester:
 >
 > See the `model` node land clean, with no warning?
 
-Wait for confirmation. Mark `reserved`: done. Auto-advance to `publish`.
+Wait for confirmation.
+
+**Beat 2, prove the vendor exception by switching the lens (hands-on).** First
+`Write` `<provider_dir>/goal/SKILL.md` (a skill named after the Antigravity
+built-in verb `goal`):
+
+```markdown
+---
+name: goal
+description: |
+  Captures a goal for the site and tracks it to done.
+---
+
+# goal
 
-**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.
+Notes a goal and checks it off when shipped.
+```
+
+The watcher adds it clean (on your open-standard lens `goal` is just a name). The
+agent does NOT touch settings (Inviolable rule #2); the tester drives the
+Settings UI. Tell the tester:
+
+> Now let's make that warning real by switching the lens. I added one more skill,
+> `goal`, an Antigravity built-in verb. On your open standard it landed clean,
+> same as `model`.
+>
+> Open **Settings** (the sliders icon, top right) and the **Project** tab. Find
+> **Active provider** and switch it from the open standard to **Google's
+> Antigravity**, then confirm. skill-map clears the old lens's scan, so the Map
+> goes quiet; click the **refresh** button (the sync icon in the topbar) to
+> re-scan under the new lens.
+>
+> Watch the Map: `goal` now wears a **`name-reserved`** warning (under Antigravity
+> `/goal` is a built-in command, so your skill would be shadowed), while `model`
+> stays clean (it is not one of Antigravity's verbs). Same files, different lens:
+> the lens decides what is reserved.
+>
+> Now switch **Active provider** back to the open standard, confirm, and click
+> refresh once more. The warning on `goal` clears, you are back on the neutral
+> standard that reserves nothing.
+>
+> Did the warning appear under Antigravity and clear when you switched back?
+
+Wait for confirmation. The lens MUST be back on the open standard before
+continuing. Mark `reserved`: done. Auto-advance to `publish`.
 
 ---
 
@@ -194,10 +221,6 @@ lesson above.
 
 ## 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
@@ -126,8 +128,8 @@ You edit `notes/todo.md` so it becomes the **hub** that points to the other
 nodes. On this lens there is exactly one connector: the **markdown reference**.
 A bullet links to another file with `[label](relative/path)`; skill-map reads
 that as a `references` link and draws an arrow when the target resolves to a
-real file. (The rich track also has `/`-invokes and `@`-mentions; the open
-standard connects by file links only, and that is all this lens emits.)
+real file. (Wiring everything with file links keeps the harness portable: a
+reference resolves the same way on any runtime that speaks the open standard.)
 
 Apply the hub bullets (content lives in `fixtures-data/`). The edit appends
 three bullets after the `# Pending` heading. Backstage (silent):
@@ -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.
 

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,21 +57,16 @@ 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):
 
-> Create a file called `CLAUDE.md` at the project root with exactly this content:
+> Create a file called `README.md` at the project root with exactly this content:
 >
 > ```markdown
 > See the [handbook](AGENTS.md).
 > ```
 >
-> Save it. Watch the map: a new `CLAUDE.md` node appears with a `references`
+> Save it. Watch the map: a new `README.md` node appears with a `references`
 > connector pointing at `AGENTS.md`, solid at 1.00. The markdown link
 > `[handbook](AGENTS.md)` is a file pointer (the same kind of reference you met
 > in the prologue), and since the handbook is right there the link resolves with
@@ -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):
 
 ```
@@ -129,7 +117,7 @@ Tell the tester:
 > front of you:
 >
 > - **skill**: `content-editor` (does work on your behalf).
-> - **markdown**: `AGENTS.md`, `CLAUDE.md`, the two docs (plain notes and
+> - **markdown**: `AGENTS.md`, `README.md`, the two docs (plain notes and
 >   manuals).
 >
 > Your lens authors exactly these two; Claude and Codex projects add `agent` and
@@ -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):
@@ -205,10 +188,10 @@ Continue the tester message:
 > - `publish -> content-editor` (the `[content-editor](../content-editor/SKILL.md)` link)
 > - `publish -> docs/DEPLOY.md` (the `[deploy runbook](../../../docs/DEPLOY.md)` link)
 >
-> One node, three connectors, all references. On a vendor lens (claude/codex) the
-> first two would be a `/`-invoke and an `@`-mention; the open standard wires
-> everything with file links, and that is all this lens emits. The harness is
-> starting to look like a real graph.
+> One node, three connectors, all references. Wiring the whole harness with
+> markdown file links keeps it portable: each reference resolves the same way on
+> any runtime that speaks the open standard. The harness is starting to look
+> like a real graph.
 >
 > 💡 Tip: to tidy the layout, click **Re-arrange layout** in the map toolbar.
 >
@@ -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):
 
 ```

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

@@ -125,15 +125,6 @@ broken-reference markers, and confidence live.
 
 ## Chapter `setup` - Make it yours and bring it up (~5 min)
 
-**Context**: the harness is wired (you built it in the earlier parts). Now you
-put it to work on a real day. First, make the site yours, about whatever you
-like, then serve it and open it in the browser, the early payoff before the
-daily loop fills it with pages. The honest beat: the HTML
-and CSS are Layer 2 (the harness's output); skill-map maps the harness (Layer 1,
-the `.md` files), so the site landing on disk does NOT move the graph, and that
-is correct, not a bug. The tester runs the serve commands themselves (one of the
-few non-`sm` beats); guide them, do not run them.
-
 **Preparation**:
 
 1. Ask the tester the two questions straight, with no "before we build, let's
@@ -326,10 +317,6 @@ Wait for confirmation. Mark `add-page`: done. Auto-advance to `broken-ref`.
 
 ## Chapter `broken-ref` - A rename breaks a link (~4 min)
 
-**Context**: the daily safety net, and where skill-map earns its keep: rename and
-move things freely, and skill-map shows you exactly what you forgot to update
-before it ships broken.
-
 **Preparation**: none (the tester drives). Everything here is watched live on
 the Map; no `sm` commands.
 
@@ -405,10 +392,6 @@ Wait for confirmation. Mark `reserved`: done. Auto-advance to `publish`.
 
 ## Chapter `publish` - Ship it: run /publish for real (~4 min)
 
-**Context**: the publish flow only earns its keep when something is actually
-wrong, so first you plant a real bug in the site, then watch `/publish` catch and
-fix it for real.
-
 **Preparation**: make sure the pages exist (`index`, `about`, `projects` from the
 earlier chapters; lay any that are missing from the templates in `setup`).
 

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

@@ -200,8 +200,6 @@ Mark `inspector`: done.
 
 ## Chapter `edit-link` - Edit a link, the topology changes (~3 min)
 
-**Context**: the `first-edit` chapter had the tester edit a scalar (`description`) and watch the inspector card refresh. This chapter raises the bar: edit Markdown links and watch the MAP TOPOLOGY change both ways, a connector disappears when you remove a link, and a new one appears (clearing the broken-reference error) when you fix the unresolved one.
-
 The server has been live since the `init` chapter, leave it running; this chapter and the next two (the workspace tour, then `.skillmapignore`) reuse it.
 
 > Your turn. Edit `notes/todo.md` with your editor of choice and
@@ -232,8 +230,6 @@ You verify by reading `notes/todo.md` to confirm both edits landed (the `@demo-a
 
 ## Chapter `workspace` - Navigate the workspace (files, search, isolate) (~2 min)
 
-**Context**: you've built the graph and understood it; this beat is about *moving around* it. The workspace has two halves: the **Map** you've been working in, and a **Files** panel, a folder tree of every node. You'll open that tree and filter it with the search box. The same `sm` session you booted back in the `init` chapter is still running.
-
 Walk the three tester actions below one at a time (open the Files
 panel, then search, then isolate); each ends with its own
 confirmation, so present one and wait for the tester before the next.

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

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

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

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