@skill-map/cli 0.39.0 → 0.40.0

package/dist/cli/tutorial/sm-master/references/tour-authoring.md

@@ -81,10 +81,6 @@ Then narrate, one file at a time:
 > - `specCompat` / `catalogCompat`: which `sm` and plugin catalog
 >   version your plugin targets.
 >
-> - `granularity`: `'bundle'` (whole plugin enables/disables as one)
->   or `'extension'` (each extension toggles independently). The
->   scaffold picks `'bundle'`, the right default for 95% of plugins.
->
 > - `settings`: user-configurable knobs. The scaffold ships
 >   `keywords`, a `string-list` defaulting to `["TODO", "FIXME"]`.
 >   Browse other input types with `sm plugins slots list`.

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

@@ -553,6 +553,12 @@ tutorial-state.yml
 # clean up (sm export, sm db dump).
 export.*
 dump.sql
+
+# Step 14 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.
+link-validation/
 ```
 
 ### 4. Generate `tutorial-state.yml`
@@ -612,7 +618,7 @@ long_steps:
   - id: "11-issues"
     title: "Issues: broken refs"
     status: "pending"
-    verbs: ["sm check", "sm check --analyzers broken-ref",
+    verbs: ["sm check", "sm check --analyzers reference-broken",
             "sm check --json"]
   - id: "12-plugins"
     title: "Plugins"
@@ -624,6 +630,10 @@ long_steps:
     title: "Annotations and the .sm consent prompt"
     status: "pending"
     verbs: ["sm sidecar annotate"]
+  - id: "14-reference-paths"
+    title: "Validate links to folders outside the scan scope"
+    status: "pending"
+    verbs: ["sm config set scan.referencePaths", "sm scan", "sm check"]
 findings_file: "./findings.md"
 ```
 
@@ -1283,20 +1293,20 @@ captures the notes folder regardless of the catch-all kind.
 
 ### Step 11: Issues: broken refs (~3 min)
 
-`broken-ref` is one of the deterministic rules `sm check` runs.
+`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
 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
+> ℹ️ `reference-broken` is one of ~16 built-in rules. Others surface
+> different families: `core/name-reserved` (a file shadows a vendor
+> built-in like `/help`), `core/link-self-loop` (a node links to itself),
+> `core/reference-redundant` (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
+> We will not plant fixtures for the rest, the reference-broken demo
 > covers the mechanics.
 
 Ask the tester to **append one bullet** to `notes/todo.md`:
@@ -1312,7 +1322,7 @@ checking:
 ```bash
 sm scan
 sm check
-sm check --analyzers broken-ref
+sm check --analyzers reference-broken
 sm check --json
 ```
 
@@ -1428,6 +1438,195 @@ 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)
+
+**Context**: until now the graph 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
+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.
+
+**Setup (you, silent)**: write the fixture under the tutorial cwd
+so both sub-projects are siblings of each other but children of the
+tutorial root. The agent does this with `Write`, no confirmation
+beat needed, the tester learns about the files in the next message.
+
+```
+link-validation/
+├── hijoA/
+│   └── note-with-external-link.md   ← contains [spec](../hijoB/spec.md)
+└── hijoB/
+    └── spec.md                      ← the real target file
+```
+
+`link-validation/hijoA/note-with-external-link.md`:
+```markdown
+---
+name: note-with-external-link
+description: |
+  Demo note that links out to a sibling project (hijoB) sitting
+  next to this one. Used to teach scan.referencePaths.
+tags: [demo, link-validation]
+---
+
+# Note with external link
+
+See the [spec](../hijoB/spec.md) for the agreed format.
+```
+
+`link-validation/hijoB/spec.md`:
+```markdown
+---
+name: spec
+description: |
+  Target of the cross-folder link. Lives outside hijoA's scan
+  scope on purpose: that is precisely what scan.referencePaths
+  is designed to bridge.
+tags: [demo, link-validation]
+---
+
+# External spec
+
+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:
+>
+> ```
+> link-validation/
+> ├── hijoA/
+> │   └── note-with-external-link.md   ← contiene [spec](../hijoB/spec.md)
+> └── hijoB/
+>     └── spec.md                      ← el archivo target real
+> ```
+>
+> 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.
+>
+> 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:
+
+```bash
+cd link-validation/hijoA
+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.
+>
+> Pásame la salida (o un OK) y seguimos con el fix.
+
+Wait for confirmation before showing the fix. Mark the warning
+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:
+
+> 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/`.
+>
+> En tu segundo terminal (todavía dentro de `link-validation/hijoA/`):
+
+```bash
+sm config set scan.referencePaths '["../hijoB"]' --yes
+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.
+>
+> Pásame la salida y vemos cómo quedó persistido.
+
+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:
+
+```bash
+cat .skill-map/settings.local.json
+```
+
+> Vas a ver algo así:
+>
+> ```json
+> {
+>   "scan": {
+>     "referencePaths": ["../hijoB"]
+>   }
+> }
+> ```
+>
+> 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.
+
+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/`:
+
+```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.
+>
+> Cuando termines de mirar, Ctrl+C en el terminal para cerrar el
+> servidor.
+
+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`.
+
 ---
 
 ## Scope clarifications (on demand)
@@ -1460,24 +1659,30 @@ extension table to spot the one you queried.
 
 ### IDs for `plugins disable` / `plugins enable`
 
-Those verbs accept either a **bundle id** (e.g. `claude`, which
-toggles every Claude extension at once) or a **qualified extension
-id** `<bundle>/<ext-id>` (e.g. `core/external-url-counter`). The
-display format you see in `plugins list`
+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`. Per-extension toggles only work on
-extension-granularity bundles like `core`; the `claude` bundle is
-bundle-granularity and only accepts the bundle id.
+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 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).
+agent-skills` or `sm plugins enable claude/at-directive core/external-url-counter`.
+Batches are all-or-nothing: if any id is unknown the entire call
+aborts before any `config_plugins` write, so the user never lands
+in a partial state. Repeated ids are deduped; locked extensions
+inside a batch are silently skipped (matching `--all` semantics).
 
 ### Reserved names (e.g. `commands/help.md`)
 
@@ -1526,14 +1731,59 @@ 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.
->
-> To delete everything THIS tutorial left behind, if the cwd was a
-> dedicated dir:
+
+**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).
+
+If the cwd is dedicated, render:
+
+> To delete everything THIS tutorial left behind:
 >
 >     cd ~ && rm -rf <cwd>
 >
 > Thanks for testing skill-map!
 
+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):
+
+> 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!
+
 ## Resume / restart
 
 When the skill is re-invoked and `tutorial-state.yml` already exists in
@@ -1582,6 +1832,7 @@ anything**:
    > notes/todo.md
    > notes/demo-guideline.md
    > notes/private-credentials.md
+   > link-validation/                             (if Step 14 ran)
    > export.*                (if present)
    > dump.sql                (if present)
    > ```
@@ -1600,8 +1851,10 @@ anything**:
    `rmdir` the per-provider subdirs that actually exist
    (`<provider_dir>/agents`, `<provider_dir>/commands`,
    `<provider_dir>/skills`), then `notes/` and `<provider_dir>/`,
-   each one only if empty (silent failure if not). Then start
-   everything from pre-flight.
+   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
+   start everything from pre-flight.
 
 ## Edge cases