@skill-map/cli 0.53.4 → 0.53.5

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

@@ -145,7 +145,7 @@ every other `<cwd>` mention.
 >    output, and I verify.
 > 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.
+>    That's where you copy and paste every command I give you to run.
 
 ```bash
 cd <cwd>
@@ -195,12 +195,13 @@ the files the prologue's own chapters lay as taught steps, exactly this
 set: `<provider_dir>/agents/demo-agent.md`,
 `<provider_dir>/skills/demo-skill/`,
 `<provider_dir>/commands/demo-command.md`, `notes/todo.md`,
-`notes/demo-guideline.md`, `notes/private-credentials.md`. This is the
+`notes/demo-guideline.md`, `notes/demo-guideline2.md`,
+`notes/private-credentials.md`. This is the
 single source for that list. Four entry points delete exactly this set
 when the prologue ran first in the dir: `portfolio-init`, the campaign
-`seed` fast-forward, and `backstage-init` (Part 7), each so the part's
+`seed` fast-forward, and `backstage-init` (Part 6), each so the part's
 own fixture starts from a clean slate, plus start-over (§Menu, resume,
-wrap-up). Part 8 `cli` is the inverse
+wrap-up). Part 7 `cli` is the inverse
 consumer: its `prologue-built` seed *lays* this fixture (the
 connector-chapter subset, without `notes/private-credentials.md`)
 instead of deleting it, see `fixtures.md` §Seed snapshots. Keep the list
@@ -332,7 +333,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 7 `extend`): the part teaches plugins on
+- **`backstage-init`** (Part 6 `extend`): the part teaches plugins on
   its own **master fixture**, distinct from both the demo and the
   portfolio, so on entry make the master fixture the only one on disk.
   Silently, with no narration: (1) clear whatever prior-part fixture is
@@ -352,10 +353,10 @@ When a part begins, honour its `preflight` from the manifest:
   `Write` the part's fixture (read `references/fixtures.md` for the
   verbatim `master-agent` / `master-skill` / `notes/ideas` files; skip
   kinds the provider doesn't claim). If nothing needed clearing and the
-  dir was already initialised with the master fixture in place (Part 7
+  dir was already initialised with the master fixture in place (Part 6
   re-entry), that is fine: skip the init and just ensure the fixture
   files are present.
-- **`seed: prologue-built`** (Part 8 `cli`): the part reads the **Part 0
+- **`seed: prologue-built`** (Part 7 `cli`): the part reads the **Part 0
   demo fixture**, NOT the cumulative portfolio, so on entry make that
   fixture the one on disk. Read the state, then:
   - Demo fixture already present (the tester came straight from the
@@ -374,7 +375,15 @@ When a part begins, honour its `preflight` from the manifest:
   On entry, read the state file:
   - If every predecessor campaign part up the `prereq` chain is `done`
     → reuse the accumulated state; an `sm scan` to refresh is enough,
-    nothing to lay.
+    nothing to lay. **`mcp` is the exception**: it is ordered last,
+    after `extend` (Part 6) and `cli` (Part 7), which both replace the
+    portfolio on disk with their own master / demo fixture, so its
+    accumulated state cannot be trusted to still be the portfolio.
+    `mcp` therefore ALWAYS re-lays its `harness-connected` snapshot on
+    entry (clearing a master / demo fixture first if one is present,
+    the same clears the `backstage-init` and `prologue-built` cases
+    do), then `sm init` if `.skill-map/` is missing and `sm scan`,
+    exactly like the fast-forward branch below.
   - Else → **fast-forward, silently** (backstage, do not narrate the
     plumbing): first, if the prologue ran first in this dir, clear the
     full Part 0 demo fixture set (§Fixture and state templates) so the
@@ -413,7 +422,7 @@ All three are specified in `_core.md`:
   the **numbered start menu** (Part 0 is option 1, the recommended
   first pick); the menu (the ToC from `_manifest.yml`, numbered,
   completed parts ticked, `planned` parts hidden, `prereq` gating only
-  seedless parts, none today since Part 8 `cli` now self-seeds) is the
+  seedless parts, none today since Part 7 `cli` now self-seeds) is the
   entry point on the first
   invocation and after every part closes / on resume. Render it with
   the format in `_core.md` §Menu format.
@@ -421,7 +430,7 @@ All three are specified in `_core.md`:
   wipe list is whatever the tester's parts actually created:
   `tutorial-state.yml`, `findings.md`, `.skillmapignore`,
   `.skill-map/`, the full Part 0 demo fixture set (§Fixture and state
-  templates), the Part 7 fixture if `extend` ran
+  templates), the Part 6 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

@@ -293,11 +293,11 @@ For every chapter:
   §Menu format).
 - **Which parts to list**: parts in `order`, `status: active` only
   (`planned` parts are hidden). A part with a `seed` (the campaign
-  parts plus Part 8 `cli`) is always shown, even out of order, its
+  parts plus Part 7 `cli`) 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` would be
   shown only once its `prereq` is `done`; no active part is in that
