@skill-map/cli 0.53.4 → 0.53.6

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

@@ -32,9 +32,9 @@ Wait for confirmation. Mark `init`: done.
 
 ## Chapter `kinds` - The other kinds appear (~1 min)
 
-Leave the browser open and the terminal with `sm` running. You create four more nodes **without any cross-fixture links** yet, pure standalone nodes, so the tester sees four new dots pop in. Three new **kinds** show up in this step (skill, command, markdown), the fourth file is a second `markdown` node that the hub in the `connectors` chapter will point at via a real `references` link.
+Leave the browser open and the terminal with `sm` running. You create five more nodes **without any cross-fixture links** yet, pure standalone nodes, so the tester sees five new dots pop in. Three new **kinds** show up in this step (skill, command, markdown); the last two files are sibling `markdown` notes (`demo-guideline`, `demo-guideline2`) the hub in the `connectors` chapter reaches two ways, a faint mention that can't resolve and the same handle plus `.md` that resolves to a real file.
 
-Create these four files (with `Write`), exactly in this order. Per §Provider detection, **substitute `.claude/` with the detected `<provider_dir>` and skip files whose kind is not in the provider's supported set** (`agent-skills` / Antigravity: skip both `demo-agent` and `demo-command`, only the skill + the two markdown notes remain). Adjust the node count, the "four new nodes" message, and the file list shown to the tester in the sample below accordingly:
+Create these five files (with `Write`), exactly in this order. Per §Provider detection, **substitute `.claude/` with the detected `<provider_dir>` and skip files whose kind is not in the provider's supported set** (`agent-skills` / Antigravity: skip both `demo-agent` and `demo-command`, only the skill + the three markdown notes remain). Adjust the node count, the "five new nodes" message, and the file list shown to the tester in the sample below accordingly:
 
 1. `.claude/skills/demo-skill/SKILL.md` (kind: skill):
    ```markdown
@@ -43,15 +43,6 @@ Create these four files (with `Write`), exactly in this order. Per §Provider de
    description: |
      Example skill that walks a file and returns a Markdown report.
      Showcases the `skill` kind in the demo map.
-   inputs:
-     - name: target
-       type: path
-       description: File to process.
-       required: true
-   outputs:
-     - name: report
-       type: string
-       description: Markdown summary.
    ---
 
    # demo-skill
@@ -70,20 +61,14 @@ Create these four files (with `Write`), exactly in this order. Per §Provider de
    ---
    name: demo-command
    description: |
-     Example slash-style command that wraps the demo-skill behind
-     a keyboard shortcut. Showcases the `command` kind.
-   shortcut: "ctrl+alt+d"
-   args:
-     - name: target
-       type: path
-       description: File the command will hand off to the skill.
-       required: true
+     Example slash command that wraps the demo-skill. Showcases the
+     `command` kind.
    ---
 
    # demo-command
 
-   Quick keyboard entry point for running the demo flow on a
-   target file. Connectors land in the next sub-step.
+   Quick entry point for running the demo flow on a target file.
+   Connectors land in the next sub-step.
    ```
 
 3. `notes/todo.md`, classified as `kind: markdown` today
@@ -96,23 +81,21 @@ Create these four files (with `Write`), exactly in this order. Per §Provider de
      Live list of things to review in the demo. Will become the
      hub that points to the rest of the fixture in the next
      sub-step.
-   tags: [notes, demo]
    ---
 
    # Pending
    ```
 
-4. `notes/demo-guideline.md`, second `kind: markdown` node, the
-   one the hub will reach via a real markdown link in the
-   `connectors` chapter:
+4. `notes/demo-guideline.md`, second `kind: markdown` node, reached
+   in the `connectors` chapter by a bare `@`-mention that can't
+   resolve, so it stays skill-map's faintest connector:
    ```markdown
    ---
    name: demo-guideline
    description: |
-     Static reference notes that the rest of the demo points at.
-     Showcases a second markdown node so the demo can exercise
-     the `references` link kind without ambiguity.
-   tags: [notes, demo]
+     Static reference notes the rest of the demo points at. The hub
+     reaches it with a bare `@`-mention, which stays a faint guess
+     (0.50) because it can't resolve to a known entity.
    ---
 
    # Demo Guideline
