@skill-map/cli 0.60.4 → 0.61.1

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/es/notes/private-credentials.md

@@ -0,0 +1,11 @@
+---
+name: private-credentials
+description: |
+  Tokens de API personales, existe en el repo pero no debería
+  aparecer en el mapa de skill-map. Demuestra el flujo de
+  .skillmapignore.
+---
+
+# Privado
+
+API_TOKEN: example-not-real

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/es/notes/todo.md

@@ -0,0 +1,9 @@
+---
+name: Demo TODO list
+description: |
+  Lista en vivo de cosas para revisar en la demo. Se convertirá en
+  el hub que apunta al resto del set de prueba en el próximo
+  sub-paso.
+---
+
+# Pendientes

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/universal/en/findings.md

@@ -0,0 +1,10 @@
+# Findings: sm-tutorial
+
+If you spot anything weird during the tutorial, log it here.
+
+Per finding:
+- **Chapter**: <id>
+- **Command**: `sm ...`
+- **Expected**: ...
+- **Got**: ...
+- **Notes**: ...

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/universal/es/findings.md

@@ -0,0 +1,10 @@
+# Hallazgos: sm-tutorial
+
+Si ves algo raro durante el tutorial, anótalo aquí.
+
+Por hallazgo:
+- **Capítulo**: <id>
+- **Comando**: `sm ...`
+- **Esperado**: ...
+- **Obtenido**: ...
+- **Notas**: ...

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/universal/shared/.skillmapignore

@@ -0,0 +1,28 @@
+# Bundled defaults that matter inside the tutorial scope.
+.git/
+.skill-map/
+.tmp/
+.DS_Store
+
+# sm-tutorial internal files. Without these, the first sm init scan
+# reports the tutorial's own .md files as project nodes.
+sm-tutorial.md
+findings.md
+tutorial-state.json
+
+# sm-tutorial skill installation (loaded as a project-local skill).
+.claude/skills/sm-tutorial/
+.agents/skills/sm-tutorial/
+
+# Tutorial outputs that may land at the root.
+export.*
+dump.sql
+
+# The reference-paths chapter spawns a self-contained sub-project
+# under link-validation/hijoA with its own .skill-map/.
+link-validation/
+
+# Portfolio campaign: the Express install and the generated HTML
+# (the site output, not part of the harness graph).
+node_modules/
+public/

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

@@ -193,16 +193,22 @@ first kind quoted, the second kind never.
    `sm init` in pre-flight, the tester runs it as the first taught
    step. You also DO NOT run `sm plugins create` on their behalf;
    the scaffold is part of the authoring chapters.
