@skill-map/cli 0.60.3 → 0.61.0

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
@@ -429,25 +443,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,309 @@
+{
+  "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 and CLAUDE.md (@AGENTS.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": "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": "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