@@ -124,27 +107,48 @@ Create these four files (with `Write`), exactly in this order. Per §Provider de
    - Body stays minimal, only what's needed to teach the kind.
    ```
 
+5. `notes/demo-guideline2.md`, a sibling `markdown` node identical
+   to `demo-guideline`, reached by the same handle plus a `.md`
+   extension (`@demo-guideline2.md`), which makes it a file reference
+   that resolves to this node and lands at full confidence:
+   ```markdown
+   ---
+   name: demo-guideline2
+   description: |
+     Sibling of demo-guideline. The hub reaches it with an
+     `@`-mention that carries the `.md` extension, so the link
+     resolves to this file and lands certain (1.00).
+   ---
+
+   # Demo Guideline 2
+
+   Same conventions as demo-guideline; it exists so the hub can
+   reach it with a resolved reference instead of a bare mention.
+   ```
+
 Tell the tester:
 
-> Look at the browser. Four new nodes should have popped in:
-> `demo-skill`, `demo-command`, **Demo TODO list**, and `demo-guideline`.
-> Five total now, **still unconnected**: they're floating dots.
+> Look at the browser. Five new nodes should have popped in:
+> `demo-skill`, `demo-command`, **Demo TODO list**, `demo-guideline`,
+> and `demo-guideline2`.
+> Six total now, **still unconnected**: they're floating dots.
 > The viewport auto-fits whenever a node is added or removed, so
-> all five should be visible without panning.
+> all six should be visible without panning.
 >
-> What I just did behind the scenes: I created four new files in
+> What I just did behind the scenes: I created five new files in
 > your project, and the watcher picked them up on its own, that's
-> why four new dots appeared without you running anything:
+> why five new dots appeared without you running anything:
 >
 > - `.claude/skills/demo-skill/SKILL.md` (kind: skill)
 > - `.claude/commands/demo-command.md` (kind: command)
 > - `notes/todo.md` (kind: markdown)
 > - `notes/demo-guideline.md` (kind: markdown)
+> - `notes/demo-guideline2.md` (kind: markdown)
 >
 > Same loop you'll use yourself in the next step, only this time
 > the writes came from me.
 >
-> Did the four appear? Confirm so we can wire them up.
+> Did the five appear? Confirm so we can wire them up.
 
 Wait for confirmation. Mark `kinds`: done.
 
@@ -168,24 +172,24 @@ Tell the tester:
 >
 > Watch the browser. The `demo-agent` card should refresh its
 > description in real time, no reload, no Ctrl+C, same watcher
-> that picked up the four new nodes a moment ago, this time
+> that picked up the five new nodes a moment ago, this time
 > reacting to YOUR edit.
 >
-> Confirm so we wire the five up.
+> Confirm so we wire the six up.
 
 Wait for confirmation. You MAY use `Read` on the file afterwards to verify the change landed (read-only, allowed under Inviolable rule #1) before moving on. Mark `first-edit`: done.
 
 ## Chapter `connectors` - The connectors light up (~2 min)
 
-You edit `notes/todo.md` so it becomes the **hub** that points to each of the other four nodes. Each bullet uses a syntax that maps to a specific **link kind**:
+You edit `notes/todo.md` so it becomes the **hub** that points to each of the other five nodes. Each bullet uses a syntax that maps to a specific **link kind**:
 
 - an `@handle` token → kind `mentions`
+- an `@handle.md` token (a `@` handle that ends in a file extension) → kind `references`
 - a `/slash` token → kind `invokes`
-- a markdown link `[text](path)` → kind `references`
 
-Five bullets, three kinds: `invokes` and `mentions` each appear twice, `references` once. The last two bullets both point at the **same** node (`demo-guideline`), on purpose: a markdown link AND an `@`-mention of it, so the next beat can contrast their confidence (the file link is certain, the name drop is a softer guess).
+Five bullets, three kinds: `invokes` and `mentions` each appear twice, `references` once. The last two bullets are the confidence lesson: a bare `@demo-guideline` mention (which can't resolve, so it stays a faint guess) next to `@demo-guideline2.md`, the same handle shape plus a `.md` extension that points at a real sibling file (so it resolves and lands certain). Two separate nodes, two clearly different confidences.
 
-Apply with `Edit` on `notes/todo.md` (do not rewrite the file). Per §Provider detection, **substitute `.claude/` with the detected `<provider_dir>` and drop any bullet whose target node was not created in the `kinds` chapter** (on `agent-skills` / Antigravity there is no agent and no command → skip the `@demo-agent` and `/demo-command` bullets; the `@demo-guideline` mention stays and is the faint connector on those providers too).
+Apply with `Edit` on `notes/todo.md` (do not rewrite the file). Per §Provider detection, **substitute `.claude/` with the detected `<provider_dir>` and drop any bullet whose target node was not created in the `kinds` chapter** (on `agent-skills` / Antigravity there is no agent and no command → skip the `@demo-agent` and `/demo-command` bullets; the two guideline bullets stay, so the confidence contrast, faint mention 0.50 vs resolved reference 1.00, is intact on those providers too).
 
 **Edit `notes/todo.md`**: append these bullets after the `# Pending` heading:
 
