@skill-map/cli 0.25.0 → 0.26.1

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

@@ -51,7 +51,11 @@ must internalise before talking to the tester:
 - **Language mirroring**: if the tester's first message is in
   Spanish, run the conversation in **neutral Spanish (tú-form, not
   rioplatense)**, e.g. `puedes`, `prueba`, `mira`, NOT `podés`,
-  `probá`, `mirá`. If in English, plain English.
+  `probá`, `mirá`. If in English, plain English. Also avoid
+  overly colloquial imperatives even when they're grammatical:
+  prefer `espera` / `aguarda` over `aguanta`, `revisa` over
+  `chequea`, `observa` / `fíjate en` over `fijate`. Casual is
+  OK; slangy is not.
 - **Vocabulary translation (Spanish)**: same equivalences as
   `sm-tutorial` (`kind → tipo`, `watcher → observador`, `scan` verb
   → `escanear`, `scan` noun → `escaneo`, `node → nodo`, `link →
@@ -118,6 +122,33 @@ must internalise before talking to the tester:
    All command blocks assume the second terminal is anchored to the
    fixture folder.
 
+## Provider detection
+
+Same logic as `sm-tutorial`'s §Provider detection. Recap:
+
+| Provider       | Base dir              | Kinds claimed                | Env-var signal                                  |
+|----------------|-----------------------|------------------------------|-------------------------------------------------|
+| `claude`       | `.claude/`            | `agent`, `command`, `skill`  | `CLAUDECODE=1` OR `AI_AGENT` starts with `claude-code` |
+| `gemini`       | `.gemini/`            | `agent`, `skill`             | `GEMINI_CLI=1` OR `AI_AGENT` starts with `gemini` |
+| `agent-skills` | `.agents/skills/`     | `skill` only                 | no formal env yet, opt-in if the tester asks   |
+
+**During pre-flight**, inspect the env, pick the provider, and
+persist it into `master-state.yml.master.provider`. Fallback to
+`claude` with a one-line heads-up if nothing matched (verbatim
+fallback blockquote in `sm-tutorial`, copy it here).
+
+**Global substitution rule**: wherever this file (or any module
+file) says `.claude/<…>`, swap it for the detected
+`<provider_dir>`. Skip any fixture file or step whose kind is
+not in the provider's supported set (`gemini`: skip the
+`master-command`-style stub if a module references one;
+`agent-skills`: only the skill + the markdown note are valid).
+
+**Reality check (don't mention)**: this skill ships at
+`.claude/skills/sm-master/`, so in practice Claude Code is the
+only host today. The detection wiring is here so mirrored skills
+in `.gemini/skills/` / `.agents/skills/` reuse it as-is.
+
 ## Pre-flight
 
 ### 1. Verify the working directory (empty dir)
@@ -224,23 +255,26 @@ without further commentary:
 
 > Quick heads-up before we start: I'm about to set up the
 > scenario for this tutorial in your directory, that means
-> creating a handful of files. Hold on while I finish.
+> creating a handful of files. Please wait a moment while I finish.
 
 The fixture is **smaller than `sm-tutorial`'s** because the lessons
 focus on plugins, settings, and slots, not on graph topology. Three
 nodes are enough. Read `references/fixture-templates.md` for the
-verbatim layout and file contents, then write each of the four
-files (`master-agent`, `master-skill`, `notes/ideas`, `findings.md`)
-to the cwd. Translate the natural-language prose to the tester's
-language; keep paths, frontmatter keys, identifiers, and link
-targets in English.
+verbatim layout and file contents, then write each file to the cwd
+under the detected `<provider_dir>` (per §Provider detection).
+**Skip files whose kind is not in the provider's supported set**:
+on `gemini` keep agent + skill + note; on `agent-skills` keep only
+skill + note (no agent kind there). Translate the natural-language
+prose to the tester's language; keep paths, frontmatter keys,
+identifiers, and link targets in English.
 
 ### 4. Generate `master-state.yml`
 
 Read the `## State YAML` block at the bottom of
 `references/fixture-templates.md` and write it to
-`<cwd>/master-state.yml`. Substitute the three placeholders:
-`<ISO-8601 now>`, `<output of pwd>`, and `<output of sm version>`.
+`<cwd>/master-state.yml`. Substitute the four placeholders:
+`<ISO-8601 now>`, `<output of pwd>`, `<output of sm version>`,
+and the resolved `provider` (`claude` / `gemini` / `agent-skills`).
 
 ## Menu
 
@@ -324,6 +358,12 @@ and re-render the menu.
 
 ## Final wrap-up
 
+<!-- TODO(arquitecto): remove the "send findings to Pusher" flow from
+this tutorial. It is not part of the roadmap v1 surface and the
+Pusher hand-off should not appear in the public tester experience.
+Strip the report-to-Pusher offer, the `sm-master-report.md`
+template, and any closing copy that names Pusher. -->
+
 When the tester picks option 4 or signals they are done, **offer to
 generate a report file to send to Pusher**:
 
@@ -409,8 +449,11 @@ anything**:
    > and re-invoke me from there, or delete `master-state.yml` by
    > hand if you really want to start fresh here.
 
-2. If the cwd matches, show the exact list of paths to delete and
-   ask for the literal `yes, wipe` confirmation:
+2. If the cwd matches, read `master.provider` from the yaml and
+   use it to compute `<provider_dir>` plus the subset of files
+   actually created (gemini and agent-skills drop some). Show the
+   resolved list to the tester and ask for the literal
+   `yes, wipe` confirmation:
 
    > Start over will delete these paths from `<cwd>`:
    >
@@ -419,21 +462,25 @@ anything**:
    > findings.md
    > .skillmapignore
    > .skill-map/
-   > .claude/agents/master-agent.md
-   > .claude/skills/master-skill/
-   > .claude/plugins/                  (if any module created some)
+   > <provider_dir>/agents/master-agent.md       (claude, gemini)
+   > <provider_dir>/skills/master-skill/         (all three)
+   > .skill-map/plugins/                         (if any module created some)
    > notes/ideas.md
-   > sm-master-report.md               (if present)
+   > sm-master-report.md                         (if present)
    > ```
    >
    > Type **`yes, wipe`** (exact text) to confirm. Anything else
    > cancels.
 
+   Render the ACTUAL list (substitute `<provider_dir>` and drop
+   rows the saved provider did not create) so the tester sees real
+   paths.
+
 3. Only on the literal `yes, wipe` reply, delete those exact
-   paths. Do NOT recursively `rm -rf` `.claude/` or `notes/` as
-   directories, only the specific tutorial-owned files inside.
-   After deletion, `rmdir` empty parents silently. Then start
-   from pre-flight.
+   paths. Do NOT recursively `rm -rf` `<provider_dir>/` or
+   `notes/` as directories, only the specific tutorial-owned files
+   inside. After deletion, `rmdir` empty parents silently. Then
+   start from pre-flight.
 
 ## Edge cases
 

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

@@ -41,7 +41,11 @@ optional second phase (~20-30 min) covering the rest of the CLI.
   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`).
