@skill-map/cli 0.53.0 → 0.53.2

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

@@ -148,25 +148,28 @@ Apply §Provider detection from `_core.md`. Persist the result into
 > Got the second terminal open and anchored to the folder? Confirm
 > before we move on.
 
-### 5. Lay the Part 0 fixture and route
+### 5. Write the universal files and show the menu
 
-Part 0 (`fundamentals`) is `preflight: taught-init`: pre-lay its
-fixture now (silently), so the tester's `sm init` in the `init`
-chapter produces a clean scan, but the tester runs `sm init`
-themselves. Write, substituting `<provider_dir>` per detection:
+Pre-flight does NOT pre-lay any part's fixture and does NOT auto-enter
+a part. It writes only the two files every part needs, then routes to
+the menu:
 
-- `<provider_dir>/agents/demo-agent.md` (the single boot node).
-- `.skillmapignore` (block below). Write it NOW, before `sm init`,
-  so the first scan never sees the tutorial's own files. `sm init`
-  only writes `.skillmapignore` when absent, so this stays put.
 - `findings.md` (block below).
-- `tutorial-state.yml` (template below).
+- `tutorial-state.yml` (template below; it starts with `parts: {}`,
+  empty, a part's entry is added the first time the tester picks it).
 
-Then **route** per §Routing in `_core.md`: no prior state → enter
-Part 0 at chapter `init`, **with no menu**. After Part 0 closes,
-render the ToC menu.
+Then **route** per §Routing + menu in `_core.md`: render the **start
+menu** (numbered, Part 0 the prologue as option 1, the recommended
+first pick). The tester picks a part by number; that part's own
+`preflight` (see §Entering a part) lays its fixture when it begins.
+Part 0's demo fixture (the `demo-agent` + the demo `.skillmapignore`,
+blocks below) is laid by its `taught-init` entry, not here.
 
-## Fixture blocks (Part 0 / `taught-init`)
+## Fixture and state templates
+
+The `findings.md` and `tutorial-state.yml` here are universal (written
+in pre-flight); the `demo-agent.md` + the demo `.skillmapignore` are
+Part 0's fixture (laid by its `taught-init` entry).
 
 `<provider_dir>/agents/demo-agent.md`:
 ```markdown
@@ -245,33 +248,39 @@ tutorial:
   provider: "<claude | agent-skills | antigravity>"
 tester:
   level: 2
+parts: {}   # filled in as the tester picks parts from the menu
+findings_file: "./findings.md"
+```
+
+When the tester picks a part from the menu, add its `parts.<id>`
+entry the first time it starts, seeded from the manifest, e.g.:
+
+```yaml
 parts:
   fundamentals:
-    status: "in_progress"   # not_started | in_progress | done | declined
+    status: "in_progress"   # not_started | in_progress | done | declined | skipped
     chapters:
       init:        { status: "pending" }   # pending | done | failed | skipped
       kinds:       { status: "pending" }
-      first-edit:  { status: "pending" }
-      connectors:  { status: "pending" }
-      inspector:   { status: "pending" }
-      edit-link:   { status: "pending" }
-      workspace:   { status: "pending" }
-      ignore:      { status: "pending" }
-findings_file: "./findings.md"
+      # … one row per chapter in the part's manifest entry
 ```
 
-When the tester enters another part from the menu, add a
-`parts.<id>` entry for it (with a `chapters` map seeded from the
-manifest) the first time it starts. Planned parts are not tracked
-until they have content.
+Planned parts are not tracked until they have content. Parts the
+`seed` mechanism fast-forwards past are recorded with `status:
+"skipped"`.
 
 ## Entering a part
 
 When a part begins, honour its `preflight` from the manifest:
 
-- **`taught-init`** (Part 0): the fixture + `.skillmapignore` were
-  pre-laid in pre-flight; the tester runs `sm init` inside the
-  first chapter. Nothing to do here.
+- **`taught-init`** (Part 0): silently, before the tester's `sm init`
+  in the `init` chapter, `Write` the demo fixture (the
+  `<provider_dir>/agents/demo-agent.md` boot node + the demo
+  `.skillmapignore`, both in the §Fixture blocks above), substituting
+  `<provider_dir>` per detection. Write `.skillmapignore` BEFORE the
+  tester runs `sm init` so the first scan never sees the tutorial's
+  own files (`sm init` only writes that file when absent). The tester
+  runs `sm init` themselves in the first chapter.
 - **`portfolio-init`** (Part 1 `project-kickoff`): the campaign's
   real project begins. Backstage, before the tester's `sm init` in
   the `kickoff` chapter: (1) if the prologue ran first in this dir,