@@ -193,9 +197,8 @@ Apply with `Edit` on `notes/todo.md` (do not rewrite the file). Per §Provider d
 - [ ] Brief @demo-agent on the rough edges.
 - [ ] Run /demo-command before publishing.
 - [ ] Trigger /demo-skill when the input lands.
-- [ ] Re-read the
-      [demo-guideline](./demo-guideline.md) before shipping.
 - [ ] Ping @demo-guideline if the conventions change.
+- [ ] Ping @demo-guideline2.md if the conventions change.
 ```
 
 Tell the tester:
@@ -207,22 +210,32 @@ Tell the tester:
 > - `Demo TODO list → demo-agent` (kind: `mentions`)
 > - `Demo TODO list → demo-command` (kind: `invokes`)
 > - `Demo TODO list → demo-skill` (kind: `invokes`)
-> - `Demo TODO list → demo-guideline` (kind: `references`, the markdown link)
-> - `Demo TODO list → demo-guideline` (kind: `mentions`, the @ handle)
+> - `Demo TODO list → demo-guideline` (kind: `mentions`, the bare `@` handle)
+> - `Demo TODO list → demo-guideline2` (kind: `references`, the `@` handle with a `.md` extension)
+>
+> The kind comes from the syntax in the bullet: an `@handle` is a
+> mention, a `/skill` or `/command` is an invoke, and an `@handle`
+> that ends in a file extension (`@name.md`) is a reference, the
+> extension turns the name drop into a file pointer. Five arrows,
+> three kinds.
+>
+> Now look closely: the two guideline arrows are not equally solid.
+> Skill-map draws each connector's **confidence** as opacity, how
+> sure it is the link resolves to something real:
 >
-> The kind comes from the syntax in the bullet: an `@handle` is
-> always a mention, a `/skill` or `/command` is always an invoke, a
-> markdown link is always a reference. Five arrows, three kinds.
+> - `@demo-guideline` is a bare `@`-mention. A bare mention only
+>   firmly resolves to an *agent*, and `demo-guideline` is a note,
+>   not an agent, so skill-map keeps it a soft guess (0.50), drawn
+>   faint. (That's also why `@demo-agent` above is solid: it does
+>   resolve to a real agent.)
+> - `@demo-guideline2.md` adds the `.md`, so skill-map reads a file
+>   pointer, finds the real `demo-guideline2.md` node, and is certain
+>   (1.00), drawn solid.
 >
-> Now look closely: the two arrows to **demo-guideline** are not
-> equally solid. Skill-map draws each connector's **confidence** as
-> opacity, how sure it is the link is real. The markdown link
-> `[demo-guideline](./demo-guideline.md)` points at a real file, so
-> it's certain (1.00) and looks solid; the `@demo-guideline` mention
-> is a looser name drop, a softer guess (0.50), so it's drawn fainter.
-> A glance at the map tells you which links are rock solid and which
-> are skill-map's best guess; the exact number per link is in the
-> inspector, next chapter.
+> Same handle, one `.md` apart, and the confidence jumps from a guess
+> to a certainty. A glance at the map tells you which links are rock
+> solid and which are skill-map's best guess; the exact number per
+> link is in the inspector, next chapter.
 >
 > Confirm when you see it. If a connector is missing, refresh the
 > browser and let me know.
@@ -238,12 +251,11 @@ The connector opacity tells the confidence story at a glance; the exact per-link
 > by default): it has two sections, **Outgoing** and **Incoming**.
 > Demo TODO list lists **5 links** under Outgoing (the hub) and 0
 > under Incoming; open the Inspector for a targeted node to see its
-> Incoming count (demo-guideline shows **2**, the reference plus the
-> mention; the others 1 each). Each row shows the link kind
-> (`mentions`, `invokes`, `references`) and a badge with its
-> confidence: the numeric value. Here you'll see the contrast in
-> numbers, the `references` to demo-guideline reads `1.00`, the
-> `mentions` of it reads `0.50`.
+> Incoming count (each node the hub points at shows **1**). Each row
+> shows the link kind (`mentions`, `invokes`, `references`) and a
+> badge with its confidence: the numeric value. Here you'll see the
+> contrast in numbers, the `mentions` to `demo-guideline` reads
+> `0.50`, while the `references` to `demo-guideline2` reads `1.00`.
 >
 > 💡 Tip: if all these changes left the nodes crowded together, the
 > map toolbar has a **Re-arrange layout** button (tooltip "Re-arrange
@@ -283,7 +295,7 @@ Per §Provider detection, on `agent-skills` / Antigravity the fixture has fewer
 > by default: click the expand handle there (the `>` arrow, its
 > tooltip reads "Expand files panel"). The sidebar opens into a
 > **folder tree** (a nested view of your folders and the nodes inside
-> them): your five nodes grouped under `.claude/` and `notes/`, each
+> them): your six nodes grouped under `.claude/` and `notes/`, each
 > row showing its kind and how many links go in and out.
 >
 > Tell me when the tree is open.
@@ -292,11 +304,12 @@ Per §Provider detection, on `agent-skills` / Antigravity the fixture has fewer
 
 > 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 `demo-guideline` and the **Map** drops every node
-> except `demo-guideline`. The search matches a node's name, path,
+> 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.
 >
-> Now clear the box. All five nodes come back, in both the tree and
+> Now clear the box. All six nodes come back, in both the tree and
 > the Map. Confirm you saw it filter and then restore.
 
 **Beat 3, isolate (tester does this).**
@@ -306,7 +319,8 @@ Per §Provider detection, on `agent-skills` / Antigravity the fixture has fewer
 > "Isolate this node and its direct links on the map"). Click it.
 >
 > The Map collapses to **Demo TODO list** plus only the nodes it
-> links to (`demo-command`, `demo-skill`, `demo-guideline`).
+> links to (`demo-command`, `demo-skill`, `demo-guideline`,
+> `demo-guideline2`).
 > `demo-agent`, which lost its only connector back in the last step,
 > drops out of view, and the Inspector opens on **Demo TODO list**.
 > That's how you
@@ -314,7 +328,7 @@ Per §Provider detection, on `agent-skills` / Antigravity the fixture has fewer
 >
 > To bring the rest back, look at the toolbar along the bottom of
 > the Map: there's a **Show all** button (an eye icon). Click it and
-> all five nodes return.
+> all six nodes return.
 >
 > Did the map isolate and then restore?
 
@@ -344,14 +358,14 @@ description: |
 API_TOKEN: example-not-real
 ```
 
