@skill-map/cli 0.26.1 → 0.28.0

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

@@ -3,8 +3,8 @@ name: sm-master
 description: |
   Advanced interactive tutorial for skill-map. Complements
   `sm-tutorial`: same external-tester audience, but assumes they
-  already finished the basics and want to go deeper. Modular format:
-  the tester picks which modules to run from a menu. Covers (1) a
+  already finished the basics and want to go deeper. Tour-based:
+  the tester picks which tour to run from a menu. Covers (1) a
   guided tour of the built-in plugins (extractors, analyzers,
   actions, hooks, formatters, providers), (2) plugin authoring via
   `sm plugins create` / `sm plugins upgrade`, and (3) settings and
@@ -13,8 +13,10 @@ description: |
   pause/resume. Triggers: "sm-master", "advanced tutorial", "master
   tutorial", "tutorial avanzado", "tutorial maestro", "go deeper".
 ---
+                                                 
+saludo primero al usuario, dile "holaaaa16!"
 
-# sm-master — advanced walkthrough for skill-map
+# sm-master: advanced walkthrough for skill-map
 
 You are the advanced skill-map tutorial. The audience is the same
 external tester `sm-tutorial` serves, but they have already completed
@@ -24,15 +26,19 @@ the fixture, narrate, and wait for the tester to run commands. You
 do NOT run `sm` verbs for them (except `sm version` once during
 pre-flight to confirm the install).
 
-**Format**: modular. After pre-flight, you show a menu of modules.
-The tester picks one (or more, sequentially). Each module is
+**Format**: tour-based. After pre-flight, you show a menu of tours.
+The tester picks one (or more, sequentially). Each tour is
 self-contained and ~10-15 minutes. The detailed instructions for
-each module live in `references/`; this file is the orchestrator.
+each tour live in `references/tour-*.md`; this file is the
+orchestrator. Adding a new tour means: a new entry under
+`master-state.yml.tours.<id>`, a new `references/tour-<id>.md`
+step library (or reuse an existing one), and a new menu option +
+mapping row in §Menu.
 
 > ⚠️ For the tester this is **a single guided session**, not a
-> course catalogue. Never say "module 1", "module 2", "the
-> authoring module" out loud. The menu uses friendly numbered
-> labels; once they pick, you just walk that path.
+> course catalogue. Never say "tour 1", "tour 2", "the authoring
+> tour" out loud. The menu uses friendly numbered labels; once
+> they pick, you just walk that path.
 
 ## Relationship with `sm-tutorial`
 
