@skill-map/cli 0.70.0 → 0.71.0

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.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
@@ -180,24 +171,12 @@ The watcher picks up the new skill. Tell the tester:
 
 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**
 
 ## 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.
 

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):
 
 ```

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:

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

@@ -45,10 +45,6 @@ The chapters grow the harness from there.
 
 ## Chapter `kickoff` - Start the portfolio (~2 min)
 
-**Context**: same `sm init` the tester learned in the prologue, but
-now on a real project. The map will show the project's harness, not
-throwaway demo nodes.
-
 If the prologue (`fundamentals`) ran first in this directory, the
 demo fixture (`demo-agent`, `demo-skill`, `notes/…`) is still on
 disk. The orchestrator's `portfolio-init` already cleared it during
@@ -90,12 +86,6 @@ Wait for confirmation. Mark `kickoff`: done.
 
 ## Chapter `manual` - The handbook (AGENTS.md) and CLAUDE.md (~2 min)
 
-**Context**: the dogfood beat. Real Claude Code projects can
-reference the generic `AGENTS.md` from their `CLAUDE.md` (this very
-repo does). That one-line pointer is a real `references` link (the
-`.md` extension makes `@AGENTS.md` a file pointer), the tester's first
-connector on the real project.
-
 Tell the tester to create the file themselves (it is their project's
 file, Inviolable rule #2). Backstage, get the content:
 `node .claude/skills/sm-tutorial/scripts/fixtures.js cat portfolio --file "CLAUDE.md" --provider <provider> --lang <lang>`,
@@ -147,11 +137,6 @@ Wait for confirmation. Mark `first-agent`: done.
 
 ## Chapter `real-kinds` - The real kinds in context (~2 min)
 
-**Context**: the prologue showed the four 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 markdown docs the harness references later (their content
 + translation live in `fixtures-data/`). Backstage (silent):
 
@@ -181,8 +166,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` command in the next chapter is its caller.
-
 Lay the `check-links` skill (its content + translation live in
 `fixtures-data/`; this kind exists on every provider, so no skip).
 Backstage (silent):
@@ -203,9 +186,7 @@ Wait for confirmation. Mark `check-links`: done.
 
 ## Chapter `publish` - The publish command (~4 min)
 
-**Context**: this is the chapter where the graph comes alive. The `/publish` command ties three pieces together in one body: it invokes the link checker, mentions the content editor, and references the deploy runbook. Three connectors light up from a single new node, one per link syntax.
-
-Tell the tester to create the file themselves (it is their project's file, Inviolable rule #2). Substitute `<provider_dir>` per `_core.md` in the path you give them. Backstage, get the content: `node .claude/skills/sm-tutorial/scripts/fixtures.js cat harness --file "__PROVIDER__/commands/publish.md" --provider <provider> --lang <lang>`, then render it as a **top-level fenced code block**: at column 0, NOT inside the `> ` blockquote and with NO leading indentation, so the tester's copy keeps every line flush left. The frontmatter fences (`---`) MUST land on column 0. If the block is rendered (or pasted) indented, the opening and closing `---` shift off column 0, the YAML never parses, and the `publish` node loads body-only without its `name` / `description` (`sm check` then warns `frontmatter-malformed`). Present the block below exactly as written.
+Tell the tester to create the file themselves (it is their project's file, Inviolable rule #2). Substitute `<provider_dir>` per `_core.md` in the path you give them. Backstage, get the content: `node .claude/skills/sm-tutorial/scripts/fixtures.js cat harness --file "__PROVIDER__/commands/publish.md" --provider <provider> --lang <lang>`, then render it as a **top-level fenced code block**: at column 0, NOT inside the `> ` blockquote and with NO leading indentation, so the tester's copy keeps every line flush left. The frontmatter fences (`---`) MUST land on column 0. If the block is rendered (or pasted) indented, the opening and closing `---` shift off column 0, the YAML never parses, and the `publish` node loads body-only without its `name` / `description` (`sm check` then warns `frontmatter-malformed`). Present the block below exactly as written, line for line: never soft-wrap, and never let a newline fall inside a `[text](path)` link (a break inside the `(path)`, e.g. `(../../docs/DEPLOY.md)`, splits it and the link stops resolving). See `_core.md` §Language mirroring + fixture content.
 
 > Create `.claude/commands/publish.md` with exactly this content (the first line is `---`, nothing before it):
 
@@ -253,8 +234,6 @@ Wait for confirmation. You MAY use `Read` on the file afterwards to verify it la
 
 ## Chapter `links` - The handbook becomes the hub (~4 min)
 
-**Context**: the handbook (`AGENTS.md`) has been a lonely node since the start of this part. Here it becomes the hub: we add two bullets so it mentions the content editor and invokes the publish command. We also give the content editor a reference to the style guide it follows. Several connectors land, and we recap the three link kinds and which syntax produced each.
-
 Apply both edits (their content + translation live in `fixtures-data/`).
 The first appends the two hub bullets to `AGENTS.md`; the second adds
 the style-guide reference line to the content-editor. Backstage (silent):
@@ -325,9 +304,10 @@ Tell the tester:
 >
 > **IMPORTANT:** why does confidence matter? It mirrors how the runtime itself
 > resolves a reference: a deterministic name-and-path lookup, no guessing
-> and no scanning the tree for a file under some other extension. That is
-> cheaper and it does not fail, so the agent spends fewer tokens and less
-> time, the same reason a clean, well-named harness is worth keeping.
+> and no scanning the tree for a file under some other extension. A link that
+> does not resolve sends the agent guessing and retrying, which burns time and
+> tokens; a deterministic one does not fail and resolves first try, 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-settings.md

@@ -22,9 +22,6 @@ stop, do not try to re-init mid-chapter.
 
 ## Step `settings-1-layers` - the config layers (~3 min)
 
-**Context**: where settings live and how `sm` resolves a value
-when more than one place sets it.
-
 > `sm` resolves every setting through a stack of **layers**, each
 > one overriding the layer below it:
 >
@@ -74,9 +71,6 @@ Mark `settings-1-layers: done`.
 
 ## Step `settings-2-resolve` - read, resolve, and set a value (~3 min)
 
-**Context**: the four config verbs (`get`, `show`, `set`, `reset`)
-and how `show --source` reveals which layer won.
-
 > Read a single setting. We'll use `scan.maxNodes`, the cap on how
 > many nodes a scan walks:
 
@@ -123,10 +117,8 @@ Mark `settings-2-resolve: done`.
 
 ## Step `settings-3-lens` - the active provider lens (~2 min)
 
-**Context**: the single most consequential setting, the lens that
-decides which provider types the project's files. It auto-detects and
-never touches your `.md` files. (Agent: substitute `<provider>` with
-`tutorial.provider`, the lens this run was scaffolded for.)
+(Agent: substitute `<provider>` with `tutorial.provider`, the lens
+this run was scaffolded for.)
 
 > One setting earns its own step: the **active provider lens**. A
 > skill-map project reads its files through exactly **one** provider