@skill-map/cli 0.60.4 → 0.61.1

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 +161 -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 +85 -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 +16 -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 +16 -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 +60 -40
  63. package/dist/cli/tutorial/sm-tutorial/references/_manifest.json +304 -0
  64. package/dist/cli/tutorial/sm-tutorial/references/_manifest.yml +4 -5
  65. package/dist/cli/tutorial/sm-tutorial/references/fixtures.md +93 -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 +21 -40
  69. package/dist/cli/tutorial/sm-tutorial/references/part-daily-loop.md +107 -194
  70. package/dist/cli/tutorial/sm-tutorial/references/part-fundamentals.md +58 -143
  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 +22 -69
  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-DG3EAGXB.js +3 -0
  84. package/dist/ui/index.html +1 -1
  85. package/dist/ui/{main-VJJVD754.js → main-32BO6UKY.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,166 @@ 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
163
-
164
- 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).
164
+ **HARD STOP here.** This message ends at the confirmation question
165
+ above, that is its own beat. Do NOT run step 5, do NOT render the
166
+ menu, do NOT add a "meanwhile / mientras tanto" bridge in the same
167
+ message. Wait for the tester to confirm the second terminal is open
168
+ and anchored; only then continue to step 5.
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
170
+ ### 5. Initialise state, lay the universal files, show the menu
228
171
 
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
- ```
172
+ **Run this only after the tester has confirmed step 4.** Pre-flight
173
+ does NOT pre-lay any part's fixture and does NOT auto-enter a part. It
174
+ initialises state, lays the universal files every part needs, then
175
+ routes to the menu. The init + lay are silent (backstage); the menu is
176
+ the first thing the tester sees in this post-confirmation message:
236
177
 
237
- `findings.md`:
238
- ```markdown
239
- # Findings: sm-tutorial
178
+ - Create the state file (carries the detected provider, the running
179
+ `sm version`, the cwd, and the tester's language):
240
180
 
241
- If you spot anything weird during the tutorial, log it here.
181
+ ```bash
182
+ node .claude/skills/sm-tutorial/scripts/state.js init \
183
+ --cwd "$(pwd)" --sm-version "<sm version>" --provider <provider> --lang <en|es>
184
+ ```
242
185
 
243
- Per finding:
244
- - **Chapter**: <id>
245
- - **Command**: `sm ...`
246
- - **Expected**: ...
247
- - **Got**: ...
248
- - **Notes**: ...
249
- ```
186
+ - Lay the universal files (`.skillmapignore` + `findings.md`) ONCE,
187
+ before any `sm init`:
250
188
 
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
- ```
189
+ ```bash
190
+ node .claude/skills/sm-tutorial/scripts/fixtures.js lay universal --provider <provider> --lang <en|es>
191
+ ```
280
192
 
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
- ```
193
+ The `.skillmapignore` keeps the tutorial's own machinery out of the
194
+ map (this skill's dir, `findings.md`, `tutorial-state.json`, the CLI
195
+ part's `link-validation/`, the campaign's `node_modules/` and
196
+ `public/`). It ignores the tutorial skill dir ONLY, never the whole
197
+ `<provider_dir>/`: the harness the tester builds lives under it and
198
+ must stay on the map. Laying it here once guarantees no part-entry
199
+ can forget it; a later `sm init` only writes `.skillmapignore` when
200
+ absent, so it leaves this one intact.
297
201
 
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
- ```
202
+ Then **route** per §Routing + menu in `_core.md`: render the **start
203
+ menu** (numbered, Part 0 the prologue as option 1, the recommended
204
+ first pick). The tester picks a part by number; that part's own
205
+ `preflight` (see §Entering a part) lays its fixture when it begins.
310
206
 
311
- Planned parts are not tracked until they have content. Parts the
312
- `seed` mechanism fast-forwards past are recorded with `status:
313
- "skipped"`.
207
+ ## Fixtures and state: data + scripts (no inline content)
208
+
209
+ All laid content lives in `fixtures-data/` and is laid by
210
+ `scripts/fixtures.js`; progress lives in `tutorial-state.json` and is
211
+ owned by `scripts/state.js`. **You never embed file content in a
212
+ message or hand-edit the state file.** See `references/fixtures.md`
213
+ for the data layout and the verb surface.
214
+
215
+ - **Fixture sets** (laid by `fixtures.js lay <set>` / `seed <snap>`):
216
+ `universal` (the two files above), `prologue` (the Part 0 demo),
217
+ `portfolio` (Part 1 boot + harness members), `harness` (the Part 2
218
+ additions), `master` (Part 4), `cli-external` (Part 5
219
+ reference-paths). The script resolves the `__PROVIDER__` token,
220
+ skips kinds the provider does not claim, and reports `nodeCount` +
221
+ `skipped` for you to narrate.
222
+ - **Footprints** (the on-disk reach of each fixture, including files a
223
+ part's later chapters add) live once in `fixtures-data/manifest.json`
224
+ and back both `fixtures.js clear <footprint>` (part-entry resets)
225
+ and `state.js wipe` (start-over). Add or drop a harness file there,
226
+ not in this prose.
227
+ - **State**: `state.js init` (pre-flight), `pick <part>` (on entry,
228
+ seeds the chapter rows from the manifest), `mark <part> <chapter>
229
+ done|failed|skipped` (after every chapter, Inviolable rule #4),
230
+ `set-part <part> skipped` (predecessors a seed fast-forwards past),
231
+ `set-identity` (the daily-loop `setup` chapter), `status` (menu /
232
+ resume render). The shape is version 2: `tutorial` (version,
233
+ started_at, cwd, sm_version, provider, lang), `tester` (level,
234
+ optional `site_identity`), `parts.<id>.{status, chapters.<id>.status}`,
235
+ `findings_file`.
314
236
 
315
237
  ## Entering a part
316
238
 
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,
239
+ On entry, first run `state.js pick <partId>` (idempotent; seeds the
240
+ chapter rows from the manifest). Then honour the part's `preflight`.
241
+ All commands below are backstage (silent); fill `<provider>` and
242
+ `<lang>` from `tutorial.{provider,lang}`. The fixture scripts resolve
243
+ the `__PROVIDER__` token and skip kinds the provider does not claim.
244
+
245
+ - **`taught-init`** (Part 0 `fundamentals`): the prologue reveals its
246
+ fixture progressively, so on entry lay ONLY the boot node, just
247
+ before the tester's `sm init` in the `init` chapter:
248
+
249
+ ```bash
250
+ node .claude/skills/sm-tutorial/scripts/fixtures.js lay prologue --only "__PROVIDER__/agents/demo-agent.md" --provider <provider> --lang <lang>
251
+ ```
252
+
253
+ The universal `.skillmapignore` is already on disk, so the first
254
+ scan never sees the tutorial's own files. The tester runs `sm init`
255
+ themselves in the first chapter; the `kinds` and `ignore` chapters
256
+ lay the rest of the set (`lay prologue --only …`) and `connectors`
257
+ wires the hub (`edit todo-connectors`).
258
+
259
+ - **`portfolio-init`** (Part 1 `project-kickoff`): the real project
260
+ begins. Backstage, before the tester's `sm init` in the `kickoff`
261
+ chapter:
262
+ 1. If the prologue ran first here, clear it and drop the stale DB:
263
+ `fixtures.js clear prologue --provider <provider>` then
264
+ `rm -rf .skill-map`.
265
+ 2. Lay the portfolio boot (Express skeleton + handbook):
266
+ `fixtures.js lay portfolio --only "AGENTS.md,server.js,package.json,public/index.html" --provider <provider> --lang <lang>`.
267
+ The harness members (`CLAUDE.md`, `content-editor`, the docs) are
268
+ laid by their own chapters.
269
+
270
+ The tester runs `sm init` in the first chapter. (Later campaign
271
+ parts use `preflight: seed`; `portfolio-init` is Part 1's flavour,
342
272
  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`.
273
+
274
+ - **`backstage-init`** (Part 4 `extend`): teaches plugins on its own
275
+ **master fixture**. On entry, silently:
276
+ 1. Clear whatever prior fixture is present (each a no-op when absent),
277
+ then drop the DB: `fixtures.js clear prologue --provider <provider>`,
278
+ `fixtures.js clear portfolio --provider <provider>`, `rm -rf .skill-map`.
279
+ 2. `sm init --no-scan` (the pre-flight `.skillmapignore` stays).
280
+ 3. `fixtures.js lay master --provider <provider> --lang <lang>`.
281
+
282
+ On a Part 4 re-entry where the master fixture is already in place the
283
+ clears + lay are idempotent; just `sm scan`.
284
+
285
+ - **`seed: prologue-built`** (Part 5 `cli`): reads the Part 0 demo
286
+ fixture, NOT the portfolio. On entry:
287
+ 1. If the portfolio is present, clear it + drop the DB:
288
+ `fixtures.js clear portfolio --provider <provider>`, `rm -rf .skill-map`.
289
+ 2. `fixtures.js seed prologue-built --provider <provider> --lang <lang>`
290
+ (lays the six demo nodes, wires the hub, drops `private-credentials`).
291
+ Run this ALWAYS, even if a demo fixture from a prior prologue run is
292
+ on disk, so the deliberate broken reference is the pristine
293
+ `prologue-built` state, not whatever the tester edited in the
294
+ prologue (they resolve it by hand in `edit-link`).
295
+ 3. `sm init` (single `.claude/` marker, no lens prompt), then `sm scan`.
296
+ If `.skill-map/` already exists, skip the init and just `sm scan`.
297
+
298
+ - **`seed`** (campaign parts `connect-harness`, `daily-loop`): builds
299
+ on the accumulating portfolio, but the tester may have jumped here.
300
+ Run `state.js status`; if every predecessor up the `prereq` chain is
301
+ `done`, the harness is already on disk, just `sm scan`. Otherwise
302
+ **fast-forward, silently**:
303
+ 1. If the prologue ran first here, `fixtures.js clear prologue --provider <provider>`.
304
+ 2. Seed: `fixtures.js seed <harness-built|harness-connected> --provider <provider> --lang <lang>`
305
+ (`harness-built` for `connect-harness`, `harness-connected` for
306
+ `daily-loop`).
307
+ 3. Provision with the **non-interactive lens recipe**: the seeded
308
+ portfolio has BOTH a root `AGENTS.md` (an `openai` marker) and
309
+ `.claude/` (a `claude` marker), so a plain `sm init` would stop on
310
+ `⚠ Multiple provider markers detected`. Run `sm init --no-scan`,
311
+ then `sm config set activeProvider claude`, then `sm scan`. (If
312
+ `.skill-map/` already exists, just `sm scan`.)
313
+ 4. Mark the skipped predecessors: `state.js set-part <predecessor> skipped`
314
+ for each (they stay in the menu). Then emit exactly ONE
315
+ tester-facing line:
316
+
317
+ > I set the project up to where this part begins, so you can start
318
+ > here. The earlier parts that build up to this are still in the
319
+ > menu if you want them later.
320
+
321
+ Either way, then walk the part's chapters in manifest order,
322
+ dispatching each chapter id to its `step_file` per the §Per-step cycle
323
+ in `_core.md` and the part's `pace`.
422
324
 
423
325
  ## Menu, resume, wrap-up
424
326
 
@@ -432,19 +334,12 @@ All three are specified in `_core.md`:
432
334
  `cli` now self-seeds) is the entry point on the first
433
335
  invocation and after every part closes / on resume. Render it with
434
336
  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`.
337
+ - **Resume / restart**: §Resume / restart. On start-over you do NOT
338
+ enumerate paths by hand: `state.js wipe-list` computes the exact set
339
+ from the parts the state records (universals + each tracked part's
340
+ footprint from `fixtures-data/manifest.json`, including a part's
341
+ later-chapter additions, plus any `export.*` / `dump.sql`), and
342
+ re-checks `pwd` against `tutorial.cwd`. Show its `paths`, require the
343
+ literal `yes, wipe`, then `state.js wipe --confirm`.
449
344
  - **Final wrap-up**: §Final wrap-up. Reached when the tester says
450
345
  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.