-  state today (Part 8 `cli` used to be, now it self-seeds).
+  state today (Part 7 `cli` used to be, now it self-seeds).
 - **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

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

@@ -51,7 +51,7 @@ parts:
       - id: ignore          ; title: "Silence a file via .skillmapignore"  ; est_min: 2
 
   - id: extend
-    order: 7
+    order: 6
     title: "Extend skill-map for the site"
     # Spans three chapter libraries; dispatch by chapter-id prefix:
     #   settings-*  -> part-settings.md
@@ -81,7 +81,7 @@ parts:
       - id: authoring-6-upgrade      ; title: "Try `sm plugins upgrade`" ; est_min: 2
 
   - id: cli
-    order: 8
+    order: 7
     title: "The CLI in depth"
     step_file: part-cli.md
     pace: auto-advance
@@ -142,8 +142,9 @@ 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: 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: editor-live ; title: "Let the content-editor agent write a posts page (optional)" ; est_min: 3
 
   - id: maintain
     order: 4
@@ -157,14 +158,13 @@ parts:
     chapters:
       - id: broken-ref   ; title: "A ref breaks (you rename DEPLOY.md)" ; est_min: 3
       - id: analyzers    ; title: "The analyzer catalogue (what sm check catches)" ; est_min: 3
-      - id: orphans      ; title: "Orphans (sm orphans)" ; est_min: 2
+      - id: orphans      ; title: "Orphans (a page nobody links to)" ; est_min: 2
       - id: reserved     ; title: "Reserved names" ; est_min: 2
       - id: sidecar      ; title: "Annotations .sm and consent" ; est_min: 3
-      - id: versions     ; title: "Versions: sm bump and history" ; est_min: 2
 
   - id: mcp
-    order: 5
-    title: "MCP"            # a chapter apart, just before the finale
+    order: 8
+    title: "MCP"            # standalone appendix, ordered last; ALWAYS re-seeds harness-connected (extend/cli wipe the portfolio before it)
     step_file: part-mcp.md
     pace: auto-advance
     preflight: seed
@@ -175,7 +175,7 @@ parts:
       - id: mcp-node ; title: "content-editor declares an MCP tool; the mcp:// node appears" ; est_min: 3
 
   - id: live-site
-    order: 6
+    order: 5
     title: "Ship the site (the full publish pipeline)"  # the finale / climax
     step_file: part-live-site.md
     pace: auto-advance

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

@@ -1,7 +1,7 @@
 # Fixture templates
 
 Fixtures the orchestrator lays for the auto-fixtured parts. Two full
