@skill-map/cli 0.59.0 → 0.60.0

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

@@ -394,11 +394,18 @@ When a part begins, honour its `preflight` from the manifest:
     (`node_modules/`, `public/`) are appended to the universal
     `.skillmapignore` pre-flight already wrote, so the tutorial's own
     `.claude/skills/sm-tutorial/` files stay out of the scan even on a
-    direct jump here. Then run `sm init` if `.skill-map/` is missing
-    (it will not overwrite that `.skillmapignore`), then `sm scan` so
-    the map reflects the seeded harness. Mark the skipped
-    predecessor campaign parts `skipped` in the state (they stay in the
-    menu for later). Then emit exactly ONE tester-facing line:
+    direct jump here. Then provision the DB if `.skill-map/` is missing,
+    with the **non-interactive lens recipe**: the seeded portfolio has
+    BOTH a root `AGENTS.md` (an `openai` marker) and `.claude/` (a
+    `claude` marker), so a plain `sm init` would stop on the
+    `⚠ Multiple provider markers detected` prompt with no tester to
+    answer it. Instead run `sm init --no-scan` (skips first-scan
+    detection, never prompts; it will not overwrite that
+    `.skillmapignore`), then `sm config set activeProvider claude`, then
+    `sm scan` so the map reflects the seeded harness under the claude
+    lens. (If `.skill-map/` already exists, just `sm scan`.) Mark the
+    skipped predecessor campaign parts `skipped` in the state (they stay
+    in the menu for later). Then emit exactly ONE tester-facing line:
 
     > I set the project up to where this part begins, so you can start
     > here. The earlier parts that build up to this are still in the

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

