@skill-map/cli 0.60.3 → 0.61.0

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

@@ -1,277 +1,100 @@
-# Fixture templates
+# Fixtures and state: the data + script model
 
-Fixtures the orchestrator lays for the auto-fixtured parts. Two full
-templates live here: the **master fixture** (Part 4, "Extend
-skill-map", `backstage-init`) right below, and the **portfolio
-fixture** (Part 1, "The project from zero", `portfolio-init`) at the
-end of this file. The **Part 0 demo fixture** is not templated here:
-its content lives in `SKILL.md` (§Fixture and state templates) and
-`part-fundamentals.md`, and the `prologue-built` seed snapshot below
-just points at those. Read the set for the part being entered.
+The tutorial no longer embeds fixture content in prose or hand-edits
+the state file. **Content lives in `fixtures-data/` and is laid by
+`scripts/fixtures.js`; progress lives in `tutorial-state.json` and is
+owned by `scripts/state.js`.** This file is the reference for that
+model; the per-chapter invocations live in each `part-*.md`.
 
-**Authoring note (command fixtures).** A `command` node's H1 is a plain
-title (`# publish`), never the slash form (`# /publish`). The `slash`
-extractor reads a `/name` token anywhere in the body, the H1 included,
-as an `invoke`, so `# /publish` makes the command invoke itself and
-`sm check` emits a spurious `core/link-self-loop` the tester has no
-context for. Holds for every command fixture wherever it is defined
-(today: the prologue `demo-command`, the `publish` command, and the
-`reserved` chapter's `init`).
-
-## Master fixture (Part 4): layout (per provider)
-
-Per §Provider detection in `SKILL.md`, the `<provider_dir>`
-placeholder resolves to `.claude/` or `.agents/skills/` depending
-on the detected runtime (Google's Antigravity CLI, which replaced
-Gemini CLI on 2026-05-19, adopted the same open standard as
-`agent-skills`, so both share the `.agents/skills/` layout). Drop
-any file whose kind is not in the provider's supported set: on
-`agent-skills` / Antigravity only the skill + note are valid;
-on `claude` (default) all three apply.
-
-Canonical layout (substitute `<provider_dir>` per detection):
-
-```
-<cwd>/
-├── <provider_dir>/
-│   ├── agents/                    (claude only)
-│   │   └── master-agent.md
-│   └── skills/                    (both providers)
-│       └── master-skill/
-│           └── SKILL.md
-├── notes/
-│   └── ideas.md
-└── findings.md
-```
-
-On `agent-skills` the `agents/` subtree is omitted (the provider
-does not claim that kind); the skill lives at
-`.agents/skills/master-skill/SKILL.md`.
-
-Translate the natural-language prose (descriptions, body text,
-list items) to the tester's language. Keep paths, frontmatter
-keys, identifiers, and link targets in English.
-
-## File: `.claude/agents/master-agent.md` (kind: agent)
-
-```markdown
----
-name: master-agent
-description: |
-  Example agent used by the advanced tutorial. Has a couple of
-  tools so the `core/tools-counter` extractor emits a count.
-tools: [Read, Bash, Edit]
-model: sonnet
----
-
-# master-agent
-
-Walks the master-skill outputs and reports findings. Used as the
-target node when we exercise extractors, analyzers, and the
-plugin-authoring flow.
-```
-
-## File: `.claude/skills/master-skill/SKILL.md` (kind: skill)
-
-```markdown
----
-name: master-skill
-description: |
-  Example skill paired with the master-agent for the advanced
-  tutorial. Links to the agent so extractors and analyzers have
-  something to chew on.
----
-
-# master-skill
-
-Hands heavy work over to the
-[master-agent](../../agents/master-agent.md) and emits a Markdown
-report.
-
-## Steps
-1. Read the `target`.
-2. Validate the frontmatter.
-3. Delegate to the agent.
-```
-
-## File: `notes/ideas.md` (kind: markdown)
-
-```markdown
----
-name: Ideas backlog
-description: |
-  Free-form notes for the advanced tutorial. Demonstrates the
-  catch-all markdown kind alongside the agent and skill.
----
-
-# Ideas
-
-- [ ] Compare extractor outputs side by side.
-- [ ] Sketch a tiny plugin that surfaces a counter on the agent.
-```
-
-## File: `findings.md`
-
-```markdown
-# Findings
-
-If you spot anything weird during the tutorial, log it here.
-
-Per finding:
-- **Chapter**: <id>
-- **Command**: `sm ...`
-- **Expected**: ...
-- **Got**: ...
-- **Notes**: ...
-```
-
-## Portfolio fixture (Part 1, `portfolio-init`)
-
-Laid backstage before the tester's `sm init` in Part 1. The Express
-skeleton (`server.js`, `package.json`, `public/index.html`) is plain
-scaffolding, not `.md`, so the scan ignores it; it makes the project
-real and runnable (the daily loop, Part 3, runs and ships it). The one boot node is the
-handbook `AGENTS.md`. On `agent-skills` / Antigravity (no `agent`
-kind) the harness still works: the agent member is created as a skill
-in a later chapter.
-
-Layout:
+## Data layout (`fixtures-data/`)
 
 ```
-<cwd>/
-├── <provider_dir>/            (harness, grown by the chapters)
-├── docs/                      (created in the real-kinds chapter)
-├── public/
-│   └── index.html
-├── AGENTS.md                  (the boot node)
-├── server.js
-└── package.json
+fixtures-data/
+  manifest.json                 sets, footprints, edits, seeds, providerToken, langs
+  sets/<set>/
+    shared/                     lang-invariant files (code: server.js, package.json, CLAUDE.md)
+    en/  es/                    one tree per language (files with translatable prose)
+  edits/<edit-id>/
+    en/  es/                    append fragments (one file per fragment)
 ```
 
-The daily loop (Part 3) grows this further as taught steps, all Layer 2
-or loose notes (not part of the harness graph): `public/style.css` plus
-the generated pages (`index.html` rewritten, `about.html`,
-`projects.html`, `posts.html`), `docs/draft.md`, the renamed `new-page`
-command, `AGENTS.sm`, and `.skill-map/settings.local.json`. The
-start-over wipe and the `extend` / `cli` clears account for them via
-this section.
-
-### File: `AGENTS.md` (kind: markdown, the boot node)
-
-No frontmatter: a real handbook is plain prose (this repo's own
-`AGENTS.md` and the tutorial's `CLAUDE.md` carry none either), and a
-`name:` that differs from the filename only confuses the tester. The
-node displays by its path, `AGENTS.md`.
-
-**No backtick-wrapped relative `.md` paths in the body either.**
-`core/backtick-path` (Decision #127) turns a `` `docs/STYLE.md` `` written
-inside a code span into a `points` link, and at kickoff (before the
-`docs/` files exist) that link lands as a broken reference, which would
-break the "one lonely node" beat the `kickoff` chapter promises. Name the
-docs in prose (the style guide, the deploy runbook), never as backticked
-paths. They become real nodes in the `real-kinds` chapter and are wired
-in explicitly in Part 2.
-
-```markdown
-# Portfolio handbook
-
-A small static portfolio site, served by Express (`server.js`). The
-`.claude/` harness maintains it: an agent writes the pages, a skill
-checks the links, a command publishes. The conventions live in the
-style guide; the deploy steps in the deploy runbook.
-```
-
-### File: `server.js` (not scanned; runnable scaffolding)
-
-```js
-// Minimal static server for the portfolio. No framework, one dep.
-const express = require('express');
-const path = require('node:path');
-
-const app = express();
-app.use(express.static(path.join(__dirname, 'public')));
-
-const port = process.env.PORT || 3000;
-app.listen(port, () => console.log(`Portfolio live at http://localhost:${port}`));
-```
-
-### File: `package.json` (not scanned)
-
-```json
-{
-  "name": "my-portfolio",
-  "private": true,
-  "scripts": { "start": "node server.js" },
-  "dependencies": { "express": "4.21.2" }
-}
-```
-
-### File: `public/index.html` (not scanned; placeholder until Part 3)
-
-```html
-<!doctype html>
-<meta charset="utf-8">
-<title>My portfolio</title>
-<h1>My portfolio</h1>
-<p>Pages land here once the content-editor generates them.</p>
-```
-
-### `.skillmapignore` additions
-
-Append to the universal `.skillmapignore` (written in pre-flight, see
-`SKILL.md`): `node_modules/` (the Express install) and `public/`
-(generated HTML, not part of the harness graph).
-
-## Seed snapshots (for `preflight: seed`)
-
-When the orchestrator enters a seedable part out of order (the campaign
-parts when their predecessors are not `done`, or Part 5 `cli` when the
-demo fixture is not the one on disk), it fast-forwards the project by
-laying the snapshot below, then `sm init` (if `.skill-map/` is missing) +
-`sm scan`. These are **checklists, not content**: each row names a file
-and the chapter that holds its canonical content. Lay each file by
-copying the content from the named chapter (substitute `<provider_dir>`
-and skip provider-unsupported kinds per `_core.md`); an `EDIT` row is
-applied on top of the file an earlier row laid. Keep these lists in
-sync only when a harness FILE is added or removed, the file CONTENT
-lives in the chapters, so editing a chapter needs no change here.
-
-### Seed snapshot: `harness-built` (start of Part 2)
-
-The portfolio skeleton plus the harness members Part 1 created, before
-any cross-links:
-
-1. `AGENTS.md`, `server.js`, `package.json`, `public/index.html`, and
-   the portfolio `.skillmapignore` additions  <-  the `## Portfolio
-   fixture` section above.
-2. `CLAUDE.md` (`@AGENTS.md`)  <-  part-project-kickoff.md, chapter `manual`.
-3. `<provider_dir>/agents/content-editor.md`  <-  part-project-kickoff.md, chapter `first-agent`.
-4. `docs/STYLE.md` and `docs/DEPLOY.md`  <-  part-project-kickoff.md, chapter `real-kinds`.
-
-### Seed snapshot: `harness-connected` (start of the daily-loop part)
-
-Everything in `harness-built`, PLUS the Part 2 wiring:
-
-5. `<provider_dir>/skills/check-links/SKILL.md`  <-  part-connect-harness.md, chapter `check-links`.
-6. `<provider_dir>/commands/publish.md`  <-  part-connect-harness.md, chapter `publish`.
-7. EDIT `AGENTS.md`: append the two hub bullets (mention `@content-editor`, invoke `/publish`)  <-  part-connect-harness.md, chapter `links`.
-8. EDIT `<provider_dir>/agents/content-editor.md`: add the `[style guide](../../docs/STYLE.md)` line  <-  part-connect-harness.md, chapter `links`.
-
-After laying a campaign snapshot the map matches the state a tester would
-have at the END of the part just before the one being entered.
-
-### Seed snapshot: `prologue-built` (Part 5 `cli`)
-
-NOT cumulative and NOT the portfolio: this is the **Part 0 demo
-fixture**, the six standalone demo nodes with `notes/todo` wired as the
-hub, the state at the end of the prologue's connector chapters: five hub
-links, one of them (`@demo-guideline`, a bare mention that resolves to no
-agent) a deliberate broken reference that `sm check` reports as a single
-`reference-broken` error. Part 5 only reads it. Because it is a different
-fixture from the portfolio, entry first resets any portfolio on disk
-(see SKILL.md §Entering a part, the `cli` case).
-
-1. `<provider_dir>/agents/demo-agent.md`  <-  SKILL.md §Fixture and state templates. (The `.skillmapignore` is universal, already on disk from pre-flight; the snapshot does not lay it.)
-2. `<provider_dir>/skills/demo-skill/SKILL.md`, `<provider_dir>/commands/demo-command.md`, `notes/todo.md`, `notes/demo-guideline.md`, `notes/demo-guideline2.md`  <-  part-fundamentals.md, chapter `kinds`.
-3. EDIT `notes/todo.md`: wire the hub bullets pointing at the five other nodes  <-  part-fundamentals.md, chapter `connectors`.
-
+- **`__PROVIDER__`** is a literal path segment in the data tree (e.g.
+  `sets/prologue/en/__PROVIDER__/agents/demo-agent.md`). The script
+  resolves it per provider: `.claude/agents/…` on claude,
+  `.agents/skills/…` on agent-skills (where the `skills/` segment
+  collapses, since that layout has no `agents`/`commands` dirs). Only
+  the PATH is resolved; file CONTENT is laid verbatim.
+- **Kind** is derived from the path (`__PROVIDER__/agents|commands|skills`
+  → agent/command/skill, else markdown); files whose kind the provider
+  does not claim are skipped automatically.
+- **Language**: pass `--lang en|es`. A missing language tier for a set
+  falls back to the default (`en`). Translate prose (descriptions,
+  body, list items, anchor text); keep paths, frontmatter keys, node
+  identifiers, link targets, and code in English.
+
+## Sets
+
+| Set | What it lays | Used by |
+|---|---|---|
+| `universal` | `.skillmapignore`, `findings.md` | pre-flight |
+| `prologue` | the seven Part 0 demo nodes | Part 0 (progressive, `--only`), `prologue-built` seed |
+| `portfolio` | Express skeleton, handbook, `content-editor`, `docs/STYLE` + `DEPLOY` | Part 1 (`--only` boot, chapters lay the rest), `harness-*` seeds |
+| `harness` | `check-links` skill, `publish` command | Part 2 chapters, `harness-connected` seed |
+| `master` | `master-agent`, `master-skill`, `notes/ideas` | Part 4 `backstage-init` |
+| `cli-external` | `link-validation/hijoA` + `hijoB` | Part 5 `reference-paths` |
+
+## Edits (append fragments)
+
+`edit <id>` appends fragment files to a target (after a one-time
+`prefix`). A `requiresKind` on a fragment (or on the edit's target
+kind) drops it on a provider that does not claim that kind.
+
+| Edit | Target | Fragments |
+|---|---|---|
+| `todo-connectors` | `notes/todo.md` | five hub bullets (agent / command / skill gated by kind) |
+| `agents-hub` | `AGENTS.md` | the two handbook hub bullets |
+| `content-editor-style` | `<provider_dir>/agents/content-editor.md` | the style-guide reference line (agent target, so skipped on agent-skills) |
+
+## Seeds (fast-forward snapshots)
+
+`seed <id>` composes sets + edits + drops to fast-forward into a part
+entered out of order.
+
+| Seed | Lays | Edits | Drops |
+|---|---|---|---|
+| `prologue-built` (Part 5) | `prologue` | `todo-connectors` | `notes/private-credentials.md` |
+| `harness-built` (Part 2) | `portfolio` | , | , |
+| `harness-connected` (Part 3) | `portfolio` + `harness` | `agents-hub`, `content-editor-style` | , |
+
+## Footprints (what `clear` and `wipe` remove)
+
+`manifest.json#footprints` lists the full on-disk reach of each
+fixture, INCLUDING files a part's later chapters add (the daily loop's
+`docs/draft.md`, `public/style.css` + generated pages, the renamed
+`new-page` command, `AGENTS.sm`; the portfolio's `DEPLOYMENT.md`
+rename). `fixtures.js clear <footprint>` (part-entry resets) and
+`state.js wipe` (start-over) both read it, so the per-fixture path list
+lives in ONE place. Add or drop a harness file there.
+
+## Changing a fixture
+
+Edit the data file under `fixtures-data/`; the chapter that teaches it
+reads the same file (the agent lays it with `fixtures.js`, or shows it
+to the tester with `fixtures.js cat <set> --file <relpath>`). There is
+no second copy to keep in sync. After any change, rebuild
+(`pnpm --filter @skill-map/cli build`) so the byte-for-byte payload
+test sees the new bytes.
+
+## Authoring notes (still apply)
+
+- **A `command` node's H1 is a plain title (`# publish`), never the
+  slash form (`# /publish`).** The `slash` extractor reads a `/name`
+  token anywhere in the body (the H1 included) as an `invoke`, so
+  `# /publish` makes the command invoke itself and `sm check` emits a
+  spurious `core/link-self-loop`. Holds for every command fixture
+  (`demo-command`, `publish`, the daily-loop `init`).
+- **No backtick-wrapped relative `.md` paths in `AGENTS.md`'s body.**
+  `core/backtick-path` turns a `` `docs/STYLE.md` `` in a code span
+  into a `points` link; at kickoff (before `docs/` exists) that lands
+  as a broken reference and breaks the "one lonely node" beat. Name
+  the docs in prose, never as backticked paths.

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

@@ -282,5 +282,4 @@ Mark `authoring-6-upgrade: done`.
 >
 > Anything weird worth logging? If not, back to the menu.
 
-Mark the authoring 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`.

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

@@ -92,7 +92,13 @@ Mark `annotations`: done.
 
 **Context**: until now the map 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 map.
 
-**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.
+**Setup (you, silent)**: lay the fixture under the tutorial cwd so both sub-projects are siblings of each other but children of the tutorial root (its content + translation live in `fixtures-data/`). No confirmation beat needed, the tester learns about the files in the next message. Backstage (silent):
+
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay cli-external --provider <provider> --lang <lang>
+```
+
+The fixture lays:
 
 ```
 link-validation/
@@ -102,35 +108,6 @@ link-validation/
     └── 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.
----
-
-# 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.
----
-
-# External spec
-
-Anything that hijoA points at lives here.
-```
-
 Once the files are in place, tell the tester:
 
 > I just dropped two sibling folders inside the tutorial cwd:

package/dist/cli/tutorial/sm-tutorial/references/part-connect-harness.md

@@ -6,25 +6,12 @@ This is the wiring part. Part 1 grew a small set of standalone nodes around the
 
 **Context**: the harness needs a guard that runs before publishing: a skill that walks every page and checks the internal links resolve. We only create it here (its first standalone `skill` node); the `publish` command in the next chapter is what invokes it.
 
-`Write` `.claude/skills/check-links/SKILL.md` (substitute `<provider_dir>` per `_core.md`; this kind exists on every provider, so no skip):
+Lay the `check-links` skill (its content + translation live in
+`fixtures-data/`; this kind exists on every provider, so no skip).
+Backstage (silent):
 
-```markdown
----
-name: check-links
-description: |
-  Validates the portfolio's internal links before publishing. Walks
-  every generated page and reports any link whose target is missing.
----
-
-# check-links
-
-The last gate before the site goes out.
-
-## Steps
-1. List every HTML file under `public/`.
-2. For each page, collect its internal links (every `href` to `/` or to a `.html` file).
-3. Check the target exists under `public/` (treat `/` as `public/index.html`).
-4. Report any link whose target is missing; if none, report "0 broken links".
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay harness --only "__PROVIDER__/skills/check-links/SKILL.md" --provider <provider> --lang <lang>
 ```
 
 Tell the tester:
@@ -45,7 +32,7 @@ Wait for confirmation. Mark `check-links`: done.
 
 On `agent-skills` / Antigravity there is no `command` kind, so skip this whole chapter and fold its purpose into the prose of the next one.
 
-Tell the tester to create the file themselves (it is their project's file, Inviolable rule #2). Substitute `<provider_dir>` per `_core.md` in the path you give them. The frontmatter fence (`---`) MUST sit on column 0 with no leading spaces: present the block below exactly as written, and if the tester pastes it indented, have them strip the leading whitespace. An indented `---` does not parse as YAML, so the `publish` node would land without its `name` or `description`.
+Tell the tester to create the file themselves (it is their project's file, Inviolable rule #2). Substitute `<provider_dir>` per `_core.md` in the path you give them. Backstage, get the content: `node .claude/skills/sm-tutorial/scripts/fixtures.js cat harness --file "__PROVIDER__/commands/publish.md" --provider <provider> --lang <lang>`, then render it in the fenced block the tester copies. The frontmatter fence (`---`) MUST sit on column 0 with no leading spaces: present the block below exactly as written, and if the tester pastes it indented, have them strip the leading whitespace. An indented `---` does not parse as YAML, so the `publish` node would land without its `name` or `description`.
 
 > Create `.claude/commands/publish.md` with exactly this content (the first line is `---`, nothing before it):
 
@@ -97,19 +84,14 @@ Wait for confirmation. You MAY use `Read` on the file afterwards to verify it la
 
 **Context**: the handbook (`AGENTS.md`) has been a lonely node since Part 1. Here it becomes the hub: we add two bullets so it mentions the content editor and invokes the publish command. We also give the content editor a reference to the style guide it follows. Several connectors land, and we recap the three link kinds and which syntax produced each.
 
-Apply both edits with `Edit` (do not rewrite the files).
+Apply both edits (their content + translation live in `fixtures-data/`).
+The first appends the two hub bullets to `AGENTS.md`; the second adds
+the style-guide reference line to the content-editor (an agent target,
+so it folds away on `agent-skills`). Backstage (silent):
 
-**Edit `AGENTS.md`**: append these two bullets at the end of the body (substitute `<provider_dir>` only in prose, the link tokens below stay as written):
-
-```markdown
-- When a page needs writing or fixing, brief @content-editor.
-- When the site is ready to go out, run /publish.
 ```
-
-**Edit `.claude/agents/content-editor.md`**: add this line at the end of the body, after the `Rules:` line (substitute `<provider_dir>` per `_core.md`):
-
-```markdown
-Every page follows the [style guide](../../docs/STYLE.md).
+node .claude/skills/sm-tutorial/scripts/fixtures.js edit agents-hub --provider <provider> --lang <lang>
+node .claude/skills/sm-tutorial/scripts/fixtures.js edit content-editor-style --provider <provider> --lang <lang>
 ```
 
 Tell the tester:

package/dist/cli/tutorial/sm-tutorial/references/part-daily-loop.md

@@ -14,8 +14,9 @@ substitution, the `> ` rendering rule, the per-step cycle, §Closing a part,
 **The site is the tester's.** The `setup` chapter asks who it is for and builds
 it around that answer. Identity lives in Layer 2 (the HTML / CSS under
 `public/`), which skill-map does not map, so the graph stays identical no matter
-what the tester names their portfolio. Persist the answer in `tutorial-state.yml`
-under `tester.site_identity` (`{ name, tagline }`).
+what the tester names their portfolio. Persist the answer with
+`state.js set-identity --name "<name>" --tagline "<tagline>"` (it records
+`tester.site_identity` in `tutorial-state.json`).
 
 **Provider note (read once).** Substitute `.claude/` with the detected
 `<provider_dir>`. On `agent-skills` / Antigravity the `content-editor` is a
@@ -49,8 +50,9 @@ correct, not a bug.
 1. Ask the tester, in one short exchange: what the site should be called (their
    name or a title) and one line about what it is for. Keep it light; if they do
    not care, offer defaults ("My Portfolio" / "Small, sturdy things on the
-   web"). Save both into `tutorial-state.yml` under `tester.site_identity`
-   (`{ name, tagline }`).
+   web"). Persist both with
+   `node .claude/skills/sm-tutorial/scripts/state.js set-identity --name "<name>" --tagline "<tagline>"`
+   (it writes `tester.site_identity` into `tutorial-state.json`).
 2. Backstage, `Write` `public/style.css` exactly as below (Layer 2, ignored by
    the scan; one stylesheet shared by every page).
 3. `Write` `public/index.html` and `public/about.html` from the templates below,