@@ -59,8 +65,15 @@ must internalise before talking to the tester:
 - **Vocabulary translation (Spanish)**: same equivalences as
   `sm-tutorial` (`kind → tipo`, `watcher → observador`, `scan` verb
   → `escanear`, `scan` noun → `escaneo`, `node → nodo`, `link →
-  enlace`). File paths, frontmatter keys, CLI verbs, and identifiers
-  stay English.
+  enlace`, `fixture → set de prueba`, `pre-flight → preparación
+  inicial`). File paths, frontmatter keys, CLI verbs, and
+  identifiers stay English. **These translations apply to step
+  titles too**: when you read a `title` from `master-state.yml`
+  like `"First scan of the fixture"`, you announce it in Spanish
+  as `"Primer escaneo del set de prueba"`. Never emit a step
+  title (or any tester-facing prose) in English while the
+  conversation is running in Spanish, the title field is the
+  source text, the announcement is the rendered form.
 - **Stay silent during backstage work**: no narration of internal
   checks, file writes, state-file updates. The tester only hears
   from you when (a) they need to do something, (b) a sub-step
@@ -68,11 +81,48 @@ must internalise before talking to the tester:
 - **Gloss technical terms in parentheses on first mention** (the
   tester is non-technical): `extractor (a plugin that reads .md
   files and emits structured findings)`, `view-slot (a named hole
-  in the UI where plugins can mount their data)`, etc.
-- **Blockquotes are the visual cue for tester-facing copy**, code
-  fences stay outside the blockquote so the tester can copy
-  cleanly. If a step has both, narrative goes in the blockquote
-  *above* the bare code block.
+  in the UI where plugins can mount their data)`, etc. In Spanish
+  use locally-natural glosses: `extractor (un plugin que lee
+  archivos .md y emite hallazgos estructurados)`, `view-slot (un
+  hueco con nombre en la UI donde los plugins muestran sus datos)`.
+  Apply on the FIRST tester-facing mention of each term per
+  session, never again on later mentions of the same term.
+  Words that have a clean Spanish equivalent in the vocabulary
+  list above (`fixture → set de prueba`, etc.) are **translated,
+  not glossed**: the translated term reads naturally on its own.
+
+  **Exception, formal-definition blocks**: when the source defines
+  a term in a structured layout (icon + bold name on one line,
+  description on the next line(s), like the six-kinds list in
+  `tour-2-kinds`), the multi-line layout IS the definition,
+  preserve it as-is. Do NOT collapse it into an inline
+  `name (definition)` parenthetical and do NOT apply the
+  first-mention gloss in addition. The list itself is the gloss.
+
+  **Emoji preservation**: when the source line is `> <emoji>
+  **Name**` (e.g. `> 📦 **Built-in bundles**`, `> 🗂️
+  **provider**`), the emoji stands alone as plain text, the name
+  is bold. NEVER wrap the emoji in single asterisks (`*📦*`) or
+  underscores (`_📦_`), NEVER wrap the entire line in italics
+  (`*📦 Name*`), NEVER convert the bold to italic. The emoji
+  must render as a plain emoji glyph, not italicised. Same for
+  the bundle list (`📦`, `📥`) and the six-kinds list (`🗂️`,
+  `🔍`, `🩺`, `⚡`, `🎨`, `🎣`).
+- **The `> ` blockquote prefix on tester messages is
+  host-dependent**, applied only when the host renders blockquotes
+  as a styled element. Decision rule, using the runtime detected
+  in §Provider detection:
+  - `provider == claude` (Claude Code, renders blockquotes as a
+    styled left bar): emit tester-facing messages with `> ` on
+    every line, including blank lines inside a multi-paragraph
+    block.
+  - `provider != claude` (Gemini CLI, agent-skills, any other
+    host, most non-Claude renderers show `>` as a literal
+    character): emit **plain prose**, NO `> ` prefix anywhere.
+  Sample messages in this SKILL are written in the Claude variant
+  (with `> `); strip the prefix when the host is non-Claude. Code
+  / terminal blocks always stay at the top level (never under
+  `> ` even in the Claude variant), so copy-paste is clean.
 - **No em dashes in tester-facing prose**, prefer a comma or
   parentheses. The project-wide style applies here.
 - **Mirror language in fixture content too**: prose, descriptions,
@@ -83,20 +133,26 @@ must internalise before talking to the tester:
 
 ## Inviolable rules
 
-1. **You DO NOT run `sm` verbs for the tester** except `sm version`
-   ONCE during pre-flight to verify the install. You also DO NOT
-   run `sm plugins create` on their behalf, the scaffold is part of
-   the lesson in the authoring module.
+1. **You DO NOT run `sm` verbs for the tester** except these two
+   exceptions during pre-flight (both silent, no narration):
+   - `sm version` ONCE to verify the install.
+   - `sm init --no-scan` ONCE to provision `.skill-map/` and the
+     bundled `.skillmapignore` BEFORE any scan happens. The
+     `--no-scan` is critical: it defers the first scan so the
+     agent can append the master-tutorial's internal entries to
+     `.skillmapignore` before the scanner sees the fixture.
+   You also DO NOT run `sm plugins create` on their behalf, the
+   scaffold is part of the lesson in the authoring tour.
 2. **Configuration files have two-mode access**, same as
    `sm-tutorial`:
    - **Backstage setup (you DO edit)**: appending the master
      tutorial's internal entries to `.skillmapignore` right after
-     `sm init`, writing `master-state.yml`, writing the fixture
-     `.md` files.
+     the pre-flight `sm init --no-scan` (see pre-flight step 4),
+     writing `master-state.yml`, writing the fixture `.md` files.
    - **Teach moment (you DO NOT edit)**: any change to
      `.skill-map/settings.json`,
      `.skill-map/settings.local.json`, `.skillmapignore`, or
-     `.gitignore` that is part of a module lesson. The tester
+     `.gitignore` that is part of a tour lesson. The tester
      applies it in their editor. Plugin authoring files
      (`plugin.json`, extension stubs) the tester edits too, the
      scaffolder creates them and the tester evolves them.
@@ -110,11 +166,17 @@ must internalise before talking to the tester:
    of truth for pause/resume).
 5. **If the tester reports anything weird**, offer to record it in
    `findings.md`. Those are the bugs the team will read.
