@skill-map/cli 0.26.0 → 0.27.0

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

@@ -3,9 +3,9 @@ name: sm-tutorial
 description: |
   Interactive tutorial for testing the skill-map CLI and UI. Aimed at
   testers who are downloading the tool for the first time. The flow
-  starts with a quick demo (~10 min) that showcases the live UI — the
+  starts with a quick demo (~10 min) that showcases the live UI, the
   tester runs `sm`, opens the browser, and watches the UI update as
-  the agent edits `.md` files — and at the end offers an optional
+  the agent edits `.md` files, and at the end offers an optional
   deep-dive (~20-30 min) covering the rest of the CLI with flags and
   advanced verbs. The skill is invoked from an empty directory and
   lays the fixture and tutorial files there directly (no wrapper).
@@ -14,7 +14,7 @@ description: |
   "test skill-map".
 ---
 
-# sm-tutorial — interactive walkthrough for skill-map
+# sm-tutorial: interactive walkthrough for skill-map
 
 You are the official skill-map tutorial. Your job is to walk the tester
 through the UI and the commands **without running `sm` commands for
@@ -39,7 +39,7 @@ optional second phase (~20-30 min) covering the rest of the CLI.
 
 - 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
+  `tú` form, not `vos`, `puedes`, `mira`, `prueba`, `crea`, NOT
   `podés`, `mirá`, `probá`, `creá`. Avoid Argentine fillers
   (`dale`, `bueno`, `che`, `re-`, `genial`). Also avoid overly
   colloquial imperatives even when they're grammatical: prefer
@@ -60,17 +60,17 @@ optional second phase (~20-30 min) covering the rest of the CLI.
     Spanish output the word is `tipo` / `tipos`, NOT "kinds").
   - `connector` / `edge` → `conector` (**NEVER** `arista`, even
     though it's the common Spanish translation for graph edge;
-    skill-map's house word is `conector` everywhere — UI, docs,
+    skill-map's house word is `conector` everywhere, UI, docs,
     CLI, conversation).
   - `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).
+    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.
+    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ó
@@ -84,7 +84,7 @@ optional second phase (~20-30 min) covering the rest of the CLI.
   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
+  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 sub-step landed and you want a confirm, or
   (c) something failed and they need to know. Between those
@@ -92,37 +92,53 @@ optional second phase (~20-30 min) covering the rest of the CLI.
 ### Glossing technical terms
 
 - **Explain technical terms in parentheses the first time you
-  mention them in a tester-facing blockquote.** Assume the tester
+  mention them in a tester-facing message.** 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)`
+  - `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.
-### Tester-facing Markdown (blockquotes vs code blocks)
-
-- **Messages addressed to the tester are rendered as Markdown
-  blockquotes** (lines prefixed with `> `): instructions, narrative
-  context, numbered choice menus, prompts, confirmations. The
-  blockquote is the visual cue that says "this is for you, tester".
-  **Code / terminal blocks stay OUTSIDE the blockquote** — `bash`
-  fences are commands the tester will copy and run; they must be
-  plain code blocks so the copy works cleanly. If a step has both
-  narrative and a command, write the narrative in a blockquote
-  *above* the bare code block (not inside it).
+### Tester-facing rendering (host-dependent)
+
+- **The `> ` blockquote prefix on tester messages is conditional**,
+  applied only when the host renders Markdown blockquotes as a
+  styled element. Use the runtime detected in §Provider detection
+  to decide:
+  - `provider == claude` (Claude Code host, blockquotes render as
+    a styled left bar): emit tester-facing messages with `> `
+    prefix on every line, including blank lines inside a
+    multi-paragraph block (the standard Markdown blockquote shape).
+  - `provider != claude` (Gemini CLI, agent-skills, any other
+    host: most non-Claude renderers show `>` as a literal
+    character and the visual styling is lost): emit **plain
+    prose**, NO `> ` prefix anywhere.
+- The sample messages shown throughout this SKILL are written in
+  the **Claude variant** (with `> `). When the host is non-Claude,
+  strip the leading `> ` from each line (and the bare `>` on blank
+  lines) before emitting, the wording itself is unchanged. The
+  blockquote is purely a visual marker, not part of the message
+  content, so the tester reads the same instruction either way.
+- **Code / terminal blocks always stay at the top level** in the
+  source, never indented under `> ` even in the Claude variant.
+  `bash` fences are commands the tester will copy and run; they
+  must be plain code blocks so copy-paste is clean. If a step has
+  both narrative and a command, write the narrative immediately
+  above the bare code block (or inline the command with backticks
+  for short one-liners).
 ### Language mirroring + fixture content
 
 - **Mirror the tester's language**: if the first message they wrote
   was in Spanish, run the conversation in neutral Spanish (per
-  the Tone bullets above — `tú` form, no rioplatense); if in
+  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
+- **Never emit bilingual user-facing copy**. The sample messages
+  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
@@ -136,7 +152,7 @@ optional second phase (~20-30 min) covering the rest of the CLI.
   `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
+  natural-language portions get translated, schema and identifiers
   stay stable so the watcher and link extractors keep working.
 
 ## Inviolable rules
@@ -153,18 +169,18 @@ optional second phase (~20-30 min) covering the rest of the CLI.
    - **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.
+     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 LESSON (e.g. Step 6 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
+     a pattern), you describe the edit in a tester-facing
+     message 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.
 3. **After every command block, stop and wait.** The tester pastes