@@ -163,13 +163,22 @@ No frontmatter: a real handbook is plain prose (this repo's own
 `name:` that differs from the filename only confuses the tester. The
 node displays by its path, `AGENTS.md`.
 
+**No backtick-wrapped relative `.md` paths in the body either.**
+`core/backtick-path` (Decision #127) turns a `` `docs/STYLE.md` `` written
+inside a code span into a `points` link, and at kickoff (before the
+`docs/` files exist) that link lands as a broken reference, which would
+break the "one lonely node" beat the `kickoff` chapter promises. Name the
+docs in prose (the style guide, the deploy runbook), never as backticked
+paths. They become real nodes in the `real-kinds` chapter and are wired
+in explicitly in Part 2.
+
 ```markdown
 # Portfolio handbook
 
 A small static portfolio site, served by Express (`server.js`). The
 `.claude/` harness maintains it: an agent writes the pages, a skill
-checks the links, a command publishes. The conventions live in
-`docs/STYLE.md`; the deploy steps in `docs/DEPLOY.md`.
+checks the links, a command publishes. The conventions live in the
+style guide; the deploy steps in the deploy runbook.
 ```
 
 ### File: `server.js` (not scanned; runnable scaffolding)
@@ -255,8 +264,10 @@ have at the END of the part just before the one being entered.
 
 NOT cumulative and NOT the portfolio: this is the **Part 0 demo
 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 5 only reads it. Because it is a different
+hub, the state at the end of the prologue's connector chapters: five hub
+links, one of them (`@demo-guideline`, a bare mention that resolves to no
+agent) a deliberate broken reference that `sm check` reports as a single
+`reference-broken` error. Part 5 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).
 

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

@@ -13,7 +13,7 @@ sm show .claude/skills/demo-skill/SKILL.md
 sm check
 ```
 
-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`.
+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 resolution pair: a broken `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 prologue fixture carries one deliberate broken reference (the bare `@demo-guideline` mention from the `connectors` chapter resolves to no agent), so `sm check` reports `1 error` (`reference-broken` on `notes/todo.md`), NOT `✓ No issues`. The `issues` chapter plants a SECOND broken ref and watches the rule catch it after a fresh `sm scan`.
 
 Mark `browse`: done.
 
@@ -33,7 +33,7 @@ Mark `graph-export`: done.
 
 ## Chapter `issues` - Issues and broken refs (--analyzers, --json) (~3 min)
 
-`reference-broken` is one of the deterministic rules `sm check` runs. We'll plant one and watch it surface, that's the easiest way to internalise that it is an **issue** on a node, NOT a connector and NOT the same thing as an "orphan".
+`reference-broken` is one of the deterministic rules `sm check` runs. The hub already carries one broken reference from the prologue (the bare `@demo-guideline` mention that resolves to no agent); we'll plant a second, an explicit markdown link to a missing file, and watch the rule catch it too, that's the easiest way to internalise that it is an **issue** on a node, NOT a connector and NOT the same thing as an "orphan".
 
 > ℹ️ `reference-broken` is one of ~16 built-in rules. Others surface
 > different families: `core/name-reserved` (a file shadows a vendor
@@ -61,7 +61,7 @@ sm check --analyzers reference-broken
 sm check --json
 ```
 
-Expected: the error surfaces the dangling link from `notes/todo.md` to the non-existent `missing-page.md`. The `--analyzers` filter lets you focus on a single issue type; `--json` emits the structured payload (useful for CI / scripting). When done, the tester can leave the bullet in place or delete it, the rest of the deep-dive doesn't depend on it.
+Expected: `sm check` now reports **2 errors**, both `reference-broken` on `notes/todo.md`, the pre-existing `@demo-guideline` mention from the prologue plus the freshly planted `[flow diagram](./missing-page.md)` you just added (the dangling markdown link to the non-existent `missing-page.md`). The `--analyzers reference-broken` filter narrows `sm check` to a single rule (still both rows here, since both are that rule); `--json` emits the structured payload (useful for CI / scripting). When done, the tester can leave the bullet in place or delete it, the rest of the deep-dive doesn't depend on it.
 
 Mark `issues`: done.
 

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

@@ -140,16 +140,17 @@ Wait for confirmation. You MAY use `Read` on the two files afterwards to verify
 
 ## Chapter `confidence` - How sure is each link (~3 min)
 
-**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.
+**Context**: skill-map records 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 broken-reference case is the one the tester met in the prologue (the bare `@demo-guideline` mention that resolved to no agent, drawn as no arrow and flagged `reference-broken` at 0.50). 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?
-> 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.
+> 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**
@@ -164,18 +165,21 @@ Tell the tester:
 >
 > 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**.
+> does a link that does NOT resolve look like? You saw one back in the
+> prologue: `@demo-guideline` was a bare `@`-mention, and a bare
+> `@handle` only resolves to an agent. `demo-guideline` is a note, so
+> it had nothing to land on: 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 there was one character:
+> `@demo-guideline2.md`, the same handle plus a `.md`, resolved to the
+> real file and drew a solid arrow at **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.
+> So confidence here is really about resolution: **1.00** for a link
+> that lands on a real node, **0.50** for one flagged broken. There is
+> a third rung, **0.10**, for a link that resolves to a real file the
+> runtime would ignore (a reserved name); you meet that one in the
+> daily-loop part. The opacity on the canvas is just that number drawn
+> as transparency.
 >
 > Do you see every badge reading 1.00 in the Inspector?
 

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

@@ -330,8 +330,10 @@ sm check
 > ```
 >
 > That is the `reference-broken` analyzer: a link whose target no longer exists.
-> On the Map the `publish → docs/DEPLOY.md` arrow has gone faint. `sm check` runs
-> the full analyzer catalogue (around a dozen rules); to narrow it to one rule:
+> On the Map the `publish → docs/DEPLOY.md` arrow has disappeared: a broken link
+> resolves to no node, so skill-map stops drawing it and flags the `publish` card
+> with a red error instead. `sm check` runs the full analyzer catalogue (around a
+> dozen rules); to narrow it to one rule:
 
 ```bash
 sm check --analyzers reference-broken

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

@@ -32,7 +32,7 @@ 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 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.
+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 bare mention that resolves to nothing (which lands as a broken reference, no arrow drawn) and the same handle plus `.md` that resolves to a real file (a solid arrow).
 
 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:
 
@@ -87,15 +87,17 @@ Create these five files (with `Write`), exactly in this order. Per §Provider de
    ```
 
 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:
+   in the `connectors` chapter by a bare `@`-mention that resolves to
+   no agent, so it surfaces as a broken reference instead of a drawn
+   connector:
    ```markdown
    ---
    name: demo-guideline
    description: |
      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.
+     reaches it with a bare `@`-mention, which resolves to no agent,
+     so skill-map flags it as a broken reference (0.50) instead of
+     drawing an arrow.
    ---
 
    # Demo Guideline
@@ -187,9 +189,9 @@ You edit `notes/todo.md` so it becomes the **hub** that points to each of the ot
 - an `@handle.md` token (a `@` handle that ends in a file extension) → kind `references`
 - a `/slash` token → kind `invokes`
 
-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.
+Five bullets, three kinds: `invokes` and `mentions` each appear twice, `references` once. The last two bullets are the resolution lesson: a bare `@demo-guideline` mention (which resolves to no agent, so it lands as a broken reference and draws no arrow) next to `@demo-guideline2.md`, the same handle shape plus a `.md` extension that points at a real sibling file (so it resolves and draws a solid arrow). Two separate nodes, one broken and one resolved. Five bullets but only four arrows on the canvas.
 
-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).
+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 resolution contrast, broken mention 0.50 (no arrow drawn) vs resolved reference 1.00 (solid arrow), is intact on those providers too).
 
 **Edit `notes/todo.md`**: append these bullets after the `# Pending` heading:
 
@@ -203,59 +205,70 @@ Apply with `Edit` on `notes/todo.md` (do not rewrite the file). Per §Provider d
 
 Tell the tester:
 
-> Look at the magic again. **Demo TODO list** is now the hub: five
-> arrows light up between it and the other nodes, and the UI palette
-> colours each arrow by the link kind it carries:
+> Look at the magic again. **Demo TODO list** is now the hub. You
+> wrote five linking bullets, and **four arrows** light up between it
+> and the other nodes, each coloured by the link kind it carries:
 >
-> - `Demo TODO list → demo-agent` (kind: `mentions`)
+> - `Demo TODO list → demo-agent` (kind: `mentions`, the bare `@` handle resolves to a real agent)
 > - `Demo TODO list → demo-command` (kind: `invokes`)
 > - `Demo TODO list → demo-skill` (kind: `invokes`)
