@skill-map/cli 0.60.4 → 0.61.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/README.md +1 -1
  2. package/dist/cli/tutorial/sm-tutorial/SKILL.md +149 -266
  3. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/agents-hub/en/agents-hub.md +2 -0
  4. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/agents-hub/es/agents-hub.md +2 -0
  5. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/content-editor-style/en/content-editor-style.md +1 -0
  6. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/content-editor-style/es/content-editor-style.md +1 -0
  7. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/en/todo-bullet-agent.md +1 -0
  8. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/en/todo-bullet-command.md +1 -0
  9. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/en/todo-bullet-guideline.md +1 -0
  10. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/en/todo-bullet-guideline2.md +1 -0
  11. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/en/todo-bullet-skill.md +1 -0
  12. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/es/todo-bullet-agent.md +1 -0
  13. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/es/todo-bullet-command.md +1 -0
  14. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/es/todo-bullet-guideline.md +1 -0
  15. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/es/todo-bullet-guideline2.md +1 -0
  16. package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/es/todo-bullet-skill.md +1 -0
  17. package/dist/cli/tutorial/sm-tutorial/fixtures-data/manifest.json +87 -0
  18. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/cli-external/en/link-validation/hijoA/note-with-external-link.md +10 -0
  19. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/cli-external/en/link-validation/hijoB/spec.md +11 -0
  20. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/cli-external/es/link-validation/hijoA/note-with-external-link.md +10 -0
  21. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/cli-external/es/link-validation/hijoB/spec.md +11 -0
  22. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/harness/en/__PROVIDER__/commands/publish.md +15 -0
  23. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/harness/en/__PROVIDER__/skills/check-links/SKILL.md +16 -0
  24. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/harness/es/__PROVIDER__/commands/publish.md +16 -0
  25. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/harness/es/__PROVIDER__/skills/check-links/SKILL.md +17 -0
  26. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/en/__PROVIDER__/agents/master-agent.md +14 -0
  27. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/en/__PROVIDER__/skills/master-skill/SKILL.md +18 -0
  28. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/en/notes/ideas.md +11 -0
  29. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/es/__PROVIDER__/agents/master-agent.md +15 -0
  30. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/es/__PROVIDER__/skills/master-skill/SKILL.md +18 -0
  31. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/es/notes/ideas.md +11 -0
  32. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/en/AGENTS.md +6 -0
  33. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/en/__PROVIDER__/agents/content-editor.md +21 -0
  34. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/en/docs/DEPLOY.md +11 -0
  35. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/en/docs/STYLE.md +20 -0
  36. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/en/public/index.html +5 -0
  37. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/es/AGENTS.md +7 -0
  38. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/es/__PROVIDER__/agents/content-editor.md +21 -0
  39. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/es/docs/DEPLOY.md +12 -0
  40. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/es/docs/STYLE.md +21 -0
  41. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/es/public/index.html +5 -0
  42. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/shared/CLAUDE.md +1 -0
  43. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/shared/package.json +6 -0
  44. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/shared/server.js +11 -0
  45. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/en/__PROVIDER__/agents/demo-agent.md +18 -0
  46. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/en/__PROVIDER__/commands/demo-command.md +11 -0
  47. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/en/__PROVIDER__/skills/demo-skill/SKILL.md +16 -0
  48. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/en/notes/demo-guideline.md +16 -0
  49. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/en/notes/demo-guideline2.md +12 -0
  50. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/en/notes/private-credentials.md +11 -0
  51. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/en/notes/todo.md +9 -0
  52. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/es/__PROVIDER__/agents/demo-agent.md +18 -0
  53. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/es/__PROVIDER__/commands/demo-command.md +11 -0
  54. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/es/__PROVIDER__/skills/demo-skill/SKILL.md +16 -0
  55. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/es/notes/demo-guideline.md +16 -0
  56. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/es/notes/demo-guideline2.md +13 -0
  57. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/es/notes/private-credentials.md +11 -0
  58. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/es/notes/todo.md +9 -0
  59. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/universal/en/findings.md +10 -0
  60. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/universal/es/findings.md +10 -0
  61. package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/universal/shared/.skillmapignore +28 -0
  62. package/dist/cli/tutorial/sm-tutorial/references/_core.md +55 -40
  63. package/dist/cli/tutorial/sm-tutorial/references/_manifest.json +309 -0
  64. package/dist/cli/tutorial/sm-tutorial/references/_manifest.yml +1 -1
  65. package/dist/cli/tutorial/sm-tutorial/references/fixtures.md +94 -271
  66. package/dist/cli/tutorial/sm-tutorial/references/part-authoring.md +1 -2
  67. package/dist/cli/tutorial/sm-tutorial/references/part-cli.md +7 -30
  68. package/dist/cli/tutorial/sm-tutorial/references/part-connect-harness.md +12 -30
  69. package/dist/cli/tutorial/sm-tutorial/references/part-daily-loop.md +6 -4
  70. package/dist/cli/tutorial/sm-tutorial/references/part-fundamentals.md +14 -116
  71. package/dist/cli/tutorial/sm-tutorial/references/part-plugins.md +2 -3
  72. package/dist/cli/tutorial/sm-tutorial/references/part-project-kickoff.md +13 -65
  73. package/dist/cli/tutorial/sm-tutorial/scripts/fixtures.js +238 -0
  74. package/dist/cli/tutorial/sm-tutorial/scripts/lib/args.js +29 -0
  75. package/dist/cli/tutorial/sm-tutorial/scripts/lib/fixtures-manifest.js +32 -0
  76. package/dist/cli/tutorial/sm-tutorial/scripts/lib/io.js +37 -0
  77. package/dist/cli/tutorial/sm-tutorial/scripts/lib/manifest.js +24 -0
  78. package/dist/cli/tutorial/sm-tutorial/scripts/lib/paths.js +68 -0
  79. package/dist/cli/tutorial/sm-tutorial/scripts/state.js +262 -0
  80. package/dist/cli.js +7 -8
  81. package/dist/index.js +6 -4
  82. package/dist/kernel/index.js +6 -4
  83. package/dist/ui/chunk-FDBHGLTW.js +3 -0
  84. package/dist/ui/index.html +1 -1
  85. package/dist/ui/{main-VJJVD754.js → main-5GMGTLYQ.js} +1 -1
  86. package/package.json +5 -3
  87. package/dist/ui/chunk-DDDCORVR.js +0 -3