-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.
+It lands in the map as a seventh 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.
 
 **The tester hides it (single tester-facing message, one confirmation).**
 
 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. Your `private-credentials` note just popped into
-> the map as a sixth node, that's the watcher again. Now let's hide
+> the map as a seventh node, that's the watcher again. Now let's hide
 > it. Here's what your directory looks like right now:
 
 ```
@@ -367,6 +381,7 @@ Give the tester a mental map of the folder so they know where the file lives, th
 └── notes/
     ├── todo.md
     ├── demo-guideline.md
+    ├── demo-guideline2.md
     └── private-credentials.md   ← what we want to hide
 ```
 
@@ -387,8 +402,8 @@ notes/private-*.md
 >
 > Watch the browser when you save. The
 > `notes/private-credentials` node should disappear from the
-> **Map** in real time, without restarting anything. Six nodes
-> back to five.
+> **Map** in real time, without restarting anything. Seven nodes
+> back to six.
 >
 > Did the node vanish?
 

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

@@ -1,4 +1,4 @@
-# Part 6: Ship the site (the full publish pipeline) (step library, finale, `pipeline` + `golive`)
+# Part 5: Ship the site (the full publish pipeline) (step library, finale, `pipeline` + `golive`)
 
 The finale, the climax of the whole campaign. In Part 3 you ran the
 harness once, the simple way (generate two pages, serve them). Here you
