@skill-map/cli 0.16.0 → 0.16.2

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

@@ -35,10 +35,58 @@ optional second phase (~30-40 min) covering the rest of the CLI.
 
 ## Tone
 
-- Español casual, neutro con un toque argentino. Frases cortas. Cero
-  jerga innecesaria.
-- Llamás al tester por su nombre si te lo dice; si no, "vos".
-- No sos condescendiente. Si pide algo que va a romper, lo avisás claro.
+- Spanish (when the tester's language is Spanish): casual, neutral,
+  NOT rioplatense. Short sentences. No unnecessary jargon. Use
+  `tú` form, not `vos` — `puedes`, `mira`, `prueba`, `crea`, NOT
+  `podés`, `mirá`, `probá`, `creá`. Avoid Argentine fillers
+  (`dale`, `bueno`, `che`, `re-`, `genial`).
+- Address the tester by name if they introduced themselves; if not,
+  the implicit second person from the verb is enough. No need to
+  invent a stand-in pronoun.
+- Don't be condescending. If they ask for something that will
+  break, say so directly.
+- **Translate product vocabulary into Spanish, do NOT leave English
+  loanwords embedded in Spanish prose.** When rendering tester-facing
+  copy in Spanish, use these equivalences:
+  - `kind` → `tipo` (skill-map talks about node "kinds"; in
+    Spanish output the word is `tipo` / `tipos`, NOT "kinds").
+  - `connector` → `conector`.
+  - `watcher` → `observador` (or rephrase: "skill-map sigue tus
+    cambios" instead of "el watcher detecta...").
+  - `scan` (verb) → `escanear`; `scan` (noun) → `escaneo`.
+  - `node` → `nodo`; `link` → `enlace` or `vínculo`; `frontmatter`
+    keep as-is (it's a technical term with no clean Spanish
+    equivalent — explain in parens per the rule above).
+  - File paths, frontmatter keys (`name`, `description`, `event`,
+    etc.), 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 cuatro kinds",
+  "el watcher detectó el cambio", "vamos a hacer un scan ahora".
+  Correct: "aparecen los otros cuatro tipos", "skill-map detectó
+  el cambio", "vamos a escanear ahora".
+- **Stay silent during backstage work.** Do NOT narrate operational
+  steps you're about to take or internal checks. Forbidden patterns
+  include "Voy a verificar primero que el directorio esté listo",
+  "Let me run `sm version` to confirm the binary works", "Mientras
+  esperás, te cuento el estado", "Vamos a ir paso a paso", "OK, ya
+  preparé los archivos, ahora seguimos con...", and any other
+  meta-narration of your own plumbing. Pre-flight checks, file
+  reads, `Bash ls`, `Write` of fixtures, state-file updates — all
+  silent. The tester only hears from you when (a) you need them to
+  do something, (b) a reveal landed and you want a confirm, or
+  (c) something failed and they need to know. Between those
+  moments, work without commentary.
+- **Explain technical terms in parentheses the first time you
+  mention them in a tester-facing blockquote.** Assume the tester
+  is non-technical; many will not know what `frontmatter`,
+  `findings`, `glob`, `watcher`, `connector`, `extractor`, or
+  `kind` mean. Examples:
+  - `frontmatter (the YAML block at the top of every .md, between the two --- lines)`
+  - `findings (any bugs or rough edges you spot — I'll log them for the team)`
+  - `glob (a pattern with wildcards, same shape as .gitignore)`
+  Internal narration in this SKILL.md does not need the gloss;
+  this rule is purely about what the agent says to the tester.
+  After the first mention in a session, the bare term is fine.
 - **Messages addressed to the tester are rendered as Markdown
   blockquotes** (lines prefixed with `> `): instructions, narrative
   context, numbered choice menus, prompts, confirmations. The
@@ -49,20 +97,58 @@ optional second phase (~30-40 min) covering the rest of the CLI.
   narrative and a command, write the narrative in a blockquote
   *above* the bare code block (not inside it).
 - **Mirror the tester's language**: if the first message they wrote
-  was in Spanish, run the conversation in Argentine Spanish (per
-  the Tone bullets above, voseo and all); if in English, run it in
-  plain English. Internal narration in this SKILL.md stays in
-  English regardless.
+  was in Spanish, run the conversation in neutral Spanish (per
+  the Tone bullets above — `tú` form, no rioplatense); if in
+  English, run it in plain English. Internal narration in this
+  SKILL.md stays in English regardless.
+- **Never emit bilingual user-facing copy**. The samples in the
+  blockquotes throughout this SKILL are written in English as the
+  base; translate the entire block to Spanish when the tester
+  speaks Spanish. Do NOT show "Spanish / English" pairs inline,
+  do NOT keep one sentence in English while another is in Spanish,
+  do NOT sprinkle isolated Spanish words inside English paragraphs
+  (or vice versa). Pick one language and commit.
+- **Fixture content also follows the tester's language**. When you
+  `Write` the demo `.md` files (frontmatter `description`, body
+  prose, link anchor text, list items), translate the human text
+  to the tester's language. **Keep these English regardless**:
+  file paths and filenames (`.claude/agents/demo-agent.md`),
+  frontmatter keys (`name`, `description`, `metadata`, `tools`,
+  `event`, etc.), node identifiers (`demo-agent`, `demo-skill`),
+  link target paths inside `[...]( ... )`, code snippets, fenced
+  blocks, and anything the kernel parses structurally. Only the
+  natural-language portions get translated — schema and identifiers
+  stay stable so the watcher and link extractors keep working.
 
 ## Inviolable rules
 
 1. **You DO NOT run `sm` verbs for the tester** except `sm version`
    ONCE during pre-flight to verify the install. Your responsibilities:
    - Write fixture files and `tutorial-state.yml` directly in the cwd.
-   - Edit `.md` files when a step calls for it (the live-UI demo
-     needs this so the watcher has something to react to).
+   - Edit `.md` fixture files when a step calls for it (the live-UI
+     demo needs this so the watcher has something to react to).
    - Read files to verify what the tester modified.
    - Everything else is run by the tester.
+   - **Configuration files have two-mode access**: backstage setup
+     vs teach moment.
+     - **Backstage setup (you DO edit)**: right after `sm init` in
+       Step 1, you append the tutorial's internal entries
+       (`sm-tutorial.md`, `findings.md`, `tutorial-state.yml`,
+       `sm-tutorial-report.md`, etc.) to the freshly created
+       `.skillmapignore` with `Edit`. That is plumbing — the
+       tester does not need to learn that the tutorial hides its
+       own scaffolding from the scan. Do it silently and move on.
+     - **Teach moment (you DO NOT edit)**: any time the SKILL
+       calls for a change to `.skillmapignore`,
+       `.skill-map/settings.json`,
+       `.skill-map/settings.local.json`, or `.gitignore` AS PART
+       OF A REVEAL OR LESSON (e.g. Reveal 5 in Step 2 hides a
+       private node by appending a pattern), you describe the
+       edit in a blockquote and the tester applies it in their
+       own editor. The pedagogical point is that those files
+       belong to the user — they need to internalise where they
+       live and how to change them. Doing it for them in a
+       teach moment defeats the lesson.
 2. **After every command block, stop and wait.** The tester pastes
    the output or replies "OK" / "done". Only then do you advance.
 3. **Persist progress after every step / stage.** Update
@@ -183,6 +269,12 @@ which sm
 sm version
 ```
 
+This check is **silent on success**. Do NOT narrate the result to
+the tester ("`sm` v X.Y.Z responded, all good"). Save the version
+internally and move on. The tester does not need a status report
+for a backstage health check; speaking up here adds noise without
+information. Only break the silence if something actually fails.
+
 If `sm` isn't installed, tell the tester:
 
 > You don't have `sm` yet. You'll need Node 20+ and then:
@@ -198,8 +290,8 @@ permissions issue. Suggest `node --version` and walk them through it.
 
 ### 3. Create the initial fixture (one node only)
 
-The tutorial builds the graph **progressively** in three reveals during
-Step 3 (Live UI). Right now, in pre-flight, you only create **one
+The tutorial builds the graph **progressively** in five reveals during
+Step 2 (Live UI). Right now, in pre-flight, you only create **one
 file** — a single agent — so the tester's first look at the UI
 shows exactly one node. The other four kinds (skill, command, hook,
 note) and the connectors between all five are added later, one
@@ -273,16 +365,13 @@ route:
     status: "not_started"   # not_started | in_progress | done | declined
     estimated_min: 35
 short_steps:
-  - id: "1-version"
-    title: "sm version"
-    status: "pending"
-  - id: "2-init"
+  - id: "1-init"
     title: "sm init"
     status: "pending"
-  - id: "3-ui-live"
+  - id: "2-ui-live"
     title: "⭐ Live UI: bare sm + live edits by the agent"
     status: "pending"
-  - id: "4-handoff"
+  - id: "3-handoff"
     title: "Wrap-up of the demo and offer to keep going"
     status: "pending"
 long_stages:
@@ -336,16 +425,7 @@ to resume (re-invoke the skill from the same dir).
 
 Always runs. The pedagogical hook is the live UI.
 
-### Step 1 — `sm version` (30 s)
-
-Already done in pre-flight. Confirm to the tester in one short
-blockquote, translated to their language:
-
-> OK, `sm` v X.Y.Z responded. Let's go.
-
-Mark `1-version: done`.
-
-### Step 2 — `sm init` (1 min)
+### Step 1 — `sm init` (1 min)
 
 **Context**: `sm init` creates a hidden `.skill-map/` folder in the
 cwd holding the database where skill-map stores what it learns about
@@ -376,27 +456,34 @@ export.*
 dump.sql
 ```
 
-Mark `2-init: done`.
+Mark `1-init: done`.
 
-### Step 3 — ⭐ Live UI (4-5 min)
+### Step 2 — ⭐ Live UI (4-5 min)
 
 **Context**: typing `sm` alone (no arguments) in an initialised dir
 starts the UI server with the watcher built in. One process, one
 terminal: it boots the server, scans the `.md` files, detects
 changes, and pushes events over WebSocket to the live UI.
 
-This step has **three reveals**, each one driven by you editing
-files while the server stays up:
+This step has **five reveals**, each one driven by you editing
+files while the server stays up — except Reveal 3, where the
+tester takes the keyboard for the first time.
 
 1. **Reveal 1 (boot)** — one node alone (the agent).
 2. **Reveal 2 (kinds)** — the four other kinds appear as new nodes,
    still unconnected.
-3. **Reveal 3 (connectors)** — the connectors light up between all
+3. **Reveal 3 (your first edit)** — the **tester** edits the
+   `description` of the agent's `.md` and watches the card
+   refresh in the graph.
+4. **Reveal 4 (connectors)** — the connectors light up between all
    five nodes.
+5. **Reveal 5 (ignore)** — a private file appears, then disappears
+   the moment a pattern is added to `.skillmapignore`.
 
-The pedagogical arc: a single dot → a constellation of dots → a
-graph. Each reveal stops at a confirm prompt before you do the
-next.
+The pedagogical arc: a single dot → a constellation of dots →
+your own edit lands → graph → a graph that respects the user's
+ignore list. Each reveal stops at a confirm prompt before you do
+the next.
 
 **Command** (one terminal):
 
@@ -404,20 +491,52 @@ next.
 sm
 ```
 
+Before Reveal 1, ask the tester to set up a **side-by-side view** so
+they can watch the magic happen without alt-tabbing every reveal.
+Tell the tester:
+
+> Arrange your screen so two windows are visible at the same time:
+>
+> 1. **The browser** — where the graph will update in real time.
+>    Leave it ready to navigate to a URL; we'll get the link in a
+>    moment.
+> 2. **This terminal** — the one where you're talking to me. You'll
+>    see me announce each reveal here, then confirm what you see
+>    in the browser.
+>
+> The third window — the terminal running `sm` — you can leave
+> minimized or off to the side; it will just print scan progress
+> lines and you don't need to read them.
+>
+> A typical layout: browser on the left half, this chat on the
+> right half. Or any split that lets you see both at once. 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):
+
+> In the terminal you opened for `sm`, run the command above. 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.
+
 #### Reveal 1 — the lone agent
 
 Tell the tester:
 
-> The server is running. Open the URL it printed (typically
-> **http://127.0.0.1:4242**).
->
 > You'll see exactly **one node** in the graph: `demo-agent` (kind
 > `agent`). That's our starting point.
 >
 > Walk the 3 views before we go on:
 > 1. **Graph** — the single agent node.
 > 2. **List** — one row, with path / kind / metadata.
-> 3. **Inspector** — click the node to see frontmatter and links.
+> 3. **Inspector** — click the node to see its frontmatter (the
+>    YAML block at the top of every `.md`, between the two `---`
+>    lines) and links.
 >
 > Did the node show up?
 
@@ -507,42 +626,70 @@ Create these four files (with `Write`), exactly in this order:
    wired into the rest of the fixture next.
    ```
 
-4. `notes/todo.md` (kind: note — has a **deliberately broken link**
-   that we exploit later in stage L4):
+4. `notes/todo.md` (kind: note):
    ```markdown
    ---
    name: Demo TODO list
    description: |
      Live list of things to review in the demo. Will become the
      hub between skill / agent / command / hook in the next
-     reveal. Contains a broken link on purpose for the broken-ref
-     stage later on.
+     reveal.
    tags: [notes, demo]
    metadata:
      version: "1.0.0"
    ---
 
    # Pending
-
-   - [ ] Document the [flow diagram](./missing-page.md) — broken
-         link on purpose, leave it.
    ```
 
 Tell the tester:
 
-> Mirá el navegador / Look at the browser. Four new nodes should
-> have popped in: `demo-skill`, `demo-command`, `demo-hook`, and
+> Look at the browser. Four new nodes should have popped in:
+> `demo-skill`, `demo-command`, `demo-hook`, and
 > `notes/todo`. Five total now, **still unconnected** — they're
-> floating dots.
->
-> If you don't see them, zoom out with the mouse wheel or the UI
-> zoom control — new nodes sometimes land off-screen.
+> floating dots. The viewport auto-fits whenever a node is added or
+> removed, so all five should be visible without panning.
 >
 > Did the four appear? Confirm so we can wire them up.
 
 Wait for confirmation.
 
-#### Reveal 3 — the connectors light up
+#### Reveal 3 — your first edit
+
+Up to here you've been watching the agent write files. Now hand
+the keyboard over: the lesson is that the watcher reacts to
+**any** `.md` edit under the cwd, not just to files the agent
+authors. After this beat, the tester has the muscle memory for
+"save → graph updates", which Reveal 5 (`.skillmapignore`) reuses
+verbatim.
+
+Tell the tester:
+
+> Your turn. First, in the browser, **expand the `demo-agent`
+> card** (click the chevron / arrow on the card to open it). That
+> reveals the description currently showing for the node — that's
+> the field you'll edit next, so leave the card open and the
+> change will be obvious.
+>
+> Now open `.claude/agents/demo-agent.md` in your editor of
+> choice. In the **frontmatter** (the YAML block at the top of
+> the file, between the two `---` lines), change the
+> `description:` field to any text you want — the actual content
+> does not matter, just make it different from what's there now.
+> Save the file.
+>
+> Watch the browser. The `demo-agent` card should refresh its
+> description in real time, no reload, no Ctrl+C — same watcher
+> that picked up the four new nodes a moment ago, this time
+> reacting to YOUR edit.
+>
+> Confirm so we wire the five up.
+
+Wait for confirmation. You MAY use `Read` on the file afterwards
+to verify the change landed (read-only, allowed under Inviolable
+rule #1) before moving on.
+
+#### Reveal 4 — the connectors light up
 
 Now you edit the existing files to add the cross-fixture links —
 each one becomes a connector in the graph. Apply with `Edit` (do
@@ -571,11 +718,9 @@ not rewrite the files):
    See [pending items](../../notes/todo.md) for operational
    context.
    ```
-5. **Edit `notes/todo.md`** — replace the existing single bullet
-   with these three (keep the broken-link bullet intact):
+5. **Edit `notes/todo.md`** — append these two bullets after the
+   `# Pending` heading:
    ```markdown
-   - [ ] Document the [flow diagram](./missing-page.md) — broken
-         link on purpose, leave it.
    - [ ] Polish the
          [demo-skill](../.claude/skills/demo-skill/SKILL.md)
          prompt.
@@ -585,8 +730,8 @@ not rewrite the files):
 
 Tell the tester:
 
-> Mirá la magia de nuevo / Look at the magic again. The five
-> floating nodes should now be wired together — connectors light
+> Look at the magic again. The five floating nodes should now be
+> wired together — connectors light
 > up between them as the watcher picks up each edit:
 >
 > - `demo-skill → demo-agent`
@@ -595,90 +740,118 @@ Tell the tester:
 > - `demo-hook → notes/todo`
 > - `notes/todo → demo-skill`, `notes/todo → demo-hook`
 >
-> The intentional broken link inside `notes/todo` (pointing at the
-> non-existent `missing-page.md`) does **not** show up as a
-> connector in the graph — it surfaces as a `broken-ref` **issue**
-> on the `notes/todo` node (look for a warning marker on the node
-> or open it in the inspector). We'll explore that issue properly
-> in stage L4 if you continue with the deeper part.
->
-> Confirmá / confirm. If a connector is missing, refresh the
-> browser and tell me.
+> Confirm. If a connector is missing, refresh the browser and tell
+> me.
 
-Wait for confirmation. **Do NOT move on to Reveal 4** until the
-connectors are confirmed visible — Reveal 4 reuses the same live UI
+Wait for confirmation. **Do NOT move on to Reveal 5** until the
+connectors are confirmed visible — Reveal 5 reuses the same live UI
 session.
 
-#### Reveal 4 — silence a private file via `.skillmapignore`
+#### Reveal 5 — silence a private file via `.skillmapignore`
 
-The first three reveals showed the watcher picking up new files and
-edits. Reveal 4 flips the direction: a file the tester DOES NOT want
+The first four reveals showed the watcher picking up new files and
+edits (yours and theirs). Reveal 5 flips the direction: a file the
+tester DOES NOT want
 in the graph (a draft, a scratch file, a secret) gets hidden by a
 single line in `.skillmapignore`. Same live mechanism — no restart.
 
 `sm init` already wrote a starter `.skillmapignore` at the scope
-root. The tester edits that file plus creates one new fixture node:
+root. The flow has three beats:
 
-1. Create (`Write`) `notes/private-credentials.md` — kind `note`,
-   simulates a file the tester would never want surfacing publicly:
-   ```markdown
-   ---
-   name: private-credentials
-   description: |
-     Personal API tokens — exists in the repo but should not show
-     up in the skill-map graph. Demonstrates the .skillmapignore
-     flow.
-   metadata:
-     version: "0.0.1"
-   ---
+**Beat A — you create one new fixture file (the agent does this).**
 
-   # Private
+`Write` `notes/private-credentials.md` — kind `note`, simulates a
+file the tester would never want surfacing publicly:
 
-   API_TOKEN: example-not-real
-   ```
+```markdown
+---
+name: private-credentials
+description: |
+  Personal API tokens — exists in the repo but should not show
+  up in the skill-map graph. Demonstrates the .skillmapignore
+  flow.
+metadata:
+  version: "0.0.1"
+---
 
-2. Confirm the file appears in the graph as a sixth node
-   (`notes/private-credentials`). The watcher sees it like any
-   other `.md` — that's the point of the demo.
+# Private
 
-3. Edit (`Edit`) `.skillmapignore` and append a single new line at
-   the end:
-   ```
-   notes/private-*.md
-   ```
-   (Pattern syntax mirrors `.gitignore` — kaelzhang's `ignore`
-   under the hood. A literal path like `notes/private-credentials.md`
-   would also work; the glob teaches the broader habit.)
+API_TOKEN: example-not-real
+```
 
-4. Confirm the node disappears from the graph in the browser, no
-   refresh needed. Six nodes back to five.
+Confirm the file appears in the graph as a sixth node
+(`notes/private-credentials`). The watcher sees it like any
+other `.md` — that's the point of the demo.
 
-Tell the tester:
+**Beat B — you show the project structure (the agent does this).**
+
+Before asking the tester to touch `.skillmapignore`, give them a
+mental map of the folder so they know where the file lives and
+what's around it. Use `Bash` (`ls -la` and `ls -la notes/` if a
+deeper view helps) and present the listing inside a blockquote so
+the tester sees what their cwd holds:
 
-> Última magia / one last trick: skill-map stops tracking a file
-> the moment it matches a pattern in `.skillmapignore`. No restart
-> needed — same watcher, opposite direction.
+> Antes del último paso, esto es lo que tenés en el directorio
+> ahora mismo:
 >
-> Two steps:
+> ```
+> .                            ← your cwd
+> ├── .claude/
+> │   ├── agents/demo-agent.md
+> │   ├── commands/demo-command.md
+> │   ├── hooks/demo-hook.md
+> │   └── skills/demo-skill/SKILL.md
+> ├── .skill-map/              ← project DB + settings (managed)
+> ├── .skillmapignore          ← the file we're about to edit
+> ├── notes/
+> │   ├── todo.md
+> │   └── private-credentials.md   ← what we want to hide
+> └── sm-tutorial.md           ← the tutorial file you loaded
+> ```
+>
+> The `.skillmapignore` at the root is the file we'll touch
+> next. Same syntax as `.gitignore`. Anything matching a pattern
+> there is invisible to skill-map's scan.
+
+Adjust the actual tree shown to whatever `ls -la` returns — the
+goal is "tester recognises their own filesystem", not a copy of
+the snippet above.
+
+**Beat C — the tester edits `.skillmapignore` (NOT the agent).**
+
+Per Inviolable rule #1, you DO 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:
+>
+> ```
+> notes/private-*.md
+> ```
 >
-> 1. Create `notes/private-credentials.md` with the content I'll
->    paste → a new node appears on the graph (watcher magic again,
->    expected).
-> 2. Open `.skillmapignore` and append `notes/private-*.md` on a
->    new line → the node disappears from the graph.
+> Save the file. The pattern uses 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.
 >
-> Use this whenever you have drafts, scratch files, or anything
-> you don't want surfacing in the map. Syntax is the same as
-> `.gitignore`: globs, `!pattern` to re-include, `#` for comments.
+> Watch the browser when you save. The
+> `notes/private-credentials` node should disappear from the
+> graph in real time, without restarting anything. Six nodes
+> back to five.
 >
 > Did the node vanish?
 
-Wait for confirmation. Once they confirm, ask them to stop the
-server with **Ctrl+C** in the terminal before continuing.
+After they confirm, you MAY use `Read` on `.skillmapignore` to
+verify the appended pattern landed correctly (in case
+`sm check` later reports something odd) — that is read-only and
+allowed. Once confirmed, ask them to stop the server with
+**Ctrl+C** in the terminal before continuing.
 
-Mark `3-ui-live: done`.
+Mark `2-ui-live: done`.
 
-### Step 4 — Wrap-up of the demo and offer to keep going (30 s)
+### Step 3 — Wrap-up of the demo and offer to keep going (30 s)
 
 > All set! That's the heart of skill-map: you edit a `.md` and the
 > UI sees it instantly. In **~7 minutes** you've already seen the
@@ -733,9 +906,9 @@ Save into `tester.level` and modulate:
 they can do it from their editor.
 
 This stage needs the server running. **Check first** before asking
-them to launch it: many testers leave it running from Step 3 and
+them to launch it: many testers leave it running from Step 2 and
 the demo wraps without an explicit Ctrl+C. Word the prompt as a
-conditional, e.g. "If the server from Step 3 is still up, leave it
+conditional, e.g. "If the server from Step 2 is still up, leave it
 — if not, run `sm` again from the tutorial cwd and reopen the
 browser." Do not just say "start it again" — that risks a second
 process trying to bind the same port and confusing the tester.
@@ -746,7 +919,8 @@ process trying to bind the same port and confusing the tester.
 >
 > Expected: the `demo-skill → demo-agent` connector disappears. If
 > `demo-agent.md` ends up with no one linking to it, it shows up as
-> an orphan (we'll exploit this in stage L4).
+> an orphan (we'll create a similar dangling situation in stage L4
+> to see how `sm check` flags it).
 
 You verify by reading `.claude/skills/demo-skill/SKILL.md` to confirm
 the change was applied. Once they confirm, ask them to **Ctrl+C**
@@ -763,8 +937,9 @@ sm check
 ```
 
 Expected: you see the 5 fixture nodes listed with their kind;
-`check` reports the broken-link issue in `notes/todo.md` pointing
-at `missing-page.md`.
+`check` runs the deterministic rules and reports a clean fixture
+(no issues at this point — we will plant one in stage L4 and watch
+the rule catch it).
 
 ### Stage L3 — ASCII: graph + export (~3 min)
 
@@ -781,10 +956,18 @@ or json.
 
 ### Stage L4 — Issues: broken refs (~3 min)
 
-The fixture has a deliberate broken link in `notes/todo.md`
-pointing at `notes/missing-page.md`. skill-map flags it as a
-**`broken-ref` issue** (not a graph connector, not an "orphan" —
-those are different concepts).
+`broken-ref` is one of the deterministic rules `sm check` runs.
+We'll plant one and watch it surface — that's the easiest way to
+internalise that it is an **issue** on a node, NOT a graph
+connector and NOT the same thing as an "orphan".
+
+Ask the tester to **append one bullet** to `notes/todo.md`:
+
+```markdown
+- [ ] Document the [flow diagram](./missing-page.md).
+```
+
+`./missing-page.md` deliberately doesn't exist. Save the file.
 
 ```bash
 sm check
@@ -795,7 +978,9 @@ sm check --json
 Expected: the warning surfaces the dangling link from
 `notes/todo.md` to the non-existent `missing-page.md`. The
 `--rules` filter lets you focus on a single issue type; `--json`
-emits the structured payload (useful for CI / scripting).
+emits the structured payload (useful for CI / scripting). When
+done, the tester can leave the bullet in place or delete it — the
+rest of the deep-dive doesn't depend on it.
 
 > **Heads up about scope** (mention only if the tester asks):
 >
@@ -846,8 +1031,9 @@ generate a report file to send to Pusher**:
 
 > Thanks! That's a wrap. Before closing:
 >
-> Want me to generate a consolidated **report file** (recap of the
-> walkthrough + findings + environment) ready to send to **Pusher**?
+> Want me to generate a consolidated **report file** (a recap of
+> the walkthrough + findings — the bugs or rough edges you spotted
+> along the way — + environment info) ready to send to **Pusher**?
 > I'll save it as `<cwd>/sm-tutorial-report.md`.
 >
 > 1. **Yes, generate it**