@skill-map/cli 0.53.2 → 0.53.3

package/dist/cli/tutorial/sm-tutorial/SKILL.md

@@ -132,18 +132,27 @@ Apply §Provider detection from `_core.md`. Persist the result into
 
 ### 4. Two-terminals heads-up (one time)
 
+Agent-only: in the `cd` block below, substitute `<cwd>` with the
+tester's actual cwd (the absolute path of the folder the tutorial is
+running in) so the command is copy-pasteable, same substitution as
+every other `<cwd>` mention.
+
 > ⚠️ Heads up: throughout the tutorial you'll be using **two
 > terminals**.
 >
 > 1. **This terminal**: the one you're using right now to talk to
 >    me (Claude Code). I show you the commands, you paste me the
 >    output, and I verify.
-> 2. **A second terminal**: open it now (new window or tab). In it
->    run `cd <cwd>` so it's anchored **exactly to this folder**.
+> 2. **A second terminal**: open it now (new window or tab), then run
+>    the command below so it's anchored **exactly to this folder**.
 >    That's where you copy and paste every `sm` command.
->
+
+```bash
+cd <cwd>
+```
+
 > Keep both terminals open until the end. If you accidentally close
-> the second one, reopen it and `cd <cwd>` again.
+> the second one, reopen it and run that `cd` again.
 >
 > Got the second terminal open and anchored to the folder? Confirm
 > before we move on.
@@ -298,7 +307,7 @@ When a part begins, honour its `preflight` from the manifest:
   `preflight: seed` to fast-forward into them directly, see the `seed`
   case below; `portfolio-init` is just Part 1's flavour of that,
   handling the Part 0 to Part 1 transition.)
-- **`backstage-init`** (Part 6 `extend`): silently, with no
+- **`backstage-init`** (Part 7 `extend`): silently, with no
   narration: run `sm init --no-scan` from the cwd, then `Edit` the
   freshly created `.skillmapignore` to append the tutorial's
   internal entries (the `sm-tutorial.md` / `findings.md` /
@@ -309,13 +318,13 @@ When a part begins, honour its `preflight` from the manifest:
   the dir was already initialised by an earlier part, that is fine:
   the DB already exists, skip the init and just ensure the fixture
   files are present.
-- **`reuse`** (Part 7 `cli`): assumes the prologue fixture and
-  `.skill-map/` already exist; nothing to lay. The menu offers Part 7
+- **`reuse`** (Part 8 `cli`): assumes the prologue fixture and
+  `.skill-map/` already exist; nothing to lay. The menu offers Part 8
   only once its `prereq` (`fundamentals`) is done, so the state is
   there. If `.skill-map/` is somehow missing, point the tester back to
   the prologue rather than re-initialising mid-part.
-- **`seed`** (the campaign parts `connect-harness` / `maintain` /
-  `mcp` / `live-site`): the part builds on the accumulating portfolio
+- **`seed`** (the campaign parts `connect-harness` / `run-harness` /
+  `maintain` / `mcp` / `live-site`): the part builds on the accumulating portfolio
   harness, but the tester may have jumped straight here from the menu.
   On entry, read the state file:
   - If every predecessor campaign part up the `prereq` chain is `done`
@@ -361,7 +370,7 @@ All three are specified in `_core.md`:
   `<provider_dir>/skills/demo-skill/`,
   `<provider_dir>/commands/demo-command.md`, `notes/todo.md`,
   `notes/demo-guideline.md`, `notes/private-credentials.md`), the
-  Part 6 fixture if `extend` ran
+  Part 7 fixture if `extend` ran
   (`<provider_dir>/agents/master-agent.md`,
   `<provider_dir>/skills/master-skill/`, `notes/ideas.md`,
   `.skill-map/plugins/`), `link-validation/` if the CLI part ran,

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

@@ -287,20 +287,52 @@ For every chapter:
   the book ToC, numbered, and let the tester pick a part by number.
   Part 0 (the prologue) is option 1, the recommended starting point,
   so a brand-new tester just types `1`. Do NOT auto-enter a part; the
-  menu is the entry point every time. On later renders, prefix any
-  completed part's title with `✓ `.
+  menu is the entry point every time. On later renders, mark completed
+  parts with a `✓` in their description line, not on the title (see
+  §Menu format).
 - **Which parts to list**: parts in `order`, `status: active` only
   (`planned` parts are hidden). A part with a `seed` (the campaign
   parts) is always shown, even out of order, its `preflight: seed`
   fast-forwards the project into it (SKILL.md §Entering a part). A