@@ -80,8 +80,8 @@ Tell the tester:
 >
 > **Step 2, brief the editor** (`@content-editor`). The check found
 > nothing to fix, so there is no brief to hand off this time, that is
-> the happy path. (Part 4 is where a link actually breaks and this
-> step earns its keep.)
+> the happy path. (Maintaining the harness is where a link actually
+> breaks, and that is where this step earns its keep.)
 >
 > **Step 3, follow the deploy runbook** (`docs/DEPLOY.md`). It lists:
 > generate the pages (done), run the link check (done), start the
@@ -122,7 +122,7 @@ Tell the tester:
 > Last step, the fun one. In your terminal, run these two commands:
 >
 > `npm install` downloads the one small library the server needs
-> (Express). If you already ran it in Part 3 it just confirms it is
+> (Express). If you already ran it earlier it just confirms it is
 > there. Then `node server.js` starts the server; it prints a line
 > like `Listening on http://localhost:3000`.
 >
@@ -134,7 +134,7 @@ Tell the tester:
 > Now take it all in at once. On one side, the real running site you
 > can click through. On the other, the skill-map graph of the harness
 > that built it: the handbook, the content editor, the style guide,
-> the publish command, the link checker, the MCP tool, all wired
+> the publish command, the link checker, all wired
 > together. You started in an empty folder with nothing, and you have
 > ended with a real, running site and a living map of how it all fits.
 >

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

@@ -1,4 +1,4 @@
-# Part 4: Maintain the site (step library, `maintain`)
+# Part 4: Maintain the harness (step library, `maintain`)
 
 This is the upkeep part. The harness from Part 2 is wired and clean; real projects drift, links break, drafts pile up, names collide. Here the tester breaks something on purpose and fixes it, meets the analyzer catalogue that catches those problems, finds an orphan nobody links to, clears a reserved-name warning, and learns the `.sm` companion files that carry the tool's bookkeeping. `pace: auto-advance` (walk straight into the next chapter once one is marked done), `preflight: seed` (it builds on the portfolio harness from Parts 1 and 2, reusing the accumulated state when its predecessors are done, 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.
 
@@ -113,7 +113,7 @@ Wait for confirmation. Mark `analyzers`: done.
 
 ## Chapter `orphans` - A page nobody links to (~3 min)
 
-**Context**: a different kind of loose end. A node can be perfectly valid and still be an orphan: nothing in the harness links to it. We create a draft page that no one references, and `sm orphans` finds it. The point is to separate three ideas the tester now has names for: orphan (nothing points at it) vs broken-ref (a link with no target) vs issue (a rule violation).
+**Context**: a different kind of loose end. A node can be perfectly valid and still be an orphan: nothing in the harness links to it. We create a draft page that no one references; it lands on the **Map** as a floating dot, and `sm show` confirms it has no incoming links. The point is to separate three ideas the tester now has names for: orphan (nothing points at it) vs broken-ref (a link with no target) vs issue (a rule violation). Note: orphan-ness is a property of the graph (visible on the Map / inspector), there is no `sm check` analyzer for it. The separate `sm orphans` verb is unrelated (it surfaces history stranded by a rename, not unlinked pages), so do NOT run it or bring it up with the tester here.
 
 `Write` `docs/draft.md` (markdown kind), a half-finished page nobody has wired up yet:
 
@@ -123,7 +123,6 @@ name: draft
 description: |
   Half-finished page nobody links to yet. Here to show what an
   orphan looks like: a valid node with no incoming connectors.
-tags: [docs, portfolio, draft]
 ---
 
 # Draft page