+  (`dale`, `bueno`, `che`, `re-`, `genial`). Also avoid overly
+  colloquial imperatives even when they're grammatical: prefer
+  `espera` / `aguarda` over `aguanta`, `revisa` over `chequea`,
+  `observa` / `fíjate en` over `fijate`. Casual is OK; slangy is
+  not.
 - 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.
@@ -67,9 +71,9 @@ optional second phase (~20-30 min) covering the rest of the CLI.
   - 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",
+  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 cuatro tipos", "skill-map detectó
+  Correct: "aparecen los otros tres tipos", "skill-map detectó
   el cambio", "vamos a escanear ahora".
 ### Silence during backstage work
 
@@ -186,6 +190,58 @@ optional second phase (~20-30 min) covering the rest of the CLI.
 11. **Never skip the level question when entering the deep-dive.**
     The level drives modulation of every Step 8+ instruction.
 
+## Provider detection
+
+Skill-map ships with three built-in providers, each one walks its
+own on-disk convention:
+
+| Provider       | Base dir              | Kinds it claims                | Detect via env var(s)                          |
+|----------------|-----------------------|--------------------------------|------------------------------------------------|
+| `claude`       | `.claude/`            | `agent`, `command`, `skill`    | `CLAUDECODE=1` OR `AI_AGENT` starts with `claude-code` |
+| `gemini`       | `.gemini/`            | `agent`, `skill`               | `GEMINI_CLI=1` OR `AI_AGENT` starts with `gemini` (any equivalent vendor var) |
+| `agent-skills` | `.agents/skills/`     | `skill` only (vendor-neutral)  | no formal env yet; treat as opt-in if the tester says so |
+
+**Decision logic, applied silently during pre-flight**:
+
+1. Inspect the agent's environment (`process.env` in your runtime).
+2. If a Claude-flavoured var is present → `provider = claude`,
+   `<provider_dir> = .claude`, supported kinds = `{agent, command,
+   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:
+
+   > Heads up: I couldn't detect which agent runtime is hosting
+   > me, so I'll demo skill-map's Claude provider (`.claude/`).
+   > If you actually use Gemini or agent-skills, tell me and I
+   > swap the fixture to `.gemini/` or `.agents/skills/`.
+
+**Reality check (do not mention to the tester unless asked)**:
+this SKILL.md lives at `.claude/skills/sm-tutorial/SKILL.md`, so
+in practice only Claude Code loads it today. The detection logic
+is wired so that the day mirrored skills land at
+`.gemini/skills/sm-tutorial/` and `.agents/skills/sm-tutorial/`,
+they reuse this same body and the fixture follows automatically.
+
+### Global substitution rule
+
+The rest of this file says `.claude/<…>` as the canonical example
+because that is the 100% case today. **Wherever you see
+`.claude/`, swap it for the detected `<provider_dir>` when writing
+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 `notes/todo → demo-command`
+connector in Step 5; on `agent-skills`, skip both `demo-agent`
+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
+re-detect.
+
 ## Pre-flight
 
 ### 1. Verify the working directory (empty dir)
@@ -318,7 +374,7 @@ 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
-> handful of files. Hold on while I finish.
+> handful of files. Please wait a moment while I finish.
 
 Then proceed straight to the writes below — no pause, no "ready?"
 prompt.
@@ -326,9 +382,9 @@ 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
-UI shows exactly one node. The other four kinds (skill, command,
-hook, note) and the connectors between all five are added later,
-one step at a time.
+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.
 
 ```
 <cwd>/