package/README.md CHANGED
@@ -45,7 +45,7 @@ The verb `sm tutorial` installs the skill directory under your agent's skill fol
45
45
 
46
46
  ```bash
47
47
  sm --version # single-line version
48
- sm version # multi-line matrix (sm / kernel / spec / runtime / db-schema)
48
+ sm version # multi-line matrix (sm / spec / runtime / db-schema)
49
49
  sm --help # top-level help
50
50
  sm init # scaffold .skill-map/ in the current scope, run first scan
51
51
  sm scan [roots...] [--json] # walk roots, persist scan_* tables; pretty or JSON
@@ -8,7 +8,7 @@ description: |
8
8
  further parts (extend skill-map with plugins/settings/slots, the
9
9
  CLI in depth). The skill is invoked from an empty directory and
10
10
  lays its fixture there directly. State persists in
11
- `tutorial-state.yml` for pause/resume. Triggers: "tutorial",
11
+ `tutorial-state.json` for pause/resume. Triggers: "tutorial",
12
12
  "sm-tutorial", "tutorial me", "run the tutorial", "ejecuta el
13
13
  tutorial", "test skill-map", "advanced tutorial", "go deeper",
14
14
  "tutorial avanzado".
@@ -66,13 +66,13 @@ ls -A
66
66
  **Items you ignore** when evaluating "empty" (internal
67
67
  infrastructure, not user content): `.claude` (skills/agents infra),
68
68
  `.tmp` (Claude Code scratch dir), `SKILL.md` / `sm-tutorial.md`
69
- (loose copies of this skill), `tutorial-state.yml` (resume mode).
69
+ (loose copies of this skill), `tutorial-state.json` (resume mode).
70
70
 
71
71
  The whitelist is internal; do NOT enumerate it to the tester.
72
72
 
73
73
  **Order of checks**:
74
74
 
75
- 1. Look at the **raw** `ls -A`. If `tutorial-state.yml` is present
75
+ 1. Look at the **raw** `ls -A`. If `tutorial-state.json` is present
76
76
  → **resume mode** (see §Resume / restart in `_core.md`); stop
77
77
  here and follow that branch.
78
78
  2. Otherwise apply the ignore filter:
@@ -129,8 +129,10 @@ version` errors, suspect an old Node (`node --version`).
129
129
 
130
130
  ### 3. Provider detection
131
131
 
132
- Apply §Provider detection from `_core.md`. Persist the result into
133
- `tutorial.provider` in the state file.
132
+ Apply §Provider detection from `_core.md`. Hold the result (provider
133
+ + `<provider_dir>`); it is persisted into `tutorial.provider` by
134
+ `state init` in step 5. Also note the tester's language (`en` / `es`,
135
+ per §Language mirroring) to pass as `--lang`.
134
136
 
135
137
  ### 4. Two-terminals heads-up (one time)
136
138
 
@@ -159,266 +161,154 @@ cd <cwd>
159
161
  > Got the second terminal open and anchored to the folder? Confirm
160
162
  > before we move on.
161
163
 
162
- ### 5. Write the universal files and show the menu
164
+ ### 5. Initialise state, lay the universal files, show the menu
163
165
 
164
166
  Pre-flight does NOT pre-lay any part's fixture and does NOT auto-enter