@@ -337,11 +346,13 @@ and the part's `pace`.
 
 All three are specified in `_core.md`:
 
-- **Routing + menu**: §Routing + menu. The first-timer skips the
-  menu and lands in Part 0; the menu (the ToC rendered from
-  `_manifest.yml`, completed chapters ticked, `planned` parts hidden,
-  `prereq` gating only the parts that have no `seed`) appears after a
-  part closes or on resume.
+- **Routing + menu**: §Routing + menu. The session always starts at
+  the **numbered start menu** (Part 0 is option 1, the recommended
+  first pick); the menu (the ToC from `_manifest.yml`, numbered,
+  completed parts ticked, `planned` parts hidden, `prereq` gating only
+  the parts that have no `seed`) is the entry point on the first
+  invocation and after every part closes / on resume. Render it with
+  the format in `_core.md` §Menu format.
 - **Resume / restart**: §Resume / restart. On start-over, the exact
   wipe list is whatever the tester's parts actually created:
   `tutorial-state.yml`, `findings.md`, `.skillmapignore`,

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

@@ -38,8 +38,11 @@ loanwords embedded in Spanish prose:
 - `connector` / `edge` → `conector` (**NEVER** `arista`, even
   though it is the common graph translation; skill-map's house
   word is `conector` everywhere).
-- `watcher` → `observador` (or rephrase: "skill-map sigue tus
-  cambios").
+- `watcher` and `browser` stay **English**, do NOT translate them to
+  `observador` / `navegador`. They are words the tester reads in
+  skill-map's own UI and docs, keep them recognisable. If a bare
+  English noun reads oddly mid-sentence, rephrase ("skill-map sigue
+  tus cambios" instead of forcing "el watcher detecta...").
 - `scan` (verb) → `escanear`; `scan` (noun) → `escaneo`.
 - `node` → `nodo`; `link` → `enlace` or `vínculo`; `fixture` →
   `set de prueba`; `pre-flight` → `preparación inicial`;
@@ -49,10 +52,9 @@ loanwords embedded in Spanish prose:
   …), CLI verbs (`sm init`, `sm watch`), and code identifiers stay
   English, that's the public surface, not jargon.
 
-Anti-pattern (do NOT emit): "aparecen los otros tres kinds", "el
-watcher detectó el cambio", "vamos a hacer un scan ahora". Correct:
-"aparecen los otros tres tipos", "skill-map detectó el cambio",
-"vamos a escanear ahora". These translations apply to **chapter
+Anti-pattern (do NOT emit): "aparecen los otros tres kinds", "vamos a
+hacer un scan ahora". Correct: "aparecen los otros tres tipos", "vamos
+a escanear ahora" (and `watcher` / `browser` stay as-is in English). These translations apply to **chapter
 titles** too: a `title` like `"First scan of the fixture"` is
 announced as `"Primer escaneo del set de prueba"`. Never emit a
 chapter title (or any tester-facing prose) in English while the
@@ -175,19 +177,24 @@ first kind quoted, the second kind never.
    the output or replies "OK" / "done". Only then advance.
 4. **Persist progress after every chapter.** Update the state file
    (`parts.<id>.chapters.<id>.status` = `done` / `failed` /
-   `skipped` + a timestamp). Mirror the same status on the harness
-   task via `TaskUpdate`; the harness list is the in-session view,
-   the state file is the cross-session source of truth.
+   `skipped` + a timestamp). The state file is the ONLY progress
+   tracker. Do NOT create harness tasks (`TaskCreate` / `TaskUpdate`)
+   for tutorial progress, they clutter the tester's task list and add
+   nothing the state file does not already hold.
 5. **If the tester reports anything weird**, offer to record it in
    `findings.md` (in the cwd). Reactive, not proactive: only offer
    the findings log when the tester flags something, asks "is that
    normal?", or pastes an error. Never on a clean OK.