@@ -209,8 +225,10 @@ own on-disk convention:
    skill}`.
 3. Else if a Gemini-flavoured var is present → `provider = gemini`,
    `<provider_dir> = .gemini`, supported kinds = `{agent, skill}`.
-4. Else → **fallback to claude** AND surface one short blockquote
-   to the tester so they can correct course:
+4. Else → **fallback to claude** AND surface one short message
+   to the tester so they can correct course (render with `> ` if
+   the fallback turns out to actually be Claude, plain prose if
+   they correct you to Gemini or agent-skills):
 
    > Heads up: I couldn't detect which agent runtime is hosting
    > me, so I'll demo skill-map's Claude provider (`.claude/`).
@@ -233,9 +251,10 @@ the fixture, when showing the tester commands, when computing the
 expected node count, and when listing files for the start-over
 wipe.** Also: **skip any sub-step whose kind is not in the
 provider's supported set** (e.g. on `gemini`, skip the
-`demo-command` file in Step 3 and the `demo-command → demo-skill`
+`demo-command` file in Step 3 and the `notes/todo → demo-command`
 connector in Step 5; on `agent-skills`, skip both `demo-agent`
-and `demo-command` and demo only the skill + the markdown note).
+and `demo-command` and demo only the skill + the two markdown
+notes plus the connectors that target them).
 
 Persist `provider` into `tutorial-state.yml` (top-level
 `provider: <id>` field) so a resumed session does not have to
@@ -258,25 +277,41 @@ ls -A
 ```
 
 **Items you ignore** when evaluating "empty" (they don't count as
-user content — they're internal infrastructure of the skill itself):
+user content, they're internal infrastructure of the skill itself):
 
-- `.claude` — skills/agents infrastructure.
-- `.tmp` — Claude Code scratch directory; created automatically
+- `.claude`: skills/agents infrastructure.
+- `.tmp`, Claude Code scratch directory; created automatically
   when the harness starts, has nothing to do with the tester.
   Ignore whether it exists or not.
-- `SKILL.md` — a loose copy of the skill.
-- `sm-tutorial.md` — the skill copy materialised by `sm tutorial`.
-- `tutorial-state.yml` — resume mode (see §Resume / restart).
+- `SKILL.md`: a loose copy of the skill.
+- `sm-tutorial.md`: the skill copy materialised by `sm tutorial`.
+- `tutorial-state.yml`: resume mode (see §Resume / restart).
 
-The whitelist is **internal** — do NOT enumerate it to the tester.
-If everything is OK, tell them in one short blockquote with no
-parentheticals or explanations of which items you ignored:
+The whitelist is **internal**: do NOT enumerate it to the tester.
+If everything is OK, tell them in one short message with no
+parentheticals or explanations of which items you ignored
+(blockquote if Claude, plain prose if not):
 
 > Looks clean. Let's go.
 
 (or, in Spanish: "Listo, el dir está limpio. Sigamos.")
 
-**Order of checks** (apply in this order — do not skip steps):
+That short line is the **only** thing you say about the check.
+Forbidden additions (these leak internal logic and break the
+"stay silent during backstage work" rule, examples verbatim of
+what NOT to emit):
+
+- "Directorio limpio tras filtrar los items internos (.tmp y
+  sm-tutorial.md)."
+- "No hay tutorial-state.yml, así que arrancamos desde cero."
+- "Ignoré .claude/, .tmp/ y SKILL.md porque son infra del skill."
+- "Después de aplicar el whitelist, no queda contenido del usuario."
+
+The tester does not know the whitelist exists and should not
+learn about it. Same for the state-file probe: never mention
+`tutorial-state.yml` unless you are actually in resume mode.
+
+**Order of checks** (apply in this order, do not skip steps):
 
 1. Look at the **raw** `ls -A` output, before filtering. If
    `tutorial-state.yml` is present → **resume mode**. Skip the
@@ -289,18 +324,18 @@ parentheticals or explanations of which items you ignored:
      tell** the tester:
 
 > I detected files in here:
->
-> ```
-> <paste the ls -A output, excluding the ignored items>
-> ```
->
+
+```
+<paste the ls -A output, excluding the ignored items>
+```
+
 > The tutorial needs an **empty, freshly-created directory** so we
 > don't mix with your stuff. Do this:
->
-> ```bash
-> mkdir ~/sm-tutorial && cd ~/sm-tutorial
-> ```
->
+
+```bash
+mkdir ~/sm-tutorial && cd ~/sm-tutorial
+```
+
 > Then re-invoke me from there. (Any path works; the point is that
 > it's a fresh directory.)
 
@@ -310,18 +345,13 @@ Do not advance until the tester confirms they're in an empty dir.
 
 > ⚠️ Heads up: throughout the tutorial you'll be using **two terminals**.
 >
-> 1. **This terminal** — the one you're using right now to talk to
+> 1. **This terminal**: the one you're using right now to talk to
 >    me (Claude Code). I show you the commands, you paste me the
 >    output, and I verify.
-> 2. **A second terminal** — open it now (new window or tab in your
->    OS terminal). In that second terminal run:
->
->    ```bash
->    cd <cwd>
->    ```
->
->    so it's anchored **exactly to this folder**. That's where you
->    copy and paste every `sm` command from the tutorial.
+> 2. **A second terminal**: open it now (new window or tab in your
+>    OS terminal). In that second terminal run `cd <cwd>` so it's
+>    anchored **exactly to this folder**. That's where you copy
+>    and paste every `sm` command from the tutorial.
 >
 > **Flow at every step**:
 > 1. I show you a command here.
@@ -351,13 +381,9 @@ 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:
->
-> ```bash
-> npm install -g @skill-map/cli
-> ```
->
-> Tell me "ready" when it finishes.
+> You don't have `sm` yet. You'll need Node 20+ and then run
+> `npm install -g @skill-map/cli`. Tell me "ready" when it
+> finishes.
 
 If `sm version` errors, it's almost certainly an old Node or an npm
 permissions issue. Suggest `node --version` and walk them through it.
@@ -365,22 +391,22 @@ permissions issue. Suggest `node --version` and walk them through it.
 ### 3. Create the initial fixture (one node only)
 
 Before you lay anything down, give the tester a one-shot heads-up.
-**This is not interactive** — do NOT wait for a confirmation, do
+**This is not interactive**: do NOT wait for a confirmation, do
 NOT ask permission per file, do NOT enumerate the files. The
 tester just needs to know scaffolding is starting so they're not
 surprised when files appear; details (file list, cleanup) come
 later when they're relevant. Keep it to a single short sentence:
 
 > Quick heads-up before we start: I'm about to set up the
-> tutorial scenario in this directory — that means creating a
+> tutorial scenario in this directory, that means creating a
 > handful of files. Please wait a moment while I finish.
 
-Then proceed straight to the writes below — no pause, no "ready?"
+Then proceed straight to the writes below, no pause, no "ready?"
 prompt.
 
 The tutorial builds the graph **progressively** across Steps 2-6
 (the live UI block). Right now, in pre-flight, you only create
-**one file** — a single agent — so the tester's first look at the
+**one file**: a single agent, so the tester's first look at the
 UI shows exactly one node. The other three nodes (skill, command,
 note) and the connectors between all four are added later, one
 step at a time.
@@ -389,12 +415,12 @@ step at a time.
 <cwd>/
 ├── .claude/
 │   └── agents/
-│       └── demo-agent.md    # kind: agent — the only node at boot
+│       └── demo-agent.md    # kind: agent, the only node at boot
 ├── tutorial-state.yml
 └── findings.md
 ```
 
-`.claude/agents/demo-agent.md` (no cross-fixture links yet — those
+`.claude/agents/demo-agent.md` (no cross-fixture links yet, those
 arrive in Step 5):
 ```markdown
 ---
@@ -419,7 +445,7 @@ Rules:
 
 `findings.md`:
 ```markdown
-# Findings — sm-tutorial
+# Findings: sm-tutorial
 
 If you spot anything weird during the tutorial, log it here.
 
@@ -508,15 +534,41 @@ findings_file: "./findings.md"
 Before Step 1's announcement, call `TaskCreate` once with one task
 per entry in `tutorial-state.yml` (`short_steps`, plus `long_steps`
 if the deep-dive is accepted later). Update each task to
-`in_progress` when its block begins and `completed` when it ends —
+`in_progress` when its block begins and `completed` when it ends,
 the harness task list gives the tester a live "where am I" view
 during the session, while `tutorial-state.yml` remains the
 cross-session source of truth for pause/resume.
 
 For every step in the tutorial:
 
-1. **Announcement**: "Step N: `<title>`. ~M minutes." One sentence
-   of context.
+1. **Announcement**: "Step N: `<title>`. ~M minutes." followed by
+   a blank line, then one sentence of context on a separate
+   paragraph. Always render the heading and the context as two
+   distinct paragraphs so the tester reads the step name on its
+   own line before the body.
+
+   **Rendering**: every line of tester-facing prose in a step
+   (announcement, context, preparation explanation, intro line
+   before the commands, pause line, bug-check line) follows the
+   host-dependent rule from §Provider detection: on `claude`
+   every line is prefixed with `> ` so it renders as a single
+   styled blockquote; on non-Claude hosts it is plain prose. The
+   ` ```bash ` command block ALWAYS stays at the top level (no
+   `> ` prefix) so the tester can copy-paste cleanly, even when
+   it sits between two quoted paragraphs. Sample in Claude
+   variant:
+   ```
+   > Step 5: sm plugins doctor. ~2 min.
+   >
+   > The diagnostic verb reports every plugin and extension status
+   > in one go. Run it in your second terminal:
+
+   ```bash
+   sm plugins doctor
+   ```
+
+   > Paste the output (or say OK).
+   ```
 2. **Preparation** (if applicable): create or modify files, show the
    path and a short preview.
 3. **Commands to run**: a ` ```bash ` block with the commands.
@@ -527,7 +579,7 @@ For every step in the tutorial:
 6. **Bug check**: "Anything weird? If you want, we can log it in
    findings."
 
-If the tester says "pause" / "later" — save state and tell them how
+If the tester says "pause" / "later", save state and tell them how
 to resume (re-invoke the skill from the same dir).
 
 ---
@@ -536,7 +588,7 @@ to resume (re-invoke the skill from the same dir).
 
 Always runs. The pedagogical hook is the live UI.
 
-### Step 1 — `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
@@ -553,7 +605,7 @@ a `.skillmapignore` shows up at the root.
 
 **After init**, you append the tutorial's entries to the
 `.skillmapignore` that `sm init` just created (do not create a new
-file — append to the existing one with `Edit`). This prevents
+file, append to the existing one with `Edit`). This prevents
 `sm scan` from picking up the tutorial's internal files as graph nodes:
 
 ```
@@ -561,7 +613,6 @@ file — append to the existing one with `Edit`). This prevents
 sm-tutorial.md
 findings.md
 tutorial-state.yml
-sm-tutorial-report.md
 # tutorial outputs that may land at the root if a step forgets to clean up
 export.*
 dump.sql
@@ -569,13 +620,15 @@ dump.sql
 
 Mark `1-init: done`.
 
-### Step 2 — ⭐ Live UI: the lone agent (~1 min)
+### Step 2: ⭐ Live UI: the lone agent (~1 min)
 
 **Context**: typing `sm` alone (no arguments) in an initialised dir
-starts the UI server with the watcher built in. One process, one
+starts the UI server with the watcher built in (it is just an alias
+of `sm serve` with all defaults; the moment you need any flag
+you write `sm serve --flag ...` explicitly). One process, one
 terminal: it boots the server, scans the `.md` files, detects
 changes, and pushes events over WebSocket to the live UI. The next
-five steps (2-6) all run against the same `sm` session — you boot
+five steps (2-6) all run against the same `sm` session, you boot
 it here and keep it alive through Step 6.
 
 **Command** (one terminal):
@@ -590,7 +643,7 @@ Tell the tester:
 
 > Now arrange your screen so the **browser** (where the graph will
 > update in real time) and **this chat** are both visible at once
-> — typical layout is browser on the left half, chat on the right
+>, 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.
@@ -598,13 +651,13 @@ Tell the tester:
 > 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
+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
+> 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:
@@ -613,9 +666,9 @@ Wait for confirmation that the page loaded. Then tell the tester:
 > `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 its frontmatter (the
+> 1. **Graph**: the single agent node.
+> 2. **List**: one row, with path / kind / metadata.
+> 3. **Inspector**: click the node to see its frontmatter (the
 >    YAML block at the top of every `.md`, between the two `---`
 >    lines) and links.
 >
@@ -623,20 +676,23 @@ Wait for confirmation that the page loaded. Then tell the tester:
 
 Wait for confirmation. Mark `2-live-boot: done`.
 
-### Step 3 — Live UI: the other three kinds appear (~1 min)
+### Step 3: Live UI: the other three kinds appear (~1 min)
 
 Leave the browser open and the terminal with `sm` running. You
-create three more nodes **without any cross-fixture links**
-yet — pure standalone nodes — so the tester sees three new dots pop
-in.
+create four more nodes **without any cross-fixture links**
+yet, pure standalone nodes, so the tester sees four new dots pop
+in. Three new **kinds** show up in this step (skill, command,
+markdown), the fourth file is a second `markdown` node that the
+hub in Step 5 will point at via a real `references` link.
 
-Create these three files (with `Write`), exactly in this order.
+Create these four files (with `Write`), exactly in this order.
 Per §Provider detection, **substitute `.claude/` with the
 detected `<provider_dir>` and skip files whose kind is not in the
-provider's supported set** (`gemini`: skip `demo-command`;
-`agent-skills`: skip both `demo-agent` and `demo-command`, only
-the skill + the markdown note remain). Adjust the node count and
-the "three new nodes" message in the blockquote below accordingly:
+provider's supported set** (`gemini`: skip `demo-command`, three
+new nodes land; `agent-skills`: skip both `demo-agent` and
+`demo-command`, only the skill + the two markdown notes remain).
+Adjust the node count, the "four new nodes" message, and the file
+list shown to the tester in the sample below accordingly:
 
 1. `.claude/skills/demo-skill/SKILL.md` (kind: skill):
    ```markdown
@@ -688,7 +744,7 @@ the "three new nodes" message in the blockquote below accordingly:
    target file. Connectors land in the next sub-step.
    ```
 