-templates live here: the **master fixture** (Part 7, "Extend
+templates live here: the **master fixture** (Part 6, "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. The **Part 0 demo fixture** is not templated here:
@@ -18,7 +18,7 @@ context for. Holds for every command fixture wherever it is defined
 (today: the prologue `demo-command`, the `publish` command, and the
 `reserved` chapter's `init`).
 
-## Master fixture (Part 7): layout (per provider)
+## Master fixture (Part 6): layout (per provider)
 
 Per §Provider detection in `SKILL.md`, the `<provider_dir>`
 placeholder resolves to `.claude/` or `.agents/skills/` depending
@@ -146,7 +146,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 3 runs it, Part 6 ships it). The one boot node is the
+real and runnable (Part 3 runs it, Part 5 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.
@@ -224,7 +224,7 @@ Append to the universal `.skillmapignore` (written in pre-flight, see
 ## Seed snapshots (for `preflight: seed`)
 
 When the orchestrator enters a seedable part out of order (the campaign
-parts when their predecessors are not `done`, or Part 8 `cli` when the
+parts when their predecessors are not `done`, or Part 7 `cli` when the
 demo fixture is not the one on disk), it fast-forwards the project by
 laying the snapshot below, then `sm init` (if `.skill-map/` is missing) +
 `sm scan`. These are **checklists, not content**: each row names a file
@@ -259,16 +259,16 @@ Everything in `harness-built`, PLUS the Part 2 wiring:
 After laying a campaign snapshot the map matches the state a tester would
 have at the END of the part just before the one being entered.
 
-### Seed snapshot: `prologue-built` (Part 8 `cli`)
+### Seed snapshot: `prologue-built` (Part 7 `cli`)
 
 NOT cumulative and NOT the portfolio: this is the **Part 0 demo
-fixture**, the five standalone demo nodes with `notes/todo` wired as the
+fixture**, the six standalone demo nodes with `notes/todo` wired as the
 hub, the clean state (`✓ No issues`) at the end of the prologue's
-connector chapters. Part 8 only reads it. Because it is a different
+connector chapters. Part 7 only reads it. Because it is a different
 fixture from the portfolio, entry first resets any portfolio on disk
 (see SKILL.md §Entering a part, the `cli` case).
 
 1. `<provider_dir>/agents/demo-agent.md`  <-  SKILL.md §Fixture and state templates. (The `.skillmapignore` is universal, already on disk from pre-flight; the snapshot does not lay it.)
-2. `<provider_dir>/skills/demo-skill/SKILL.md`, `<provider_dir>/commands/demo-command.md`, `notes/todo.md`, `notes/demo-guideline.md`  <-  part-fundamentals.md, chapter `kinds`.
-3. EDIT `notes/todo.md`: wire the hub bullets pointing at the four other nodes  <-  part-fundamentals.md, chapter `connectors`.
+2. `<provider_dir>/skills/demo-skill/SKILL.md`, `<provider_dir>/commands/demo-command.md`, `notes/todo.md`, `notes/demo-guideline.md`, `notes/demo-guideline2.md`  <-  part-fundamentals.md, chapter `kinds`.
+3. EDIT `notes/todo.md`: wire the hub bullets pointing at the five other nodes  <-  part-fundamentals.md, chapter `connectors`.
 

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

@@ -1,6 +1,6 @@
-# Part 7 (c): Extend skill-map - build plugins (step library, `authoring-*` ids)
+# Part 6 (c): Extend skill-map - build plugins (step library, `authoring-*` ids)
 
-Step bodies for the plugin-authoring chapters of Part 7.
+Step bodies for the plugin-authoring chapters of Part 6.
 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 8: The CLI in depth - step library
+# Part 7: 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 `preflight: seed` with the `prologue-built` snapshot: it self-seeds its own copy of the Part 0 demo fixture, so it works even if the campaign already replaced that fixture with the portfolio (see SKILL.md §Entering a part, the `cli` case). Shared conventions (tone, provider detection / substitution, the `> ` rendering rule, the per-step cycle) live in `_core.md`; do not restate them here.
 
@@ -13,7 +13,7 @@ sm show .claude/skills/demo-skill/SKILL.md
 sm check
 ```
 
-Expected: you see the 5 fixture nodes listed with their kind: `demo-skill` (skill), `demo-agent` (agent), `demo-command` (command), `notes/todo` (`markdown`, the catch-all per the `kinds` chapter), and `notes/demo-guideline` (`markdown` as well, the target of the hub's `references` link). `check` reads the persisted `scan_issues` table, it does NOT re-walk the filesystem. The fixture is clean (the connector / inspector chapters captured the latest state before Ctrl+C), so the verb prints `✓ No issues`. We will plant one in the `issues` chapter and watch the rule catch it after a fresh `sm scan`.
+Expected: you see the 6 fixture nodes listed with their kind: `demo-skill` (skill), `demo-agent` (agent), `demo-command` (command), `notes/todo` (`markdown`, the catch-all per the `kinds` chapter), and the two guideline notes `notes/demo-guideline` and `notes/demo-guideline2` (both `markdown`, the hub's confidence pair: a faint `mentions` at 0.50 and a resolved `references` at 1.00). `check` reads the persisted `scan_issues` table, it does NOT re-walk the filesystem. The fixture is clean (the connector / inspector chapters captured the latest state before Ctrl+C), so the verb prints `✓ No issues`. We will plant one in the `issues` chapter and watch the rule catch it after a fresh `sm scan`.
 
 Mark `browse`: done.
 

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

@@ -55,9 +55,9 @@ Wait for confirmation. Mark `check-links`: done.
 
 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:
+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. The frontmatter fence (`---`) MUST sit on column 0 with no leading spaces: present the block below exactly as written, and if the tester pastes it indented, have them strip the leading whitespace. An indented `---` does not parse as YAML, so the `publish` node would land without its `name`, `description`, or `shortcut`.
 
-> Create `.claude/commands/publish.md` with exactly this content:
+> Create `.claude/commands/publish.md` with exactly this content (the first line is `---`, nothing before it):
 
 ```markdown
 ---
@@ -99,6 +99,12 @@ Continue the tester message:
 > 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 (tooltip
+> "Re-arrange the visible nodes"). Handy whenever the graph starts to
+> look crowded. If you've dragged nodes by hand it asks for
+> confirmation first, otherwise it just re-arranges.
+>
 > Did the three arrows appear?
 
 Wait for confirmation. You MAY use `Read` on the file afterwards to verify it landed. Mark `publish`: done.
@@ -150,34 +156,43 @@ Wait for confirmation. You MAY use `Read` on the two files afterwards to verify
 
 ## Chapter `confidence` - How sure is each link (~3 min)
 
-**Context**: the connectors do not all look equally solid, and that is on purpose. Skill-map estimates how sure it is of every connection and shows that as opacity. Here we open the Inspector on a real harness node and read the per-link confidence numbers, mirroring the prologue's connectors beat but on the portfolio.
+**Context**: skill-map estimates how sure it is of every connection and shows that as opacity. In this harness every link resolves to a real node, so they all read solid (1.00); the faint, low-confidence case is the one the tester met in the prologue (the bare `@demo-guideline` mention that had nothing to resolve to). Here we open the Inspector on a real harness node, read the all-solid numbers, and point back to that prologue contrast. Mirrors the prologue's connectors beat on the portfolio.
 
 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?
-> Look closely at the **Map** and you'll notice the arrows are not all
-> equally solid. The more confident skill-map is that a link is real,
-> the more solid the arrow; the less sure, the more translucent.
+> It estimates a **confidence** for every link and draws it as opacity:
+> the surer a connection is real, 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 **Connections** panel and read the **Outgoing**
-> rows. Each row shows the link kind and a confidence badge:
+> 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.
 >
-> - `publish -> docs/DEPLOY.md` (`references`) reads **1.00** and looks
->   solid: it is a markdown link to a file that really exists on disk,
->   so skill-map is certain.
-> - `publish -> content-editor` (`mentions`) and `publish ->
->   check-links` (`invokes`) read high too, because each `@handle` and
->   `/slash` token resolves cleanly to a node that exists in your
->   harness.
+> 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 *low*-confidence connector look like? You saw one back in the
+> prologue: `@demo-guideline` was a bare `@`-mention pointing at a
+> note, and a bare `@handle` only firmly resolves to an agent, so it
+> had nothing to land on and stayed a soft guess at **0.50**, drawn
+> translucent. The fix there was one character: `@demo-guideline2.md`,
+> the same handle plus a `.md`, resolved to the real file and jumped to
+> **1.00**.
 >
 > The number is the certainty, and the opacity on the canvas is just
 > that number drawn as transparency: a glance at the **Map** tells you
 > which connections are rock solid and which are skill-map's best
 > guess.
 >
-> Do you see the confidence badges in the Inspector?
+> 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/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
@@ -102,16 +102,16 @@ Create these four files (with `Write`), exactly in this order. Per §Provider de
    # 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.
+     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.
    tags: [notes, demo]
    ---
 
@@ -124,27 +124,49 @@ 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).
+   tags: [notes, demo]
+   ---
+
+   # 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 +190,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 +215,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 +228,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 +269,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 +313,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 +322,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 +337,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 +346,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 +376,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 +399,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 +420,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
@@ -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.
 >