-   Your responsibilities: `Write` fixture files and the state file;
-   `Edit` `.md` fixtures when a chapter calls for it (the live-UI
-   chapters need this so the watcher has something to react to);
-   `Read` files to verify what the tester modified. Everything else
-   the tester runs.
+   **The tutorial's own backstage scripts are NOT teaching `sm` verbs.**
+   `node .claude/skills/sm-tutorial/scripts/fixtures.js …` (lays /
+   seeds / clears fixtures) and `…/scripts/state.js …` (owns the state
+   file) are machinery you run silently, the same class as `Write`.
+   Your responsibilities: run those scripts to lay / seed / clear
+   fixtures and to read / update progress; `Edit` a fixture `.md` when
+   a chapter's live-UI beat needs the watcher to react, or generate
+   tester-specific content yourself when a chapter calls for it (the
+   daily loop's pages); `Read` files to verify what the tester
+   modified. Everything else the tester runs.
 2. **Configuration files have two-mode access.**
-   - **Backstage setup (you DO edit)**: writing the universal
-     `.skillmapignore` in pre-flight and appending a part's own
-     additions on entry (the portfolio's `node_modules/` / `public/`);
-     writing the state file; writing fixture `.md` files.
+   - **Backstage setup (you DO run the scripts)**: laying the
+     universal files (`.skillmapignore`, `findings.md`) and every
+     fixture via `fixtures.js`; reading / updating progress via
+     `state.js`. You never embed file content or hand-edit the state
+     file; the scripts own both.
    - **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 chapter
@@ -212,9 +218,11 @@ first kind quoted, the second kind never.
      too.
 3. **After every command block, stop and wait.** The tester pastes
    the output or replies "OK" / "done". Only then advance.
-4. **Persist progress after every chapter.** Update the state file
-   (`parts.<id>.chapters.<id>.status` = `done` / `failed` /
-   `skipped` + a timestamp). The state file is the ONLY progress
+4. **Persist progress after every chapter** by running
+   `node .claude/skills/sm-tutorial/scripts/state.js mark <part> <chapter> done|failed|skipped`.
+   The script owns `tutorial-state.json` (stamps the timestamp and
+   auto-promotes the part to `done` when its last chapter lands);
+   never hand-edit the file. The state file is the ONLY progress
    tracker. Do NOT create harness tasks (`TaskCreate` / `TaskUpdate`)
    for tutorial progress, they clutter the tester's task list and add
    nothing the state file does not already hold.
@@ -233,9 +241,9 @@ first kind quoted, the second kind never.
    per exchange, `auto-advance` may chain chapters that need no tester
    action; neither asks "¿seguimos?".)
 7. **If the state file already exists** when invoked, do not
-   overwrite anything. Read it, show progress, offer to continue,
-   pick another part, or start over (the last requires explicit
-   confirmation, see §Resume / restart).
+   overwrite anything. Run `state.js status`, show progress, offer to
+   continue, pick another part, or start over (the last requires
+   explicit confirmation, see §Resume / restart).
 8. **Never modify files outside the tutorial cwd.**
 9. **Never ask the tester to `cd` outside the tutorial cwd.** All
    command blocks assume the second terminal is anchored to the
@@ -272,12 +280,18 @@ on-disk convention:
 Persist `provider` into the state file (`tutorial.provider`) so a
 resumed session does not re-detect.
 
-**Global substitution rule**: wherever a part 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** (on
-`agent-skills` / Antigravity: only the skill + markdown notes are
-valid; drop agent + command files and the connectors that target
-them, and adjust node counts accordingly).
+**Global substitution rule**: the fixture scripts do the file-level
+work. You pass `--provider <p>` (the value persisted in
+`tutorial.provider`) and `--lang <l>`, and they resolve the
+`__PROVIDER__` path token, skip files whose kind the provider does
+not claim, and report the adjusted `nodeCount` plus the `skipped`
+list in their summary. Your job is the **narration**: wherever a part
+file's tester-facing prose says `.claude/`, swap it for the detected
+`<provider_dir>`, and narrate the node count from the script summary
+(on `agent-skills` / Antigravity only the skill + markdown notes
+exist, so the count is lower and the agent / command beats fold
+away). The campaign cross-link chapters target `claude` today (see
+the reality check below).
 
 **Reality check (don't mention to the tester)**: this skill ships
 at `.claude/skills/sm-tutorial/`, so Claude Code is the only host
@@ -324,6 +338,11 @@ For every chapter:
    Inviolable rule #6, NO "¿seguimos?"). `pace` only decides batching:
    `per-step` presents one chapter per exchange, `auto-advance` may
    chain chapters that need no tester action into one response.
+   **Either pace still emits every chapter's `Capítulo S.N` Announcement
+   (step 1).** `auto-advance` drops only the inter-chapter "¿seguimos?"
+   pause, never the per-chapter announcement, so any chapter with a
+   tester-facing beat always opens with its number, even when it
+   follows straight on from the previous one.
 
 ## Routing + menu (orchestrator)
 
@@ -429,25 +448,26 @@ the title stays plain):
 ## Resume / restart
 
 When re-invoked and the state file already exists, do NOT repeat
-pre-flight from scratch. Show progress (one line per part with its
-status) and offer: **continue** the current part, **pick another
-part** (re-show the ToC), **start over** (wipes the tutorial
-content, asks for confirmation), or **exit**.
-
-On **start over**, before deleting anything:
-
-1. Read `tutorial.cwd` from the state file and compare with `pwd`.
-   If they differ, **refuse** and tell the tester to move to the
-   saved cwd or delete the state file by hand (their `.claude/`,
-   `notes/`, etc. here are probably theirs, not the tutorial's).
-2. If the cwd matches, read `tutorial.provider`, compute
-   `<provider_dir>` + the subset of files actually created, show
-   the exact list of paths you'll delete, and require the literal
-   typed confirmation `yes, wipe`.
-3. Only on `yes, wipe`, delete those exact paths (do NOT `rm -rf`
-   `<provider_dir>/` or `notes/` as directories, only the specific
-   tutorial-owned files inside; `rmdir` empty parents silently).
-   Then start from pre-flight.
+pre-flight from scratch. Run
+`node .claude/skills/sm-tutorial/scripts/state.js status` and render
+progress from its `parts[]` (one line per part with its status), then
+offer: **continue** the current part, **pick another part** (re-show
+the ToC), **start over** (wipes the tutorial content, asks for
+confirmation), or **exit**.
+
+On **start over**, the script owns the path computation and the cwd
+safety check:
+
+1. Run `state.js wipe-list`. It re-checks `tutorial.cwd` against the
+   current dir and returns a `cwd-mismatch` error if they differ;
+   surface that refusal (tell the tester to move to the saved cwd or
+   delete `tutorial-state.json` by hand, their `.claude/`, `notes/`,
+   etc. here are probably theirs).
+2. Show the returned `paths` and require the literal typed
+   confirmation `yes, wipe`.
+3. Only on `yes, wipe`, run `state.js wipe --confirm` (it deletes
+   exactly those paths and `rmdir`s empty parents, never a whole user
+   dir). Then start from pre-flight.
 
 ## Edge cases
 

package/dist/cli/tutorial/sm-tutorial/references/_manifest.json

@@ -0,0 +1,304 @@
+{
+  "parts": [
+    {
+      "id": "fundamentals",
+      "order": 0,
+      "title": "The live map (prologue)",
+      "status": "active",
+      "preflight": "taught-init",
+      "seed": null,
+      "prereq": null,
+      "pace": "per-step",
+      "chapters": [
+        {
+          "id": "init",
+          "title": "Your first node (sm init, sm, the UI)",
+          "est_min": 2
+        },
+        {
+          "id": "kinds",
+          "title": "The other kinds appear",
+          "est_min": 1
+        },
+        {
+          "id": "first-edit",
+          "title": "Your first edit (the watcher reacts)",
+          "est_min": 1
+        },
+        {
+          "id": "connectors",
+          "title": "The connectors light up",
+          "est_min": 2
+        },
+        {
+          "id": "inspector",
+          "title": "The inspector and connections",
+          "est_min": 1
+        },
+        {
+          "id": "edit-link",
+          "title": "Edit a link, the topology changes",
+          "est_min": 3
+        },
+        {
+          "id": "workspace",
+          "title": "Navigate the workspace (files, search, isolate)",
+          "est_min": 2
+        },
+        {
+          "id": "ignore",
+          "title": "Silence a file via .skillmapignore",
+          "est_min": 2
+        }
+      ]
+    },
+    {
+      "id": "project-kickoff",
+      "order": 1,
+      "title": "The project from zero",
+      "status": "active",
+      "preflight": "portfolio-init",
+      "seed": null,
+      "prereq": null,
+      "pace": "per-step",
+      "chapters": [
+        {
+          "id": "kickoff",
+          "title": "Start the portfolio (sm init on the real skeleton)",
+          "est_min": 2
+        },
+        {
+          "id": "manual",
+          "title": "The handbook (AGENTS.md) and CLAUDE.md",
+          "est_min": 2
+        },
+        {
+          "id": "first-agent",
+          "title": "The first harness agent (content-editor)",
+          "est_min": 2
+        },
+        {
+          "id": "real-kinds",
+          "title": "The real kinds in context",
+          "est_min": 2
+        }
+      ]
+    },
+    {
+      "id": "connect-harness",
+      "order": 2,
+      "title": "Connect the harness",
+      "status": "active",
+      "preflight": "seed",
+      "seed": "harness-built",
+      "prereq": "project-kickoff",
+      "pace": "auto-advance",
+      "chapters": [
+        {
+          "id": "check-links",
+          "title": "The check-links skill",
+          "est_min": 2
+        },
+        {
+          "id": "publish",
+          "title": "The /publish command invokes the skill",
+          "est_min": 3
+        },
+        {
+          "id": "links",
+          "title": "Mentions (@) and references between assets",
+          "est_min": 3
+        },
+        {
+          "id": "confidence",
+          "title": "Connector confidence (opacity = certainty)",
+          "est_min": 2
+        }
+      ]
+    },
+    {
+      "id": "daily-loop",
+      "order": 3,
+      "title": "The daily loop (add, improve, publish)",
+      "status": "active",
+      "preflight": "seed",
+      "seed": "harness-connected",
+      "prereq": "connect-harness",
+      "pace": "auto-advance",
+      "chapters": [
+        {
+          "id": "setup",
+          "title": "Make it yours, make it presentable",
+          "est_min": 3
+        },
+        {
+          "id": "preview",
+          "title": "Bring it up and see your site",
+          "est_min": 2
+        },
+        {
+          "id": "add-page",
+          "title": "Add a page with your agent",
+          "est_min": 4
+        },
+        {
+          "id": "broken-ref",
+          "title": "A rename breaks a link",
+          "est_min": 4
+        },
+        {
+          "id": "reserved",
+          "title": "A reserved name collides",
+          "est_min": 2
+        },
+        {
+          "id": "publish",
+          "title": "Ship it: run /publish for real",
+          "est_min": 4
+        },
+        {
+          "id": "stability",
+          "title": "Set a node's stability (and the `.sm` sidecar)",
+          "est_min": 3
+        },
+        {
+          "id": "golive",
+          "title": "Your portfolio, live next to the graph",
+          "est_min": 3
+        }
+      ]
+    },
+    {
+      "id": "extend",
+      "order": 4,
+      "title": "Extend skill-map for the site",
+      "status": "active",
+      "preflight": "backstage-init",
+      "seed": null,
+      "prereq": null,
+      "pace": "auto-advance",
+      "chapters": [
+        {
+          "id": "settings-1-layers",
+          "title": "The config layers and `sm config list`",
+          "est_min": 3
+        },
+        {
+          "id": "settings-2-resolve",
+          "title": "Read, resolve, and set a value with `sm config`",
+          "est_min": 3
+        },
+        {
+          "id": "settings-3-lens",
+          "title": "The active provider lens (`activeProvider`)",
+          "est_min": 4
+        },
+        {
+          "id": "tour-1-intro",
+          "title": "How plugins work",
+          "est_min": 4
+        },
+        {
+          "id": "tour-2-kinds",
+          "title": "The six extension kinds",
+          "est_min": 5
+        },
+        {
+          "id": "tour-3-explore",
+          "title": "Explore one extension up close",
+          "est_min": 4
+        },
+        {
+          "id": "authoring-1-scaffold",
+          "title": "`sm plugins create demo-highlight`",
+          "est_min": 2
+        },
+        {
+          "id": "authoring-2-anatomy",
+          "title": "Tour the scaffold (plugin.json + stubs + README)",
+          "est_min": 3
+        },
+        {
+          "id": "authoring-3-edit-setting",
+          "title": "Edit a setting (string-list) and observe it in the UI",
+          "est_min": 3
+        },
+        {
+          "id": "authoring-4-edit-slot",
+          "title": "Change the view-slot the contribution targets",
+          "est_min": 2
+        },
+        {
+          "id": "settings-6-contributions",
+          "title": "Watch contributions land in the inspector",
+          "est_min": 2
+        },
+        {
+          "id": "authoring-5-doctor-author",
+          "title": "Catch a manifest mistake with `sm plugins doctor`",
+          "est_min": 2
+        },
+        {
+          "id": "authoring-6-upgrade",
+          "title": "Try `sm plugins upgrade`",
+          "est_min": 2
+        }
+      ]
+    },
+    {
+      "id": "cli",
+      "order": 5,
+      "title": "The CLI in depth",
+      "status": "active",
+      "preflight": "seed",
+      "seed": "prologue-built",
+      "prereq": "fundamentals",
+      "pace": "auto-advance",
+      "chapters": [
+        {
+          "id": "browse",
+          "title": "list / show / check",
+          "est_min": 3
+        },
+        {
+          "id": "graph-export",
+          "title": "graph / export (query, formatters)",
+          "est_min": 3
+        },
+        {
+          "id": "issues",
+          "title": "Issues and broken refs (--analyzers, --json)",
+          "est_min": 3
+        },
+        {
+          "id": "annotations",
+          "title": "Annotations and the .sm consent prompt",
+          "est_min": 3
+        },
+        {
+          "id": "reference-paths",
+          "title": "Validate links to folders outside the scan scope",
+          "est_min": 4
+        }
+      ]
+    },
+    {
+      "id": "mcp",
+      "order": 6,
+      "title": "MCP",
+      "status": "planned",
+      "preflight": "seed",
+      "seed": "harness-connected",
+      "prereq": "connect-harness",
+      "pace": "auto-advance",
+      "chapters": [
+        {
+          "id": "mcp-node",
+          "title": "\"content-editor declares an MCP tool",
+          "est_min": 3
+        }
+      ]
+    }
+  ],
+  "findings_file": "./findings.md"
+}

package/dist/cli/tutorial/sm-tutorial/references/_manifest.yml

@@ -77,7 +77,7 @@ parts:
       - id: authoring-3-edit-setting ; title: "Edit a setting (string-list) and observe it in the UI" ; est_min: 3
       - id: authoring-4-edit-slot    ; title: "Change the view-slot the contribution targets" ; est_min: 2
       - id: settings-6-contributions ; title: "Watch contributions land in the inspector" ; est_min: 2
-      - id: authoring-5-doctor-author; title: "Catch a manifest mistake with `sm plugins doctor`" ; est_min: 2
+      - id: authoring-5-doctor-author ; title: "Catch a manifest mistake with `sm plugins doctor`" ; est_min: 2
       - id: authoring-6-upgrade      ; title: "Try `sm plugins upgrade`" ; est_min: 2
 
   - id: cli
@@ -113,7 +113,7 @@ parts:
     status: active
     chapters:
       - id: kickoff     ; title: "Start the portfolio (sm init on the real skeleton)" ; est_min: 2
-      - id: manual      ; title: "The handbook and CLAUDE.md (@AGENTS.md)" ; est_min: 2
+      - id: manual      ; title: "The handbook (AGENTS.md) and CLAUDE.md" ; est_min: 2
       - id: first-agent ; title: "The first harness agent (content-editor)" ; est_min: 2
       - id: real-kinds  ; title: "The real kinds in context" ; est_min: 2
 
@@ -144,13 +144,12 @@ parts:
     status: active
     chapters:
       - id: setup            ; title: "Make it yours, make it presentable" ; est_min: 3
+      - id: preview          ; title: "Bring it up and see your site" ; est_min: 2
       - id: add-page         ; title: "Add a page with your agent" ; est_min: 4
-      - id: orphan-draft     ; title: "A page nobody links to yet" ; est_min: 2
-      - id: wire-and-improve ; title: "Wire the draft in" ; est_min: 3
       - id: broken-ref       ; title: "A rename breaks a link" ; est_min: 4
       - id: reserved         ; title: "A reserved name collides" ; est_min: 2
       - id: publish          ; title: "Ship it: run /publish for real" ; est_min: 4
-      - id: sidecar          ; title: "Annotate the handbook (.sm and consent)" ; est_min: 3
+      - id: stability        ; title: "Set a node's stability (and the `.sm` sidecar)" ; est_min: 3
       - id: golive           ; title: "Your portfolio, live next to the graph" ; est_min: 3
 
   # ----- parked: MCP returns later as its own iteration (body kept in part-mcp.md) -----