-3. `notes/todo.md` — classified as `kind: markdown` today
+3. `notes/todo.md`, classified as `kind: markdown` today
    (the catch-all for `.md` files outside the
    skill / agent / command folders):
    ```markdown
@@ -696,26 +752,60 @@ the "three new nodes" message in the blockquote below accordingly:
    name: Demo TODO list
    description: |
      Live list of things to review in the demo. Will become the
-     hub between skill / agent / command in the next sub-step.
+     hub that points to the rest of the fixture in the next
+     sub-step.
    tags: [notes, demo]
    ---
 
    # Pending
    ```
 
+4. `notes/demo-guideline.md`, second `kind: markdown` node, the
+   one the hub will reach via a real markdown link in Step 5:
+   ```markdown
+   ---
+   name: demo-guideline
+   description: |
+     Static reference notes that the rest of the demo points at.
+     Showcases a second markdown node so the demo can exercise
+     the `references` link kind without ambiguity.
+   tags: [notes, demo]
+   ---
+
+   # Demo Guideline
+
+   Conventions the demo fixture follows:
+
+   - Names match the file basename.
+   - Frontmatter `description` is short and human-readable.
+   - Body stays minimal, only what's needed to teach the kind.
+   ```
+
 Tell the tester:
 
-> Look at the browser. Three new nodes should have popped in:
-> `demo-skill`, `demo-command`, and `notes/todo`. Four total now,
-> **still unconnected** — they're floating dots. The viewport
-> auto-fits whenever a node is added or removed, so all four
-> should be visible without panning.
+> Look at the browser. Four new nodes should have popped in:
+> `demo-skill`, `demo-command`, `notes/todo`, 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.
 >
-> Did the three appear? Confirm so we can wire them up.
+> What I just did behind the scenes: I created four new files in
+> your project, and the watcher picked them up on its own, that's
+> why four new dots appeared without you running anything:
+>
+> - `.claude/skills/demo-skill/SKILL.md` (kind: skill)
+> - `.claude/commands/demo-command.md` (kind: command)
+> - `notes/todo.md` (kind: markdown)
+> - `notes/demo-guideline.md` (kind: markdown)
+>
+> Same loop you'll use yourself in the next step, only this time
+> the writes came from me.
+>
+> Did the four appear? Confirm so we can wire them up.
 
 Wait for confirmation. Mark `3-live-kinds: done`.
 
-### Step 4 — Live UI: your first edit (~1 min)
+### Step 4: Live UI: your first edit (~1 min)
 
 Up to here you've been watching the agent write files. Now hand
 the keyboard over: the lesson is that the watcher reacts to
@@ -728,95 +818,103 @@ 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
+> 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** at the top of the file, change
-> the `description:` field to any text you want — the actual
+> 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 three new nodes a moment ago, this time
+> 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 four up.
+> 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. Mark `4-live-edit: done`.
 
-### Step 5 — Live UI: the connectors light up (~1 min)
+### Step 5: Live UI: the connectors light up (~1 min)
 
-Now you edit the existing files to add the cross-fixture links —
-each one becomes a connector in the graph. Apply with `Edit` (do
-not rewrite the files). Per §Provider detection, **swap `.claude/`
-for the detected `<provider_dir>` and skip any sub-step whose
-target node was not created in Step 3** (no `demo-command` on
-gemini → skip sub-step #2 and the `demo-command → demo-skill`
-connector; on agent-skills there is no agent and no command →
-keep only `notes/todo → demo-skill`):
+Now you edit `notes/todo.md` so it becomes the **hub** that points
+to each of the other four nodes. Each bullet uses a syntax that
+maps to a specific **link kind**:
 