-  part with a `prereq` but NO `seed` (Part 7 `cli`) is shown only once
+  part with a `prereq` but NO `seed` (Part 8 `cli`) is shown only once
   its `prereq` is `done`.
-- **After the tester picks**: walk that part; when it ends, return to
-  this menu.
+- **After the tester picks**: walk that part; when it ends, run
+  §Closing a part (a tester-facing close, then this menu).
 - **Adding content** is data-only: a new chapter in a part (or a new
   `part-<id>.md` + a manifest row). Keep chapter-id prefixes matching
   the file name so dispatch stays mechanical.
 
+### Closing a part
+
+A part must FEEL finished before the menu comes back: the tester
+should never slide into the next part as if it auto-continued. When a
+part's last chapter (the last in `_manifest.yml` order) is confirmed,
+before re-rendering the menu emit a short tester-facing close:
+
+- A `✓` line naming the part just finished BY ITS TITLE (from
+  `_manifest.yml`), not the internal "Part N" index, which is off by
+  one from the menu numbering the tester sees.
+- One line recapping what they built or learned (same source as the
+  menu description).
+- A hand-off line: back to the menu, pick the next part.
+
+Then render the menu (§Menu format) with this part now marked done (a
+`✓` in its description line, not on the title); its intro may lean to
+"what's next" on a post-part render. The last
+chapter's own confirmation stays scoped to that chapter, it does NOT
+promise or pre-announce the next part, the close and the menu own the
+transition. Sample (Claude variant, mirror the tester's language,
+apply the host rendering rule):
+
+> ✓ Listo, terminaste **El proyecto desde cero**. Levantaste un
+> proyecto real, su handbook y el harness `.claude/` con sus primeros
+> nodos.
+>
+> Volvés al menú, elegí con qué seguir.
+
+If every active part is now `✓` (nothing left to pick), skip the menu
+and go straight to §Final wrap-up.
+
 ### Menu format
 
 Render the menu numbered and formatted (NOT a bare list), translated
@@ -308,6 +340,11 @@ to the tester's language. A one-line intro, then per part a **bold
 numbered title line** (number + title + `(~M min)`) as plain prose,
 immediately followed by a single-level `> ` blockquote one-line
 description (what the part covers, derived from its title + chapters).
