@skill-map/cli 0.60.3 → 0.61.0

package/dist/cli/tutorial/sm-tutorial/references/part-fundamentals.md

@@ -6,7 +6,7 @@ The live-UI prologue: the tester runs `sm init`, opens the browser, and watches
 
 Agent background (do NOT render this as a separate context paragraph; the tester-facing version is folded into the message below): `sm init` creates a hidden `.skill-map/` folder in the cwd holding the database where skill-map stores what it learns about the project, and runs an initial scan (mandatory first step). Typing `sm` alone (no arguments) in an initialised dir then starts the UI server with the watcher built in (it is just an alias 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 chapters all run against this same `sm` session, you boot it here and keep it alive through the `ignore` chapter.
 
-Expected: `.skill-map/skill-map.db` appears (plus config files), and the initial scan reports a small node / link count from the demo-agent fixture. `sm init` runs and exits; `sm` then starts the UI server and stays running. (Agent context, do not narrate: pre-flight's `.skillmapignore` keeps the tutorial's own files, `sm-tutorial.md` / `findings.md` / `tutorial-state.yml`, out of the scan; `sm init` leaves that file alone since it only writes when absent.)
+Expected: `.skill-map/skill-map.db` appears (plus config files), and the initial scan reports a small node / link count from the demo-agent fixture. `sm init` runs and exits; `sm` then starts the UI server and stays running. (Agent context, do not narrate: pre-flight's `.skillmapignore` keeps the tutorial's own files, `sm-tutorial.md` / `findings.md` / `tutorial-state.json`, out of the scan; `sm init` leaves that file alone since it only writes when absent.)
 
 Give the tester the whole flow in ONE message with ONE confirmation, do NOT pause for the `sm init` output separately. Order matters: **lead with the browser setup**, then explain what the two commands do as you hand them over, then the command block, then the URL. Do NOT print the command block or an explanation paragraph before the browser instruction. Don't hardcode the URL, the verb logs the bound `http://host:port` after listen. Tell the tester:
 
@@ -38,99 +38,13 @@ Wait for confirmation. Mark `init`: done.
 
 Leave the browser open and the terminal with `sm` running. You create five more nodes **without any cross-fixture links** yet, pure standalone nodes, so the tester sees five new dots pop in. Three new **kinds** show up in this step (skill, command, markdown); the last two files are sibling `markdown` notes (`demo-guideline`, `demo-guideline2`) the hub in the `connectors` chapter reaches two ways, a bare mention that resolves to nothing (which lands as a broken reference, no arrow drawn) and the same handle plus `.md` that resolves to a real file (a solid arrow).
 
-Create these five files (with `Write`), exactly in this order. Per §Provider detection, **substitute `.claude/` with the detected `<provider_dir>` and skip files whose kind is not in the provider's supported set** (`agent-skills` / Antigravity: skip both `demo-agent` and `demo-command`, only the skill + the three markdown notes remain). Adjust the node count, the "five new nodes" message, and the file list shown to the tester in the sample below accordingly:
-
-1. `.claude/skills/demo-skill/SKILL.md` (kind: skill):
-   ```markdown
-   ---
-   name: demo-skill
-   description: |
-     Example skill that walks a file and returns a Markdown report.
-     Showcases the `skill` kind in the demo map.
-   ---
-
-   # demo-skill
-
-   This skill walks a file and returns a report. Will be wired up
-   to the rest of the demo fixture in the next sub-step.
-
-   ## Steps
-   1. Read the `target`.
-   2. Validate the frontmatter against the schemas.
-   3. Generate the report.
-   ```
-
-2. `.claude/commands/demo-command.md` (kind: command):
-   ```markdown
-   ---
-   name: demo-command
-   description: |
-     Example slash command that wraps the demo-skill. Showcases the
-     `command` kind.
-   ---
-
-   # demo-command
-
-   Quick entry point for running the demo flow on a target file.
-   Connectors land in the next sub-step.
-   ```
-
-3. `notes/todo.md`, classified as `kind: markdown` today
-   (the catch-all for `.md` files outside the
-   skill / agent / command folders):
-   ```markdown
-   ---
-   name: Demo TODO list
-   description: |
-     Live list of things to review in the demo. Will become the
-     hub that points to the rest of the fixture in the next
-     sub-step.
-   ---
-
-   # Pending
-   ```
-
-4. `notes/demo-guideline.md`, second `kind: markdown` node, reached
-   in the `connectors` chapter by a bare `@`-mention that resolves to
-   no agent, so it surfaces as a broken reference instead of a drawn
-   connector:
-   ```markdown
-   ---
-   name: demo-guideline
-   description: |
-     Static reference notes the rest of the demo points at. The hub
-     reaches it with a bare `@`-mention, which resolves to no agent,
-     so skill-map flags it as a broken reference (0.50) instead of
-     drawing an arrow.
-   ---
-
-   # Demo Guideline
-
-   Conventions the demo fixture follows:
-
-   - Names match the file basename.
-   - Frontmatter `description` is short and human-readable.
-   - Body stays minimal, only what's needed to teach the kind.
-   ```
-
-5. `notes/demo-guideline2.md`, a sibling `markdown` node identical
-   to `demo-guideline`, reached by the same handle plus a `.md`
-   extension (`@demo-guideline2.md`), which makes it a file reference
-   that resolves to this node and lands at full confidence:
-   ```markdown
-   ---
-   name: demo-guideline2
-   description: |
-     Sibling of demo-guideline. The hub reaches it with an
-     `@`-mention that carries the `.md` extension, so the link
-     resolves to this file and lands certain (1.00).
-   ---
-
-   # Demo Guideline 2
-
-   Same conventions as demo-guideline; it exists so the hub can
-   reach it with a resolved reference instead of a bare mention.
-   ```
+Lay these five files in one go (their content + translation live in `fixtures-data/`). The script resolves `__PROVIDER__` and auto-skips kinds the provider does not claim (`agent-skills` / Antigravity: both `demo-agent` and `demo-command` fold away, only the skill + the three markdown notes remain), so read the actual node count from the summary's `nodeCount`. Backstage (silent):
+
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay prologue --only "__PROVIDER__/skills/demo-skill/SKILL.md,__PROVIDER__/commands/demo-command.md,notes/todo.md,notes/demo-guideline.md,notes/demo-guideline2.md" --provider <provider> --lang <lang>
+```
+
+Adjust the node count, the "five new nodes" message, and the file list shown to the tester in the sample below to match the laid set.
 
 Tell the tester:
 
@@ -195,16 +109,10 @@ You edit `notes/todo.md` so it becomes the **hub** that points to each of the ot
 
 Five bullets, three kinds: `invokes` and `mentions` each appear twice, `references` once. The last two bullets are the resolution lesson: a bare `@demo-guideline` mention (which resolves to no agent, so it lands as a broken reference and draws no arrow) next to `@demo-guideline2.md`, the same handle shape plus a `.md` extension that points at a real sibling file (so it resolves and draws a solid arrow). Two separate nodes, one broken and one resolved. Five bullets but only four arrows on the canvas.
 
-Apply with `Edit` on `notes/todo.md` (do not rewrite the file). Per §Provider detection, **substitute `.claude/` with the detected `<provider_dir>` and drop any bullet whose target node was not created in the `kinds` chapter** (on `agent-skills` / Antigravity there is no agent and no command → skip the `@demo-agent` and `/demo-command` bullets; the two guideline bullets stay, so the resolution contrast, broken mention 0.50 (no arrow drawn) vs resolved reference 1.00 (solid arrow), is intact on those providers too).
-
-**Edit `notes/todo.md`**: append these bullets after the `# Pending` heading:
+Apply the hub bullets (their content + translation live in `fixtures-data/`). The edit appends after the `# Pending` heading; the script drops any bullet whose target kind the provider does not claim (on `agent-skills` / Antigravity there is no agent and no command → the `@demo-agent` and `/demo-command` bullets fold away; the two guideline bullets stay, so the resolution contrast, broken mention 0.50 (no arrow drawn) vs resolved reference 1.00 (solid arrow), is intact on those providers too). Backstage (silent):
 
-```markdown
-- [ ] Brief @demo-agent on the rough edges.
-- [ ] Run /demo-command before publishing.
-- [ ] Trigger /demo-skill when the input lands.
-- [ ] Ping @demo-guideline if the conventions change.
-- [ ] Ping @demo-guideline2.md if the conventions change.
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js edit todo-connectors --provider <provider> --lang <lang>
 ```
 
 Tell the tester:
@@ -363,20 +271,10 @@ Earlier chapters showed the watcher picking up new files and edits (yours and th
 
 **The agent seeds the file (no tester action, no separate pause).**
 
-`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 skill-map's map. Demonstrates the .skillmapignore
-  flow.
----
+Lay `notes/private-credentials.md`, kind `markdown`, which simulates a file the tester would never want surfacing publicly (its content + translation live in `fixtures-data/`). Backstage (silent):
 
-# Private
-
-API_TOKEN: example-not-real
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay prologue --only "notes/private-credentials.md" --provider <provider> --lang <lang>
 ```
 
 It lands in the map as a seventh node (`notes/private-credentials`); the watcher sees it like any other `.md`. Do NOT pause to confirm the appearance, it folds into the single vanish confirmation at the end of this step.

package/dist/cli/tutorial/sm-tutorial/references/part-plugins.md

@@ -17,7 +17,7 @@ Before announcing the first step, verify the fixture is initialised
 `backstage-init` preflight ran `sm init --no-scan` to provision it;
 the universal `.skillmapignore` from pre-flight keeps the tutorial's
 own files out of the scan. If any of that is missing, surface the
-bootstrap mismatch ("tutorial-state.yml says we are running, but
+bootstrap mismatch ("tutorial-state.json says we are running, but
 the bootstrap is missing. Re-run the tutorial from an empty dir or
 restore the files.") and stop.
 
@@ -189,8 +189,7 @@ Mark `tour-3-explore: done`.
 >
 > Anything weird worth logging? If not, back to the menu.
 
-Mark the plugins chapters done in `tutorial-state.yml`, update the
-matching harness task, return to the menu in `SKILL.md`.
+Mark the chapters done (rule #4) and return to the menu in `SKILL.md`.
 
 ## Reference: how `sm` decides what to load
 

package/dist/cli/tutorial/sm-tutorial/references/part-project-kickoff.md

@@ -74,7 +74,9 @@ repo does). That one-line pointer is a real `references` link (the
 mention), the tester's first connector on the real project.
 
 Tell the tester to create the file themselves (it is their project's
-file, Inviolable rule #2):
+file, Inviolable rule #2). Backstage, get the content:
+`node .claude/skills/sm-tutorial/scripts/fixtures.js cat portfolio --file "CLAUDE.md" --provider <provider> --lang <lang>`,
+then render it in the fenced block the tester copies:
 
 > Create a file called `CLAUDE.md` at the project root with exactly
 > this content:
@@ -98,37 +100,13 @@ Wait for confirmation. Mark `manual`: done.
 
 ## Chapter `first-agent` - The first harness agent (~2 min)
 
-**Context**: the harness's job is content creation. Its first member
-is `content-editor`, an agent that writes the site's HTML pages. Here
-we only create it (the cross-references come in the next part).
-
-`Write` `.claude/agents/content-editor.md` (substitute
-`<provider_dir>` per `_core.md`; on `agent-skills` / Antigravity,
-which has no `agent` kind, create a `skill` instead and adjust the
-prose):
-
-```markdown
----
-name: content-editor
-description: |
-  Writes and edits the portfolio's pages. Reads a brief, follows the
-  style guide, and emits the HTML into public/.
-tools: [Read, Write]
-model: sonnet
----
-
-# content-editor
-
-Turns a short brief into a finished portfolio page.
-
-## How to write a page
-1. Read the style guide and the shared stylesheet in public/.
-2. Write one HTML file under public/, named after the page (a projects page becomes `public/projects.html`).
-3. Start from `<!doctype html>`, link the stylesheet with `<link rel="stylesheet" href="/style.css">`, and set a `<title>`.
-4. Use one `<h1>`, group sections under `<h2>`, and reuse the shared header, nav, and footer so every page matches.
-5. Add a link back to Home, and link the new page from the home nav.
-
-Rules: plain static HTML, no framework, no client JS, one page per file.
+Lay the first harness agent (its content + translation live in
+`fixtures-data/`). The script resolves `__PROVIDER__`; on
+`agent-skills` / Antigravity, which has no `agent` kind, adjust the
+prose to the skill the set lays there. Backstage (silent):
+
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay portfolio --only "__PROVIDER__/agents/content-editor.md" --provider <provider> --lang <lang>
 ```
 
 Tell the tester:
@@ -149,45 +127,11 @@ nodes. Now name them on the real project, and add the two markdown
 docs the harness references later (the style guide and the deploy
 runbook), so the Daily Loop's maintenance beats have something to point at.
 
-`Write` two docs (markdown kind):
-
-`docs/STYLE.md`:
-```markdown
----
-name: style-guide
-description: |
-  Writing and markup conventions every portfolio page follows.
----
-
-# Style guide
-
-## Voice
-- Short, plain sentences. No marketing fluff.
+Lay the two markdown docs the harness references later (their content
++ translation live in `fixtures-data/`). Backstage (silent):
 
-## Structure
-- One H1 per page; sections under H2.
-- Every page shares the same header, nav, and footer.
-- Every page links back to Home.
-
-## Markup
-- Plain static HTML: no framework, no client JS.
-- Link the shared stylesheet `/style.css` in every page head.
-- Use semantic tags: header, nav, main, footer.
 ```
-
-`docs/DEPLOY.md`:
-```markdown
----
-name: deploy-runbook
-description: |
-  How the portfolio gets published once the pages are written.
----
-
-# Deploy runbook
-
-1. Generate or update the pages in public/.
-2. Run the link check and fix anything it reports.
-3. Start the server with `node server.js`, then open the site in your browser.
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay portfolio --only "docs/STYLE.md,docs/DEPLOY.md" --provider <provider> --lang <lang>
 ```
 
 Tell the tester:

package/dist/cli/tutorial/sm-tutorial/scripts/fixtures.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * fixtures.js, the sm-tutorial fixture engine.
+ *
+ * Lays / edits / seeds / clears the demo, portfolio, harness, master,
+ * and cli-external fixtures from `fixtures-data/` instead of having the
+ * agent reproduce file content verbatim. Zero-dep, Node 24+, ESM.
+ * Backstage machinery (same class as `Write`), NOT a teaching `sm` verb.
+ *
+ * Content lives under `fixtures-data/sets/<set>/{shared,<lang>}/` with
+ * the provider dir as a literal `__PROVIDER__` path segment; only the
+ * PATH is rewritten per provider (content is verbatim, relative links
+ * are depth-correct in the claude layout). Kind is derived from the
+ * path (paths.js#kindForPath); files whose kind the provider does not
+ * claim are skipped.
+ *
+ * Verbs (all but `cat` print one JSON line to stdout):
+ *   lay <set>   [--provider p] [--lang l]
+ *   edit <id>   [--provider p] [--lang l]
+ *   seed <snap> [--provider p] [--lang l]
+ *   clear <footprint>          [--provider p]
+ *   cat <set> --file <relpath> [--provider p] [--lang l]   (raw content to stdout)
+ *
+ * `clear` removes a named footprint (part-entry resets); the full
+ * start-over wipe is `state.js wipe` (cwd-guarded + confirmation-gated).
+ */
+
+import { join, dirname, relative } from 'node:path';
+import {
+  readFileSync, writeFileSync, mkdirSync, rmSync, rmdirSync, readdirSync, statSync, existsSync,
+} from 'node:fs';
+
+import { parseArgs } from './lib/args.js';
+import { emit, succeed, die } from './lib/io.js';
+import { loadFixturesManifest, fixturesDir, resolveFootprint } from './lib/fixtures-manifest.js';
+import {
+  providerDir, kindsFor, resolveTargetPath, kindForPath, PROVIDER_TOKEN,
+} from './lib/paths.js';
+
+function opts(args) {
+  return { provider: args.flags.provider ?? 'claude', lang: args.flags.lang ?? 'en' };
+}
+
+function pdirAndKinds(o) {
+  return { pdir: providerDir(o.provider), kinds: kindsFor(o.provider) };
+}
+
+/** Recursively list files under `root`, relative to `root`, sorted. */
+function walk(root) {
+  const out = [];
+  if (!existsSync(root)) return out;
+  const stack = [root];
+  while (stack.length) {
+    const cur = stack.pop();
+    for (const entry of readdirSync(cur)) {
+      const full = join(cur, entry);
+      if (statSync(full).isDirectory()) stack.push(full);
+      else out.push(relative(root, full));
+    }
+  }
+  return out.sort();
+}
+
+function writeFileEnsuring(abs, content) {
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content);
+}
+
+/**
+ * Lay one set's files for the given lang + provider. `only` (a Set of
+ * token-form relpaths) restricts to those files, for the prologue's
+ * progressive reveal where each chapter lands its own nodes.
+ */
+function laySet(manifest, set, o, only = null) {
+  const { kinds } = pdirAndKinds(o);
+  if (!manifest.sets.includes(set)) die('unknown-set', `set '${set}' is not in the manifest.`);
+  const base = join(fixturesDir(), 'sets', set);
+  const langDir = existsSync(join(base, o.lang)) ? o.lang : (manifest.defaultLang ?? 'en');
+  const laid = [];
+  const skipped = [];
+  // Lang-invariant `shared/` tier first, then the language tier.
+  for (const tier of ['shared', langDir]) {
+    const tierRoot = join(base, tier);
+    for (const rel of walk(tierRoot)) {
+      // `rel` is the token-form target path (e.g. __PROVIDER__/agents/x.md).
+      if (only && !only.has(rel)) continue;
+      const kind = kindForPath(rel);
+      if (!kinds.has(kind)) { skipped.push({ path: rel, kind }); continue; }
+      const target = resolveTargetPath(rel, o.provider);
+      writeFileEnsuring(join(process.cwd(), target), readFileSync(join(tierRoot, rel)));
+      laid.push(target);
+    }
+  }
+  return { laid, skipped };
+}
+
+const nodeCount = (paths) => paths.filter((p) => p.endsWith('.md')).length;
+
+/** Resolve a fragment file path, falling back to the default language. */
+function fragmentPath(manifest, id, lang, file) {
+  const langTry = join(fixturesDir(), 'edits', id, lang, file);
+  return existsSync(langTry) ? langTry : join(fixturesDir(), 'edits', id, manifest.defaultLang ?? 'en', file);
+}
+
+/** Apply one manifest edit (append fragments) honoring requiresKind. */
+function applyEdit(manifest, id, o) {
+  const { kinds } = pdirAndKinds(o);
+  const def = manifest.edits?.[id];
+  if (!def) die('unknown-edit', `edit '${id}' is not in the manifest.`);
+  const target = resolveTargetPath(def.target, o.provider);
+  // Skip the whole edit if the target's own kind is unsupported (e.g. a
+  // content-editor agent does not exist on agent-skills).
+  if (!kinds.has(kindForPath(def.target))) return { target, appended: [], skipped: true };
+  const targetAbs = join(process.cwd(), target);
+  if (!existsSync(targetAbs)) die('edit-target-missing', `edit '${id}' target not found: ${target}`);
+
+  const fragments = (def.fragments ?? []).filter((f) => !f.requiresKind || kinds.has(f.requiresKind));
+  if (fragments.length === 0) return { target, appended: [] };
+
+  let content = readFileSync(targetAbs, 'utf8');
+  if (!content.endsWith('\n')) content += '\n';
+  if (def.prefix) content += def.prefix;
+  const appended = [];
+  for (const frag of fragments) {
+    content += readFileSync(fragmentPath(manifest, id, o.lang, frag.file), 'utf8');
+    appended.push(frag.file);
+  }
+  writeFileSync(targetAbs, content);
+  return { target, appended };
+}
+
+const VERBS = {
+  lay(args) {
+    const set = args.positional[0];
+    if (!set) die('bad-args', 'usage: lay <set> [--only a,b] [--provider p] [--lang l]');
+    const o = opts(args);
+    const only = args.flags.only ? new Set(String(args.flags.only).split(',')) : null;
+    const manifest = loadFixturesManifest();
+    const { laid, skipped } = laySet(manifest, set, o, only);
+    succeed({ laid, skipped, nodeCount: nodeCount(laid), needsProvision: !existsSync(join(process.cwd(), '.skill-map')) });
+  },
+
+  edit(args) {
+    const id = args.positional[0];
+    if (!id) die('bad-args', 'usage: edit <edit-id> [--provider p] [--lang l]');
+    const manifest = loadFixturesManifest();
+    succeed(applyEdit(manifest, id, opts(args)));
+  },
+
+  seed(args) {
+    const snap = args.positional[0];
+    if (!snap) die('bad-args', 'usage: seed <snapshot> [--provider p] [--lang l]');
+    const o = opts(args);
+    const manifest = loadFixturesManifest();
+    const def = manifest.seeds?.[snap];
+    if (!def) die('unknown-seed', `seed '${snap}' is not in the manifest.`);
+    const laid = [];
+    const skipped = [];
+    for (const set of def.lay ?? []) {
+      const r = laySet(manifest, set, o);
+      laid.push(...r.laid);
+      skipped.push(...r.skipped);
+    }
+    const edits = [];
+    for (const id of def.edits ?? []) edits.push(applyEdit(manifest, id, o));
+    const dropped = [];
+    for (const rel of def.drop ?? []) {
+      const resolved = resolveTargetPath(rel, o.provider);
+      const abs = join(process.cwd(), resolved);
+      if (existsSync(abs)) { rmSync(abs, { recursive: true, force: true }); dropped.push(resolved); }
+    }
+    const present = laid.filter((p) => !dropped.includes(p));
+    succeed({
+      laid, skipped, edits, dropped,
+      nodeCount: nodeCount(present),
+      needsProvision: !existsSync(join(process.cwd(), '.skill-map')),
+    });
+  },
+
+  clear(args) {
+    const name = args.positional[0];
+    if (!name) die('bad-args', 'usage: clear <footprint> [--provider p]');
+    const manifest = loadFixturesManifest();
+    if (!manifest.footprints?.[name]) die('unknown-footprint', `footprint '${name}' is not in the manifest.`);
+    const o = opts(args);
+    const { pdir } = pdirAndKinds(o);
+    const deleted = [];
+    for (const rel of resolveFootprint(manifest, name, o.provider)) {
+      const abs = join(process.cwd(), rel);
+      if (existsSync(abs)) { rmSync(abs, { recursive: true, force: true }); deleted.push(rel); }
+    }
+    rmdirEmptyParents(pdir);
+    succeed({ deleted });
+  },
+
+  cat(args) {
+    const set = args.positional[0];
+    const file = args.flags.file;
+    if (!set || typeof file !== 'string') {
+      emit({ ok: false, code: 'bad-args', error: 'usage: cat <set> --file <relpath> [--provider p] [--lang l]' });
+      process.exit(1);
+    }
+    const o = opts(args);
+    const { pdir } = pdirAndKinds(o);
+    const manifest = loadFixturesManifest();
+    const base = join(fixturesDir(), 'sets', set);
+    const langDir = existsSync(join(base, o.lang)) ? o.lang : (manifest.defaultLang ?? 'en');
+    // Accept a resolved path (`.claude/...`) or token form; normalise to token.
+    const tokenForm = file.startsWith(`${pdir}/`) ? PROVIDER_TOKEN + file.slice(pdir.length) : file;
+    const found = [join(base, langDir, tokenForm), join(base, 'shared', tokenForm)].find((c) => existsSync(c));
+    if (!found) {
+      emit({ ok: false, code: 'not-found', error: `file '${file}' not found in set '${set}'.` });
+      process.exit(1);
+    }
+    process.stdout.write(readFileSync(found, 'utf8'));
+    process.exit(0);
+  },
+};
+
+function rmdirEmptyParents(pdir) {
+  const candidates = ['notes', 'docs', 'public', `${pdir}/agents`, `${pdir}/skills`, `${pdir}/commands`, pdir];
+  for (const rel of candidates) {
+    try { rmdirSync(join(process.cwd(), rel)); } catch { /* not empty or missing */ }
+  }
+}
+
+function main() {
+  const [verb, ...rest] = process.argv.slice(2);
+  const handler = VERBS[verb];
+  if (!handler) {
+    die('unknown-verb', `unknown verb '${verb ?? ''}'; expected one of ${Object.keys(VERBS).join(', ')}`);
+  }
+  handler(parseArgs(rest));
+}
+
+main();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7deeaba5-0c50-5d6e-93cc-ad31c6b5a37c")}catch(e){}}();
+//# debugId=7deeaba5-0c50-5d6e-93cc-ad31c6b5a37c

package/dist/cli/tutorial/sm-tutorial/scripts/lib/args.js

@@ -0,0 +1,29 @@
+/**
+ * Minimal zero-dep argv parser shared by the tutorial scripts. Splits
+ * `--key value` pairs and bare `--flag` booleans from positionals.
+ * No external CLI framework (the script ships to a tester cwd with no
+ * node_modules).
+ */
+
+export function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i++;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="11379635-8a15-5ac2-a59e-af05707a526b")}catch(e){}}();
+//# debugId=11379635-8a15-5ac2-a59e-af05707a526b

package/dist/cli/tutorial/sm-tutorial/scripts/lib/fixtures-manifest.js

@@ -0,0 +1,32 @@
+/**
+ * Reads `fixtures-data/manifest.json`, the index for the fixture
+ * engine (sets, footprints, edits, seeds). Shared by `fixtures.js`
+ * (lay / edit / seed / clear) and `state.js` (wipe reads footprints,
+ * so the per-fixture on-disk reach lives in ONE place).
+ */
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readJson } from './io.js';
+import { resolveTargetPath } from './paths.js';
+
+const LIB_DIR = dirname(fileURLToPath(import.meta.url));
+// lib/ -> scripts/ -> sm-tutorial/ -> fixtures-data/
+const FIXTURES_DIR = resolve(LIB_DIR, '..', '..', 'fixtures-data');
+const MANIFEST = resolve(FIXTURES_DIR, 'manifest.json');
+
+export function fixturesDir() {
+  return FIXTURES_DIR;
+}
+
+export function loadFixturesManifest() {
+  return readJson(MANIFEST);
+}
+
+/** Footprint paths for a named fixture, resolved for the provider. */
+export function resolveFootprint(manifest, name, provider) {
+  const fp = manifest.footprints?.[name] ?? [];
+  return fp.map((p) => resolveTargetPath(p, provider));
+}
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="22500f53-280a-5e92-b22b-2608486d3d0c")}catch(e){}}();
+//# debugId=22500f53-280a-5e92-b22b-2608486d3d0c