@@ -138,28 +137,40 @@ Tell the tester:
 > I dropped a new note into your project, `docs/draft.md`, a
 > half-finished page. Look at the **Map**: it shows up as a floating
 > dot with no arrows touching it. Nothing in your harness links to it,
-> which makes it an **orphan**.
+> which makes it an **orphan**. Click the dot, the inspector shows no
+> connections in or out.
+>
+> You can confirm the same thing from the CLI:
 >
 > ```bash
-> sm orphans
+> sm show docs/draft.md
 > ```
 >
-> `sm orphans` lists exactly that: nodes nothing points at. It is
-> worth keeping three ideas apart, because they are easy to confuse:
+> It prints the node's details, and there is **no "Links in"
+> section**, nothing references it. That absence is exactly what
+> "orphan" means here.
+>
+> It is worth keeping three ideas apart, because they are easy to
+> confuse:
 >
 > - **orphan**: a real, valid node that simply has no incoming link
->   (your `docs/draft`). Not an error, just unreferenced.
+>   (your `docs/draft`). Not an error, just unreferenced, and visible
+>   on the Map as a floating dot.
 > - **broken-ref**: a link whose target file does not exist (the one
->   you triggered by renaming the runbook). That is a real issue.
+>   you triggered by renaming the runbook). That is a real issue
+>   `sm check` reports.
 > - **issue**: any rule violation `sm check` reports (broken-ref is
 >   one family; name-reserved, self-loop and the rest are others).
 >
-> An orphan is not automatically a problem (a draft you have not wired
-> up yet is fine), it is just skill-map pointing out the page is not
-> reachable from anywhere. When you link to it later, it stops being
-> an orphan.
+> An orphan is not automatically a problem. Sometimes it is a draft you
+> have not wired up yet; sometimes it is a node you deliberately keep on
+> its own, isolated on purpose, and that is just as valid. skill-map is
+> only pointing out that the page is not reachable from anywhere, not
+> telling you to fix it: if you link to it later it stops being an
+> orphan, and if you never do, that was your call, not an error.
 >
-> Did `sm orphans` list `docs/draft`?
+> Did `docs/draft` land as a floating dot, with `sm show` confirming
+> no links in?
 
 Wait for confirmation. Mark `orphans`: done.
 
@@ -175,11 +186,6 @@ name: init
 description: |
   Bootstraps a fresh portfolio scaffold. Named init on purpose, to
   collide with the runtime built-in and trigger name-reserved.
-args:
-  - name: target
-    type: path
-    description: Folder to scaffold into.
-    required: true
 ---
 
 # init
@@ -264,38 +270,15 @@ sm sidecar annotate AGENTS.md
 > layer (gitignored), so each contributor consents on their own
 > checkout and the choice never travels through git.
 >
-> Did the prompt appear, and does `AGENTS.sm` exist now?
-
-Wait for confirmation. You MAY use `Read` on `AGENTS.sm` to verify it landed. Mark `sidecar`: done.
-
-## Chapter `versions` - Bump a version, read its history (~3 min)
-
-**Context**: now that the consent is granted, the day-to-day versioning verbs go through silently. `sm bump` increments a node's frontmatter version and appends a record to its `.sm` companion; `sm history` reads that trail back. We bump the content editor and read its history. Same consent gate as the previous chapter, already satisfied.
-
-This is a CLI beat, the tester runs everything (substitute `<provider_dir>` in the path per `_core.md`):
-
-```bash
-sm bump content-editor
-sm history content-editor
-```
-
-> `sm bump <node>` is the everyday versioning verb: it nudges the
-> `version` field in the node's frontmatter up by one and appends an
-> entry to that node's `.sm` companion file, recording that the bump
-> happened. Because you already granted consent in the last chapter,
-> it runs without prompting (the `.sm` write is pre-authorized for
-> this checkout).
->
-> `sm history <node>` reads that trail back: it prints the version
-> entries skill-map has recorded for the content editor, so you can
-> see how it has changed over time. Right after one bump you will see
-> the single entry the bump just wrote.
->
-> The two verbs are a pair: `sm bump` writes a version checkpoint into
-> the companion file, `sm history` reads the checkpoints back out.
-> Your `.md` body never gets cluttered with this, it all lives in the
-> `.sm` alongside it.
+> **Tip:** that `.sm` is also where the inspector gets a node's
+> **Metadata**. With the live `sm` still running, click the `AGENTS`
+> node on the **Map**: the inspector now shows a **Metadata** section
+> that was not there before you created the companion file. It reads
+> straight from `AGENTS.sm`, so a node with no `.sm` has no Metadata
+> section at all. For now it reads **never bumped**, because you only
+> scaffolded the file; once you start running `sm bump AGENTS.md` that
+> panel fills in **Created** and **Last bumped**.
 >