-6. **One step at a time inside a chapter.** Finish a chapter (mark
-   it `done`), then **auto-advance** to the next chapter's
-   Announcement in the same response, unless the manifest entry is
-   `pace: per-step` (then ask "¿seguimos?" between steps, as the
-   fundamentals part does today). The continue-prompt at a **part
-   boundary** routes back to the ToC menu.
+6. **The chapter's confirmation IS the go-ahead.** When the tester
+   confirms a chapter, mark it `done` and advance straight to the next
+   chapter's Announcement. NEVER ask a separate "¿seguimos?" / "shall
+   we continue?" between chapters, the per-chapter confirmation already
+   gates advancement and a second question is exactly the redundancy
+   testers complain about. The ONLY continue-prompt is at a **part
+   boundary**, where you route back to the ToC menu. (`pace` controls
+   batching only, see the per-step cycle: `per-step` walks one chapter
+   per exchange, `auto-advance` may chain chapters that need no tester
+   action; neither asks "¿seguimos?".)
 7. **If the state file already exists** when invoked, do not
    overwrite anything. Read it, show progress, offer to continue,
    pick another part, or start over (the last requires explicit
@@ -242,46 +249,87 @@ today. The detection wiring is here so mirrored skills at
 
 ## Per-step cycle (inside a chapter)
 
-When you enter a part, call `TaskCreate` once with one task per
-chapter in that part's `chapters` list. Update each to
-`in_progress` when its block begins and `completed` when it ends.
+A **chapter is the unit of confirmation**. Walk it as ONE beat:
+announce it, do the preparation, hand the tester everything they need
+to do, and ask for confirmation **exactly once, at the end**. Do NOT
+pepper a chapter with several "tell me when…" / "¿viste X?" prompts,
+bundle the actions into a single instruction ("hacé A, después B, y
+avisame cuando el mapa muestre …"). Split a chapter's confirmation
+ONLY when a later action genuinely cannot start until the tester
+finished an earlier one (e.g. they must have the browser open before
+they can watch a node change), and even then keep it to the minimum.
+Never call `TaskCreate` / `TaskUpdate` (Inviolable rule #4).
 
-For every step in a chapter:
+For every chapter:
 
 1. **Announcement**: "Capítulo N: `<title>`. ~M min." then a blank
    line, then (optionally) one sentence of context on its own
    paragraph. `N` is the 1-based index of the chapter inside its
-   part; it resets per part. The context paragraph renders ONLY
-   when the source has a `**Context**:` field; if omitted, announce
-   the title alone. The title comes from the chapter's `title` in
+   part; it resets per part. The context paragraph renders ONLY when
+   the source has a `**Context**:` field; if omitted, announce the
+   title alone. The title comes from the chapter's `title` in
    `_manifest.yml` (translated per §Tone), not the internal id.
-2. **Preparation** (if applicable): create or modify files, show
-   the path and a short preview.
-3. **Commands to run**: a ` ```bash ` block.
-4. **Pause**: "Run that and paste me the output (or say OK)."
-5. **Verification**: read their reply. If something errored,
-   suggest a fix before advancing. If fine, mark `done`. Honour the
-   part's `pace`: `auto-advance` moves straight into the next
-   chapter's Announcement; `per-step` asks "¿seguimos?" first.
+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,
+   bundled into one flow, closed by the single confirmation.
+4. **Verification**: read their reply. If something errored, suggest
+   a fix before advancing. If fine, mark `done` and move straight into
+   the next chapter's Announcement (the confirmation is the go-ahead,
+   Inviolable rule #6, NO "¿seguimos?"). `pace` only decides batching:
+   `per-step` presents one chapter per exchange, `auto-advance` may
+   chain chapters that need no tester action into one response.
 
 ## Routing + menu (orchestrator)
 
-- **No state (first-timer)**: enter the first `spine` part of
-  lowest `order` (Part 0) at its chapter 1, **with no ToC** (the
-  onboarding flow is a single continuous path; never expose the
-  part split).
-- **After a part closes, or state exists**: render the **ToC menu**
-  from `_manifest.yml`, parts in `order` with their chapters,
-  completed chapters prefixed `✓ `. A part with a `seed` (the campaign
-  parts) is **always shown**, even out of order: its `preflight: seed`
-  fast-forwards the project into it (SKILL.md §Entering a part). A part
-  with a `prereq` but NO `seed` (Part 7 `cli`) is shown only once its
-  `prereq` is `done`. Parts with `status: planned` (no `step_file`) are
-  NOT shown. Let the tester pick; walk that part; return to the menu
-  when it ends.
-- **Adding content** is data-only: a new chapter in a part (or a
-  new `part-<id>.md` + a manifest row). Keep chapter-id prefixes
-  matching the file name so dispatch stays mechanical.
+- **Always start at the menu.** On the first invocation (no state)
+  AND after any part closes / on resume, render the **start menu**:
+  the book ToC, numbered, and let the tester pick a part by number.
+  Part 0 (the prologue) is option 1, the recommended starting point,
+  so a brand-new tester just types `1`. Do NOT auto-enter a part; the
+  menu is the entry point every time. On later renders, prefix any
+  completed part's title with `✓ `.
+- **Which parts to list**: parts in `order`, `status: active` only
+  (`planned` parts are hidden). A part with a `seed` (the campaign
+  parts) is always shown, even out of order, its `preflight: seed`
+  fast-forwards the project into it (SKILL.md §Entering a part). A
+  part with a `prereq` but NO `seed` (Part 7 `cli`) is shown only once
+  its `prereq` is `done`.
+- **After the tester picks**: walk that part; when it ends, return to
+  this menu.
+- **Adding content** is data-only: a new chapter in a part (or a new
+  `part-<id>.md` + a manifest row). Keep chapter-id prefixes matching
+  the file name so dispatch stays mechanical.
+
+### Menu format
+
+Render the menu numbered and formatted (NOT a bare list), translated
+to the tester's language. A one-line intro, then per part a **bold
+numbered title line** (number + title + `(~M min)`) as plain prose,
+immediately followed by a single-level `> ` blockquote one-line
+description (what the part covers, derived from its title + chapters).
+NO blank line between a title and its description; ONE blank line
+between parts; NO outer blockquote around the whole menu. Close with a
+short "¿Cuál?" / "Which one?" on its own line. Sample (Claude variant,
+fill the parts and durations from `_manifest.yml`):
+
+```
+¿Por dónde querés arrancar? Podés volver al menú cuando termines cada parte.
+
+**1. El mapa en vivo** (~12 min)
+> El prólogo: corrés `sm`, abrís el browser y ves el mapa actualizarse en vivo mientras editás `.md`. Si es tu primera vez, empezá por acá.
+
+**2. El proyecto desde cero** (~8 min)
+> Arrancás un proyecto real (un portfolio) y su harness `.claude/`.
+
+¿Cuál?
+```
+
+This menu is the ONE exception to the "wrap tester-facing prose in a
+single blockquote" rule: the intro, the bold titles and the trailing
+"¿Cuál?" are plain prose; only the description lines carry `> `. On
+non-Claude hosts the `> ` collapses to plain prose, indent each
+description two spaces so it stays subordinate to its title.
 
 ## Resume / restart
 

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

@@ -1,6 +1,6 @@
 # Part 0: The live map (prologue) - step library
 
-The live-UI prologue: the tester runs `sm init`, opens the browser, and watches the map update in real time as files are written and edited. `pace: per-step` (ask "¿seguimos?" between steps), `preflight: taught-init` (the tester runs `sm init` as the first taught step, not pre-flight), and the chapters lay the basics fixture progressively, one node at a time. Shared conventions (tone, provider detection / substitution, the `> ` rendering rule, the per-step cycle) live in `_core.md`; do not restate them here.
+The live-UI prologue: the tester runs `sm init`, opens the browser, and watches the map update in real time as files are written and edited. `pace: per-step` (one chapter per exchange; the chapter's own confirmation advances to the next, NO separate "¿seguimos?"), `preflight: taught-init` (the tester runs `sm init` as the first taught step, not pre-flight), and the chapters lay the basics fixture progressively, one node at a time. Shared conventions (tone, provider detection / substitution, the `> ` rendering rule, the per-step cycle) live in `_core.md`; do not restate them here.
 
 ## Chapter `init` - Your first node (~2 min)
 
@@ -8,47 +8,25 @@ The live-UI prologue: the tester runs `sm init`, opens the browser, and watches
 
 ```bash
 sm init
-ls -la .skill-map/
+sm
 ```
 
-Expected: `.skill-map/skill-map.db` appears (plus config files). The initial scan reports a small node / link / issue count from the demo-agent fixture, NOT 14+ phantom issues from the tutorial's own prose: pre-flight already wrote `.skillmapignore` with the right exclusions in place, so `sm init` leaves that file alone (it only writes when absent) and the scan never sees `sm-tutorial.md` / `findings.md` / `tutorial-state.yml`.
+Expected: `.skill-map/skill-map.db` appears (plus config files), and the initial scan reports a small node / link count from the demo-agent fixture. `sm init` runs and exits; `sm` then starts the UI server and stays running. (Agent context, do not narrate: pre-flight's `.skillmapignore` keeps the tutorial's own files, `sm-tutorial.md` / `findings.md` / `tutorial-state.yml`, out of the scan; `sm init` leaves that file alone since it only writes when absent.)
 
-Before launching the server, ask the tester to set up a **side-by-side view** so they can watch the magic happen without alt-tabbing every step. Tell the tester:
+Give the tester the whole flow in one message with ONE confirmation, do NOT pause for the `sm init` output separately. Don't hardcode the URL, the verb logs the bound `http://host:port` after listen. Tell the tester:
 
-> Now arrange your screen so the **browser** (where the **Map**
-> updates in real time) and **this chat** are both visible at once
->, typical layout is browser on the left half, chat on the right
-> (or any split that lets you see both). The terminal running
-> `sm` can stay off to the side; it just prints scan progress
-> lines and you don't need to read them.
+> First, **open your browser** and put it side by side with this
+> chat (browser on one half, chat on the other, any split that lets
+> you see both) so you can watch the **Map** update in real time.
 >
-> Tell me when you're set up and we start.
-
-Wait for confirmation before moving on. Once they're ready, prompt them to launch the server and open the link it prints, without hardcoding the URL here, since the verb itself is the source of truth (it logs the bound `http://host:port` after listen):
-
-> Run `sm`. After a couple of seconds it will print a line with the
-> URL where the UI is listening, copy that link and open it in the
-> browser you just arranged. Tell me when you see the page load.
-
-Wait for confirmation that the page loaded. Then tell the tester:
-
-> You'll see exactly **one node** in the **Map**: `demo-agent`
-> (kind `agent`). That's our starting point.
+> Then, in your second terminal, run the two commands above: `sm
+> init` sets the project up (it creates `.skill-map/` and runs a
+> first scan), and `sm` boots the live UI. After a couple of seconds
+> `sm` prints a URL, copy it and open it in your browser. The
+> terminal keeps printing scan lines, you don't need to read them.
 >
-> The workspace opens **map-first**: the canvas fills the screen and
-> the **Files** panel sits collapsed against the left edge. Click the
-> expand handle on the far left (the `>` arrow, its tooltip reads
-> "Expand files panel") to open it.
->
-> Now walk the two views before we go on:
-> 1. **Map**: the single agent node on the canvas.
-> 2. **Files**: one row, with path / kind / metadata.
->
-> Then, back in **Map**, click the node: the **Inspector** panel
-> slides out with its frontmatter (the YAML block at the top of
-> every `.md`, between the two `---` lines) and its links.
->
-> Did the node show up?
+> You'll see one node in the **Map**: `demo-agent`. Tell me when the
+> page is open showing it.
 
 Wait for confirmation. Mark `init`: done.
 
@@ -149,7 +127,7 @@ Create these four files (with `Write`), exactly in this order. Per §Provider de
 Tell the tester:
 
 > Look at the browser. Four new nodes should have popped in:
-> `demo-skill`, `demo-command`, `notes/todo`, and `demo-guideline`.
+> `demo-skill`, `demo-command`, **Demo TODO list**, and `demo-guideline`.
 > Five total now, **still unconnected**: they're floating dots.
 > The viewport auto-fits whenever a node is added or removed, so
 > all five should be visible without panning.
@@ -182,11 +160,6 @@ Tell the tester:
 > the field you'll edit next, so leave the card open and the
 > change will be obvious.
 >
-> ⚠ Heads-up: the inspector header shows a couple of action
-> buttons (**Bump version**, **Refresh body**). **Don't click
-> them yet**, they write files to your project and we cover that
-> flow deliberately in the annotations chapter. For now, just look.
->
 > Now open `.claude/agents/demo-agent.md` in your editor of
 > choice. In the **frontmatter** at the top of the file, change
 > the `description:` field to any text you want, the actual
@@ -210,9 +183,9 @@ You edit `notes/todo.md` so it becomes the **hub** that points to each of the ot
 - a `/slash` token → kind `invokes`
 - a markdown link `[text](path)` → kind `references`
 
-Four bullets, three kinds (the `invokes` kind shows up twice because both the command and the skill are addressed by slash).
+Five bullets, three kinds: `invokes` and `mentions` each appear twice, `references` once. The last two bullets both point at the **same** node (`demo-guideline`), on purpose: a markdown link AND an `@`-mention of it, so the next beat can contrast their confidence (the file link is certain, the name drop is a softer guess).
 
-Apply with `Edit` on `notes/todo.md` (do not rewrite the file). Per §Provider detection, **substitute `.claude/` with the detected `<provider_dir>` and drop any bullet whose target node was not created in the `kinds` chapter** (on `agent-skills` / Antigravity there is no agent and no command → skip the `@demo-agent` and `/demo-command` bullets, two connectors land).
+Apply with `Edit` on `notes/todo.md` (do not rewrite the file). Per §Provider detection, **substitute `.claude/` with the detected `<provider_dir>` and drop any bullet whose target node was not created in the `kinds` chapter** (on `agent-skills` / Antigravity there is no agent and no command → skip the `@demo-agent` and `/demo-command` bullets; the `@demo-guideline` mention stays and is the faint connector on those providers too).
 
 **Edit `notes/todo.md`**: append these bullets after the `# Pending` heading:
 
@@ -222,32 +195,34 @@ Apply with `Edit` on `notes/todo.md` (do not rewrite the file). Per §Provider d
 - [ ] Trigger /demo-skill when the input lands.
 - [ ] Re-read the
       [demo-guideline](./demo-guideline.md) before shipping.
+- [ ] Ping @demo-guideline if the conventions change.
 ```
 
 Tell the tester:
 
-> Look at the magic again. `notes/todo` is now the hub: four
-> arrows light up between it and the other nodes, and the UI
-> palette colours each arrow by the link kind it carries:
+> Look at the magic again. **Demo TODO list** is now the hub: five
+> arrows light up between it and the other nodes, and the UI palette
+> colours each arrow by the link kind it carries:
 >
-> - `notes/todo → demo-agent` (kind: `mentions`)
-> - `notes/todo → demo-command` (kind: `invokes`)
-> - `notes/todo → demo-skill` (kind: `invokes`)
-> - `notes/todo → demo-guideline` (kind: `references`)
+> - `Demo TODO list → demo-agent` (kind: `mentions`)
+> - `Demo TODO list → demo-command` (kind: `invokes`)
+> - `Demo TODO list → demo-skill` (kind: `invokes`)
+> - `Demo TODO list → demo-guideline` (kind: `references`, the markdown link)
+> - `Demo TODO list → demo-guideline` (kind: `mentions`, the @ handle)
 >
 > The kind comes from the syntax in the bullet: an `@handle` is
-> always a mention, a `/command` is always an invoke, a markdown
-> link is always a reference. Four arrows, three kinds, three
-> colours on the canvas (the two `invokes` share a colour, as you
-> would expect).
+> always a mention, a `/skill` or `/command` is always an invoke, a
+> markdown link is always a reference. Five arrows, three kinds.
 >
-> Notice too that the connectors have different transparency.
-> Skill-map estimates how sure it is of each connection: a
-> `[text](file.md)` that points at a real file (confidence 1.00,
-> now that the target exists) looks solid, while an `@handle` that
-> resolves to no node sits at 0.5 (ambiguous) and looks
-> translucent. The opacity tells that story at a glance: the more
-> solid the arrow, the more reliable the inference.
+> Now look closely: the two arrows to **demo-guideline** are not
+> equally solid. Skill-map draws each connector's **confidence** as
+> opacity, how sure it is the link is real. The markdown link
+> `[demo-guideline](./demo-guideline.md)` points at a real file, so
+> it's certain (1.00) and looks solid; the `@demo-guideline` mention
+> is a looser name drop, a softer guess (0.50), so it's drawn fainter.
+> A glance at the map tells you which links are rock solid and which
+> are skill-map's best guess; the exact number per link is in the
+> inspector, next chapter.
 >
 > Confirm when you see it. If a connector is missing, refresh the
 > browser and let me know.
@@ -258,25 +233,27 @@ If a connector is missing, do not advance, the next chapter inspects the same hu
 
 The connector opacity tells the confidence story at a glance; the exact per-link breakdown lives in the Inspector. Open it on the hub so the tester registers the surface before the `edit-link` chapter changes topology.
 
-> 🆕 Open the Inspector for `notes/todo` (click the node on the
-> map). Scroll down to the **Linked nodes** panel: it has two
-> sections, **Outgoing** and **Incoming**. `notes/todo` lists 4
-> links under Outgoing (it's the hub pointing at four nodes) and 0
-> under Incoming; if you open the Inspector for any of the four
-> targeted nodes, you'll see 1 under Incoming. Each row shows the
-> link kind (`mentions`, `invokes`, `references`) and a badge with
-> its confidence: the numeric value (`1.00`, `0.50`, …).
+> 🆕 Open the Inspector for **Demo TODO list** (click the node on
+> the map). **Expand** the **Connections** section (it's collapsed
+> by default): it has two sections, **Outgoing** and **Incoming**.
+> Demo TODO list lists **5 links** under Outgoing (the hub) and 0
+> under Incoming; open the Inspector for a targeted node to see its
+> Incoming count (demo-guideline shows **2**, the reference plus the
+> mention; the others 1 each). Each row shows the link kind
+> (`mentions`, `invokes`, `references`) and a badge with its
+> confidence: the numeric value. Here you'll see the contrast in
+> numbers, the `references` to demo-guideline reads `1.00`, the
+> `mentions` of it reads `0.50`.
+>
+> 💡 Tip: if all these changes left the nodes crowded together, the
+> map toolbar has a **Re-arrange layout** button (tooltip "Re-arrange
+> the visible nodes"): it tidies the layout so everything reads
+> better. If you've moved nodes by hand it asks for confirmation
+> first, otherwise it just re-arranges.
 >
 > Let me know when you see it.
 
-After the tester confirms, drop this tip:
-
-> 💡 Tip: if all these changes left the nodes crowded together,
-> the map toolbar has a **Reset layout** button: it re-runs the
-> auto-layout so everything reads better. It asks for confirmation
-> because it discards any positions you moved by hand.
-
-Wait for confirmation. Mark `inspector`: done.
+Mark `inspector`: done.
 
 ## Chapter `edit-link` - Edit a link, the topology changes (~3 min)
 
@@ -288,7 +265,7 @@ The server has been live since the `init` chapter, leave it running; this chapte
 > delete the bullet that contains `@demo-agent`. Save. Watch the
 > UI.
 >
-> Expected: the `notes/todo → demo-agent` connector (kind:
+> Expected: the `Demo TODO list → demo-agent` connector (kind:
 > `mentions`) disappears in real time. The two nodes stay in the
 > **Map**; only the edge goes.
 
@@ -296,19 +273,18 @@ You verify by reading `notes/todo.md` to confirm the change was applied. (On `ag
 
 ## 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, filter it with the search box, and use **isolate** to collapse the map down to a single node and the things it touches. No file edits here, pure navigation, and the same `sm` session you booted back in the `init` chapter is still running.
+**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. No file edits here, pure navigation, and the same `sm` session you booted back in the `init` chapter is still running.
 
 Per §Provider detection, on `agent-skills` / Antigravity the fixture has fewer nodes (`demo-skill` plus the two `notes/` files), so swap the node names below for ones that exist in that set; the gestures are identical.
 
 **Beat 1, open the Files panel (tester does this).**
 
-> Make sure the **Files** panel is open, the one you expanded back
-> in the first chapter on the left edge. If you collapsed it since,
-> click the expand handle (the `>` arrow, tooltip "Expand files
-> panel") to reopen it. The sidebar shows a **folder tree** (a
-> nested view of your folders and the nodes inside them): your five
-> nodes grouped under `.claude/` and `notes/`, each row showing its
-> kind and how many links go in and out.
+> Open the **Files** panel. It sits collapsed against the left edge
+> by default: click the expand handle there (the `>` arrow, its
+> tooltip reads "Expand files panel"). The sidebar opens into a
+> **folder tree** (a nested view of your folders and the nodes inside
+> them): your five nodes grouped under `.claude/` and `notes/`, each
+> row showing its kind and how many links go in and out.
 >
 > Tell me when the tree is open.
 
@@ -318,27 +294,26 @@ Per §Provider detection, on `agent-skills` / Antigravity the fixture has fewer
 > `Search…`). Type `guideline`. Watch both halves at once: the tree
 > narrows down to `demo-guideline` and the **Map** drops every node
 > except `demo-guideline`. The search matches a node's name, path,
-> tags or description, and filters live as you type, no Enter
-> needed.
+> or description, and filters live as you type, no Enter needed.
 >
 > Now clear the box. All five nodes come back, in both the tree and
 > the Map. Confirm you saw it filter and then restore.
 
 **Beat 3, isolate (tester does this).**
 
-> Last one. In the tree, find the `notes/todo` row: at its right
-> edge there's a small **sitemap** icon (its tooltip reads "Isolate
-> this node and its direct links on the map"). Click it.
+> Last one. In the tree, find the **Demo TODO list** row: at its
+> right edge there's a small **sitemap** icon (its tooltip reads
+> "Isolate this node and its direct links on the map"). Click it.
 >
-> The Map collapses to `notes/todo` plus only the nodes it links to
-> (`demo-command`, `demo-skill`, `demo-guideline`). `demo-agent`,
-> which lost its only connector back in the last step, drops out of
-> view, and the Inspector opens on `notes/todo`. That's how you
+> The Map collapses to **Demo TODO list** plus only the nodes it
+> links to (`demo-command`, `demo-skill`, `demo-guideline`).
+> `demo-agent`, which lost its only connector back in the last step,
+> drops out of view, and the Inspector opens on **Demo TODO list**.
+> That's how you
 > focus on one node's neighborhood when a map gets busy.
 >
 > To bring the rest back, look at the toolbar along the bottom of
-> the Map: there's a **Show all** button (an eye icon, tooltip
-> "Clear the map selection and show every node again"). Click it and
+> the Map: there's a **Show all** button (an eye icon). Click it and
 > all five nodes return.
 >
 > Did the map isolate and then restore?
