@skill-map/cli 0.68.0 → 0.69.0

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

@@ -5,7 +5,7 @@ The live-UI prologue: the tester runs `sm init`, opens the browser, and watches
 **Codex deltas (rich track).** When `tutorial.provider == codex` the lay commands are unchanged (the `--only` ids match the Codex overlay), but the on-disk shapes differ; substitute in the tester-facing prose:
 
 - `init`: the boot node `demo-agent` is a **TOML agent** at `.codex/agents/demo-agent.toml`.
-- `kinds`: the node list reads `.codex/agents/demo-agent.toml` (agent), `.agents/skills/demo-command/SKILL.md` (Codex has no `command`, so this node is a **skill**), `.agents/skills/demo-skill/SKILL.md` (skill), and the `notes/*.md`. Name the kinds as agent + skill + markdown.
+- `kinds`: the node list reads `.codex/agents/demo-agent.toml` (agent), `.agents/skills/demo-command/SKILL.md` (skill), `.agents/skills/demo-skill/SKILL.md` (skill), and the `notes/*.md`. Name the kinds as agent + skill + markdown (two new kinds this step: skill + markdown). Present `demo-command` as a plain skill: do NOT tell the tester it "is a command" or narrate any command-to-skill substitution. Codex has no `command` kind, so on this track `demo-command` is simply one of the two skills, nothing to explain.
 - `first-edit`: the description to edit lives in `.codex/agents/demo-agent.toml` (the `description = "…"` TOML field, not YAML frontmatter).
 - `connectors` onward: identical, the `@`/`/` bullets resolve the same on Codex; only the `ignore` chapter's directory tree shows `.codex/agents/` + `.agents/skills/` instead of `.claude/`.
 
@@ -152,14 +152,10 @@ Tell the tester:
 > (That is also why `@demo-agent` drew fine: an `@name` mention
 > resolves when an agent by that name really exists.)
 >
-> One word on solidity: skill-map draws each connector's
-> **confidence** as opacity, and every arrow you see here is fully
-> solid (1.00) because each one lands on a real node. The faint,
-> partial case shows up later in the campaign; for now the rule is
-> simple, a reference
-> that resolves draws a solid arrow, a reference that points at
-> nothing is not drawn at all and gets flagged instead. The exact
-> per-link numbers live in the inspector, next chapter.
+> 💡 Tip: if all these changes left the nodes crowded together, the
+> map toolbar has a **Re-arrange layout** button: it tidies the
+> layout so everything reads better. If you've moved nodes by hand it
+> asks for confirmation first, otherwise it just re-arranges.
 >
 > Confirm when you see the four arrows plus the broken-reference
 > marker on the hub. If an arrow is missing, refresh the browser and