-> Does `sm history` show the bump you just made?
+> Did the prompt appear, and does `AGENTS.sm` exist now?
 
-Wait for confirmation. Mark `versions`: done. Last chapter of the part: apply §Closing a part (the close names the part by its title and routes back to the menu).
+Wait for confirmation. You MAY use `Read` on `AGENTS.sm` to verify it landed. Mark `sidecar`: done. Last chapter of the part: apply §Closing a part (the close names the part by its title and routes back to the menu).

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

@@ -1,10 +1,10 @@
-# Part 5: MCP (step library, `mcp-*` ids)
+# Part 8: MCP (step library, `mcp-*` ids)
 
-This is a chapter apart, the one just before the finale. Pace
-`auto-advance`, preflight `reuse` (it builds straight on the
-connected portfolio harness from the earlier parts, same cwd, same
-live `sm` session). One chapter only. Shared conventions live in
-`_core.md`.
+This is a chapter apart, a standalone appendix that comes last in the
+book. Pace `auto-advance`, preflight `seed` (`harness-connected`, so it
+fast-forwards onto the connected portfolio harness whether the campaign
+was just run in this directory or you jumped straight here). One chapter
+only. Shared conventions live in `_core.md`.
 
 ## Chapter `mcp-node` - The agent reaches for an MCP tool (~3 min)
 

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

@@ -1,4 +1,4 @@
-# Part 7 (b): Extend skill-map - plugins (step library, `tour-*` ids)
+# Part 6 (b): Extend skill-map - plugins (step library, `tour-*` ids)
 
 Guided tour of the **built-in plugins** that ship with `sm`. Three
 steps: a quick mental model of what plugins are plus a peek at

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

@@ -5,7 +5,7 @@ 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 (Part 3 runs it, Part 6 ships it).
+is plain HTML the harness produces (Part 3 runs it, Part 5 ships it).
 `pace: per-step`, `preflight: portfolio-init`. Shared
 conventions live in `_core.md`.
 
@@ -54,8 +54,9 @@ Wait for confirmation. Mark `kickoff`: done.
 
 **Context**: the dogfood beat. Real Claude Code projects keep a
 `CLAUDE.md` that just points at `AGENTS.md` (this very repo does).