@@ -384,6 +440,7 @@ tutorial:
   started_at: "<ISO-8601 now>"
   cwd: "<output of pwd>"
   sm_version: "<output of sm version>"
+  provider: "<claude | gemini | agent-skills>"   # filled from §Provider detection
 tester:
   level: 2   # default; only asked if they advance into the deep-dive
 route:
@@ -403,7 +460,7 @@ short_steps:
     title: "⭐ Live UI: the lone agent"
     status: "pending"
   - id: "3-live-kinds"
-    title: "⭐ Live UI: the other four kinds appear"
+    title: "⭐ Live UI: the other three kinds appear"
     status: "pending"
   - id: "4-live-edit"
     title: "⭐ Live UI: your first edit"
@@ -567,14 +624,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 four 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 the four missing kinds **without any cross-fixture links**
+create four more nodes **without any cross-fixture links**
 yet — pure standalone nodes — so the tester sees four new dots pop
-in.
-
-Create these four files (with `Write`), exactly in this order:
+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 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`, 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 blockquote below accordingly:
 
 1. `.claude/skills/demo-skill/SKILL.md` (kind: skill):
    ```markdown
@@ -626,52 +692,64 @@ Create these four files (with `Write`), exactly in this order:
    target file. Connectors land in the next sub-step.
    ```
 
-3. `.claude/hooks/demo-hook.md` — **don't skip this one**, the
-   fields differ on purpose so the body reads like a real hook
-   manifest. The CLI classifies it as `kind: markdown` today
-   (the catch-all kind for `.md` files outside the
-   skill / agent / command folders); a dedicated `hook` kind
-   is on the roadmap:
+3. `notes/todo.md` — classified as `kind: markdown` today
+   (the catch-all for `.md` files outside the
+   skill / agent / command folders):
    ```markdown
    ---
-   name: demo-hook
+   name: Demo TODO list
    description: |