@@ -171,12 +167,6 @@ Expected: four drawn arrows plus one `core/reference-broken` error on `notes/tod
 
 The canvas only draws the resolved arrows; the full per-link breakdown, including the broken one that never drew, lives in the Inspector. Open it on the hub so the tester registers the surface before the `edit-link` chapter changes topology.
 
-> 💡 Tip: if all these changes left the nodes crowded together, the
-> map toolbar has a **Re-arrange layout** button (tooltip "Re-arrange
-> the visible nodes"): it tidies the layout so everything reads
-> better. If you've moved nodes by hand it asks for confirmation
-> first, otherwise it just re-arranges.
->
 > 🆕 Open the Inspector for **Demo TODO list** (click the node on
 > the map). Find the **Connections** section: it has two sections,
 > **Outgoing** and **Incoming**.
@@ -187,7 +177,7 @@ The canvas only draws the resolved arrows; the full per-link breakdown, includin
 > confidence: the numeric value. Here you'll see the contrast, the
 > `references` to `demo-guideline2` reads `1.00` (resolved), while the
 > `mentions` to `demo-guideline` reads `0.50` and is marked broken,
-> that 0.5 is the broken-reference penalty, not a "halfway sure".
+> that 0.5 is the broken-reference penalty, it's a "half sure".
 >
 > Now open the Inspector for a couple of the nodes to read their
 > Incoming count. The four resolved nodes (`demo-agent`,
@@ -196,6 +186,11 @@ The canvas only draws the resolved arrows; the full per-link breakdown, includin
 > mention never landed on it, so nothing points in. Five outgoing
 > links on the hub, but only four of them reach a node.
 >
+> 💡 Tip: skill-map draws each connector's **confidence** as opacity.
+> Every arrow here is solid (1.00) because it lands on a real node; a
+> reference that points at nothing is flagged instead of drawn. The
+> fainter, partial case shows up later in the campaign.
+>
 > Let me know when you see it.
 
 Mark `inspector`: done.
@@ -252,18 +247,20 @@ action itself.
 > Tell me when the tree is open.
 
 > At the top of that sidebar there's a search box (placeholder
-> `Search…`). Type `guideline`. Watch both halves at once: the tree
-> narrows down to the two guideline nodes (`demo-guideline` and
-> `demo-guideline2`) and the **Map** drops every node except those
-> two. The search matches a node's name, path,
-> or description, and filters live as you type, no Enter needed.
+> `Search…`). Type `guideline`. Watch the tree narrow down to the
+> two guideline nodes (`demo-guideline` and `demo-guideline2`). The
+> search matches a node's name, path, or description, and filters
+> live as you type, no Enter needed. The **Map** stays put: by
+> default the search filters only the files list, not the map (the
+> tip below changes that).
 >
-> Now clear the box. All six nodes come back, in both the tree and
-> the Map. Confirm you saw it filter and then restore.
+> Now clear the box. All six nodes come back in the tree. Confirm you
+> saw it filter and then restore.
 
-> Last one. In the tree, find the **Demo TODO list** row: at its
-> right edge there's a small **sitemap** icon (its tooltip reads
-> "Isolate this node and its direct links on the map"). Click it.
+> Last one. In the tree, find the `notes/todo` row (the **Demo TODO
+> list** hub, the tree labels rows by file name): at its right edge
+> there's a small **sitemap** icon (its tooltip reads "Isolate this
+> node and its direct links on the map"). Click it.
 >
 > The Map collapses to **Demo TODO list** plus only the nodes it
 > draws an arrow to (`demo-command`, `demo-skill`,
@@ -276,10 +273,9 @@ action itself.
 >
 > 💡 Tip: remember the search box from a moment ago? The map-icon
 > button right next to it controls whether the search also filters
-> the **Map**. It's on by default, that's why the **Map** narrowed
-> along with the tree when you searched `guideline`. Click it to
-> switch to filtering only the files list, leaving the map's layout
-> in place.
+> the **Map**. It's off by default, which is why the **Map** stayed
+> put while only the tree narrowed when you searched `guideline`.
+> Click it on if you want a search to filter the map too.
 >
 > Did the map isolate and then restore?
 
@@ -317,7 +313,7 @@ Give the tester a mental map of the folder so they know where the file lives, th
 │   └── skills/
 │       ├── demo-skill/SKILL.md
 │       └── sm-tutorial/SKILL.md   ← the tutorial you loaded
-├── .skill-map/              ← project DB + settings (managed)
+├── .skill-map/              ← project DB + settings
 ├── .skillmapignore          ← the file we're about to edit
 └── notes/
     ├── todo.md

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

@@ -1,13 +1,17 @@
-# Part 1: The project from zero (step library, `kickoff-*` ids)
+# Part 1: The harness from zero (step library, `kickoff-*` ids)
 
 The campaign turns real here. After the abstract prologue, the tester
 starts an actual project: a tiny personal **portfolio website**,
 fully static, served by a ~15-line Express server, plus the
 `.claude/` **harness** that maintains it. skill-map maps the harness
 (the `.md` assets and how they reference each other); the site itself
-is plain HTML the harness produces (the daily loop, Part 3, runs and ships it).
-`pace: per-step`, `preflight: portfolio-init`. Shared
-conventions live in `_core.md`.
+is plain HTML the harness produces (the daily loop, Part 2, runs and ships it).
+This part runs end to end: it boots the project and grows its harness
+members (the `kickoff` to `real-kinds` chapters), then wires them into a
+connected graph, a link checker, a publish command, the handbook turned
+hub, and a close-up on connector confidence (the `check-links` to
+`confidence` chapters). `pace: per-step`, `preflight: portfolio-init`.
+Shared conventions live in `_core.md`.
 
 The orchestrator's `portfolio-init` pre-flight (backstage, silent)
 has already laid the bare project skeleton before the tester runs
@@ -33,7 +37,9 @@ The chapters grow the harness from there.
 - `real-kinds`: Codex's kinds are `agent` (TOML) + `skill` + `markdown`, there is
   no `command`. Lay only `docs/DEPLOY.md` here (STYLE landed in `first-agent`),
   and name the kinds as agent + skill + markdown (the skill + the publish piece
-  arrive in Part 2 as skills).
+  arrive later in this part as skills).
+- `publish`: Codex has no `command` kind, so the tester creates a **skill** at `.agents/skills/publish/SKILL.md` instead of `.claude/commands/publish.md`. The body is the Codex one (same `/check-links` + `@content-editor` + deploy reference); fetch it with `fixtures.js cat harness --file "__PROVIDER__/skills/publish/SKILL.md" --provider codex --lang <lang>`. Tell the tester they are creating a `skill` (one node, three connectors); present it plainly as a skill, with no mention of a command or a substitution (per _core.md §Rendering the rich book on Codex, silent substitution). The fixture lays no `publish` for codex in this chapter (the tester authors it), so the `cat` is the source.
+- `links`: the `content-editor-style` reference is baked into the Codex content-editor's TOML (`developer_instructions`) at lay time, so the `edit content-editor-style` step is a no-op on Codex, the `content-editor -> docs/STYLE.md` arrow is already drawn from earlier in this part. Run only `edit agents-hub` and narrate the two `AGENTS.md` arrows; mention the style-guide arrow as already present.
 
 ## Chapter `kickoff` - Start the portfolio (~2 min)
 
@@ -106,8 +112,7 @@ then render it in the fenced block the tester copies:
 > as a file pointer (the same `@name.md` reference you met in the
 > prologue), and since the handbook is right there
 > the link resolves with full confidence. It tells anyone (and
-> skill-map) that `CLAUDE.md` defers to the handbook. This is exactly
-> how this tool's own repo is wired.
+> skill-map) that `CLAUDE.md` defers to the handbook.
 >
 > Did the connector light up?
 
@@ -126,8 +131,8 @@ Tell the tester:
 
 > I added the first real member of your harness: an agent called
 > `content-editor` (its job is to write the site's pages). A new
-> `agent` node appeared on the map. Right now it stands alone; in the
-> next part we wire it to the handbook and the style guide.
+> `agent` node appeared on the map. Right now it stands alone; later in
+> this part we wire it to the handbook and the style guide.
 >
 > 💡 Tip: I create these harness files for you. If you'd like to see
 > what's inside, open `<provider_dir>/agents/content-editor.md` in your
@@ -162,14 +167,166 @@ Tell the tester:
 > - **agent**: `content-editor` (does work on your behalf).
 > - **markdown**: `AGENTS.md`, `CLAUDE.md`, the two docs (plain notes
 >   and manuals).
-> - **skill** and **command**: you add these (the link checker and
->   the publish command) in a later part.
+> - **skill** and **command**: you add these later in this part (the
+>   link checker and the publish command).
 >
 > Your handbook now has a real harness around it: a `content-editor`
 > agent plus its docs, all on the map.
 >
 > See the agent and the docs in the map?
 
-Wait for confirmation. Mark `real-kinds`: 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).
+Wait for confirmation. Mark `real-kinds`: done.
+
+## Chapter `check-links` - The link checker (~3 min)
+
+**Context**: the harness needs a guard that runs before publishing, a skill that checks the site's internal links resolve before it ships. We only create the `skill` node here; the `publish` command in the next chapter is its caller.
+
+Lay the `check-links` skill (its content + translation live in
+`fixtures-data/`; this kind exists on every provider, so no skip).
+Backstage (silent):
+
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay harness --only "__PROVIDER__/skills/check-links/SKILL.md" --provider <provider> --lang <lang>
+```
+
+Tell the tester:
+
+> So I added that guard: a skill called `check-links`. A new `skill`
+> node appeared on the **Map**, alone for now; the next chapter gives
+> it a caller.
+>
+> See the new skill node?
+
+Wait for confirmation. Mark `check-links`: done.
+
+## Chapter `publish` - The publish command (~4 min)
+
+**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.
+
+Tell the tester to create the file themselves (it is their project's file, Inviolable rule #2). Substitute `<provider_dir>` per `_core.md` in the path you give them. Backstage, get the content: `node .claude/skills/sm-tutorial/scripts/fixtures.js cat harness --file "__PROVIDER__/commands/publish.md" --provider <provider> --lang <lang>`, then render it as a **top-level fenced code block**: at column 0, NOT inside the `> ` blockquote and with NO leading indentation, so the tester's copy keeps every line flush left. The frontmatter fences (`---`) MUST land on column 0. If the block is rendered (or pasted) indented, the opening and closing `---` shift off column 0, the YAML never parses, and the `publish` node loads body-only without its `name` / `description` (`sm check` then warns `frontmatter-malformed`). Present the block below exactly as written.
+
+> Create `.claude/commands/publish.md` with exactly this content (the first line is `---`, nothing before it):
+
+```markdown
+---
+name: publish
+description: |
+  Publishes the portfolio: runs the link check, hands off to the
+  content editor for any last fixes, then follows the deploy runbook.
+---
+
+# publish
+
+The one command you run when the site is ready to go out.
+
+## Steps
+1. Run /check-links on the pages in public/. If it reports broken links, stop and fix them first.
+2. If a page needs a content fix, brief @content-editor with the change.
+3. Follow the [deploy runbook](../../docs/DEPLOY.md): regenerate pages, run the link check, start the server.
+```
+
+Continue the tester message:
+
+> 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.
+> - `publish -> content-editor` (kind: `mentions`), from the
+>   `@content-editor` token.
+> - `publish -> docs/DEPLOY.md` (kind: `references`), from the
+>   `[deploy runbook](../../docs/DEPLOY.md)` markdown link.
+>
+> One node, three connectors, three link kinds. The harness is
+> starting to look like a real graph.
+>
+> 💡 Tip: to tidy every node into a clean layout, click the
+> **Re-arrange layout** button in the map toolbar. Handy whenever the
+> graph starts to look crowded.
+>
+> Did the three arrows appear?
+
+Wait for confirmation. You MAY use `Read` on the file afterwards to verify it landed, in particular that the opening and closing `---` are flush at column 0. If a later `sm check` flags `frontmatter-malformed` on `publish.md`, the fences got indented on paste: have the tester re-align every line flush left (strip the leading spaces so `---` is at column 0), then the next scan reads it clean. Mark `publish`: done.
+
+## Chapter `links` - The handbook becomes the hub (~4 min)
+
+**Context**: the handbook (`AGENTS.md`) has been a lonely node since the start of this part. Here it becomes the hub: we add two bullets so it mentions the content editor and invokes the publish command. We also give the content editor a reference to the style guide it follows. Several connectors land, and we recap the three link kinds and which syntax produced each.
+
+Apply both edits (their content + translation live in `fixtures-data/`).
+The first appends the two hub bullets to `AGENTS.md`; the second adds
+the style-guide reference line to the content-editor. Backstage (silent):
+
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js edit agents-hub --provider <provider> --lang <lang>
+node .claude/skills/sm-tutorial/scripts/fixtures.js edit content-editor-style --provider <provider> --lang <lang>
+```
+
+Tell the tester:
+
+> Two edits, and the **Map** fills in. Your handbook (`AGENTS.md`) is
+> now the hub: it points at the content editor and at the publish
+> command. And the content editor now reaches the style guide it
+> follows. New arrows:
+>
+> - `AGENTS.md -> content-editor` (kind: `mentions`), from `@content-editor`.
+> - `AGENTS.md -> /publish` (kind: `invokes`), from `/publish`.
+> - `content-editor -> docs/STYLE.md` (kind: `references`), from the
+>   `[style guide](../../docs/STYLE.md)` markdown link.
+>
+> Here is the whole recap of the three link kinds, one per syntax:
+>
+> - an `@handle` token is always a **mention**.
+> - a `/slash` token is always an **invoke**.
+> - a `[text](path.md)` markdown link is always a **reference**.
+>
+> The kind comes purely from how you wrote it. Your harness is wired
+> end to end now: the handbook reaches the work, the work reaches the
+> docs, and `/publish` pulls the whole publish flow together.
+>
+> Did the new arrows light up?
+
+Wait for confirmation. You MAY use `Read` on the two files afterwards to verify the edits landed before moving on. Mark `links`: done.
+
+## Chapter `confidence` - How sure is each link (~3 min)
+
+No file edits in this chapter, pure observation on the graph the tester just built.
+
+Tell the tester:
+
+> Last beat of this part: how sure is skill-map about each connection?
+> It records a **confidence** for every link and draws it as opacity:
+> a link that resolves to a real node is solid (**1.00**), a link that
+> does not lands fainter, so a glance at the **Map** separates the
+> solid wiring from the problem links.
+>
+> Open the Inspector for the `publish` node (click it on the **Map**).
+> Scroll down to the **Connections** panel and read the **Outgoing**
+> rows. Each row shows the link kind and a confidence badge, and here
+> every one reads **1.00**:
+>
+> - `publish -> docs/DEPLOY.md` (`references`) is a markdown link to a
+>   file that exists on disk, so skill-map is certain.
+> - `publish -> content-editor` (`mentions`) resolves to the real
+>   content-editor agent, and `publish -> check-links` (`invokes`)
+>   resolves to the real check-links skill, so both are certain too.
+>
+> Your whole harness reads solid because every link lands on a real
+> node, that is what a clean, fully wired graph looks like. So what
+> does a link that does NOT resolve look like? You met one back in the
+> prologue: `@demo-guideline` was a reference skill-map could not
+> resolve, it had nothing to land on, so skill-map drew no arrow and
+> flagged it as a **broken reference**, its confidence knocked down to
+> **0.50** by the broken penalty. The fix was one character: adding
+> `.md` (`@demo-guideline.md`) turned it into a file reference to the
+> real `demo-guideline.md`, and it drew a solid arrow at **1.00**.
+>
+> **IMPORTANT:** why does confidence matter? It mirrors how the runtime itself
+> resolves a reference: a deterministic name-and-path lookup, no guessing
+> and no scanning the tree for a file under some other extension. That is
+> cheaper and it does not fail, so the agent spends fewer tokens and less
+> time, the same reason a clean, well-named harness is worth keeping.
+>
+> Do you see every badge reading 1.00 in the Inspector?
+
+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/scripts/state.js

@@ -236,8 +236,8 @@ function computeWipePaths(state) {
   // provider), so either part's presence means that fixture is on disk.
   if (has('fundamentals') || has('basic-fundamentals')) addFootprint('prologue');
   if (
-    has('project-kickoff') || has('connect-harness') || has('daily-loop')
-    || has('basic-kickoff') || has('basic-connect') || has('basic-daily')
+    has('project-kickoff') || has('daily-loop')
+    || has('basic-kickoff') || has('basic-daily')
   ) addFootprint('portfolio');
   if (has('extend')) addFootprint('master');
   // `cli` seeds the prologue demo fixture plus its external-ref demo.
@@ -274,5 +274,5 @@ function main() {
 }
 
 main();
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="803fceb9-f545-5f51-8f46-4db3cba6abcf")}catch(e){}}();
-//# debugId=803fceb9-f545-5f51-8f46-4db3cba6abcf
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3ef90c0e-0700-5a7b-a25f-c47aa19fd567")}catch(e){}}();
+//# debugId=3ef90c0e-0700-5a7b-a25f-c47aa19fd567