@@ -369,7 +344,7 @@ description: |
 API_TOKEN: example-not-real
 ```
 
-Confirm the file appears in the map as a sixth node (`notes/private-credentials`). The watcher sees it like any other `.md`, that's the point of the demo.
+Confirm the file appears in the map as a sixth node (`notes/private-credentials`). The watcher sees it like any other `.md`, that's the point of the demo. (If the tester doesn't see it, they may need to click **Show all** in the map toolbar to clear any leftover selection.)
 
 **Beat 2, you show the project structure (the agent does this).**
 
@@ -403,14 +378,19 @@ Adjust the actual tree shown to whatever `ls -la` returns, the goal is "tester r
 
 Per Inviolable rule #2, the agent does NOT touch `.skillmapignore` with your `Edit` tool. Tell the tester to do it from their editor:
 
-> Last step. Open `.skillmapignore` (it's at the cwd root) in
-> your editor of choice. At the end of the file, on a new line,
-> append the literal pattern `notes/private-*.md`. Save the
-> file. The pattern uses a glob (same as `.gitignore`):
+> Last step. Open `.skillmapignore` (it's at the cwd root) in your
+> editor of choice. At the end of the file, on a new line, append
+> this pattern:
+
+```
+notes/private-*.md
+```
+
+> Save the file. It's a glob (same as `.gitignore`):
 > `notes/private-*.md` matches `private-credentials.md` and any
 > future sibling `private-*.md`. A literal path
-> (`notes/private-credentials.md`) would also work, the glob
-> teaches the broader habit.
+> (`notes/private-credentials.md`) would also work, the glob teaches
+> the broader habit.
 >
 > Watch the browser when you save. The
 > `notes/private-credentials` node should disappear from the