-That one-line pointer is a real `mentions` link, the tester's first
-connector on the real project.
+That one-line pointer is a real `references` link (the `.md` extension
+makes `@AGENTS.md` a file pointer, not a bare mention), the tester's
+first connector on the real project.
 
 Tell the tester to create the file themselves (it is their project's
 file, Inviolable rule #2):
@@ -68,10 +69,13 @@ file, Inviolable rule #2):
 > ```
 >
 > Save it. Watch the map: a new `CLAUDE.md` node appears, with a
-> `mentions` connector pointing at `AGENTS.md`. The `@name` token is
-> the same mention syntax from the prologue, now doing real work: it
-> tells anyone (and skill-map) that `CLAUDE.md` defers to the
-> handbook. This is exactly how this tool's own repo is wired.
+> `references` connector pointing at `AGENTS.md`, solid at 1.00.
+> Because `@AGENTS.md` carries the `.md` extension, skill-map reads it
+> as a file pointer (the same `@name.md` reference you met in the
+> prologue, not a bare mention), 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.
 >
 > Did the connector light up?
 
@@ -135,7 +139,6 @@ runbook), so Part 4's maintenance beats have something to point at.
 name: style-guide
 description: |
   Writing and markup conventions every portfolio page follows.
-tags: [docs, portfolio]
 ---
 
 # Style guide
@@ -151,7 +154,6 @@ tags: [docs, portfolio]
 name: deploy-runbook
 description: |
   How the portfolio gets published once the pages are written.
-tags: [docs, portfolio]
 ---
 
 # Deploy runbook

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

@@ -1,11 +1,12 @@
-# Part 3: Run the harness (your site, live) (step library, `generate` + `serve`)
+# Part 3: Run the harness (your site, live) (step library, `generate` + `serve` + `editor-live`)
 
 The first payoff: the harness you built and wired in the earlier parts
 finally does its job and you see a real site running, without waiting
 for the finale. Pace `auto-advance`, preflight `seed` (`harness-connected`,
-so a tester can jump straight here). Two chapters, in order:
-`generate` (the agent writes the HTML pages) then `serve` (the tester
-runs the site and sees it next to the graph). This is a deliberately
+so a tester can jump straight here). Three chapters: `generate` (the
+agent writes the HTML pages), `serve` (the tester runs the site next to
+the graph), then an optional `editor-live` (the tester lets the real
+`content-editor` agent write a posts page). This is a deliberately
 simple, working pass: maintenance, MCP and the full publish pipeline
 come in the parts after it. Shared conventions live in `_core.md`.
 
@@ -149,7 +150,32 @@ stop the server with Ctrl+C and the edge case for ports applies the
 same as elsewhere. Remind them they can leave the server running or
 stop it with Ctrl+C; either way the next parts do not need it.
 
-Mark `serve`: done. Last chapter of the part: apply §Closing a part
-(the close names the part by its title and routes back to the menu;
-this is a mid-campaign payoff, NOT the campaign finale, so do not
-sign the campaign off here).
+Mark `serve`: done. Auto-advance to the optional `editor-live` chapter.
+
+## Chapter `editor-live` - Let the content-editor agent write a posts page for real (optional) (~3 min)
+
+**Context**: optional payoff, and the first time the tester runs a harness member for real instead of playing it. In `generate` the tester (as the agent) wrote the HTML by hand; here the actual `content-editor` agent does the job. The tester asks for a new **posts** page, the tutorial invokes the agent, and a real `public/posts.html` lands, proof that the nodes on the map are runnable, not just a diagram. The Layer-1 / Layer-2 split still holds: the new HTML does NOT move the graph (HTML is not `.md`). Fully skippable; run it or skip it, the part closes either way.
+
+On `agent-skills` / Antigravity the `content-editor` member is a **skill**, not an `agent`; invoke it as a skill and keep everything else identical.
+
+This chapter is OPTIONAL and the tester opts in. Offer it; if they skip, go straight to the part close below.
+
+Tell the tester:
+
+> Optional last beat, and the fun one: so far you have *played* the
+> `content-editor` yourself. Want to see it run for real? Ask me to add
+> a **posts** page with your agent, for example: "use the
+> content-editor agent to add a posts page". I'll invoke the real
+> `content-editor` in your project; it reads its own rules and the
+> style guide, then writes a new static page into `public/`.
+>
+> Watch two things: the new page lands in `public/` (and shows on the
+> live site when you open it), and the **Map does NOT move**, same
+> Layer-1 / Layer-2 split as before, the agent's HTML output is not
+> part of the harness graph.
+>
+> Or just tell me to skip it and we'll wrap up this part.
+
+If the tester opts in: invoke the project's `content-editor` (the `<provider_dir>/agents/content-editor.md` agent, or the skill on `agent-skills`) via the Task tool to write ONE new static page `public/posts.html`, following the agent's own rules and `docs/STYLE.md` (plain HTML, no framework, no client JS, one page per file, a nav link back to Home), holding two or three short sample posts (a heading plus a sentence or two each). Do NOT edit `public/index.html` or any `.md` harness file, and do NOT edit the agent definition. If the subagent is not invocable in the tester's setup, act as the `content-editor` yourself following the same rules so the beat still lands. Then tell the tester to open `http://localhost:3000/posts.html` (refresh and navigate there), confirm the posts page is live and links back home, and confirm the **Map stayed still**.
+
+Wait for confirmation (ran it or skipped). Mark `editor-live`: done. Last chapter of the part: apply §Closing a part (the close names the part by its title and routes back to the menu; this is a mid-campaign payoff, NOT the campaign finale, so do not sign the campaign off here).