165
- a part. It writes only the universal files every part needs, then
166
- routes to the menu:
167
-
168
- - `.skillmapignore` (block below). Universal, not a part fixture:
169
- every part scans, and every part needs the tutorial's own machinery
170
- kept out of the map (this skill's `.claude/skills/sm-tutorial/` dir,
171
- `findings.md`, `tutorial-state.yml`, the CLI part's
172
- `link-validation/`, and so on). Ignore that tutorial skill dir ONLY,
173
- never the whole `.claude/` (or detected `<provider_dir>/`): the
174
- harness agents, commands, and skills the tester builds live under it
175
- and must stay on the map. Writing it here, once, before any
176
- `sm init`, is what guarantees no part-entry can forget it on a
177
- direct jump from the menu. `sm init` only writes `.skillmapignore`
178
- when it is absent, so the tester's later `sm init` leaves this one
179
- intact. Parts that need more append their own lines on entry (the
180
- portfolio's `node_modules/` and `public/`).
181
- - `findings.md` (block below).
182
- - `tutorial-state.yml` (template below; it starts with `parts: {}`,
183
- empty, a part's entry is added the first time the tester picks it).
167
+ a part. It initialises state, lays the universal files every part
168
+ needs, then routes to the menu. All silent (backstage):
184
169
 
185
- Then **route** per §Routing + menu in `_core.md`: render the **start
186
- menu** (numbered, Part 0 the prologue as option 1, the recommended
187
- first pick). The tester picks a part by number; that part's own
188
- `preflight` (see §Entering a part) lays its fixture when it begins.
189
- Part 0's demo fixture (the `demo-agent` block below) is laid by its
190
- `taught-init` entry, not here.
191
-
192
- ## Fixture and state templates
193
-
194
- The `.skillmapignore`, `findings.md`, and `tutorial-state.yml` here are
195
- universal (written in pre-flight); the `demo-agent.md` is Part 0's
196
- fixture (laid by its `taught-init` entry).
197
-
198
- The **full Part 0 demo fixture** is the boot `demo-agent.md` above plus
199
- the files the prologue's own chapters lay as taught steps, exactly this
200
- set: `<provider_dir>/agents/demo-agent.md`,
201
- `<provider_dir>/skills/demo-skill/`,
202
- `<provider_dir>/commands/demo-command.md`, `notes/todo.md`,
203
- `notes/demo-guideline.md`, `notes/demo-guideline2.md`,
204
- `notes/private-credentials.md`. This is the
205
- single source for that list. Four entry points delete exactly this set
206
- when the prologue ran first in the dir: `portfolio-init`, the campaign
207
- `seed` fast-forward, and `backstage-init` (Part 4), each so the part's
208
- own fixture starts from a clean slate, plus start-over (§Menu, resume,
209
- wrap-up). Part 5 `cli` is the inverse
210
- consumer: its `prologue-built` seed *lays* this fixture (the
211
- connector-chapter subset, without `notes/private-credentials.md`)
212
- instead of deleting it, see `fixtures.md` §Seed snapshots. Keep the list
213
- here in sync if a prologue chapter adds or drops a demo file.
214
-
215
- `<provider_dir>/agents/demo-agent.md`:
216
- ```markdown
217
- ---
218
- name: demo-agent
219
- description: |
220
- Example agent that handles read and shell tasks. Solo node at
221
- boot; gets connected to the rest of the demo fixture during the
222
- Live UI step.
223
- tools: [Read, Bash]
224
- model: sonnet
225
- ---
226
-
227
- # demo-agent
228
-
229
- Processes inputs and logs every action to stderr. Will be wired up
230
- to the rest of the demo fixture later in the walkthrough.
231
-
232
- Rules:
233
- - Never run destructive commands without confirmation.
234
- - Log every action to stderr.
235
- ```
170
+ - Create the state file (carries the detected provider, the running
171
+ `sm version`, the cwd, and the tester's language):
236
172
 
237
- `findings.md`:
238
- ```markdown
239
- # Findings: sm-tutorial
173
+ ```bash
174
+ node .claude/skills/sm-tutorial/scripts/state.js init \
175
+ --cwd "$(pwd)" --sm-version "<sm version>" --provider <provider> --lang <en|es>
176
+ ```
240
177
 
241
- If you spot anything weird during the tutorial, log it here.
178
+ - Lay the universal files (`.skillmapignore` + `findings.md`) ONCE,
179
+ before any `sm init`:
242
180
 
243
- Per finding:
244
- - **Chapter**: <id>
245
- - **Command**: `sm ...`
246
- - **Expected**: ...
247
- - **Got**: ...
248
- - **Notes**: ...
249
- ```
250
-
251
- `.skillmapignore` (tutorial entries + the minimum bundle defaults
252
- the tutorial exercises; mirror new lines from
253
- `src/config/defaults/skillmapignore` if a chapter starts exercising
254
- them):
255
- ```
256
- # Bundled defaults that matter inside the tutorial scope.
257
- .git/
258
- .skill-map/
259
- .tmp/
260
- .DS_Store
261
-
262
- # sm-tutorial internal files. Without these, the first sm init scan
263
- # reports the tutorial's own .md files as project nodes.
264
- sm-tutorial.md
265
- findings.md
266
- tutorial-state.yml
267
-
268
- # sm-tutorial skill installation (loaded as a project-local skill).
269
- .claude/skills/sm-tutorial/
270
- .agents/skills/sm-tutorial/
271
-
272
- # Tutorial outputs that may land at the root.
273
- export.*
274
- dump.sql
275
-
276
- # The reference-paths chapter spawns a self-contained sub-project
277
- # under link-validation/hijoA with its own .skill-map/.
278
- link-validation/
279
- ```
181
+ ```bash
182
+ node .claude/skills/sm-tutorial/scripts/fixtures.js lay universal --provider <provider> --lang <en|es>
183
+ ```
280
184
 
281
- `tutorial-state.yml` (state shape **version 2**: a `parts.<id>`
282
- map, each with a `chapters.<id>.status`):
283
- ```yaml
284
- tutorial:
285
- version: 2
286
- started_at: "<ISO-8601 now>"
287
- cwd: "<output of pwd>"
288
- sm_version: "<output of sm version>"
289
- provider: "<claude | agent-skills | antigravity>"
290
- tester:
291
- level: 2
292
- # site_identity: { name, tagline } is added by the daily-loop `setup`
293
- # chapter when the tester names their portfolio; absent until then.
294
- parts: {} # filled in as the tester picks parts from the menu
295
- findings_file: "./findings.md"
296
- ```
185
+ The `.skillmapignore` keeps the tutorial's own machinery out of the
186
+ map (this skill's dir, `findings.md`, `tutorial-state.json`, the CLI
187
+ part's `link-validation/`, the campaign's `node_modules/` and
188
+ `public/`). It ignores the tutorial skill dir ONLY, never the whole
189
+ `<provider_dir>/`: the harness the tester builds lives under it and
190
+ must stay on the map. Laying it here once guarantees no part-entry
191
+ can forget it; a later `sm init` only writes `.skillmapignore` when
192
+ absent, so it leaves this one intact.
297
193
 
298
- When the tester picks a part from the menu, add its `parts.<id>`
299
- entry the first time it starts, seeded from the manifest, e.g.:
300
-
301
- ```yaml
302
- parts:
303
- fundamentals:
304
- status: "in_progress" # not_started | in_progress | done | declined | skipped
305
- chapters:
306
- init: { status: "pending" } # pending | done | failed | skipped
307
- kinds: { status: "pending" }
308
- # … one row per chapter in the part's manifest entry
309
- ```
194
+ Then **route** per §Routing + menu in `_core.md`: render the **start
195
+ menu** (numbered, Part 0 the prologue as option 1, the recommended
196
+ first pick). The tester picks a part by number; that part's own
197
+ `preflight` (see §Entering a part) lays its fixture when it begins.
310
198
 
311
- Planned parts are not tracked until they have content. Parts the
312
- `seed` mechanism fast-forwards past are recorded with `status:
313
- "skipped"`.
199
+ ## Fixtures and state: data + scripts (no inline content)
200
+
201
+ All laid content lives in `fixtures-data/` and is laid by
202
+ `scripts/fixtures.js`; progress lives in `tutorial-state.json` and is
203
+ owned by `scripts/state.js`. **You never embed file content in a
204
+ message or hand-edit the state file.** See `references/fixtures.md`
205
+ for the data layout and the verb surface.
206
+
207
+ - **Fixture sets** (laid by `fixtures.js lay <set>` / `seed <snap>`):
208
+ `universal` (the two files above), `prologue` (the Part 0 demo),
209
+ `portfolio` (Part 1 boot + harness members), `harness` (the Part 2
210
+ additions), `master` (Part 4), `cli-external` (Part 5
211
+ reference-paths). The script resolves the `__PROVIDER__` token,
212
+ skips kinds the provider does not claim, and reports `nodeCount` +
213
+ `skipped` for you to narrate.
214
+ - **Footprints** (the on-disk reach of each fixture, including files a
215
+ part's later chapters add) live once in `fixtures-data/manifest.json`
216
+ and back both `fixtures.js clear <footprint>` (part-entry resets)
217
+ and `state.js wipe` (start-over). Add or drop a harness file there,
218
+ not in this prose.
219
+ - **State**: `state.js init` (pre-flight), `pick <part>` (on entry,
220
+ seeds the chapter rows from the manifest), `mark <part> <chapter>
221
+ done|failed|skipped` (after every chapter, Inviolable rule #4),
222
+ `set-part <part> skipped` (predecessors a seed fast-forwards past),
223
+ `set-identity` (the daily-loop `setup` chapter), `status` (menu /
224
+ resume render). The shape is version 2: `tutorial` (version,
225
+ started_at, cwd, sm_version, provider, lang), `tester` (level,
226
+ optional `site_identity`), `parts.<id>.{status, chapters.<id>.status}`,
227
+ `findings_file`.
314
228
 
315
229
  ## Entering a part
316
230
 
317
- When a part begins, honour its `preflight` from the manifest:
318
-
319
- - **`taught-init`** (Part 0): silently, before the tester's `sm init`
320
- in the `init` chapter, `Write` the demo fixture (the
321
- `<provider_dir>/agents/demo-agent.md` boot node, in the §Fixture
322
- blocks above), substituting `<provider_dir>` per detection. The
323
- universal `.skillmapignore` is already on disk from pre-flight, so
324
- the first scan never sees the tutorial's own files; nothing to lay
325
- here for it. The tester runs `sm init` themselves in the first
326
- chapter (`sm init` only writes `.skillmapignore` when absent, so it
327
- leaves the pre-flight one intact).
328
- - **`portfolio-init`** (Part 1 `project-kickoff`): the campaign's
329
- real project begins. Backstage, before the tester's `sm init` in
330
- the `kickoff` chapter: (1) if the prologue ran first in this dir,
331
- clear its demo fixture so the map starts clean, delete ONLY the full
332
- Part 0 demo fixture set (§Fixture and state templates) plus the
333
- stale `.skill-map/` DB (a fresh `sm init` rebuilds it), never the
334
- tester's own files; (2) `Write` the portfolio fixture from
335
- `references/fixtures.md` (the Express skeleton + the handbook
336
- `AGENTS.md`); (3) append the portfolio additions (`node_modules/`,
337
- `public/`) to the universal `.skillmapignore` pre-flight already
338
- wrote (its tutorial internals are already there). The tester runs `sm init`
339
- themselves in the first chapter. (The later campaign parts use
340
- `preflight: seed` to fast-forward into them directly, see the `seed`
341
- case below; `portfolio-init` is just Part 1's flavour of that,
231
+ On entry, first run `state.js pick <partId>` (idempotent; seeds the
232
+ chapter rows from the manifest). Then honour the part's `preflight`.
233
+ All commands below are backstage (silent); fill `<provider>` and
234
+ `<lang>` from `tutorial.{provider,lang}`. The fixture scripts resolve
235
+ the `__PROVIDER__` token and skip kinds the provider does not claim.
236
+
237
+ - **`taught-init`** (Part 0 `fundamentals`): the prologue reveals its
238
+ fixture progressively, so on entry lay ONLY the boot node, just
239
+ before the tester's `sm init` in the `init` chapter:
240
+
241
+ ```bash
242
+ node .claude/skills/sm-tutorial/scripts/fixtures.js lay prologue --only "__PROVIDER__/agents/demo-agent.md" --provider <provider> --lang <lang>
243
+ ```
244
+
245
+ The universal `.skillmapignore` is already on disk, so the first
246
+ scan never sees the tutorial's own files. The tester runs `sm init`
247
+ themselves in the first chapter; the `kinds` and `ignore` chapters
248
+ lay the rest of the set (`lay prologue --only …`) and `connectors`
249
+ wires the hub (`edit todo-connectors`).
250
+
251
+ - **`portfolio-init`** (Part 1 `project-kickoff`): the real project
252
+ begins. Backstage, before the tester's `sm init` in the `kickoff`
253
+ chapter:
254
+ 1. If the prologue ran first here, clear it and drop the stale DB:
255
+ `fixtures.js clear prologue --provider <provider>` then
256
+ `rm -rf .skill-map`.
257
+ 2. Lay the portfolio boot (Express skeleton + handbook):
258
+ `fixtures.js lay portfolio --only "AGENTS.md,server.js,package.json,public/index.html" --provider <provider> --lang <lang>`.
259
+ The harness members (`CLAUDE.md`, `content-editor`, the docs) are
260
+ laid by their own chapters.
261
+
262
+ The tester runs `sm init` in the first chapter. (Later campaign
263
+ parts use `preflight: seed`; `portfolio-init` is Part 1's flavour,
342
264
  handling the Part 0 to Part 1 transition.)
343
- - **`backstage-init`** (Part 4 `extend`): the part teaches plugins on
344
- its own **master fixture**, distinct from both the demo and the
345
- portfolio, so on entry make the master fixture the only one on disk.
346
- Silently, with no narration: (1) clear whatever prior-part fixture is
347
- present so the master map starts clean (never the tester's own files;
348
- the universal `.skillmapignore` stays):
349
- - Part 0 demo fixture present (the tester came from the prologue)
350
- delete the full Part 0 demo fixture set (§Fixture and state
351
- templates);
352
- - portfolio fixture present instead (the tester ran the campaign)
353
- delete everything `portfolio-init` and the campaign chapters lay
354
- (see `fixtures.md` §Portfolio fixture + §Seed snapshots);
355
- - in either of those cases also drop the stale `.skill-map/` DB so a
356
- fresh init rebuilds it.
357
- (2) run `sm init --no-scan` from the cwd (the universal
358
- `.skillmapignore` from pre-flight is already on disk, so init leaves
359
- it intact and the tutorial's own files stay out of the scan); (3)
360
- `Write` the part's fixture (read `references/fixtures.md` for the
361
- verbatim `master-agent` / `master-skill` / `notes/ideas` files; skip
362
- kinds the provider doesn't claim). If nothing needed clearing and the
363
- dir was already initialised with the master fixture in place (Part 4
364
- re-entry), that is fine: skip the init and just ensure the fixture
365
- files are present.
366
- - **`seed: prologue-built`** (Part 5 `cli`): the part reads the **Part 0
367
- demo fixture**, NOT the cumulative portfolio, so on entry make that
368
- fixture the one on disk. Read the state, then:
369
- - Demo fixture already present (the tester came straight from the
370
- prologue) just `sm scan`, nothing to lay.
371
- - **Portfolio** fixture present instead (the tester ran the campaign)
372
- → clear it first (the inverse of `portfolio-init`: delete the
373
- portfolio fixture, everything `portfolio-init` and the campaign
374
- chapters lay, see `fixtures.md` §Portfolio fixture + §Seed snapshots,
375
- plus the stale `.skill-map/` DB; never the tester's own files), then
376
- lay the `prologue-built` snapshot from `fixtures.md` (§Seed
377
- snapshots), `sm init`, `sm scan`.
378
- - Nothing there → lay the snapshot, `sm init`, `sm scan`.
379
- - **`seed`** (the campaign parts `connect-harness` and `daily-loop`):
380
- the part builds on the accumulating portfolio harness, but the tester
381
- may have jumped straight here from the menu. On entry, read the state
382
- file:
383
- - If every predecessor campaign part up the `prereq` chain is `done`
384
- reuse the accumulated state; an `sm scan` to refresh is enough,
385
- nothing to lay.
386
- - Else → **fast-forward, silently** (backstage, do not narrate the
387
- plumbing): first, if the prologue ran first in this dir, clear the
388
- full Part 0 demo fixture set (§Fixture and state templates) so the
389
- seeded campaign map does not carry the prologue's demo nodes (the
390
- `sm scan` below reconciles the removed files out of the DB). Then
391
- lay the part's `seed` snapshot from
392
- `references/fixtures.md` (§Seed snapshots) by following its
393
- checklist, copy each file's canonical content from the chapter the
394
- row names, apply the `EDIT` rows on top, substituting
395
- `<provider_dir>` and skipping provider-unsupported kinds per
396
- `_core.md`. The snapshot's `.skillmapignore` additions
397
- (`node_modules/`, `public/`) are appended to the universal
398
- `.skillmapignore` pre-flight already wrote, so the tutorial's own
399
- `.claude/skills/sm-tutorial/` files stay out of the scan even on a
400
- direct jump here. Then provision the DB if `.skill-map/` is missing,
401
- with the **non-interactive lens recipe**: the seeded portfolio has
402
- BOTH a root `AGENTS.md` (an `openai` marker) and `.claude/` (a
403
- `claude` marker), so a plain `sm init` would stop on the
404
- `⚠ Multiple provider markers detected` prompt with no tester to
405
- answer it. Instead run `sm init --no-scan` (skips first-scan
406
- detection, never prompts; it will not overwrite that
407
- `.skillmapignore`), then `sm config set activeProvider claude`, then
408
- `sm scan` so the map reflects the seeded harness under the claude
409
- lens. (If `.skill-map/` already exists, just `sm scan`.) Mark the
410
- skipped predecessor campaign parts `skipped` in the state (they stay
411
- in the menu for later). Then emit exactly ONE tester-facing line:
412
-
413
- > I set the project up to where this part begins, so you can start
414
- > here. The earlier parts that build up to this are still in the
415
- > menu if you want them later.
416
-
417
- Either way, then walk the part's chapters.
418
-
419
- Then walk the part's chapters in manifest order, dispatching each
420
- chapter id to its `step_file` per the §Per-step cycle in `_core.md`
421
- and the part's `pace`.
265
+
266
+ - **`backstage-init`** (Part 4 `extend`): teaches plugins on its own
267
+ **master fixture**. On entry, silently:
268
+ 1. Clear whatever prior fixture is present (each a no-op when absent),
269
+ then drop the DB: `fixtures.js clear prologue --provider <provider>`,
270
+ `fixtures.js clear portfolio --provider <provider>`, `rm -rf .skill-map`.
271
+ 2. `sm init --no-scan` (the pre-flight `.skillmapignore` stays).
272
+ 3. `fixtures.js lay master --provider <provider> --lang <lang>`.
273
+
274
+ On a Part 4 re-entry where the master fixture is already in place the
275
+ clears + lay are idempotent; just `sm scan`.
276
+
277
+ - **`seed: prologue-built`** (Part 5 `cli`): reads the Part 0 demo
278
+ fixture, NOT the portfolio. On entry:
279
+ 1. If the portfolio is present, clear it + drop the DB:
280
+ `fixtures.js clear portfolio --provider <provider>`, `rm -rf .skill-map`.
281
+ 2. `fixtures.js seed prologue-built --provider <provider> --lang <lang>`
282
+ (lays the six demo nodes, wires the hub, drops `private-credentials`).
283
+ 3. `sm init` (single `.claude/` marker, no lens prompt), then `sm scan`.
284
+ If the demo was already on disk and `.skill-map/` exists, just `sm scan`.
285
+
286
+ - **`seed`** (campaign parts `connect-harness`, `daily-loop`): builds
287
+ on the accumulating portfolio, but the tester may have jumped here.
288
+ Run `state.js status`; if every predecessor up the `prereq` chain is
289
+ `done`, the harness is already on disk, just `sm scan`. Otherwise
290
+ **fast-forward, silently**:
291
+ 1. If the prologue ran first here, `fixtures.js clear prologue --provider <provider>`.
292
+ 2. Seed: `fixtures.js seed <harness-built|harness-connected> --provider <provider> --lang <lang>`
293
+ (`harness-built` for `connect-harness`, `harness-connected` for
294
+ `daily-loop`).
295
+ 3. Provision with the **non-interactive lens recipe**: the seeded
296
+ portfolio has BOTH a root `AGENTS.md` (an `openai` marker) and
297
+ `.claude/` (a `claude` marker), so a plain `sm init` would stop on
298
+ `⚠ Multiple provider markers detected`. Run `sm init --no-scan`,
299
+ then `sm config set activeProvider claude`, then `sm scan`. (If
300
+ `.skill-map/` already exists, just `sm scan`.)
301
+ 4. Mark the skipped predecessors: `state.js set-part <predecessor> skipped`
302
+ for each (they stay in the menu). Then emit exactly ONE
303
+ tester-facing line:
304
+
305
+ > I set the project up to where this part begins, so you can start
306
+ > here. The earlier parts that build up to this are still in the
307
+ > menu if you want them later.
308
+
309
+ Either way, then walk the part's chapters in manifest order,
310
+ dispatching each chapter id to its `step_file` per the §Per-step cycle
311
+ in `_core.md` and the part's `pace`.
422
312
 
423
313
  ## Menu, resume, wrap-up
424
314
 
@@ -432,19 +322,12 @@ All three are specified in `_core.md`:
432
322
  `cli` now self-seeds) is the entry point on the first
433
323
  invocation and after every part closes / on resume. Render it with
434
324
  the format in `_core.md` §Menu format.
435
- - **Resume / restart**: §Resume / restart. On start-over, the exact
436
- wipe list is whatever the tester's parts actually created:
437
- `tutorial-state.yml`, `findings.md`, `.skillmapignore`,
438
- `.skill-map/`, the full Part 0 demo fixture set (§Fixture and state
439
- templates), the portfolio fixture if any campaign part ran (see
440
- `fixtures.md` §Portfolio fixture + §Seed snapshots, including the Daily
441
- Loop's own additions: `docs/draft.md`, `public/style.css` and the
442
- generated pages, the renamed `new-page` command, `AGENTS.sm`, and
443
- `.skill-map/settings.local.json`), the Part 4 fixture if `extend` ran
444
- (`<provider_dir>/agents/master-agent.md`,
445
- `<provider_dir>/skills/master-skill/`, `notes/ideas.md`,
446
- `.skill-map/plugins/`), `link-validation/` if the CLI part ran,
447
- and any `export.*` / `dump.sql`. Confirm `pwd` matches
448
- `tutorial.cwd` and require the literal `yes, wipe`.
325
+ - **Resume / restart**: §Resume / restart. On start-over you do NOT
326
+ enumerate paths by hand: `state.js wipe-list` computes the exact set
327
+ from the parts the state records (universals + each tracked part's
328
+ footprint from `fixtures-data/manifest.json`, including a part's
329
+ later-chapter additions, plus any `export.*` / `dump.sql`), and
330
+ re-checks `pwd` against `tutorial.cwd`. Show its `paths`, require the
331
+ literal `yes, wipe`, then `state.js wipe --confirm`.
449
332
  - **Final wrap-up**: §Final wrap-up. Reached when the tester says
450
333
  they're done or finishes every available part.
@@ -0,0 +1,2 @@
1
+ - When a page needs writing or fixing, brief @content-editor.
2
+ - When the site is ready to go out, run /publish.
@@ -0,0 +1,2 @@
1
+ - Cuando una página necesita escribirse o arreglarse, informa a @content-editor.
2
+ - Cuando el sitio esté listo para salir, corre /publish.
@@ -0,0 +1 @@
1
+ Every page follows the [style guide](../../docs/STYLE.md).
@@ -0,0 +1 @@
1
+ Cada página sigue la [guía de estilo](../../docs/STYLE.md).
@@ -0,0 +1 @@
1
+ - [ ] Brief @demo-agent on the rough edges.
@@ -0,0 +1 @@
1
+ - [ ] Run /demo-command before publishing.
@@ -0,0 +1 @@
1
+ - [ ] Ping @demo-guideline if the conventions change.
@@ -0,0 +1 @@
1
+ - [ ] Ping @demo-guideline2.md if the conventions change.
@@ -0,0 +1 @@
1
+ - [ ] Trigger /demo-skill when the input lands.
@@ -0,0 +1 @@
1
+ - [ ] Informa a @demo-agent sobre los detalles pendientes.
@@ -0,0 +1 @@
1
+ - [ ] Ejecuta /demo-command antes de publicar.
@@ -0,0 +1 @@
1
+ - [ ] Avisa a @demo-guideline si cambian las convenciones.
@@ -0,0 +1 @@
1
+ - [ ] Avisa a @demo-guideline2.md si cambian las convenciones.
@@ -0,0 +1 @@
1
+ - [ ] Dispara /demo-skill cuando llegue la entrada.
@@ -0,0 +1,87 @@
1
+ {
2
+ "providerToken": "__PROVIDER__",
3
+ "langs": ["en", "es"],
4
+ "defaultLang": "en",
5
+ "comment": "Index for the tutorial fixture engine. `sets` name the directories under sets/<name>/{shared,<lang>}/ whose files lay/seed/clear act on; kind is derived from the __PROVIDER__/agents|commands|skills path prefix (else markdown). `footprints` are the full on-disk reach of a fixture (set files PLUS files taught later in its chapters) and are the single source for both `fixtures.js clear` and `state.js wipe`. `edits` append fragment files; `requiresKind` drops a fragment (or whole edit, via its target's kind) on a provider that does not claim that kind.",
6
+ "sets": ["universal", "prologue", "portfolio", "harness", "master", "cli-external"],
7
+ "footprints": {
8
+ "prologue": [
9
+ "__PROVIDER__/agents/demo-agent.md",
10
+ "__PROVIDER__/skills/demo-skill",
11
+ "__PROVIDER__/commands/demo-command.md",
12
+ "notes/todo.md",
13
+ "notes/demo-guideline.md",
14
+ "notes/demo-guideline2.md",
15
+ "notes/private-credentials.md"
16
+ ],
17
+ "portfolio": [
18
+ "AGENTS.md",
19
+ "CLAUDE.md",
20
+ "server.js",
21
+ "package.json",
22
+ "AGENTS.sm",
23
+ "public/index.html",
24
+ "public/about.html",
25
+ "public/projects.html",
26
+ "public/posts.html",
27
+ "public/style.css",
28
+ "docs/STYLE.md",
29
+ "docs/DEPLOY.md",
30
+ "docs/DEPLOYMENT.md",
31
+ "docs/draft.md",
32
+ "__PROVIDER__/agents/content-editor.md",
33
+ "__PROVIDER__/skills/check-links",
34
+ "__PROVIDER__/commands/publish.md",
35
+ "__PROVIDER__/commands/new-page.md"
36
+ ],
37
+ "master": [
38
+ "__PROVIDER__/agents/master-agent.md",
39
+ "__PROVIDER__/skills/master-skill",
40
+ "notes/ideas.md"
41
+ ],
42
+ "cli-external": [
43
+ "link-validation"
44
+ ]
45
+ },
46
+ "edits": {
47
+ "todo-connectors": {
48
+ "target": "notes/todo.md",
49
+ "prefix": "\n",
50
+ "fragments": [
51
+ { "file": "todo-bullet-agent.md", "requiresKind": "agent" },
52
+ { "file": "todo-bullet-command.md", "requiresKind": "command" },
53
+ { "file": "todo-bullet-skill.md", "requiresKind": "skill" },
54
+ { "file": "todo-bullet-guideline.md", "requiresKind": "markdown" },
55
+ { "file": "todo-bullet-guideline2.md", "requiresKind": "markdown" }
56
+ ]
57
+ },
58
+ "agents-hub": {
59
+ "target": "AGENTS.md",
60
+ "prefix": "\n",
61
+ "fragments": [
62
+ { "file": "agents-hub.md" }
63
+ ]
64
+ },
65
+ "content-editor-style": {
66
+ "target": "__PROVIDER__/agents/content-editor.md",
67
+ "prefix": "\n",
68
+ "fragments": [
69
+ { "file": "content-editor-style.md" }
70
+ ]
71
+ }
72
+ },
73
+ "seeds": {
74
+ "prologue-built": {
75
+ "lay": ["prologue"],
76
+ "edits": ["todo-connectors"],
77
+ "drop": ["notes/private-credentials.md"]
78
+ },
79
+ "harness-built": {
80
+ "lay": ["portfolio"]
81
+ },
82
+ "harness-connected": {
83
+ "lay": ["portfolio", "harness"],
84
+ "edits": ["agents-hub", "content-editor-style"]
85
+ }
86
+ }
87
+ }