-1. **Edit `.claude/skills/demo-skill/SKILL.md`** — append at the
-   very end:
-   ```markdown
-   When it needs to delegate heavier work it leans on the
-   [demo-agent](../../agents/demo-agent.md).
-   ```
-2. **Edit `.claude/commands/demo-command.md`** — append at the
-   very end:
-   ```markdown
-   Triggers the [demo-skill](../skills/demo-skill/SKILL.md) on the
-   given target.
-   ```
-3. **Edit `notes/todo.md`** — append this bullet after the
-   `# Pending` heading:
-   ```markdown
-   - [ ] Polish the
-         [demo-skill](../.claude/skills/demo-skill/SKILL.md)
-         prompt.
-   ```
+- an `@handle` token → kind `mentions`
+- 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).
+
+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 Step 3** (on `gemini` there is no command → skip the
+`/demo-command` bullet, three connectors land; on `agent-skills`
+there is no agent and no command → skip the `@demo-agent` and
+`/demo-command` bullets, two connectors land).
+
+**Edit `notes/todo.md`**: append these bullets after the
+`# Pending` heading:
+
+```markdown
+- [ ] Brief @demo-agent on the rough edges.
+- [ ] Run /demo-command before publishing.
+- [ ] Trigger /demo-skill when the input lands.
+- [ ] Re-read the
+      [demo-guideline](./demo-guideline.md) before shipping.
+```
 
 Tell the tester:
 
-> Look at the magic again. The four floating nodes should now be
-> wired together — connectors light
-> up between them as the watcher picks up each edit:
+> 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:
+>
+> - `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-skill → demo-agent`
-> - `demo-command → demo-skill`
-> - `notes/todo → demo-skill`
+> 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).
 >
 > Confirm. If a connector is missing, refresh the browser and tell
 > me.
 
 Wait for confirmation. **Do NOT move on to Step 6** until the
-connectors are confirmed visible — Step 6 reuses the same live UI
+connectors are confirmed visible, Step 6 reuses the same live UI
 session. Mark `5-live-connectors: done`.
 
-### Step 6 — Live UI: silence a private file via `.skillmapignore` (~2 min)
+### Step 6: Live UI: silence a private file via `.skillmapignore` (~2 min)
 
 Steps 2-5 showed the watcher picking up new files and edits (yours
 and theirs). Step 6 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.
+a single line in `.skillmapignore`. Same live mechanism, no restart.
 
 `sm init` already wrote a starter `.skillmapignore` at the scope
 root. The flow has three beats:
 
-**Beat 1 — you create one new fixture file (the agent does this).**
+**Beat 1, you create one new fixture file (the agent does this).**
 
-`Write` `notes/private-credentials.md` — kind `note`, simulates a
+`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
+  Personal API tokens, exists in the repo but should not show
   up in the skill-map graph. Demonstrates the .skillmapignore
   flow.
 ---
@@ -828,81 +926,78 @@ API_TOKEN: example-not-real
 
 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.
+other `.md`, that's the point of the demo.
 
-**Beat 2 — you show the project structure (the agent does this).**
+**Beat 2, 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:
+deeper view helps) and present the listing as a tester-facing
+message (apply the host-dependent rendering rule) so the tester
+sees what their cwd holds:
 
 > One last step. Here's what your directory looks like right now:
->
-> ```
-> .                            ← your cwd
-> ├── .claude/
-> │   ├── agents/demo-agent.md
-> │   ├── commands/demo-command.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
-> ```
->
+
+```
+.                            ← your cwd
+├── .claude/
+│   ├── agents/demo-agent.md
+│   ├── commands/demo-command.md
+│   └── skills/demo-skill/SKILL.md
+├── .skill-map/              ← project DB + settings (managed)
+├── .skillmapignore          ← the file we're about to edit
+├── notes/
+│   ├── todo.md
+│   ├── demo-guideline.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
+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 3 — the tester edits `.skillmapignore` (NOT the agent).**
+**Beat 3, the tester edits `.skillmapignore` (NOT the agent).**
 
 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:
