@skill-map/cli 0.36.0 → 0.38.0

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

@@ -540,6 +540,15 @@ sm-tutorial.md
 findings.md
 tutorial-state.yml
 
+# sm-tutorial / sm-master skill installations. When the tester loaded
+# the tutorial as a Claude Code (or agent-skills) project-local skill,
+# its SKILL.md lives under the project's provider dir and would
+# otherwise register as a phantom project node on the first scan.
+.claude/skills/sm-tutorial/
+.claude/skills/sm-master/
+.agents/skills/sm-tutorial/
+.agents/skills/sm-master/
+
 # Tutorial outputs that may land at the root if a step forgets to
 # clean up (sm export, sm db dump).
 export.*
@@ -917,9 +926,16 @@ Wait for confirmation. You MAY use `Read` on the file afterwards
 to verify the change landed (read-only, allowed under Inviolable
 rule #1) before moving on. Mark `4-live-edit: done`.
 
-### Step 5: Live UI: the connectors light up (~1 min)
+### Step 5: Live UI: the connectors light up (~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.
 
-Now you edit `notes/todo.md` so it becomes the **hub** that points
+**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**:
 
@@ -967,18 +983,42 @@ Tell the tester:
 >
 > 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 (95% de
-> confianza) se ve sólido, mientras que un `@handle` suelto sin
-> extensión (50%, ambiguo) se ve translúcido. La opacidad cuenta
-> esa historia de un vistazo: cuanto más sólido, más confiable es
-> la inferencia.
+> `[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.
 >
 > Confirm. If a connector is missing, refresh the browser and tell
 > me.
 
-Wait for confirmation. **Do NOT move on to Step 6** until the
-connectors are confirmed visible, Step 6 reuses the same live UI
-session. Mark `5-live-connectors: done`.
+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 cuando las veas en las cinco cards.
+
+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`.
 
 ### Step 6: Live UI: silence a private file via `.skillmapignore` (~2 min)
 
@@ -1112,9 +1152,23 @@ Mark `6-live-ignore: done`.
 > 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/`). El lente `antigravity` no
-> se auto-detecta (Google adoptó el open standard sin marker
-> propio); seleccionarlo es manual.
+> 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`,
@@ -1234,6 +1288,17 @@ We'll plant one and watch it surface, that's the easiest way to
 internalise that it is an **issue** on a node, NOT a graph
 connector and NOT the same thing as an "orphan".
 
+> ℹ️ `broken-ref` is one of ~16 built-in rules. Others surface
+> different families: `core/reserved-name` (a file shadows a vendor
+> built-in like `/help`), `core/self-loop` (a node links to itself),
+> `core/redundant-target-reference` (two surfaces in the same body
+> point at the same target), `core/signal-collision` (two extractors
+> detected the SAME byte range with different interpretations, the
+> resolver picked one and the warning explains who lost and why).
+> Same `sm check --analyzers <id>` pattern works for any of them.
+> We will not plant fixtures for the rest, the broken-ref demo
+> covers the mechanics.
+
 Ask the tester to **append one bullet** to `notes/todo.md`:
 
 ```markdown
@@ -1405,6 +1470,28 @@ the id to `disable` / `enable`. Per-extension toggles only work on
 extension-granularity bundles like `core`; the `claude` bundle is
 bundle-granularity and only accepts the bundle id.
 
+**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 core/external-url-counter`.
+Batches are all-or-nothing: if any id is unknown or
+granularity-mismatched the entire call aborts before any
+`config_plugins` write, so the user never lands in a partial state.
+Repeated ids are deduped; locked plugins inside a batch are
+silently skipped (matching `--all` semantics).
+
+### Reserved names (e.g. `commands/help.md`)
+
+If the tester ever names a file after a built-in (`/help`,
+`/clear`, `/init`, `/agents`, `/model`, or one of the documented
+agent reservations like `general-purpose`), `sm check` surfaces a
+`reserved-name` warning. The vendor runtime ignores user-owned
+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
+visually de-emphasises them. Rename the file and the warning
+clears on the next scan.
+
 ### `sm sidecar annotate` vs `sm bump` vs `sm sidecar refresh`
 
 - `sm sidecar annotate` is the scaffold verb (creates a fresh