package/dist/cli/tutorial/sm-tutorial/scripts/lib/io.js

@@ -0,0 +1,37 @@
+/**
+ * Zero-dep IO + JSON-envelope helpers shared by the tutorial scripts.
+ * Every verb prints ONE JSON line to stdout: `{ ok: true, ... }` with
+ * exit 0, or `{ ok: false, code, error }` with a non-zero exit. The
+ * orchestrating agent parses stdout; it never hand-edits state.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+
+export function exists(p) {
+  return existsSync(p);
+}
+
+export function readJson(p) {
+  return JSON.parse(readFileSync(p, 'utf8'));
+}
+
+/** Write pretty JSON with a trailing LF newline (project line-ending rule). */
+export function writeJson(p, obj) {
+  writeFileSync(p, JSON.stringify(obj, null, 2) + '\n');
+}
+
+export function emit(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+export function succeed(obj) {
+  emit({ ok: true, ...obj });
+  process.exit(0);
+}
+
+export function die(code, error) {
+  emit({ ok: false, code, error });
+  process.exit(1);
+}
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6f5406ec-7563-5466-a639-eee006c56913")}catch(e){}}();
+//# debugId=6f5406ec-7563-5466-a639-eee006c56913

package/dist/cli/tutorial/sm-tutorial/scripts/lib/manifest.js

@@ -0,0 +1,24 @@
+/**
+ * Reads the generated book ToC sidecar (`references/_manifest.json`)
+ * that the repo codegen emits from `_manifest.yml`. Zero-dep: plain
+ * `JSON.parse`. The `.yml` is never parsed at runtime (its bespoke
+ * chapter shorthand is not standard YAML).
+ */
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readJson } from './io.js';
+
+const LIB_DIR = dirname(fileURLToPath(import.meta.url));
+// lib/ -> scripts/ -> sm-tutorial/ -> references/_manifest.json
+const MANIFEST = resolve(LIB_DIR, '..', '..', 'references', '_manifest.json');
+
+export function loadManifest() {
+  return readJson(MANIFEST);
+}
+
+export function findPart(manifest, id) {
+  return manifest.parts.find((p) => p.id === id) ?? null;
+}
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b51b0ac6-99f1-5d52-8cac-40f122545c4a")}catch(e){}}();
+//# debugId=b51b0ac6-99f1-5d52-8cac-40f122545c4a