-> - `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.
+> extension turns the name drop into a file pointer.
 >
-> 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:
+> So why four arrows for five bullets? The fifth bullet,
+> `@demo-guideline`, is a bare `@`-mention, and a bare mention only
+> resolves to an *agent*. `demo-guideline` is a note, not an agent, so
+> the mention resolves to nothing: skill-map draws no arrow (there is
+> no node for it to land on) and instead flags the hub with a
+> **broken reference**, a red error marker on the **Demo TODO list**
+> card. Compare it with the bullet right after: `@demo-guideline2.md`
+> adds the `.md`, so skill-map reads a file pointer, finds the real
+> `demo-guideline2.md` node, and draws a solid arrow to it. Same
+> handle, one `.md` apart, and one resolves while the other breaks.
+> (That is also why `@demo-agent` drew fine: a bare mention DOES
+> resolve when the target is a real agent.)
 >
-> - `@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.
+> 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 (a link to a real file the runtime would ignore) 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.
 >
-> 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.
+> Confirm when you see the four arrows plus the broken-reference
+> marker on the hub. If an arrow is missing, refresh the browser and
+> let me know.
 
-If a connector is missing, do not advance, the next chapter inspects the same hub edit. Mark `connectors`: done.
+Expected: four drawn arrows plus one `core/reference-broken` error on `notes/todo.md` for the unresolved `@demo-guideline` mention (the prologue carries this single deliberate error from here on; it is the broken-reference preview the campaign and CLI parts build on). If an arrow is missing, do not advance, the next chapter inspects the same hub edit. Mark `connectors`: done.
 
 ## Chapter `inspector` - The inspector and connections (~1 min)
 
-The connector opacity tells the confidence story at a glance; the exact per-link breakdown lives in the Inspector. Open it on the hub so the tester registers the surface before the `edit-link` chapter changes topology.
+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.
 
 > 🆕 Open the Inspector for **Demo TODO list** (click the node on
 > the map). **Expand** the **Connections** section (it's collapsed
 > 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 (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`.
+> Demo TODO list lists **5 links** under Outgoing (the canvas drew
+> four arrows, but the data keeps the broken `@demo-guideline` mention
+> as a fifth row) and 0 under Incoming. Each row shows the link kind
+> (`mentions`, `invokes`, `references`) and a badge with its
+> 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".
+>
+> Now open the Inspector for a couple of the targets to read their
+> Incoming count. The four resolved targets (`demo-agent`,
+> `demo-command`, `demo-skill`, `demo-guideline2`) each show **1**
+> incoming. Open `demo-guideline` and it shows **0**: the broken
+> mention never landed on it, so nothing points in. Five outgoing
+> links on the hub, but only four of them reach a node.
 >
 > 💡 Tip: if all these changes left the nodes crowded together, the
 > map toolbar has a **Re-arrange layout** button (tooltip "Re-arrange
@@ -319,10 +332,12 @@ 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`,
+> draws an arrow to (`demo-command`, `demo-skill`,
 > `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**.
+> Two nodes drop out of view: `demo-agent`, which lost its only
+> connector back in the last step, and `demo-guideline`, whose bare
+> mention never resolved so it has no drawn connector either. The
+> Inspector opens on **Demo TODO list**.
 > That's how you
 > focus on one node's neighborhood when a map gets busy.
 >

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

@@ -28,6 +28,17 @@ disk. The orchestrator's `portfolio-init` already cleared it during
 pre-flight, so the tester sees only the portfolio. If anything demo
 lingers, mention it once and move on.
 
+**Context (agent, do not narrate the plumbing): the lens prompt.**
+Unlike the prologue (a pure `.claude/` project that auto-detected
+`claude` silently), this project has a root `AGENTS.md` (a filesystem
+marker for the `openai` lens) sitting next to the `.claude/` folder
+(the `claude` marker, where the tutorial skill itself lives). With two
+markers present, `sm init`'s first scan can NOT auto-pick a lens and
+asks the tester to choose (`⚠ Multiple provider markers detected`).
+The portfolio is a Claude project, so the answer is `claude`. The
+prompt is expected, blessed behaviour; the tester just needs to know
+which option to pick, so the message below previews it.
+
 ```bash
 sm init
 sm
@@ -40,6 +51,13 @@ Tell the tester:
 > `.claude/` folder is the **harness** (the helpers that maintain the
 > site). skill-map maps that harness.
 >
+> Run `sm init`. This folder has both a root `AGENTS.md` and a
+> `.claude/` folder, so skill-map can't tell on its own which runtime
+> you're authoring for and asks:
+> `⚠ Multiple provider markers detected. Pick the active lens: 1) claude 2) openai`.
+> Type `1` (or `claude`) and press Enter, this is a Claude project.
+> Then run `sm` to boot the live UI.
+>
 > Open the URL `sm` printed. You'll see **one node**: `AGENTS.md`,
 > the project's handbook (the operating manual for the site).
 > `server.js`, `package.json` and the HTML under `public/` are not