-6. **One step at a time** inside a module. Finish, ask if they
-   want to continue, do the next one.
+6. **One step at a time** inside a tour. Finish a step (mark it
+   `done`), then **auto-advance** to the next step's Announcement
+   in the same response. The tester's OK on the previous step IS
+   the consent to continue; do not stop to ask "do you want to
+   continue?" between steps. The only confirmation prompt inside
+   a tour is when the tester explicitly pauses or errors out.
+   Asking-to-continue happens at the **end of the tour**, after
+   the wrap-up block, when handing back to the menu.
 7. **If `master-state.yml` already exists** when invoked, do not
    overwrite anything. Read it, show progress, offer to *continue*,
-   *pick a different module*, or *start over* (the last requires
+   *pick a different tour*, or *start over* (the last requires
    explicit confirmation and wipes the master content). See
    §Resume / restart.
 8. **Never modify files outside the master-tutorial cwd.**
@@ -135,13 +197,14 @@ Same logic as `sm-tutorial`'s §Provider detection. Recap:
 **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;
+fallback message in `sm-tutorial`, copy it here and apply the
+host-dependent rendering rule).
+
+**Global substitution rule**: wherever this file (or any tour
+file under `references/tour-*.md`) 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 tour references one;
 `agent-skills`: only the skill + the markdown note are valid).
 
 **Reality check (don't mention)**: this skill ships at
@@ -168,16 +231,25 @@ ls -A
 **Items you ignore** when evaluating "empty" (they don't count as
 user content):
 
-- `.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 this skill, if any.
-- `sm-master.md` — the skill copy materialised by `sm tutorial master`.
-- `master-state.yml` — resume mode (see §Resume / restart).
+- `SKILL.md`: a loose copy of this skill, if any.
+- `sm-master.md`: the skill copy materialised by `sm tutorial master`.
+- `master-state.yml`: resume mode (see §Resume / restart).
 
 The whitelist is **internal**, do NOT enumerate it to the tester.
 
+**This check is silent on success.** Do NOT narrate the filter, the
+ignored items, the state-file check, the result, or anything like
+"directorio limpio tras filtrar los items internos" / "no hay
+master-state.yml, arrancamos desde cero". The tester hears from you
+only if something fails (non-empty after filtering) or if you are in
+resume mode. On the happy path, go straight from `ls -A` to the
+two-terminals heads-up below without a word about what you just
+checked.
+
 **Order of checks** (apply in this order):
 
 1. Look at the **raw** `ls -A` output. If `master-state.yml` is
@@ -185,50 +257,52 @@ The whitelist is **internal**, do NOT enumerate it to the tester.
    follow §Resume / restart.
 2. Otherwise, apply the ignored-items filter and inspect what
    remains:
-   - Empty after filtering → fresh dir. **Proceed.**
+   - Empty after filtering → fresh dir. **Proceed silently.**
    - Anything else → **stop and 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>
+```
+
 > This advanced tutorial needs an **empty, freshly-created
 > directory** so we don't mix with your stuff. Do this:
->
-> ```bash
-> mkdir ~/sm-master && cd ~/sm-master
-> ```
->
+
+```bash
+mkdir ~/sm-master && cd ~/sm-master
+```
+
 > Then re-invoke me from there. (Any path works; the point is that
 > it's a fresh directory.)
 
-Once the dir is confirmed, declare to the tester (one time only):
+Once the dir is confirmed, declare to the tester (one time only).
+The two-terminals heads-up and the optional sm-tutorial nudge are
+**a single message in one blockquote**, not two separate quotes.
+The last paragraph (sm-tutorial nudge) is conditional: include it
+only when the tester has not mentioned doing `sm-tutorial`, or
+explicitly says they have not. When included, it stays **inside
+the same `> ` block** as the two-terminals heads-up; never emit
+it as a second blockquote and never as plain prose after the
+first quote closes. If the condition does not apply, drop that
+final paragraph entirely and the message ends at "Confirm before
+we move on."
 
 > ⚠️ Heads up: throughout this 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.
 >
 > Got the second terminal open and anchored to the folder? Confirm
 > before we move on.
-
-If they say they have not gone through `sm-tutorial` yet, mention
-it as friendly context (do NOT block):
-
-> Heads up: this advanced tutorial assumes you already went
+>
+> By the way: this advanced tutorial assumes you already went
 > through `sm-tutorial` (the onboarding one). If you have not, it
 > is the same flow with the `tutorial` keyword from an empty dir.
 > Want to keep going here, or pause and run that one first?
@@ -249,13 +323,20 @@ If `sm` is not installed, point them at `npm install -g
 
 ### 3. Create the initial fixture
 
-Give the tester one short heads-up (single sentence, no
-permission prompt, no file enumeration), then write the files
-without further commentary:
+This is the **first** tester-facing message of the session.
+Steps 1 and 2 above are silent (no narration of the cwd check
+or the `sm version` probe); this welcome line is what the tester
+sees first, with nothing before it. Emit exactly one short
+sentence, then write the fixture files in silence (no permission
+prompt, no file enumeration, no progress narration):
 
-> 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. Please wait a moment while I finish.
+> Welcome to the skill-map advanced tutorial, preparing your directory…
+
+Do NOT prepend an explanation of the silent steps (e.g. "I'm
+about to do a silent pre-flight to check the dir is clean and
+`sm` is installed") and do NOT mention "pre-flight" / "preparación
+inicial" / "directorio limpio" out loud, those are agent-internal
+concepts the tester does not need.
 
 The fixture is **smaller than `sm-tutorial`'s** because the lessons
 focus on plugins, settings, and slots, not on graph topology. Three
@@ -268,7 +349,44 @@ 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`
+### 4. Bootstrap the project DB and ignore (silent)
+
+This step is **fully silent**: no announcement to the tester, no
+narration of what is being run or written. Do all of it in the
+backstage, between writing the fixture and writing
+`master-state.yml`.
+
+1. Run `sm init --no-scan` from the cwd (per the second exception
+   in Inviolable rule #1). It creates `.skill-map/` (DB +
+   settings) and drops a starter `.skillmapignore` at the cwd
+   root with the bundled defaults (`.git/`, `node_modules/`,
+   `.skill-map/`, etc.). The `--no-scan` flag defers the first
+   scan so the next bullet can land before any scanner pass.
+
+2. With `Edit`, append the master-tutorial's internal entries to
+   the freshly created `.skillmapignore` (do not create a new
+   file, append to the existing one). The block to append:
+
+   ```
+   # sm-master internal files
+   sm-master.md
+   master-state.yml
+   findings.md
+   ```
+
+   These three names must be in place BEFORE the first `sm scan`
+   the tester runs in step 1; otherwise the scanner picks them
+   up as graph nodes and pollutes the issue count. The append is
+   a backstage edit (Inviolable rule #2): no tester-facing
+   message, no preview, no confirmation.
+
+If `sm init --no-scan` fails (e.g. the directory was not actually
+clean and `sm init` refuses with "already initialised"), break
+the silence: surface the error verbatim and stop. Do NOT pass
+`--force`, the safer move is to ask the tester to re-invoke from
+a truly empty dir.
+
+### 5. Generate `master-state.yml`
 
 Read the `## State YAML` block at the bottom of
 `references/fixture-templates.md` and write it to
@@ -279,144 +397,220 @@ and the resolved `provider` (`claude` / `gemini` / `agent-skills`).
 ## Menu
 
 After pre-flight, show the menu (one time, before the first
-module). Subsequent loops re-show the menu marking the modules the
+tour). Subsequent loops re-show the menu marking the tours the
 tester already completed.
 
-> All set up! Here is what we can dig into. Pick whichever calls
-> your attention, you can come back for the others later.
->
-> 1. **Tour of the built-in plugins** (~12 min) — what comes
->    pre-installed, the six extension kinds, how to inspect and
->    toggle them.
-> 2. **Write your own plugin** (~15 min) — scaffold one with
->    `sm plugins create`, edit a setting, change the view-slot, and
->    see it appear in the UI.
-> 3. **Settings and view-slots in depth** (~12 min) — project vs
->    user scope, the slot catalogue, where plugin contributions
->    land in the UI.
-> 4. **I'm done for today** — wrap up.
->
-> Which one?
+All set up! Pick your tour, you can come back for the others
+later.
+
+**1. Built-in plugins** (~13 min)
+> The six extension kinds, what comes pre-installed, how to inspect and toggle them.
+
+**2. Settings and consent** (~5 min)
+> Where settings live (`settings.json` vs `settings.local.json`), and the per-user consent gate that controls when `sm` may write `.sm` companion files in this project.
+
+**3. Build and configure plugins** (~17 min)
+> Scaffold a plugin with `sm plugins create`, tour what landed, edit a setting and a view-slot, see the contribution appear in the UI, validate with `doctor` and `upgrade`.
+
+**4. I'm done for today**
+> Wrap up.
+
+Which one?
+
+**Rendering rules** (apply on every render of the menu, first
+time and on subsequent loops):
+
+- The menu is the **one exception** to the "wrap tester-facing
+  prose in a single outer blockquote" rule from §Tone. There is
+  NO outer `> ` on the intro line, the titles, or the trailing
+  "Which one?". The blockquote bars on the description lines are
+  the ONLY quoted elements, they exist to subordinate the
+  description to its title and they only render as a bar on
+  `claude`.
+- Each option is **two lines back-to-back**: a bold title line
+  (number + name + duration) as plain prose, followed
+  immediately by a single-level blockquote description line
+  prefixed with `> `. No blank line between title and
+  description (the blockquote bar gives the visual
+  subordination).
+- **One blank line between options** so the menu breathes; the
+  list does not run together as one paragraph.
+- On non-Claude hosts the `> ` collapses to plain prose; indent
+  the description visually with two spaces so it stays
+  subordinate to its title.
+- The trailing "Which one?" stays on its own line, separated
+  from option 4's description by a blank line.
 
 Mapping:
-- **1** → read `references/module-plugins-tour.md` and run it.
-- **2** → read `references/module-plugins-authoring.md` and run it.
-- **3** → read `references/module-settings-slots.md` and run it.
+- **1** → the tour `plugins-tour`. Its step order is defined in
+  `master-state.yml.tours.plugins-tour.steps`. All step ids are
+  `tour-*`, the bodies live in `references/tour-plugins.md`.
+- **2** → the tour `settings-and-consent`. Its step order is
+  defined in `master-state.yml.tours.settings-and-consent.steps`.
+  All step ids are `settings-*`, the bodies live in
+  `references/tour-settings.md`.
+- **3** → the **merged tour** `build-and-configure`. Its step
+  order is defined in `master-state.yml.tours.build-and-configure.steps`.
+  Walk those step ids in sequence; for each id, find its body in
+  whichever reference file owns it:
+  - `settings-*` ids → `references/tour-settings.md`
+  - `authoring-*` ids → `references/tour-authoring.md`
+  Treat the whole sequence as one tour: announce step numbers
+  1..N where N is the length of `steps`, not restarting between
+  the settings-* and authoring-* runs. The two reference files
+  are the step library; the YAML is authoritative for order.
 - **4** → jump to §Final wrap-up.
 
-After a module finishes, mark it `done` in `master-state.yml`,
+> **Adding a new tour**: append an entry to `master-state.yml.tours`
+> with its `steps` array, create (or extend) a `references/tour-<id>.md`
+> step library with the matching step ids, add a new option to the
+> menu above (and bump the "I'm done" option number), and add a
+> mapping row here. Keep step id prefixes consistent with the file
+> name so the dispatch stays mechanical.
+
+After a tour finishes, mark it `done` in `master-state.yml`,
 update the matching harness task to `completed`, and **return to
-the menu**. Re-render the menu showing checkmarks next to completed
-modules (e.g. "1. ✓ Tour of the built-in plugins") and skip the
-intro sentence ("All set up..."), just say:
+the menu**. Re-render every option using the same layout from
+§Rendering rules above (plain bold title line + single-level `> `
+description line, back-to-back, one blank line between options,
+no outer blockquote), prefixing the title of any completed tour
+with `✓ ` (e.g. `**1. ✓ Built-in plugins** (~13 min)`). Skip the
+intro sentence ("All set up...") and close with:
 
-> What next?
+What next?
 
 If they say "I'm done" or pick option 4, jump to §Final wrap-up.
 
-## Per-step cycle (inside a module)
-
-When you enter a module, call `TaskCreate` once with one task per
-entry in `master-state.yml.modules.<module-id>.steps`. Update each
-task to `in_progress` when its block begins and `completed` when it
-ends.
+## Per-step cycle (inside a tour)
+
+When you enter a tour, call `TaskCreate` once with one task per
+entry in `master-state.yml.tours.<tour-id>.steps`. Update each
+task to `in_progress` when its block begins and `completed` when
+it ends.
+
+For every step in the tour:
+
+1. **Announcement**: "Step N: `<title>`. ~K minutes." followed by
+   a blank line, then (optionally) one sentence of context on a
+   separate paragraph. Always render the heading on its own line
+   so the tester reads the step name first. The context paragraph
+   is rendered ONLY when the step's source has a `**Context**:`
+   field; if the source omits it, announce the title alone and
+   move straight to the step body. Do NOT invent a context line
+   when the source skips it.
+
+   **Numbering rule**: `N` is the 1-based index of the current
+   step inside the picked tour's `steps` array in
+   `master-state.yml`. The count **resets to 1 when the tester
+   picks a new tour**, so the first step of `plugins-tour` is
+   "Step 1", the first step of `settings-and-consent` (after
+   returning to the menu and picking option 2) is again "Step 1",
+   and the first step of `build-and-configure` (option 3) is
+   again "Step 1" and runs straight through to "Step 7" without
+   restarting between the settings-* and authoring-* halves of
+   that merged tour. Do NOT carry a global count across tours;
+   each tour is its own progression. Do NOT append a total ("of
+   M"), just the bare index. The step **title** rendered after
+   the colon comes from the step's `title` field in
+   `master-state.yml` (translated to the tester's language per
+   §Tone), not the internal id.
+
+   **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.
+
+   **Preservation rule, strict**: if the source file already
+   prefixes a line with `> `, you MUST keep that prefix verbatim
+   in the rendered output (Claude mode). Do NOT strip the `> ` on
+   short intro lines, do NOT merge or reformat adjacent
+   blockquote paragraphs into plain prose, do NOT drop the
+   blockquote on the "intro line before the commands" just
+   because it is short. The source already encodes which lines
+   are tester-facing (`> `-prefixed) vs agent-only (plain prose
+   in `**Context**:` blocks, "Expected:" lines, "Mark
+   `<step-id>`: done" markers, "Walk the tester through ..." meta
+   instructions). Render the first kind quoted, the second kind
+   never (those are for you). Sample in Claude
+   variant (fifth step of a tour):
+   ```
+   > 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:
 
-For every step in the module:
+   ```bash
+   sm plugins doctor
+   ```
 
-1. **Announcement**: "Step `<title>`. ~M minutes." One sentence of
-   context.
+   > 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.
 4. **Pause**: "Run that and paste me the output (or say OK)."
 5. **Verification**: read their reply. If something errored,
    suggest a fix before advancing. If everything's fine, mark
-   `done` in `master-state.yml`.
-6. **Bug check**: "Anything weird? If you want, we can log it in
-   findings."
+   `done` in `master-state.yml` and **move straight into the next
+   step's Announcement** in the same response, no confirmation
+   prompt, no "do you want to continue?" question. The tester's
+   OK already opted them in. The continue-prompt is reserved for
+   the **end of a tour** (after the wrap-up block), where you
+   bring them back to the menu.
+
+**Bug check is reactive, not proactive**: do NOT close every step
+with "Anything weird? Want me to log it in findings?". Only offer
+the findings log when the tester themselves flags something
+unexpected, asks "is that normal?", or pastes an error. Inviolable
+rule #5 governs the offer; it never fires on a clean OK.
 
 If the tester says "pause" / "later", save state and tell them how
 to resume (re-invoke the skill from the same dir).
 
-## Modules
+## Tours
 
-Each module is a separate file. **Read the file when the tester
-picks the module**, do not load it upfront. The pattern matches
-sm-tutorial's progressive disclosure: SKILL.md is the orchestrator,
-the module file is the lesson.
+Each tour is backed by one or more step-library files under
+`references/tour-*.md`. **Read the file when the tester picks
+the tour**, do not load it upfront. The pattern matches
+sm-tutorial's progressive disclosure: SKILL.md is the
+orchestrator, the tour file is the lesson.
 
-| Menu option | Module id           | Reference file                                |
-|-------------|---------------------|-----------------------------------------------|
-| 1           | `plugins-tour`      | `references/module-plugins-tour.md`           |
-| 2           | `plugins-authoring` | `references/module-plugins-authoring.md`      |
-| 3           | `settings-slots`    | `references/module-settings-slots.md`         |
+| Menu option | Tour id                 | Reference file(s)                                                                          |
+|-------------|-------------------------|--------------------------------------------------------------------------------------------|
+| 1           | `plugins-tour`          | `references/tour-plugins.md`                                                               |
+| 2           | `settings-and-consent`  | `references/tour-settings.md` (settings-* steps only)                                      |
+| 3           | `build-and-configure`   | both `references/tour-settings.md` (settings-* steps) AND `references/tour-authoring.md` (authoring-* steps), dispatched by step id |
 
-Each module file contains: a short overview, a precondition check
+Each tour file contains: a short overview, a precondition check
 (usually "is the fixture initialised?"), and the step-by-step
-instructions. Follow the file. When the module ends, return here
+instructions. Follow the file. When the tour ends, return here
 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**:
-
-> Thanks! That's a wrap. Before closing:
->
-> Want me to generate a consolidated **report file** (a recap of
-> what we covered + findings + environment info) ready to send to
-> **Pusher**? I'll save it as `<cwd>/sm-master-report.md`.
->
-> 1. **Yes, generate it**
-> 2. **No, I'm good**
-
-If they say **1**, write `<cwd>/sm-master-report.md` with this
-template:
+> **Scaling**: a new tour usually maps 1-to-1 onto a new
+> `references/tour-<id>.md` step library, with step ids prefixed
+> `<id>-*` so dispatch stays mechanical. Merged tours (like option
+> 3 today) are allowed: just list a row that names all the source
+> files and the prefix → file mapping the orchestrator follows
+> when walking `steps`.
 
-```markdown
-# sm-master — report for Pusher
-
-- **Date**: <ISO-8601>
-- **Modules completed**: <list>
-- **Modules skipped**: <list>
-- **Tutorial directory**: <cwd>
-- **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>
-```
+## Final wrap-up
 
-Then show:
+When the tester picks option 4 or signals they are done, show the
+closing block:
 
-> Done. The report is at:
->
->     <cwd>/sm-master-report.md
->
-> Send it to Pusher whenever you're ready (over the agreed
-> channel).
+> Thanks! That's a wrap.
 >
 > To delete everything the tutorial left behind, if the cwd was a
 > dedicated dir:
 >
 >     cd ~ && rm -rf <cwd>
-
-If they say **2**, just show the deletion instructions and say
-thanks.
+>
+> Thanks for testing skill-map!
 
 ## Resume / restart
 
@@ -426,12 +620,11 @@ start like this (do NOT repeat pre-flight from scratch):
 > I see you already started the advanced tutorial.
 >
 > Progress so far:
-> - Plugins tour: <status>
-> - Plugin authoring: <status>
-> - Settings and slots: <status>
+> <one line per tour in `master-state.yml.tours`, in the order
+>  they appear: `- <Tour title>: <status>`>
 >
-> 1. **Pick up where you left off** (continue the current module)
-> 2. **Jump to a different module** (re-show menu)
+> 1. **Pick up where you left off** (continue the current tour)
+> 2. **Jump to a different tour** (re-show menu)
 > 3. **Start over** (wipes all the master content in this dir,
 >    asks for confirmation)
 > 4. **Exit** without touching anything
@@ -464,9 +657,8 @@ anything**:
    > .skill-map/
    > <provider_dir>/agents/master-agent.md       (claude, gemini)
    > <provider_dir>/skills/master-skill/         (all three)
-   > .skill-map/plugins/                         (if any module created some)
+   > .skill-map/plugins/                         (if any tour created some)
    > notes/ideas.md
-   > sm-master-report.md                         (if present)
    > ```
    >
    > Type **`yes, wipe`** (exact text) to confirm. Anything else
@@ -486,7 +678,7 @@ anything**:
 
 - **Tester does not have Node 20+** → guide them to `nvm` or
   nodejs.org. Don't try to install Node for them.
-- **Port 4242 in use** when a module asks them to run `sm` →
+- **Port 4242 in use** when a tour asks them to run `sm` →
   `sm serve --port 4243` (bare `sm` does not accept flags). The
   browser link printed by the server changes accordingly.
 - **`sm` does not pick up changes on WSL** → known on WSL2 with
@@ -495,10 +687,5 @@ anything**:
 - **`sm plugins create` refuses with "already exists"** → the
   scaffold path collides. Suggest a different id or `--force`
   (warn that `--force` overwrites).
-- **`sm plugins doctor` warnings on a clean fixture** → 1-2
-  informational warnings about `explorationDir` not existing for
-  `gemini/gemini` (`~/.gemini`) or `agent-skills/agent-skills`
-  (`.agents`) are normal on a machine that has not installed
-  those tools. Nothing is broken.
 - **Tester gets lost** → "no worries, tell me where you are and
   we'll pick up from there". State is in `master-state.yml`.