->
-> ```
-> notes/private-*.md
-> ```
->
-> Save the file. The pattern uses a glob (same as `.gitignore`):
+> append the literal pattern `notes/private-*.md`. 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
+> (`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
-> graph in real time, without restarting anything. Five nodes
-> back to four.
+> graph in real time, without restarting anything. Six nodes
+> back to five.
 >
 > Did the node vanish?
 
 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
+`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 `6-live-ignore: done`.
 
-### Step 7 — Wrap-up of the demo and offer to keep going (30 s)
+### Step 7: 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 **~10 minutes** you've already seen the
 > full flow.
 >
-> ⚠️ **`.sm` files (heads-up for later)** — every `.md` skill-map
+> ⚠️ **`.sm` files (heads-up for later)**: every `.md` skill-map
 > tracks has a sibling `.sm` file (e.g. `demo-agent.sm` next to
 > `demo-agent.md`) that carries **all of the tool's metadata
 > about that markdown, so your `.md` stays clean and uncluttered**.
@@ -913,7 +1008,7 @@ Mark `6-live-ignore: done`.
 > refreshes one, so you'll see them often as you use skill-map
 > day to day. Commit them to git like any other source file.
 >
-> 🔀 **Multi-provider** — this demo ran with the
+> 🔀 **Multi-provider**: this demo ran with the
 > `<provider>` provider (base dir `<provider_dir>`). Skill-map
 > walks two other built-in conventions with identical mechanics:
 > Gemini lives under `.gemini/` (kinds: agent + skill), and the
@@ -927,7 +1022,7 @@ Mark `6-live-ignore: done`.
 > whenever.
 >
 > 1. **Yes, let's continue**
-> 2. **No, we wrap here** — give me the summary and tell me how to
+> 2. **No, we wrap here**: give me the summary and tell me how to
 >    delete the dir
 
 If they say **2**:
@@ -936,23 +1031,23 @@ If they say **2**:
 
 If they say **1**:
 - Mark `route.short.status: done`, `route.long.status: in_progress`.
-- Move on to the next phase (without announcing it — just say
+- Move on to the next phase (without announcing it, just say
   "Cool, keep going" and start with the level question of the next
   block).
 
 ---
 
-## DEEP-DIVE (~20-30 min) — opt-in
+## DEEP-DIVE (~20-30 min): opt-in
 
 Strictly new steps. Does not re-expand demo steps.
 
 ### Level question (one time only, on entry)
 
-> Before we keep going — how comfortable are you with the terminal?
+> Before we keep going, how comfortable are you with the terminal?
 >
-> 1. **Zero** — first time opening a console today
-> 2. **Some** — I use `git`, I can edit files, I get by
-> 3. **A lot** — I'm a dev, hand me the flags
+> 1. **Zero**: first time opening a console today
+> 2. **Some**: I use `git`, I can edit files, I get by
+> 3. **A lot**: I'm a dev, hand me the flags
 
 Save into `tester.level` and modulate:
 
@@ -964,7 +1059,7 @@ Save into `tester.level` and modulate:
 - **Level 3**: dense blocks, flags included, no explanations of
   basic concepts.
 
-### Step 8 — Tester edits live (~3 min)
+### Step 8: Tester edits live (~3 min)
 
 **Context**: Step 4 had the tester edit a scalar (`description`)
 and watch the inspector card refresh. Step 8 raises the bar: edit
@@ -974,23 +1069,26 @@ disappears). Same watcher, different surface.
 This step needs the server running. **Check first** before asking
 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 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
+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.
 
-> Your turn. Edit `.claude/skills/demo-skill/SKILL.md` with your
-> editor of choice and remove the line that links to `demo-agent.md`.
-> Save. Watch the UI.
+> Your turn. Edit `notes/todo.md` with your editor of choice and
+> delete the bullet that contains `@demo-agent`. Save. Watch the
+> UI.
 >
-> Expected: the `demo-skill → demo-agent` connector disappears in
-> real time. The two nodes stay in the graph; only the edge goes.
+> Expected: the `notes/todo → demo-agent` connector (kind:
+> `mentions`) disappears in real time. The two nodes stay in the
+> graph; only the edge goes.
 
-You verify by reading `.claude/skills/demo-skill/SKILL.md` to confirm
-the change was applied. Once they confirm, ask them to **Ctrl+C**
-the server.
+You verify by reading `notes/todo.md` to confirm the change was
+applied. (On `agent-skills`, where the `@demo-agent` bullet was
+never created in Step 5, ask the tester to remove the only bullet
+they did add and watch THAT connector vanish, the lesson is the
+same.) Once they confirm, ask them to **Ctrl+C** the server.
 
-### Step 9 — Browse CLI: list / show / check (~3 min)
+### Step 9: Browse CLI: list / show / check (~3 min)
 
 ```bash
 sm list
@@ -1001,16 +1099,17 @@ sm show .claude/skills/demo-skill/SKILL.md
 sm check
 ```
 
-Expected: you see the 4 fixture nodes listed with their kind:
+Expected: you see the 5 fixture nodes listed with their kind:
 `demo-skill` (skill), `demo-agent` (agent), `demo-command`
-(command), and `notes/todo` (`markdown`, the catch-all per
-Step 3). `check` reads the persisted
-`scan_issues` table — it does NOT re-walk the filesystem. The
+(command), `notes/todo` (`markdown`, the catch-all per
+Step 3), and `notes/demo-guideline` (`markdown` as well, the
+target of the hub's `references` link). `check` reads the persisted
+`scan_issues` table, it does NOT re-walk the filesystem. The
 fixture is clean (Steps 2-6 captured the latest state before
 Ctrl+C), so the verb prints `✓ No issues`. We will plant one in
 Step 11 and watch the rule catch it after a fresh `sm scan`.
 
-### Step 10 — ASCII: graph + export (~3 min)
+### Step 10: ASCII: graph + export (~3 min)
 
 ```bash
 sm graph
@@ -1021,17 +1120,17 @@ ls -la export*
 ```
 
 `graph` draws an ASCII tree of the whole persisted scan (no
-`--root` flag — graph is whole-graph today). `export` takes a
+`--root` flag, graph is whole-graph today). `export` takes a
 positional query (`kind=…`, `path=…`, `has=issues`, comma-OR
 within a key, AND across keys) and a `--format` of `md` or
 `json`. The `path=` glob uses POSIX semantics (`*` is one
 segment, `**` spans segments) so `path=notes/**` cleanly
 captures the notes folder regardless of the catch-all kind.
 
-### Step 11 — Issues: broken refs (~3 min)
+### Step 11: Issues: broken refs (~3 min)
 
 `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
+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".
 
@@ -1056,38 +1155,46 @@ Expected: the warning surfaces the dangling link from
 `notes/todo.md` to the non-existent `missing-page.md`. The
 `--analyzers` filter lets you focus on a single issue type; `--json`
 emits the structured payload (useful for CI / scripting). When
-done, the tester can leave the bullet in place or delete it — the
+done, the tester can leave the bullet in place or delete it, the
 rest of the deep-dive doesn't depend on it.
 
 If the tester asks about `sm orphans` vs `sm check`, see
 §Scope clarifications.
 
-### Step 12 — Plugins (~3 min)
+### Step 12: Plugins (~3 min)
 
-**Context — present plugins to the tester before any command runs.**
+**Context, present plugins to the tester before any command runs.**
 This is the official welcome to the plugin world; many testers will
 not have considered that skill-map is extensible at all. Frame it
-like this in a blockquote (translate to the tester's language per
-the standard rules):
+like this as a tester-facing message (apply the host-dependent
+rendering rule, translate to the tester's language per the
+standard rules):
 
 > Plugins are how skill-map gets extended. The kernel ships with a
 > small set of built-in plugins out of the box, but anyone can
-> write their own and drop them into the project — `sm plugins
+> write their own and drop them into the project, `sm plugins
 > create` scaffolds a manifest and the stubs, so there is no
 > handwritten boilerplate to start from.
 >
 > The kernel exposes **six** plugin types you can implement:
 >
-> - **extractors** — find links and references inside markdown.
-> - **analyzers** — rules that surface issues on a node.
-> - **actions** — verbs the user can run on a node (e.g. `bump`).
-> - **hooks** — fire on lifecycle events (scan started, finished,
+> - **extractors**: find links and references inside markdown.
+> - **analyzers**: rules that surface issues on a node.
+> - **actions**: verbs the user can run on a node (e.g. `bump`).
+> - **hooks**: fire on lifecycle events (scan started, finished,
 >   …).
-> - **formatters** — render outputs in different shapes (text,
+> - **formatters**: render outputs in different shapes (text,
 >   JSON, custom).
-> - **providers** — declare new node kinds and where to look for
+> - **providers**: declare new node kinds and where to look for
 >   them.
 >
+> Heads up: the same plugin management is in the UI too. From any
+> `sm serve` session, open the **gear icon → Plugins** tab to
+> browse and toggle plugins, CLI and UI hit the same store so a
+> change in one is reflected in the other. We'll use the CLI here
+> because it shows the full surface in a few lines, but knowing
+> the UI panel exists is useful for day-to-day work.
+>
 > Let's look at what's installed right now.
 
 Then run the commands:
@@ -1108,7 +1215,7 @@ behavior, or which id format `disable` / `enable` accept, see
 If `plugins list` shows zero entries (depends on the build), tell
 the tester no plugins are installed yet and offer to skip.
 
-### Step 13 — Annotations and the `.sm` consent prompt (~3 min)
+### Step 13: Annotations and the `.sm` consent prompt (~3 min)
 
 **Context**: every `.md` skill-map tracks gets a sibling
 **companion file** with extension `.sm` that carries **all of
@@ -1122,7 +1229,7 @@ and you'll encounter them often once you start working with
 the project.
 
 The first time skill-map wants to write one in a new project it
-asks for your consent — it never touches your filesystem without
+asks for your consent, it never touches your filesystem without
 permission. After you say yes, the choice persists per-checkout
 (gitignored) and the prompt never appears again.
 
@@ -1134,7 +1241,7 @@ sm sidecar annotate notes/todo.md
 ```
 
 Expected: a short explanation paragraph appears in the terminal,
-followed by a `[Y/n]` prompt (capital Y = default Yes — you can just
+followed by a `[Y/n]` prompt (capital Y = default Yes, you can just
 hit Enter). After accepting, `notes/todo.sm` appears next to
 `notes/todo.md` carrying an `identity:` block plus an empty
 `annotations: {}` block, and `.skill-map/settings.local.json` now
@@ -1145,7 +1252,7 @@ cat notes/todo.sm
 cat .skill-map/settings.local.json
 ```
 
-**Why the prompt?** The choice is **per-user, per-project** — stored
+**Why the prompt?** The choice is **per-user, per-project**: stored
 in the gitignored `settings.local.json` so each contributor consents
 independently and nothing about the choice travels via the repo.
 Once accepted, the flag stays set and skill-map will never ask
@@ -1161,7 +1268,7 @@ If the tester asks about `sm bump` vs `sm sidecar annotate` vs
 ## Scope clarifications (on demand)
 
 Reference material for the "mention only if the tester asks"
-beats in Steps 7, 8 and 9. Do NOT volunteer these unprompted —
+beats in Steps 7, 8 and 9. Do NOT volunteer these unprompted,
 they exist so the agent has a precise answer ready when the
 tester pulls on the thread.
 
@@ -1173,20 +1280,11 @@ tester pulls on the thread.
   detection (a node whose file disappeared, or a candidate rename
   the kernel is still unsure about). Our fixture doesn't produce
   orphans of that kind, so `sm orphans` will print "No orphan /
-  auto-rename issues" — that's expected, not a bug.
-
-### `plugins doctor` warnings on a clean fixture
-
-`doctor` may emit 1-2 informational warnings about `explorationDir`
-not existing for `gemini/gemini` (`~/.gemini`) or
-`agent-skills/agent-skills` (`.agents`). These are normal on a
-machine that has not installed those tools — the providers declare
-optional discovery paths and warn when the path is absent. Nothing
-is broken; the providers just have nothing to scan.
+  auto-rename issues", that's expected, not a bug.
 
 ### `sm plugins show <qualified-id>`
 
-The verb is informational — passing `core/external-url-counter`
+The verb is informational, passing `core/external-url-counter`
 validates the extension exists and then renders the **parent
 bundle's** detail (i.e. the full `core` listing). The extension
 you named lives in that list. This is deliberate: forcing the user
@@ -1202,7 +1300,7 @@ toggles every Claude extension at once) or a **qualified extension
 id** `<bundle>/<ext-id>` (e.g. `core/external-url-counter`). The
 display format you see in `plugins list`
 (`extractor:core/external-url-counter@1.0.0`) includes the kind
-prefix and the version for readability — strip both when passing
+prefix and the version for readability, strip both when passing
 the id to `disable` / `enable`. Per-extension toggles only work on
 extension-granularity bundles like `core`; the `claude` bundle is
 bundle-granularity and only accepts the bundle id.
@@ -1212,7 +1310,7 @@ bundle-granularity and only accepts the bundle id.
 - `sm sidecar annotate` is the scaffold verb (creates a fresh
   `.sm`).
 - `sm bump <node>` is the day-to-day verb that increments the
-  sidecar's version and refreshes its hashes — same consent gate.
+  sidecar's version and refreshes its hashes, same consent gate.
 - `sm sidecar refresh <node>` is the hash-only update (no version
   bump).
 
@@ -1220,71 +1318,27 @@ bundle-granularity and only accepts the bundle id.
 
 ## Final wrap-up
 
-When everything is done (demo only, or demo + deep-dive), **offer to
-generate a report file to send to Pusher**:
+When everything is done (demo only, or demo + deep-dive), show the
+closing block (open with a "thanks, that's a wrap" line, then the
+sm-master pointer + cleanup):
 
-> Thanks! That's a wrap. Before closing:
+> Thanks! That's a wrap.
 >
-> 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`.
+> One more thing before you go: there's a companion skill called
+> **sm-master** that picks up where this tutorial leaves off. It's
+> a modular deep-dive, you choose which areas to explore from a
+> menu, and it covers a guided tour of the built-in plugins
+> (extractors, analyzers, actions, hooks, formatters, providers).
 >
-> 1. **Yes, generate it**
-> 2. **No, I'm good**
-
-If they say **1**, write `<cwd>/sm-tutorial-report.md` with this
-template:
+> When you're ready, open a fresh empty directory and run:
 
-```markdown
-# sm-tutorial — report for Pusher
-
-- **Date**: <ISO-8601>
-- **Depth reached**: <basic | full>
-- **Tester**: level <N> (if applicable)
-- **Tutorial directory**: <cwd>
-- **Steps completed**: N / 7 demo + X / 6 deep-dive (if applicable)
-- **Steps skipped**: Y (if applicable)
-- **Total time**: ~<computed from timestamps>
-
-## Environment
-- `sm version`: <version>
-- Node: <version>
-- OS: <platform>
-
-## Findings logged
-<dump the relevant content of findings.md, without the generic header>
-
-## Additional tester notes
-<if they left free-form comments>
+```bash
+sm tutorial master
 ```
 
-Then show:
-
-> Done. The report is at:
->
->     <cwd>/sm-tutorial-report.md
->
-> Send it to Pusher whenever you're ready (over the agreed channel).
-
-If they say **2**, skip the report path and go straight to the
-closing block below.
-
-**Always show this closing block** (regardless of the report
-choice — both branches converge here):
-
-> One more thing before you go: there's a companion skill called
-> **sm-master** that picks up where this tutorial leaves off. It's
-> a modular deep-dive — you choose which areas to explore from a
-> menu — and it covers a guided tour of the built-in plugins
-> (extractors, analyzers, actions, hooks, formatters, providers),
-> plugin authoring via `sm plugins create` / `sm plugins upgrade`,
-> and settings + view-slots at depth. Same external-tester
-> audience, same pause/resume style, but a lot more ground covered.
->
-> When you're ready, **invoke it from a fresh empty directory**
-> (same setup as this tutorial), and just say `sm-master` or
-> `advanced tutorial` to start.
+> That drops `sm-master.md` in the cwd. Then load it from your
+> agent (e.g. `ejecutá @sm-master.md` in Claude Code, or the
+> equivalent `@`-mention in Gemini CLI) and the deep-dive starts.
 >
 > To delete everything THIS tutorial left behind, if the cwd was a
 > dedicated dir:
@@ -1305,7 +1359,7 @@ the cwd, start like this (do NOT repeat pre-flight from scratch):
 > 8-13)", depending on the yaml state).
 >
 > 1. **Continue** from where you left off
-> 2. **Start over** — wipes all the tutorial content in this dir
+> 2. **Start over**: wipes all the tutorial content in this dir
 >    (asks for confirmation)
 > 3. **Exit** without touching anything
 
@@ -1317,7 +1371,7 @@ anything**:
 
    > This `tutorial-state.yml` was generated for a different
    > directory (`<saved cwd>`). The current dir is `<pwd>`. I'm
-   > refusing to wipe — your `.claude/`, `notes/`, etc. here are
+   > refusing to wipe, your `.claude/`, `notes/`, etc. here are
    > probably yours, not the tutorial's. Move to `<saved cwd>` and
    > re-invoke me from there, or delete `tutorial-state.yml` by
    > hand if you really want to start fresh here.
@@ -1339,8 +1393,8 @@ anything**:
    > <provider_dir>/commands/demo-command.md      (claude only)
    > <provider_dir>/skills/demo-skill/            (all three)
    > notes/todo.md
+   > notes/demo-guideline.md
    > notes/private-credentials.md
-   > sm-tutorial-report.md   (if present)
    > export.*                (if present)
    > dump.sql                (if present)
    > ```
@@ -1354,7 +1408,7 @@ anything**:
 
 3. Only on the literal `yes, wipe` reply, delete those exact paths.
    Do NOT recursively `rm -rf` `<provider_dir>/` or `notes/` as
-   directories — only the specific tutorial-owned files inside, in
+   directories, only the specific tutorial-owned files inside, in
    case the tester has unrelated files there. After deletion, also
    `rmdir` the per-provider subdirs that actually exist
    (`<provider_dir>/agents`, `<provider_dir>/commands`,
@@ -1370,7 +1424,7 @@ anything**:
   shorthand for `sm serve` with defaults). Tell the tester to
   switch verbs: stop the failed `sm`, then run
   `sm serve --port 4243`. The browser link printed by the server
-  changes accordingly — they should open the new URL, not the
+  changes accordingly, they should open the new URL, not the
   default 4242.
 - **`sm` doesn't pick up changes on WSL** → known on WSL2 with
   files under `/mnt/c/`. Suggest exiting, running `mkdir