+A **completed part** keeps its plain title (NO `✓` on the title line)
+and swaps its description for the done marker: `> ✓ ` plus a short
+"already done" note (e.g. `✓ Ya la hiciste.`). The green check lives
+inside the content, mirroring the `✓` confirmations used elsewhere,
+never as a title prefix.
 NO blank line between a title and its description; ONE blank line
 between parts; NO outer blockquote around the whole menu. Close with a
 short "¿Cuál?" / "Which one?" on its own line. Sample (Claude variant,
@@ -331,6 +368,17 @@ single blockquote" rule: the intro, the bold titles and the trailing
 non-Claude hosts the `> ` collapses to plain prose, indent each
 description two spaces so it stays subordinate to its title.
 
+Same menu after Part 1 is done (the `✓` sits in the description line,
+the title stays plain):
+
+```
+**1. El mapa en vivo** (~12 min)
+> ✓ Ya la hiciste.
+
+**2. El proyecto desde cero** (~8 min)
+> Arrancás un proyecto real (un portfolio) y su harness `.claude/`.
+```
+
 ## Resume / restart
 
 When re-invoked and the state file already exists, do NOT repeat

package/dist/cli/tutorial/sm-tutorial/references/_manifest.yml

@@ -44,13 +44,13 @@ parts:
       - id: kinds           ; title: "The other kinds appear"               ; est_min: 1
       - id: first-edit      ; title: "Your first edit (the watcher reacts)" ; est_min: 1
       - id: connectors      ; title: "The connectors light up"             ; est_min: 2
-      - id: inspector       ; title: "The inspector and linked nodes"      ; est_min: 1
+      - id: inspector       ; title: "The inspector and connections"       ; est_min: 1
       - id: edit-link       ; title: "Edit a link, the topology changes"   ; est_min: 3
       - id: workspace       ; title: "Navigate the workspace (files, search, isolate)" ; est_min: 2
       - id: ignore          ; title: "Silence a file via .skillmapignore"  ; est_min: 2
 
   - id: extend
-    order: 6
+    order: 7
     title: "Extend skill-map for the site"
     # Spans three chapter libraries; dispatch by chapter-id prefix:
     #   settings-*  -> part-settings.md
@@ -80,7 +80,7 @@ parts:
       - id: authoring-6-upgrade      ; title: "Try `sm plugins upgrade`" ; est_min: 2
 
   - id: cli
-    order: 7
+    order: 8
     title: "The CLI in depth"
     step_file: part-cli.md
     pace: auto-advance
@@ -130,8 +130,21 @@ parts:
       - id: links       ; title: "Mentions (@) and references between assets" ; est_min: 3
       - id: confidence  ; title: "Connector confidence (opacity = certainty)" ; est_min: 2
 
-  - id: maintain
+  - id: run-harness
     order: 3
+    title: "Run the harness (your site, live)"
+    step_file: part-run-harness.md
+    pace: auto-advance
+    preflight: seed
+    seed: harness-connected   # fast-forward to here if the earlier parts are not done
+    prereq: connect-harness
+    status: active
+    chapters:
+      - id: generate ; title: "The agent generates the HTML in public/" ; est_min: 3
+      - id: serve    ; title: "node server.js: your portfolio, live next to the graph" ; est_min: 3
+
+  - id: maintain
+    order: 4
     title: "Maintain the site"
     step_file: part-maintain.md
     pace: auto-advance
@@ -148,7 +161,7 @@ parts:
       - id: versions     ; title: "Versions: sm bump and history" ; est_min: 2
 
   - id: mcp
-    order: 4
+    order: 5
     title: "MCP"            # a chapter apart, just before the finale
     step_file: part-mcp.md
     pace: auto-advance
@@ -160,8 +173,8 @@ parts:
       - id: mcp-node ; title: "content-editor declares an MCP tool; the mcp:// node appears" ; est_min: 3
 
   - id: live-site
-    order: 5
-    title: "The site, live"  # the finale / climax
+    order: 6
+    title: "Ship the site (the full publish pipeline)"  # the finale / climax
     step_file: part-live-site.md
     pace: auto-advance
     preflight: seed
@@ -169,7 +182,7 @@ parts:
     prereq: connect-harness
     status: active
     chapters:
-      - id: generate ; title: "The agent generates the HTML in public/" ; est_min: 3
-      - id: serve    ; title: "node server.js: your portfolio, live, next to the graph" ; est_min: 3
+      - id: pipeline ; title: "Run /publish end to end (check-links, brief, deploy runbook)" ; est_min: 4
+      - id: golive   ; title: "Ship it: the richer site live next to the full graph" ; est_min: 3
 
 findings_file: "./findings.md"

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

@@ -1,12 +1,12 @@
 # Fixture templates
 
 Fixtures the orchestrator lays for the auto-fixtured parts. Two sets
-today: the **master fixture** (Part 6, "Extend skill-map",
+today: the **master fixture** (Part 7, "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.
 Read the set for the part being entered.
 
-## Master fixture (Part 6): layout (per provider)
+## Master fixture (Part 7): layout (per provider)
 
 Per §Provider detection in `SKILL.md`, the `<provider_dir>`
 placeholder resolves to `.claude/` or `.agents/skills/` depending
@@ -134,7 +134,7 @@ Per finding:
 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 (Part 5 starts it). The one boot node is the
+real and runnable (Part 3 runs it, Part 6 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.
@@ -154,15 +154,12 @@ Layout:
 
 ### File: `AGENTS.md` (kind: markdown, the boot node)
 
-```markdown
----
-name: portfolio-handbook
-description: |
-  Operating manual for this portfolio site: how its pages get
-  written, checked, and published by the .claude/ harness.
-tags: [docs, portfolio]
----
+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`.
 
+```markdown
 # Portfolio handbook
 
 A small static portfolio site, served by Express (`server.js`). The
@@ -196,7 +193,7 @@ app.listen(port, () => console.log(`Portfolio live at http://localhost:${port}`)
 }
 ```
 
-### File: `public/index.html` (not scanned; placeholder until Part 5)
+### File: `public/index.html` (not scanned; placeholder until Part 3)
 
 ```html
 <!doctype html>
@@ -237,7 +234,7 @@ any cross-links:
 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 Parts 3, 4, 5)
+### Seed snapshot: `harness-connected` (start of Parts 3-6)
 
 Everything in `harness-built`, PLUS the Part 2 wiring:
 

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

@@ -1,6 +1,6 @@
-# Part 6 (c): Extend skill-map - build plugins (step library, `authoring-*` ids)
+# Part 7 (c): Extend skill-map - build plugins (step library, `authoring-*` ids)
 
-Step bodies for the plugin-authoring chapters of Part 6.
+Step bodies for the plugin-authoring chapters of Part 7.
 The SKILL.md orchestrator dispatches each `authoring-*` chapter id
 here; `settings-*` ids it dispatches to `part-settings.md`.
 

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

@@ -1,4 +1,4 @@
-# Part 7: The CLI in depth - step library
+# Part 8: The CLI in depth - step library
 
 The deep-dive into the rest of the CLI: browsing verbs, ASCII graph + export, broken-ref issues, the `.sm` annotation consent prompt, and validating links to folders outside the scan scope. `pace: auto-advance` (walk straight into the next chapter's Announcement once one is marked done) and it reuses the fundamentals fixture and DB built in Part 0 (no fresh fixture of its own). Shared conventions (tone, provider detection / substitution, the `> ` rendering rule, the per-step cycle) live in `_core.md`; do not restate them here.
 

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

@@ -53,7 +53,11 @@ Wait for confirmation. Mark `check-links`: done.
 
 **Context**: this is the chapter where the graph comes alive. The `/publish` command ties three pieces together in one body: it invokes the link checker, mentions the content editor, and references the deploy runbook. Three connectors light up from a single new node, one per link syntax.
 
-`Write` `.claude/commands/publish.md` (substitute `<provider_dir>` per `_core.md`; 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):
+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:
+
+> Create `.claude/commands/publish.md` with exactly this content:
 
 ```markdown
 ---
@@ -79,12 +83,11 @@ The one command you run when the site is ready to go out.
 3. Follow the [deploy runbook](../../docs/DEPLOY.md) to ship.
 ```
 
-Tell the tester:
+Continue the tester message:
 
-> I added the `/publish` command, the single entry point you run when
-> the site is ready to go live. Watch the **Map**: **three** new
-> arrows light up at once from the new `publish` node, and each one is
-> a different colour because each one is a different kind of link:
+> Save it. Watch the **Map**: **three** new arrows light up at once
+> from the new `publish` node, and each one is a different colour
+> because each one is a different kind of link:
 >
 > - `publish -> check-links` (kind: `invokes`), from the `/check-links`
 >   token in the body.
@@ -98,7 +101,7 @@ Tell the tester:
 >
 > Did the three arrows appear?
 
-Wait for confirmation. Mark `publish`: done.
+Wait for confirmation. You MAY use `Read` on the file afterwards to verify it landed. Mark `publish`: done.
 
 ## Chapter `links` - The handbook becomes the hub (~4 min)
 
@@ -159,7 +162,7 @@ Tell the tester:
 > the more solid the arrow; the less sure, the more translucent.
 >
 > Open the Inspector for the `publish` node (click it on the **Map**).
-> Scroll down to the **Linked nodes** panel and read the **Outgoing**
+> Scroll down to the **Connections** panel and read the **Outgoing**
 > rows. Each row shows the link kind and a confidence badge:
 >
 > - `publish -> docs/DEPLOY.md` (`references`) reads **1.00** and looks
@@ -177,4 +180,4 @@ Tell the tester:
 >
 > Do you see the confidence badges in the Inspector?
 
-Wait for confirmation. Mark `confidence`: done. This closes Part 2; the orchestrator returns to the ToC menu (Part 3, "Maintain the site", is next on the spine).
+Wait for confirmation. Mark `confidence`: done. Last chapter of the part: apply §Closing a part (the close names the part by its title and routes back to the menu; do NOT lead into the next part from here).

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

@@ -229,7 +229,7 @@ Tell the tester:
 
 If a connector is missing, do not advance, the next chapter inspects the same hub edit. Mark `connectors`: done.
 
-## Chapter `inspector` - The inspector and linked nodes (~1 min)
+## Chapter `inspector` - The inspector and connections (~1 min)
 
 The connector opacity tells the confidence story at a glance; the exact per-link breakdown lives in the Inspector. Open it on the hub so the tester registers the surface before the `edit-link` chapter changes topology.
 
@@ -324,9 +324,9 @@ Leave the server running, the next chapter (`.skillmapignore`) is the last one t
 
 Earlier chapters showed the watcher picking up new files and edits (yours and theirs). This chapter flips the direction: a file the tester DOES NOT want in the map (a draft, a scratch file, a secret) gets hidden by a single line in `.skillmapignore`. Same live mechanism, no restart.
 
-`sm init` already wrote a starter `.skillmapignore` at the scope root. The flow has three beats:
+`sm init` already wrote a starter `.skillmapignore` at the scope root. The chapter is one step with a single confirmation (the node vanishing): the agent seeds a file the tester would never want public, shows where it lives, and the tester hides it with one glob.
 
-**Beat 1, you create one new fixture file (the agent does this).**
+**The agent seeds the file (no tester action, no separate pause).**
 
 `Write` `notes/private-credentials.md`, kind `markdown`, simulates a file the tester would never want surfacing publicly:
 
@@ -344,13 +344,15 @@ description: |
 API_TOKEN: example-not-real
 ```
 
-Confirm the file appears in the map as a sixth node (`notes/private-credentials`). The watcher sees it like any other `.md`, that's the point of the demo. (If the tester doesn't see it, they may need to click **Show all** in the map toolbar to clear any leftover selection.)
+It lands in the map as a sixth node (`notes/private-credentials`); the watcher sees it like any other `.md`. Do NOT pause to confirm the appearance, it folds into the single vanish confirmation at the end of this step.
 
-**Beat 2, you show the project structure (the agent does this).**
+**The tester hides it (single tester-facing message, one confirmation).**
 
-Before asking the tester to touch `.skillmapignore`, give them a mental map of the folder so they know where the file lives and what's around it. Use `Bash` (`ls -la` and `ls -la notes/` if a deeper view helps) and present the listing as a tester-facing message (apply the host-dependent rendering rule) so the tester sees what their cwd holds:
+Give the tester a mental map of the folder so they know where the file lives, then the glob that hides it, all in ONE message. Use `Bash` (`ls -la`, plus `ls -la notes/` if a deeper view helps) for the real listing and apply the host-dependent rendering rule. Per Inviolable rule #2, the agent does NOT touch `.skillmapignore` with its `Edit` tool, the tester edits it from their own editor:
 
-> One last step. Here's what your directory looks like right now:
+> One last step. Your `private-credentials` note just popped into
+> the map as a sixth node, that's the watcher again. Now let's hide
+> it. Here's what your directory looks like right now:
 
 ```
 .                            ← your cwd
@@ -368,19 +370,10 @@ Before asking the tester to touch `.skillmapignore`, give them a mental map of t
     └── private-credentials.md   ← what we want to hide
 ```
 
-> The `.skillmapignore` at the root is the file we'll touch
-> next. Same syntax as `.gitignore`. Anything matching a pattern
-> there is invisible to skill-map's scan.
-
-Adjust the actual tree shown to whatever `ls -la` returns, the goal is "tester recognises their own filesystem", not a copy of the snippet above.
-
-**Beat 3, the tester edits `.skillmapignore` (NOT the agent).**
-
-Per Inviolable rule #2, the agent does NOT touch `.skillmapignore` with your `Edit` tool. Tell the tester to do it from their editor:
-
-> Last step. Open `.skillmapignore` (it's at the cwd root) in your
-> editor of choice. At the end of the file, on a new line, append
-> this pattern:
+> The `.skillmapignore` at the root uses the same syntax as
+> `.gitignore`: anything matching a pattern there is invisible to
+> skill-map's scan. Open it in your editor (it's at the cwd root)
+> and append this pattern on a new line at the end:
 
 ```
 notes/private-*.md
@@ -399,6 +392,7 @@ notes/private-*.md
 >
 > Did the node vanish?
 
-After they confirm, you MAY use `Read` on `.skillmapignore` to verify the appended pattern landed correctly (in case `sm check` later reports something odd), that is read-only and allowed. Once confirmed, ask them to stop the server with **Ctrl+C** in the terminal before continuing.
+Adjust the actual tree shown to whatever `ls -la` returns, the goal is "tester recognises their own filesystem", not a copy of the snippet above. After they confirm, you MAY use `Read` on `.skillmapignore` to verify the appended pattern landed correctly (in case `sm check` later reports something odd), that is read-only and allowed. Once confirmed, ask them to stop the server with **Ctrl+C** in the terminal before continuing.
 
-Mark `ignore`: done.
+Mark `ignore`: done. Last chapter of the part: apply §Closing a part
+(the close names the part by its title and routes back to the menu).