-     Example hook that fires when a subagent stops. Showcases the
-     `hook` kind in the demo graph.
-   event: SubagentStop
-   blocking: false
-   idempotent: true
+     Live list of things to review in the demo. Will become the
+     hub that points to the rest of the fixture in the next
+     sub-step.
+   tags: [notes, demo]
    ---
 
-   # demo-hook
-
-   Fires when a subagent terminates. Records the closure. Will get
-   wired into the rest of the fixture next.
+   # Pending
    ```
 
-4. `notes/todo.md` — also classified as `kind: markdown` today
-   (same catch-all as the hook above; a dedicated `note` kind
-   is on the roadmap):
+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 TODO list
+   name: demo-guideline
    description: |
-     Live list of things to review in the demo. Will become the
-     hub between skill / agent / command / hook in the next
-     sub-step.
+     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]
    ---
 
-   # Pending
+   # 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. 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. The viewport auto-fits whenever a node is added or
-> removed, so all five should be visible without panning.
+> `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.
+>
+> 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.
 
@@ -713,54 +791,52 @@ rule #1) before moving on. Mark `4-live-edit: done`.
 
 ### 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):
+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/agents/demo-agent.md`** — append before the
-   `Rules:` line (or at the end):
-   ```markdown
-   When the session closes, fires the
-   [demo-hook](../hooks/demo-hook.md).
-   ```
-2. **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).
-   ```
-3. **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.
-   ```
-4. **Edit `.claude/hooks/demo-hook.md`** — append at the very end:
-   ```markdown
-   See [pending items](../../notes/todo.md) for operational
-   context.
-   ```
-5. **Edit `notes/todo.md`** — append these two bullets after the
-   `# Pending` heading:
-   ```markdown
-   - [ ] Polish the
-         [demo-skill](../.claude/skills/demo-skill/SKILL.md)
-         prompt.
-   - [ ] Confirm the `event` of the
-         [demo-hook](../.claude/hooks/demo-hook.md).
-   ```
+- 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 five 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:
 >
-> - `demo-skill → demo-agent`
-> - `demo-agent → demo-hook`
-> - `demo-command → demo-skill`
-> - `demo-hook → notes/todo`
-> - `notes/todo → demo-skill`, `notes/todo → demo-hook`
+> - `notes/todo → demo-agent` (kind: `mentions`)
+> - `notes/todo → demo-command` (kind: `invokes`)
+> - `notes/todo → demo-skill` (kind: `invokes`)
+> - `notes/todo → demo-guideline` (kind: `references`)
+>
+> 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.
@@ -817,12 +893,12 @@ the tester sees what their cwd holds:
 > ├── .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
