@skill-map/cli 0.43.0 → 0.45.0

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

@@ -30,7 +30,7 @@ optional second phase (~20-30 min) covering the rest of the CLI.
 > "short path", "long path", "route", "phase 1" / "phase 2", or
 > "let's start the short one" in messages to the tester. The internal
 > split exists so YOU know what comes next; for the tester you only
-> talk about the current step and, at the end of step 7 (wrap-up),
+> talk about the current step and, at the end of step 9 (wrap-up),
 > offer "if you want, we can keep going deeper" without labelling it.
 
 ## Tone
@@ -177,7 +177,7 @@ optional second phase (~20-30 min) covering the rest of the CLI.
      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
+     OF A LESSON (e.g. Step 8 hides a private node by appending
      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
@@ -204,7 +204,7 @@ optional second phase (~20-30 min) covering the rest of the CLI.
     command blocks assume the second terminal is anchored to the
     tutorial folder.
 11. **Never skip the level question when entering the deep-dive.**
-    The level drives modulation of every Step 8+ instruction.
+    The level drives modulation of every Step 10+ instruction.
 
 ## Provider detection
 
@@ -214,7 +214,7 @@ 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` |
-| `antigravity`  | none (metadata-only)  | none — Antigravity adopted the open standard, skills land under `.agents/skills/` and route through `agent-skills` | no formal env detection yet; Antigravity CLI replaced Gemini CLI on 2026-05-19 and reuses the open-standard layout, so detection collapses into the `agent-skills` row |
+| `antigravity`  | none (metadata-only)  | none, Antigravity adopted the open standard, skills land under `.agents/skills/` and route through `agent-skills` | no formal env detection yet; Antigravity CLI replaced Gemini CLI on 2026-05-19 and reuses the open-standard layout, so detection collapses into the `agent-skills` row |
 | `openai`       | `.codex/`             | `agent` (`.codex/agents/*.toml`) | no formal env detection yet; the OpenAI Codex CLI does not host this tutorial today (this SKILL.md lives under `.claude/skills/`), so the row is informational. Add when `.codex/skills/<name>/SKILL.md` mirroring lands. |
 | `agent-skills` | `.agents/skills/`     | `skill` only (vendor-neutral, also the on-disk home for Antigravity skills) | no formal env yet; treat as opt-in if the tester says so |
 
@@ -288,7 +288,9 @@ user content, they're internal infrastructure of the skill itself):
   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`.
+- `sm-tutorial.md`: legacy loose copy from older `sm tutorial`
+  runs; today the verb scaffolds `.claude/skills/sm-tutorial/`
+  (already covered by the `.claude` entry above).
 - `tutorial-state.yml`: resume mode (see §Resume / restart).
 
 The whitelist is **internal**: do NOT enumerate it to the tester.
@@ -348,7 +350,7 @@ Do not advance until the tester confirms they're in an empty dir.
 3. Even when the cwd looks filter-empty, `<provider_dir>/` may
    already contain `.md` files from a previous tutorial run, an
    experimental hook, or any other agent runtime. `sm scan` will
-   pick them up as graph nodes and break the "exactly one node"
+   pick them up as nodes in the map and break the "exactly one node"
    promise of Step 2 (and the running node count of every
    subsequent step). Run, substituting `<provider_dir>` for the
    detected base dir:
@@ -368,7 +370,7 @@ Do not advance until the tester confirms they're in an empty dir.
 > <paste the find output verbatim>
 > ```
 >
-> Those will register as graph nodes the moment `sm scan` runs,
+> Those will register as nodes in the map the moment `sm scan` runs,
 > which means the tutorial's "exactly one node" assertion in Step
 > 2 (and every running count after it) won't match what you see.
 > Two ways out:
@@ -424,7 +426,7 @@ 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 run
+> You don't have `sm` yet. You'll need Node 24+ and then run
 > `npm install -g @skill-map/cli`. Tell me "ready" when it
 > finishes.
 
@@ -437,8 +439,8 @@ Before you lay anything down, give the tester a one-shot heads-up.
 **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:
+surprised when files appear; the specifics 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
@@ -447,7 +449,7 @@ later when they're relevant. Keep it to a single short sentence:
 Then proceed straight to the writes below, no pause, no "ready?"
 prompt.
 
-The tutorial builds the graph **progressively** across Steps 2-6
+The tutorial builds the map **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 three nodes (skill, command,
@@ -554,10 +556,10 @@ tutorial-state.yml
 export.*
 dump.sql
 
-# Step 14 spawns a self-contained sub-project under link-validation/hijoA
+# Step 15 spawns a self-contained sub-project under link-validation/hijoA
 # with its own .skill-map/. Excluded here so that, if the tester
-# relaunches `sm` from the tutorial root after Step 14, the nested
-# project does not leak into the main demo graph.
+# relaunches `sm` from the tutorial root after Step 15, the nested
+# project does not leak into the main demo map.
 link-validation/
 ```
 
@@ -597,40 +599,43 @@ short_steps:
   - id: "5-live-connectors"
     title: "⭐ Live UI: the connectors light up"
     status: "pending"
-  - id: "6-live-ignore"
+  - id: "6-live-inspector"
+    title: "⭐ Live UI: the Inspector and linked nodes"
+    status: "pending"
+  - id: "7-live-edit"
+    title: "⭐ Live UI: edit a link and watch the topology change"
+    status: "pending"
+  - id: "8-live-ignore"
     title: "⭐ Live UI: silence via .skillmapignore"
     status: "pending"
-  - id: "7-handoff"
+  - id: "9-handoff"
     title: "Wrap-up of the demo and offer to keep going"
     status: "pending"
 long_steps:
-  - id: "8-tester-edits"
-    title: "Tester edits live (extends the UI demo)"
-    status: "pending"
-  - id: "9-cli-browse"
+  - id: "10-cli-browse"
     title: "Browse CLI: list / show / check"
     status: "pending"
     verbs: ["sm list", "sm show", "sm check"]
-  - id: "10-ascii"
+  - id: "11-ascii"
     title: "ASCII: graph + export"
     status: "pending"
     verbs: ["sm graph", "sm export"]
-  - id: "11-issues"
+  - id: "12-issues"
     title: "Issues: broken refs"
     status: "pending"
     verbs: ["sm check", "sm check --analyzers reference-broken",
             "sm check --json"]
-  - id: "12-plugins"
+  - id: "13-plugins"
     title: "Plugins"
     status: "pending"
     verbs: ["sm plugins list", "sm plugins show",
             "sm plugins doctor", "sm plugins enable",
             "sm plugins disable"]
-  - id: "13-annotations"
+  - id: "14-annotations"
     title: "Annotations and the .sm consent prompt"
     status: "pending"
     verbs: ["sm sidecar annotate"]
-  - id: "14-reference-paths"
+  - id: "15-reference-paths"
     title: "Validate links to folders outside the scan scope"
     status: "pending"
     verbs: ["sm config set scan.referencePaths", "sm scan", "sm check"]
@@ -725,8 +730,8 @@ 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
-it here and keep it alive through Step 6.
+seven steps (2-8) all run against the same `sm` session, you boot
+it here and keep it alive through Step 8.
 
 **Command** (one terminal):
 
@@ -738,8 +743,8 @@ Before launching, ask the tester to set up a **side-by-side view** so
 they can watch the magic happen without alt-tabbing every step.
 Tell the tester:
 
-> Now arrange your screen so the **browser** (where the graph will
-> update in real time) and **this chat** are both visible at once
+> Now arrange your screen so the **browser** (where the **Map**
+> updates in real time) and **this chat** are both visible at once
 >, typical layout is browser on the left half, chat on the right
 > (or any split that lets you see both). The terminal running
 > `sm` can stay off to the side; it just prints scan progress
@@ -752,22 +757,22 @@ them to launch the server and open the link it prints, without
 hardcoding the URL here, since the verb itself is the source of
 truth (it logs the bound `http://host:port` after listen):
 
-> In the terminal you opened for `sm`, run the command above. After
-> a couple of seconds it will print a line with the URL where the
-> UI is listening, copy that link and open it in the browser you
-> just arranged. Tell me when you see the page load.
+> Run `sm`. After a couple of seconds it will print a line with the
+> URL where the UI is listening, copy that link and open it in the
+> browser you just arranged. Tell me when you see the page load.
 
 Wait for confirmation that the page loaded. Then tell the tester:
 
-> You'll see exactly **one node** in the graph: `demo-agent` (kind
-> `agent`). That's our starting point.
+> You'll see exactly **one node** in the **Map**: `demo-agent`
+> (kind `agent`). That's our starting point.
 >
-> Walk the 3 views before we go on:
-> 1. **Graph**: the single agent node.
-> 2. **List**: one row, with path / kind / metadata.
-> 3. **Inspector**: click the node to see its frontmatter (the
->    YAML block at the top of every `.md`, between the two `---`
->    lines) and links.
+> Walk the two views before we go on:
+> 1. **Map**: the single agent node on the canvas.
+> 2. **Files**: one row, with path / kind / metadata.
+>
+> Then, back in **Map**, click the node: the **Inspector** panel
+> slides out with its frontmatter (the YAML block at the top of
+> every `.md`, between the two `---` lines) and its links.
 >
 > Did the node show up?
 
@@ -797,7 +802,7 @@ list shown to the tester in the sample below accordingly:
    name: demo-skill
    description: |
      Example skill that walks a file and returns a Markdown report.
-     Showcases the `skill` kind in the demo graph.
+     Showcases the `skill` kind in the demo map.
    inputs:
      - name: target
        type: path
@@ -908,7 +913,7 @@ Up to here you've been watching the agent write files. Now hand
 the keyboard over: the lesson is that the watcher reacts to
 **any** `.md` edit under the cwd, not just to files the agent
 authors. After this beat, the tester has the muscle memory for
-"save → graph updates", which Step 6 (`.skillmapignore`) reuses
+"save → map updates", which Step 8 (`.skillmapignore`) reuses
 verbatim.
 
 Tell the tester:
@@ -919,10 +924,10 @@ Tell the tester:
 > the field you'll edit next, so leave the card open and the
 > change will be obvious.
 >
-> ⚠ Heads-up: the inspector header shows a few action buttons
-> (Bump, Close, etc). **Don't click any of them yet** , some of
-> them write files to your project and we cover that flow
-> deliberately in step 13. For now, just look.
+> ⚠ Heads-up: the inspector header shows a couple of action
+> buttons (**Bump version**, **Refresh body**). **Don't click
+> them yet**, they write files to your project and we cover that
+> flow deliberately in step 14. For now, just look.
 >
 > Now open `.claude/agents/demo-agent.md` in your editor of
 > choice. In the **frontmatter** at the top of the file, change
@@ -943,13 +948,6 @@ rule #1) before moving on. Mark `4-live-edit: done`.
 
 ### Step 5: Live UI: the connectors light up (~2 min)
 
-Two beats. Beat 1 wires up the connectors (the arrows and their
-kinds). Beat 2 calls out the per-node ↑/↓ chips that the same hub
-edit lit up on every card. Each beat gets its own confirm so the
-tester slows down on each surface instead of conflating them.
-
-**Beat 1, connectors (the arrows themselves).**
-
 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**:
@@ -996,50 +994,76 @@ Tell the tester:
 > colours on the canvas (the two `invokes` share a colour, as you
 > would expect).
 >
-> Fijate también que los conectores tienen distinta transparencia.
-> Skill-map estima qué tan seguro está de cada conexión: un
-> `[text](file.md)` que apunta a un archivo concreto (1.00 de
-> confianza, ahora que el target existe) se ve sólido, mientras que
-> un `@handle` que no resuelve a ningún nodo se queda en 0.5
-> (ambiguo) y se ve translúcido. La opacidad cuenta esa historia de
-> un vistazo: cuanto más sólido, más confiable es la inferencia, y
-> el badge numérico arriba del conector lo dice explícito.
+> Notice too that the connectors have different transparency.
+> Skill-map estimates how sure it is of each connection: a
+> `[text](file.md)` that points at a real file (confidence 1.00,
+> now that the target exists) looks solid, while an `@handle` that
+> resolves to no node sits at 0.5 (ambiguous) and looks
+> translucent. The opacity tells that story at a glance: the more
+> solid the arrow, the more reliable the inference.
 >
-> Confirm. If a connector is missing, refresh the browser and tell
-> me.
-
-Wait for confirmation of the connectors before moving on to Beat 2.
-If a connector is missing, do not advance, the chips below depend
-on the same hub edit having landed.
-
-**Beat 2, the ↑/↓ chips on every card.**
-
-The same edit also lit up a per-node link counter on each card.
-Call it out explicitly so the tester registers the surface before
-Step 6 changes topology, easier to notice the chips going up and
-down later if they saw the baseline now.
-
-> 🆕 Mirá también las cards de los nodos: ahora cada nodo muestra
-> dos pequeñas chips abajo a la izquierda, ↑ y ↓, que cuentan los
-> links entrantes y salientes. `notes/todo` ahora marca 0↑ / 4↓
-> (es el hub que apunta a cuatro nodos), y los cuatro nodos
-> apuntados muestran 1↑ cada uno. Pasale el mouse a una chip y se
-> abre un tooltip con el desglose por kind (`mentions`, `invokes`,
-> `references`). Es la misma info que el grafo, resumida en la
-> card por si trabajás desde la list view.
+> Confirm when you see it. If a connector is missing, refresh the
+> browser and let me know.
+
+If a connector is missing, do not advance, the next step inspects
+the same hub edit. Mark `5-live-connectors: done`.
+
+### Step 6: Live UI: the Inspector and linked nodes (~1 min)
+
+The connector opacity tells the confidence story at a glance; the
+exact per-link breakdown lives in the Inspector. Open it on the hub
+so the tester registers the surface before Step 7 changes topology.
+
+> 🆕 Open the Inspector for `notes/todo` (click the node on the
+> map). Scroll down to the **Linked nodes** panel: it has two
+> sections, **Outgoing** and **Incoming**. `notes/todo` lists 4
+> links under Outgoing (it's the hub pointing at four nodes) and 0
+> under Incoming; if you open the Inspector for any of the four
+> targeted nodes, you'll see 1 under Incoming. Each row shows the
+> link kind (`mentions`, `invokes`, `references`) and a badge with
+> its confidence: the numeric value (`1.00`, `0.50`, …).
 >
-> Confirm cuando las veas en las cinco cards.
+> Let me know when you see it.
+
+After the tester confirms, drop this tip:
+
+> 💡 Tip: if all these changes left the nodes crowded together,
+> the map toolbar has a **Reset layout** button: it re-runs the
+> auto-layout so everything reads better. It asks for confirmation
+> because it discards any positions you moved by hand.
+
+Wait for confirmation. Mark `6-live-inspector: done`.
+
+### Step 7: Live UI: edit a link and watch the topology change (~3 min)
 
-Wait for confirmation. **Do NOT move on to Step 6** until both
-beats are confirmed, Step 6 reuses the same live UI session and
-the chip counts are the baseline the tester will watch change
-when the private node disappears. Mark `5-live-connectors: done`.
+**Context**: Step 4 had the tester edit a scalar (`description`)
+and watch the inspector card refresh. Step 7 raises the bar: edit
+a Markdown link and watch the MAP TOPOLOGY change (a connector
+disappears). Same watcher, different surface.
+
+The server has been live since Step 2, leave it running; this step
+and the next one (`.skillmapignore`) both reuse it.
 
-### Step 6: Live UI: silence a private file via `.skillmapignore` (~2 min)
+> 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 `notes/todo → demo-agent` connector (kind:
+> `mentions`) disappears in real time. The two nodes stay in the
+> **Map**; only the edge goes.
+
+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, leave the server running, the next step
+reuses it. Mark `7-live-edit: done`.
+
+### Step 8: 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
+and theirs). Step 8 flips the direction: a file the tester DOES NOT
+want in the map (a draft, a scratch file, a secret) gets hidden by
 a single line in `.skillmapignore`. Same live mechanism, no restart.
 
 `sm init` already wrote a starter `.skillmapignore` at the scope
@@ -1047,15 +1071,15 @@ root. The flow has three beats:
 
 **Beat 1, you create one new fixture file (the agent does this).**
 
-`Write` `notes/private-credentials.md`, kind `note`, simulates a
-file the tester would never want surfacing publicly:
+`Write` `notes/private-credentials.md`, kind `markdown`, simulates
+a file the tester would never want surfacing publicly:
 
 ```markdown
 ---
 name: private-credentials
 description: |
   Personal API tokens, exists in the repo but should not show
-  up in the skill-map graph. Demonstrates the .skillmapignore
+  up in skill-map's map. Demonstrates the .skillmapignore
   flow.
 ---
 
@@ -1064,7 +1088,7 @@ description: |
 API_TOKEN: example-not-real
 ```
 
-Confirm the file appears in the graph as a sixth node
+Confirm the file appears in the map as a sixth node
 (`notes/private-credentials`). The watcher sees it like any
 other `.md`, that's the point of the demo.
 
@@ -1084,14 +1108,15 @@ sees what their cwd holds:
 ├── .claude/
 │   ├── agents/demo-agent.md
 │   ├── commands/demo-command.md
-│   └── skills/demo-skill/SKILL.md
+│   └── skills/
+│       ├── demo-skill/SKILL.md
+│       └── sm-tutorial/SKILL.md   ← the tutorial you loaded
 ├── .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
+└── notes/
+    ├── todo.md
+    ├── demo-guideline.md
+    └── private-credentials.md   ← what we want to hide
 ```
 
 > The `.skillmapignore` at the root is the file we'll touch
@@ -1118,7 +1143,7 @@ your `Edit` tool. Tell the tester to do it from their editor:
 >
 > Watch the browser when you save. The
 > `notes/private-credentials` node should disappear from the
-> graph in real time, without restarting anything. Six nodes
+> **Map** in real time, without restarting anything. Six nodes
 > back to five.
 >
 > Did the node vanish?
@@ -1129,80 +1154,42 @@ verify the appended pattern landed correctly (in case
 allowed. Once confirmed, ask them to stop the server with
 **Ctrl+C** in the terminal before continuing.
 
-Mark `6-live-ignore: done`.
+Mark `8-live-ignore: done`.
 
-### Step 7: Wrap-up of the demo and offer to keep going (30 s)
+### Step 9: Wrap-up of the demo and offer to keep going (30 s)
+
+Keep this short: one closing line, then a single decision. Do NOT
+dump feature notes here (no `.sm` files, multi-provider, active
+provider, or safety-net asides; those land in their own steps or in
+day-to-day use). One closing line, then ask.
+
+Closing line (tester-facing):
 
 > 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
-> 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 three other built-in conventions with identical mechanics:
-> the open agent-skills standard (also used by Google's Antigravity
-> CLI, which retired Gemini CLI in May 2026) lives under
-> `.agents/skills/` (kind: skill), OpenAI Codex lives under
-> `.codex/agents/*.toml` (TOML sub-agents), and the `antigravity`
-> lens is metadata-only (no kinds of its own; selecting it just
-> tags the project as Antigravity-flavoured). Drop a `.md` (or
-> `.toml` for Codex) in any of those and the same watcher picks it
-> up, the same connectors light up, the same rules run.
->
-> 💡 **Tip avanzado (no toques si no querés rescanear)**: en
-> Settings → Project hay un dropdown **Active provider** que
-> selecciona qué lente aplica a TODO el grafo (Claude / Antigravity
-> / Codex / Cursor / agent-skills). Cambiarlo limpia el scan
-> persistido y rearma el grafo desde cero bajo el nuevo lente, así
-> que sirve cuando tu proyecto migra de runtime. Por default
-> skill-map autodetecta el lente correcto al primer scan (en este
-> caso, `claude` porque hay `.claude/`); si tu repo tiene markers
-> ambiguos (`.claude/` + `.codex/` al mismo tiempo) `sm scan` te
-> pregunta cuál usar, o aborta con exit 2 si pasás `--yes` y todavía
-> está ambiguo. El lente `antigravity` no se auto-detecta (Google
-> adoptó el open standard sin marker propio); seleccionarlo es
-> manual.
->
-> 🛡️ **Red de seguridad**: si en algún momento desactivás el bundle
-> al que apunta el lente activo (por ejemplo `sm plugins disable
-> claude` con `activeProvider: claude`), el próximo `sm scan` te
-> avisa con un warning explícito ("the active lens points at a
-> disabled bundle") y te ofrece los dos arreglos: reactivar el
-> bundle o cambiar el lente. Lo mismo si la DB local quedó vieja
-> respecto del binario, el open de SQLite detecta el skew de
-> versiones y te dice qué correr para refrescarla. Tip: si ves uno
-> de esos warnings durante el tutorial, NO los ignores, son la
-> señal de que el grafo no refleja lo que vos esperás.
->
-> If you want, **we can keep going deeper**: I'll walk you through
-> the CLI verbs and flags (`list`, `graph`, `export`, `orphans`,
-> `plugins`, `db ops`, etc.). About ~20-30 min more, pausable
-> whenever.
->
-> 1. **Yes, let's continue**
-> 2. **No, we wrap here**: give me the summary and tell me how to
->    delete the dir
+> UI reflects it instantly. In ~10 minutes you've seen the full
+> flow.
 
-If they say **2**:
-- Mark `route.short.status: done`, `route.long.status: declined`.
-- Generate the final summary (see §Final wrap-up).
+Then ask with the **`AskUserQuestion`** tool (not a numbered list),
+translating the labels to the tester's language. One question,
+header `Tutorial`, prompt "Keep going or wrap up here?", two
+options:
 
-If they say **1**:
+- **Go deeper**: the rest of the CLI, verbs and flags (`list`,
+  `export`, `plugins`, `db`, ...), about 20-30 min, pausable
+  anytime.
+- **Wrap up here**: summary plus how to delete the dir.
+
+(If the host lacks `AskUserQuestion`, fall back to a numbered list.)
+
+On **Go deeper**:
 - Mark `route.short.status: done`, `route.long.status: in_progress`.
-- Move on to the next phase (without announcing it, just say
-  "Cool, keep going" and start with the level question of the next
-  block).
+- Move to the next phase without announcing it: a short "Dale,
+  seguimos" (tester-language equivalent), then the level question
+  of the next block.
+
+On **Wrap up here**:
+- Mark `route.short.status: done`, `route.long.status: declined`.
+- Generate the final summary (see §Final wrap-up).
 
 ---
 
@@ -1228,36 +1215,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)
-
-**Context**: Step 4 had the tester edit a scalar (`description`)
-and watch the inspector card refresh. Step 8 raises the bar: edit
-a Markdown link and watch the GRAPH TOPOLOGY change (a connector
-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
-process trying to bind the same port and confusing the tester.
-
-> 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 `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 `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 10: Browse CLI: list / show / check (~3 min)
 
 ```bash
 sm list
@@ -1276,9 +1234,9 @@ 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 12 and watch the rule catch it after a fresh `sm scan`.
 
-### Step 10: ASCII: graph + export (~3 min)
+### Step 11: ASCII: graph + export (~3 min)
 
 ```bash
 sm graph
@@ -1296,11 +1254,11 @@ within a key, AND across keys) and a `--format` of `md` or
 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 12: Issues: broken refs (~3 min)
 
 `reference-broken` is one of the deterministic rules `sm check` runs.
 We'll plant one and watch it surface, that's the easiest way to
-internalise that it is an **issue** on a node, NOT a graph
+internalise that it is an **issue** on a node, NOT a
 connector and NOT the same thing as an "orphan".
 
 > ℹ️ `reference-broken` is one of ~16 built-in rules. Others surface
@@ -1331,7 +1289,7 @@ sm check --analyzers reference-broken
 sm check --json
 ```
 
-Expected: the warning surfaces the dangling link from
+Expected: the error 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
@@ -1341,7 +1299,7 @@ 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 13: Plugins (~3 min)
 
 **Context, present plugins to the tester before any command runs.**
 This is the official welcome to the plugin world; many testers will
@@ -1352,15 +1310,13 @@ 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
-> create` scaffolds a manifest and the stubs, so there is no
-> handwritten boilerplate to start from.
+> write their own and drop them into the project.
 >
 > 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`).
+> - **analyzers**: rules that detect issues on a node.
+> - **actions**: operations the user runs on a node.
 > - **hooks**: fire on lifecycle events (scan started, finished,
 >   …).
 > - **formatters**: render outputs in different shapes (text,
@@ -1368,12 +1324,9 @@ standard rules):
 > - **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.
+> Heads up: plugins can be managed from the UI as well as the CLI.
+> We'll use the CLI here because it shows the full surface in a few
+> lines.
 >
 > Let's look at what's installed right now.
 
@@ -1384,18 +1337,17 @@ sm plugins list
 sm plugins doctor
 sm plugins show core
 sm plugins disable core/external-url-counter
-sm plugins list   # confirm it shows as disabled
+sm plugins show core   # confirm it shows as disabled
 sm plugins enable core/external-url-counter
 ```
 
-If the tester asks about `plugins doctor` warnings, `plugins show`
-behavior, or which id format `disable` / `enable` accept, see
-§Scope clarifications.
+If the tester asks about `plugins doctor` warnings or `plugins show`
+behavior, see §Scope clarifications.
 
 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 14: 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
@@ -1410,8 +1362,9 @@ 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.
+permission. After you say yes, the choice is saved to the
+project's `settings.local.json` (part of your project config,
+gitignored) and the prompt never appears again.
 
 We'll demonstrate by creating an empty annotation scaffold for
 `notes/todo.md`. **Reset any prior consent state first** so the
@@ -1447,9 +1400,9 @@ goes through silently). On a CI / non-interactive session, pass
 If the tester asks about `sm bump` vs `sm sidecar annotate` vs
 `sm sidecar refresh`, see §Scope clarifications.
 
-### Step 14: Validate links to folders outside the scan scope (~4 min)
+### Step 15: Validate links to folders outside the scan scope (~4 min)
 
-**Context**: until now the graph saw only files inside the cwd. In
+**Context**: until now the map saw only files inside the cwd. In
 real projects a repo often links to files in a sibling repo (a specs
 project, a sibling package in a monorepo). Skill-map only scans from
 its cwd downwards, so a link to `../sibling/file.md` shows up as
@@ -1457,7 +1410,7 @@ broken. The fix is to declare the external folders in
 `scan.referencePaths`, which lets the `reference-broken` analyzer
 validate path-style links against those extra roots **without
 indexing their files as nodes**. The folders are checked, not walked
-as part of the graph.
+as part of the map.
 
 **Setup (you, silent)**: write the fixture under the tutorial cwd
 so both sub-projects are siblings of each other but children of the
@@ -1505,23 +1458,23 @@ Anything that hijoA points at lives here.
 
 Once the files are in place, tell the tester:
 
-> Acabo de dejar dos carpetas hermanas dentro del cwd del tutorial:
+> I just dropped two sibling folders inside the tutorial cwd:
 >
 > ```
 > link-validation/
 > ├── hijoA/
-> │   └── note-with-external-link.md   ← contiene [spec](../hijoB/spec.md)
+> │   └── note-with-external-link.md   ← contains [spec](../hijoB/spec.md)
 > └── hijoB/
->     └── spec.md                      ← el archivo target real
+>     └── spec.md                      ← the real target file
 > ```
 >
-> Para este paso vas a cambiar de carpeta momentáneamente, así `sm`
-> trata a `hijoA/` como un proyecto separado (cwd nuevo, scope
-> acotado al subárbol). Al final del paso te indico cómo volver.
+> For this step you'll switch folders for a moment, so `sm` treats
+> `hijoA/` as a separate project (new cwd, scope limited to that
+> subtree). At the end of the step I'll tell you how to come back.
 >
-> Si quedó algún `sm` corriendo de un paso anterior, ciérralo con
-> Ctrl+C así el puerto queda libre para el de este paso. Después,
-> en tu segundo terminal:
+> If an `sm` from an earlier step is still running, close it with
+> Ctrl+C so the port is free for this one. Then, in your second
+> terminal:
 
 ```bash
 cd link-validation/hijoA
@@ -1529,33 +1482,32 @@ sm init
 sm check
 ```
 
-> Vas a ver un warning del analyzer (regla que detecta problemas)
-> `reference-broken` apuntando al link `../hijoB/spec.md`. Para
-> skill-map ese archivo no existe, porque `hijoB/` queda afuera
-> del scope (alcance) que `sm` está escaneando desde `hijoA/`:
-> cada proyecto tiene su propio `.skill-map/` y solo recorre
-> desde su cwd hacia abajo, nunca para "arriba" ni hacia carpetas
-> hermanas.
+> You'll see an error from the `reference-broken` analyzer (a rule
+> that flags problems) pointing at the link `../hijoB/spec.md`. As
+> far as skill-map is concerned that file doesn't exist, because
+> `hijoB/` sits outside the scope `sm` is scanning from `hijoA/`:
+> each project has its own `.skill-map/` and only walks from its
+> cwd downwards, never "up" and never into sibling folders.
 >
-> Pásame la salida (o un OK) y seguimos con el fix.
+> Paste me the output (or just an OK) and we'll move on to the fix.
 
-Wait for confirmation before showing the fix. Mark the warning
+Wait for confirmation before showing the fix. Mark the error
 landed as expected; if the tester reports `✓ No issues` instead,
 the most likely cause is that they ran `sm check` from the
 tutorial root by mistake (the root scan still sees both folders).
 Have them re-check that the cwd of their second terminal is
 `link-validation/hijoA/` (`pwd`) and rerun.
 
-After they confirm the broken-ref warning, present the fix:
+After they confirm the broken-ref error, present the fix:
 
-> Para resolver el link sin tener que mover `hijoB/` dentro de
-> `hijoA/`, agregas `../hijoB` al setting `scan.referencePaths`.
-> Le dice al analyzer "si un link path-style cae acá, valídalo
-> también contra estas carpetas extra". Los archivos NO se
-> agregan al grafo (no aparecen como nodos), solo se consultan
-> para resolver referencias salientes desde `hijoA/`.
+> To resolve the link without moving `hijoB/` inside `hijoA/`, you
+> add `../hijoB` to the `scan.referencePaths` setting. It tells the
+> analyzer "if a path-style link lands here, validate it against
+> these extra folders too". The files are NOT added to the map
+> (they don't show up as nodes), they're only consulted to resolve
+> outgoing references from `hijoA/`.
 >
-> En tu segundo terminal (todavía dentro de `link-validation/hijoA/`):
+> In your second terminal (still inside `link-validation/hijoA/`):
 
 ```bash
 sm config set scan.referencePaths '["../hijoB"]' --yes
@@ -1563,25 +1515,25 @@ sm scan
 sm check
 ```
 
-> El flag `--yes` confirma el privacy gate (control de privacidad):
-> estás autorizando que skill-map lea archivos fuera del project
-> root, así que pide tu OK explícito. Sin `--yes` el verb se aborta
-> y te pregunta en interactivo. Después del scan, `sm check`
-> debería imprimir `✓ No issues`: el warning desapareció y `hijoB/`
-> sigue sin entrar al grafo como nodo.
+> The `--yes` flag confirms the privacy gate: you're authorizing
+> skill-map to read files outside the project root, so it asks for
+> your explicit OK. Without `--yes` the verb aborts and asks you to
+> retry with `--yes` (it does not open an interactive prompt).
+> After the scan, `sm check` should print `✓ No issues`: the error
+> is gone and `hijoB/` still hasn't entered the map as a node.
 >
-> Pásame la salida y vemos cómo quedó persistido.
+> Paste me the output and let's see how it got persisted.
 
 Wait for confirmation. After they paste the clean `sm check`
 output, show where the value lives on disk:
 
-> Mira cómo quedó guardado el cambio:
+> Look at how the change got saved:
 
 ```bash
 cat .skill-map/settings.local.json
 ```
 
-> Vas a ver algo así:
+> You'll see something like this:
 >
 > ```json
 > {
@@ -1591,50 +1543,42 @@ cat .skill-map/settings.local.json
 > }
 > ```
 >
-> Vive en `settings.local.json` (gitignored, no viaja por git),
-> NO en el `settings.json` que sí se commitea. La razón: los
-> paths a carpetas hermanas suelen depender del layout local de
-> tu máquina (no todos los contribuidores tienen el mismo árbol
-> de proyectos en disco), por eso skill-map fuerza este setting
-> al layer local.
+> It lives in `settings.local.json` (gitignored, doesn't travel
+> through git), NOT in the `settings.json` that does get committed.
+> The reason: paths to sibling folders usually depend on your
+> machine's local layout (not every contributor has the same
+> project tree on disk), so skill-map forces this setting into the
+> local layer.
 
 Now the UI half. The tester needs `sm` running with `hijoA/` as
 cwd to see the matching panel:
 
-> Lo mismo desde la UI. En el mismo terminal, levanta el servidor
-> desde `hijoA/`:
+> Now the same thing from the UI. In the same terminal, start the
+> server from `hijoA/`:
 
 ```bash
 sm
 ```
 
-> Abre la URL que imprime el comando en el browser. Arriba a la
-> derecha está el icono ⚙ (gear), haz clic ahí, en el modal ve al
-> tab **Project** y baja hasta la sección **Folders for link
-> validation**. Vas a ver `../hijoB` listado, con botones para
-> agregar o sacar paths. La CLI y la UI escriben al mismo archivo:
-> si agregas uno desde la UI, aparece en el JSON, y viceversa.
+> Open the URL the command prints in the browser. Top right there's
+> the **sliders** icon (hover shows "Settings"), click it, in the
+> modal go to the **Project** tab and scroll down to the **Folders
+> for link validation** section. You'll see `../hijoB` listed, with buttons to add or
+> remove paths. The CLI and the UI write to the same file: if you
+> add one from the UI, it shows up in the JSON, and vice versa.
 >
-> Cuando termines de mirar, Ctrl+C en el terminal para cerrar el
-> servidor.
+> When you're done looking, Ctrl+C in the terminal to close the
+> server.
 
 Wait for confirmation that they saw the panel and closed the
 server. If the `sm` launch fails with a port-in-use error, an old
 `sm` is still bound to the default port from an earlier step;
 follow the §Edge cases recipe (`sm serve --port 4243`).
 
-Finally, return the tester to the tutorial root so any wrap-up
-work runs against the original cwd:
-
-> Último detalle: vuelve al cwd raíz del tutorial:
-
-```bash
-cd ../..
-```
-
-> Confirma cuando estés de vuelta.
-
-Mark `14-reference-paths: done`.
+The tester is still inside `link-validation/hijoA/` at this point.
+Do NOT send them back here; the return-to-root `cd ../..` now lives
+in §Final wrap-up, right before the cleanup line. Mark
+`15-reference-paths: done`.
 
 ---
 
@@ -1668,23 +1612,6 @@ extension table to spot the one you queried.
 
 ### IDs for `plugins disable` / `plugins enable`
 
-Those verbs accept either a **qualified extension id**
-`<bundle>/<ext-id>` (e.g. `core/external-url-counter`,
-`claude/at-directive`) or a **bare bundle id** (e.g. `claude`,
-`core`) which the CLI treats as a macro that fans the toggle out
-across every extension inside the bundle. 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
-the id to `disable` / `enable`.
-
-Single-extension bundles (`openai`, `antigravity`,
-`agent-skills`) flip without prompting because the macro is a
-1-1 mapping. Multi-extension bundles (`claude`, `core`,
-multi-extension user plugins) need `--yes` OR an interactive TTY
-confirm; pipe / CI contexts always need `--yes` to avoid an
-accidental cascade.
-
 **Multiple ids in one call**: both verbs accept any number of ids
 in a single invocation, e.g. `sm plugins disable antigravity openai
 agent-skills` or `sm plugins enable claude/at-directive core/external-url-counter`.
@@ -1702,7 +1629,7 @@ agent reservations like `general-purpose`), `sm check` surfaces a
 files that shadow its built-ins, so the warning is not a bug,
 it's skill-map telling the operator "Claude will never invoke this
 file; pick another name". Incoming links to the shadowed file
-resolve at confidence `0.1` instead of `1.0`, so the graph also
+resolve at confidence `0.1` instead of `1.0`, so the **Map** also
 visually de-emphasises them. Rename the file and the warning
 clears on the next scan.
 
@@ -1720,10 +1647,10 @@ clears on the next scan.
 ## Final wrap-up
 
 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):
+closing block: a "that's a wrap" line, the sm-master pointer, the
+return-to-root line (deep-dive only), and a guilt-free cleanup line.
 
-> Thanks! That's a wrap.
+> Thanks! That's a wrap, you went through the whole tutorial.
 >
 > One more thing before you go: there's a companion skill called
 > **sm-master** that picks up where this tutorial leaves off. It's
@@ -1737,61 +1664,28 @@ sm-master pointer + cleanup):
 sm tutorial master
 ```
 
-> 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 Antigravity CLI) and the deep-dive starts.
+If the deep-dive ran, the tester's second terminal is still inside
+`link-validation/hijoA/` from Step 15; send them back to the
+tutorial root before the cleanup line. **Skip this whole block if
+they stopped at the demo** (they never left the root).
 
-**Cleanup, choose ONE of the two paths**. Decide programmatically
-before showing the closing message: list the cwd (`ls -A <cwd>`)
-and compare against the set of paths this tutorial owns. If the
-ONLY entries are tutorial-owned, the cwd looks dedicated and the
-bulk path is safe. If there are unrelated entries (git repo,
-unrelated source, the tester's day-to-day work), use the per-file
-path instead. **Never recommend `rm -rf <cwd>` when the cwd
-contains any path skill-map did not put there**, the tester might
-be running the tutorial inside their actual work dir (a frequent
-finding from real sessions).
+> Last thing, go back to the tutorial root:
 
-If the cwd is dedicated, render:
-
-> To delete everything THIS tutorial left behind:
->
->     cd ~ && rm -rf <cwd>
->
-> Thanks for testing skill-map!
+```bash
+cd ../..
+```
 
-If the cwd is NOT dedicated, render the exact per-file list
-(substituting `<provider_dir>` per the saved `tutorial.provider`
-and dropping rows the provider did not create, same shape as
-the "start over" branch below):
+Then close with the thanks, a guilt-free cleanup line, and the
+findings reminder. The cleanup is safe to state plainly: `sm
+tutorial` only seeds into an empty directory, so everything in the
+cwd is tutorial-created and a whole-folder delete loses nothing of
+the tester's. Substitute `<dir>` with the actual directory name.
 
-> Your cwd has unrelated files, so removing it would also delete
-> work that is not mine. To delete only what THIS tutorial left
-> behind, remove these specific paths from `<cwd>`:
->
-> ```
-> tutorial-state.yml
-> findings.md
-> .skillmapignore
-> .skill-map/
-> <provider_dir>/agents/demo-agent.md          (claude only)
-> <provider_dir>/commands/demo-command.md      (claude only)
-> <provider_dir>/skills/demo-skill/            (both providers)
-> notes/todo.md
-> notes/demo-guideline.md
-> notes/private-credentials.md
-> link-validation/                             (if Step 14 ran)
-> export.*                (if present)
-> dump.sql                (if present)
-> ```
->
-> Do NOT `rm -rf <provider_dir>/` or `notes/` as directories,
-> remove only the tutorial-owned files inside in case you have
-> unrelated files there. `link-validation/` IS safe to remove as
-> a whole directory, the agent created it from scratch in Step 14
-> and nothing else lives inside it.
->
-> Thanks for testing skill-map!
+> Thanks for testing skill-map! You started in an empty directory, so
+> everything here was created by the tutorial: when you're done you
+> can delete the whole folder guilt-free with `cd .. && rm -rf <dir>`.
+> If anything felt off in any step, tell me and I'll log it in
+> `findings.md` before you close.
 
 ## Resume / restart
 
@@ -1800,9 +1694,9 @@ the cwd, start like this (do NOT repeat pre-flight from scratch):
 
 > I see you already started the tutorial.
 >
-> You're at step <N> of 7 (or "you've already completed the demo
-> (steps 1-7) and you're on step <M> of 6 of the deep-dive (steps
-> 8-13)", depending on the yaml state).
+> You're at step <N> of 9 (or "you've already completed the demo
+> (steps 1-9) and you're on step <M> of 6 of the deep-dive (steps
+> 10-15)", depending on the yaml state).
 >
 > 1. **Continue** from where you left off
 > 2. **Start over**: wipes all the tutorial content in this dir
@@ -1841,7 +1735,7 @@ anything**:
    > notes/todo.md
    > notes/demo-guideline.md
    > notes/private-credentials.md
-   > link-validation/                             (if Step 14 ran)
+   > link-validation/                             (if Step 15 ran)
    > export.*                (if present)
    > dump.sql                (if present)
    > ```
@@ -1862,12 +1756,12 @@ anything**:
    `<provider_dir>/skills`), then `notes/` and `<provider_dir>/`,
    each one only if empty (silent failure if not). `link-validation/`
    IS safe to remove recursively when present, the agent created it
-   from scratch in Step 14 and nothing else lives inside it. Then
+   from scratch in Step 15 and nothing else lives inside it. Then
    start everything from pre-flight.
 
 ## Edge cases
 
-- **Tester doesn't have Node 20+** → guide them to `nvm` or
+- **Tester doesn't have Node 24+** → guide them to `nvm` or
   nodejs.org. Don't try to install Node for them.
 - **Port 4242 in use** → bare `sm` doesn't accept flags (it's a
   shorthand for `sm serve` with defaults). Tell the tester to