+> │   ├── demo-guideline.md
 > │   └── private-credentials.md   ← what we want to hide
 > └── sm-tutorial.md           ← the tutorial file you loaded
 > ```
@@ -875,12 +951,24 @@ Mark `6-live-ignore: done`.
 > UI sees it instantly. In **~10 minutes** you've already seen the
 > full flow.
 >
-> ⚠️ **`.sm` files (heads-up for later)** — when skill-map needs to
-> record metadata on a node, it doesn't modify the `.md` directly;
-> it creates a sibling file with `.sm` extension (e.g. `demo-agent.sm`
-> next to `demo-agent.md`). You won't see any during this demo — they
-> only appear after `sm bump` or `sm sidecar annotate`. Commit them
-> to git like any other source file.
+> ⚠️ **`.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**.
+> Version, history, tags, annotations, anything that does not
+> belong in the human-authored body lives in the `.sm`. You write
+> the `.md` for Claude or for humans, the tool writes the `.sm`.
+> Each `sm bump` and each `sm sidecar annotate` creates or
+> 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
+> `<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
+> open agent-skills standard lives under `.agents/skills/` (kind:
+> skill). Drop a `.md` in any of those and the same watcher
+> picks it up, the same connectors light up, the same rules run.
 >
 > If you want, **we can keep going deeper**: I'll walk you through
 > the CLI verbs and flags (`list`, `graph`, `export`, `orphans`,
@@ -940,16 +1028,19 @@ conditional, e.g. "If the server from Step 2 is still up, leave it
 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)
 
@@ -964,8 +1055,9 @@ sm check
 
 Expected: you see the 5 fixture nodes listed with their kind:
 `demo-skill` (skill), `demo-agent` (agent), `demo-command`
-(command), and `demo-hook` + `notes/todo` (both `markdown` —
-the catch-all per Step 3). `check` reads the persisted
+(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
@@ -1071,10 +1163,19 @@ the tester no plugins are installed yet and offer to skip.
 
 ### Step 13 — Annotations and the `.sm` consent prompt (~3 min)
 
-**Context**: skill-map keeps a small **companion file** (extension
-`.sm`) next to each `.md` to track its version, history, and tags.
-The first time skill-map wants to write one in a new project it asks
-for your consent — it never touches your filesystem without
+**Context**: every `.md` skill-map tracks gets a sibling
+**companion file** with extension `.sm` that carries **all of
+the tool's metadata about that markdown, so your `.md` stays
+clean and uncluttered**. Version, history, tags, annotations,
+anything that does not belong in the human-authored body lives
+in the `.sm`. The `.md` is content you write for Claude or
+humans; the `.sm` is bookkeeping the tool writes. They are
+ordinary source files, committed to git like everything else,
+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
 permission. After you say yes, the choice persists per-checkout
 (gitignored) and the prompt never appears again.
 
@@ -1172,6 +1273,12 @@ bundle-granularity and only accepts the bundle id.
 
 ## Final wrap-up
 
+<!-- TODO(arquitecto): remove the "send findings to Pusher" flow from
+this tutorial. It is not part of the roadmap v1 surface and the
+Pusher hand-off should not appear in the public tester experience.
+Strip the report-to-Pusher offer, the `sm-tutorial-report.md`
+template, and any closing copy that names Pusher. -->
+
 When everything is done (demo only, or demo + deep-dive), **offer to
 generate a report file to send to Pusher**:
 
@@ -1274,8 +1381,11 @@ anything**:
    > re-invoke me from there, or delete `tutorial-state.yml` by
    > hand if you really want to start fresh here.
 
-2. If the cwd matches, show the tester the exact list of paths
-   you'll delete and ask for an explicit typed confirmation:
+2. If the cwd matches, read `tutorial.provider` from the yaml and
+   use it to compute `<provider_dir>` (and the subset of files
+   actually present, since gemini and agent-skills skip some). Then
+   show the tester the exact list of paths you'll delete and ask
+   for an explicit typed confirmation:
 
    > Start over will delete these paths from `<cwd>`:
    >
@@ -1284,11 +1394,11 @@ anything**:
    > findings.md
    > .skillmapignore
    > .skill-map/
-   > .claude/agents/demo-agent.md
-   > .claude/commands/demo-command.md
-   > .claude/hooks/demo-hook.md
-   > .claude/skills/demo-skill/
+   > <provider_dir>/agents/demo-agent.md          (claude, gemini)
+   > <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)
@@ -1298,14 +1408,19 @@ anything**:
    > Type **`yes, wipe`** (exact text) to confirm. Anything else
    > cancels.
 
+   Render the ACTUAL list (substituting `<provider_dir>` and
+   dropping the rows the saved provider didn't create) so the
+   tester sees the real paths, not the abstract placeholders.
+
 3. Only on the literal `yes, wipe` reply, delete those exact paths.
-   Do NOT recursively `rm -rf` `.claude/` or `notes/` as
+   Do NOT recursively `rm -rf` `<provider_dir>/` or `notes/` as
    directories — only the specific tutorial-owned files inside, in
    case the tester has unrelated files there. After deletion, also
-   `rmdir` `.claude/agents`, `.claude/commands`, `.claude/hooks`,
-   `.claude/skills`, `notes/`, and `.claude/` if and only if they
-   are empty (silent failure if not). Then start everything from
-   pre-flight.
+   `rmdir` the per-provider subdirs that actually exist
+   (`<provider_dir>/agents`, `<provider_dir>/commands`,
+   `<provider_dir>/skills`), then `notes/` and `<provider_dir>/`,
+   each one only if empty (silent failure if not). Then start
+   everything from pre-flight.
 
 ## Edge cases