@skill-map/cli 0.60.4 → 0.61.1

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

@@ -1,277 +1,99 @@
-# Fixture templates
+# Fixtures and state: the data + script model
 
-Fixtures the orchestrator lays for the auto-fixtured parts. Two full
-templates live here: the **master fixture** (Part 4, "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:
-its content lives in `SKILL.md` (§Fixture and state templates) and
-`part-fundamentals.md`, and the `prologue-built` seed snapshot below
-just points at those. Read the set for the part being entered.
+The tutorial no longer embeds fixture content in prose or hand-edits
+the state file. **Content lives in `fixtures-data/` and is laid by
+`scripts/fixtures.js`; progress lives in `tutorial-state.json` and is
+owned by `scripts/state.js`.** This file is the reference for that
+model; the per-chapter invocations live in each `part-*.md`.
 
-**Authoring note (command fixtures).** A `command` node's H1 is a plain
-title (`# publish`), never the slash form (`# /publish`). The `slash`
-extractor reads a `/name` token anywhere in the body, the H1 included,
-as an `invoke`, so `# /publish` makes the command invoke itself and
-`sm check` emits a spurious `core/link-self-loop` the tester has no
-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 4): layout (per provider)
-
-Per §Provider detection in `SKILL.md`, the `<provider_dir>`
-placeholder resolves to `.claude/` or `.agents/skills/` depending
-on the detected runtime (Google's Antigravity CLI, which replaced
-Gemini CLI on 2026-05-19, adopted the same open standard as
-`agent-skills`, so both share the `.agents/skills/` layout). Drop
-any file whose kind is not in the provider's supported set: on
-`agent-skills` / Antigravity only the skill + note are valid;
-on `claude` (default) all three apply.
-
-Canonical layout (substitute `<provider_dir>` per detection):
-
-```
-<cwd>/
-├── <provider_dir>/
-│   ├── agents/                    (claude only)
-│   │   └── master-agent.md
-│   └── skills/                    (both providers)
-│       └── master-skill/
-│           └── SKILL.md
-├── notes/
-│   └── ideas.md
-└── findings.md
-```
-
-On `agent-skills` the `agents/` subtree is omitted (the provider
-does not claim that kind); the skill lives at
-`.agents/skills/master-skill/SKILL.md`.
-
-Translate the natural-language prose (descriptions, body text,
-list items) to the tester's language. Keep paths, frontmatter
-keys, identifiers, and link targets in English.
-
-## File: `.claude/agents/master-agent.md` (kind: agent)
-
-```markdown
----
-name: master-agent
-description: |
-  Example agent used by the advanced tutorial. Has a couple of
-  tools so the `core/tools-counter` extractor emits a count.
-tools: [Read, Bash, Edit]
-model: sonnet
----
-
-# master-agent
-
-Walks the master-skill outputs and reports findings. Used as the
-target node when we exercise extractors, analyzers, and the
-plugin-authoring flow.
-```
-
-## File: `.claude/skills/master-skill/SKILL.md` (kind: skill)
-
-```markdown
----
-name: master-skill
-description: |
-  Example skill paired with the master-agent for the advanced
-  tutorial. Links to the agent so extractors and analyzers have
-  something to chew on.
----
-
-# master-skill
-
-Hands heavy work over to the
-[master-agent](../../agents/master-agent.md) and emits a Markdown
-report.
-
-## Steps
-1. Read the `target`.
-2. Validate the frontmatter.
-3. Delegate to the agent.
-```
-
-## File: `notes/ideas.md` (kind: markdown)
-
-```markdown
----
-name: Ideas backlog
-description: |
-  Free-form notes for the advanced tutorial. Demonstrates the
-  catch-all markdown kind alongside the agent and skill.
----
-
-# Ideas
-
-- [ ] Compare extractor outputs side by side.
-- [ ] Sketch a tiny plugin that surfaces a counter on the agent.
-```
-
-## File: `findings.md`
-
-```markdown
-# Findings
-
-If you spot anything weird during the tutorial, log it here.
-
-Per finding:
-- **Chapter**: <id>
-- **Command**: `sm ...`
-- **Expected**: ...
-- **Got**: ...
-- **Notes**: ...
-```
-
-## Portfolio fixture (Part 1, `portfolio-init`)
-
-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 (the daily loop, Part 3, runs and 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.
-
-Layout:
+## Data layout (`fixtures-data/`)
 
 ```
-<cwd>/
-├── <provider_dir>/            (harness, grown by the chapters)
-├── docs/                      (created in the real-kinds chapter)
-├── public/
-│   └── index.html
-├── AGENTS.md                  (the boot node)
-├── server.js
-└── package.json
+fixtures-data/
+  manifest.json                 sets, footprints, edits, seeds, providerToken, langs
+  sets/<set>/
+    shared/                     lang-invariant files (code: server.js, package.json, CLAUDE.md)
+    en/  es/                    one tree per language (files with translatable prose)
+  edits/<edit-id>/
+    en/  es/                    append fragments (one file per fragment)
 ```
 
-The daily loop (Part 3) grows this further as taught steps, all Layer 2
-or loose notes (not part of the harness graph): `public/style.css` plus
-the generated pages (`index.html` rewritten, `about.html`,
-`projects.html`, `posts.html`), `docs/draft.md`, the renamed `new-page`
-command, `AGENTS.sm`, and `.skill-map/settings.local.json`. The
-start-over wipe and the `extend` / `cli` clears account for them via
-this section.
-
-### File: `AGENTS.md` (kind: markdown, the boot node)
-
-No frontmatter: a real handbook is plain prose (this repo's own
-`AGENTS.md` and the tutorial's `CLAUDE.md` carry none either), and a
-`name:` that differs from the filename only confuses the tester. The
-node displays by its path, `AGENTS.md`.
-
-**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 the
-style guide; the deploy steps in the deploy runbook.
-```
-
-### File: `server.js` (not scanned; runnable scaffolding)
-
-```js
-// Minimal static server for the portfolio. No framework, one dep.
-const express = require('express');
-const path = require('node:path');
-
-const app = express();
-app.use(express.static(path.join(__dirname, 'public')));
-
-const port = process.env.PORT || 3000;
-app.listen(port, () => console.log(`Portfolio live at http://localhost:${port}`));
-```
-
-### File: `package.json` (not scanned)
-
-```json
-{
-  "name": "my-portfolio",
-  "private": true,
-  "scripts": { "start": "node server.js" },
-  "dependencies": { "express": "4.21.2" }
-}
-```
-
-### File: `public/index.html` (not scanned; placeholder until Part 3)
-
-```html
-<!doctype html>
-<meta charset="utf-8">
-<title>My portfolio</title>
-<h1>My portfolio</h1>
-<p>Pages land here once the content-editor generates them.</p>
-```
-
-### `.skillmapignore` additions
-
-Append to the universal `.skillmapignore` (written in pre-flight, see
-`SKILL.md`): `node_modules/` (the Express install) and `public/`
-(generated HTML, not part of the harness graph).
-
-## 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 5 `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
-and the chapter that holds its canonical content. Lay each file by
-copying the content from the named chapter (substitute `<provider_dir>`
-and skip provider-unsupported kinds per `_core.md`); an `EDIT` row is
-applied on top of the file an earlier row laid. Keep these lists in
-sync only when a harness FILE is added or removed, the file CONTENT
-lives in the chapters, so editing a chapter needs no change here.
-
-### Seed snapshot: `harness-built` (start of Part 2)
-
-The portfolio skeleton plus the harness members Part 1 created, before
-any cross-links:
-
-1. `AGENTS.md`, `server.js`, `package.json`, `public/index.html`, and
-   the portfolio `.skillmapignore` additions  <-  the `## Portfolio
-   fixture` section above.
-2. `CLAUDE.md` (`@AGENTS.md`)  <-  part-project-kickoff.md, chapter `manual`.
-3. `<provider_dir>/agents/content-editor.md`  <-  part-project-kickoff.md, chapter `first-agent`.
-4. `docs/STYLE.md` and `docs/DEPLOY.md`  <-  part-project-kickoff.md, chapter `real-kinds`.
-
-### Seed snapshot: `harness-connected` (start of the daily-loop part)
-
-Everything in `harness-built`, PLUS the Part 2 wiring:
-
-5. `<provider_dir>/skills/check-links/SKILL.md`  <-  part-connect-harness.md, chapter `check-links`.
-6. `<provider_dir>/commands/publish.md`  <-  part-connect-harness.md, chapter `publish`.
-7. EDIT `AGENTS.md`: append the two hub bullets (mention `@content-editor`, invoke `/publish`)  <-  part-connect-harness.md, chapter `links`.
-8. EDIT `<provider_dir>/agents/content-editor.md`: add the `[style guide](../../docs/STYLE.md)` line  <-  part-connect-harness.md, chapter `links`.
-
-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 5 `cli`)
-
-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 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).
-
-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`, `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`.
-
+- **`__PROVIDER__`** is a literal path segment in the data tree (e.g.
+  `sets/prologue/en/__PROVIDER__/agents/demo-agent.md`). The script
+  resolves it per provider: `.claude/agents/…` on claude,
+  `.agents/skills/…` on agent-skills (where the `skills/` segment
+  collapses, since that layout has no `agents`/`commands` dirs). Only
+  the PATH is resolved; file CONTENT is laid verbatim.
+- **Kind** is derived from the path (`__PROVIDER__/agents|commands|skills`
+  → agent/command/skill, else markdown); files whose kind the provider
+  does not claim are skipped automatically.
+- **Language**: pass `--lang en|es`. A missing language tier for a set
+  falls back to the default (`en`). Translate prose (descriptions,
+  body, list items, anchor text); keep paths, frontmatter keys, node
+  identifiers, link targets, and code in English.
+
+## Sets
+
+| Set | What it lays | Used by |
+|---|---|---|
+| `universal` | `.skillmapignore`, `findings.md` | pre-flight |
+| `prologue` | the seven Part 0 demo nodes | Part 0 (progressive, `--only`), `prologue-built` seed |
+| `portfolio` | Express skeleton, handbook, `content-editor`, `docs/STYLE` + `DEPLOY` | Part 1 (`--only` boot, chapters lay the rest), `harness-*` seeds |
+| `harness` | `check-links` skill, `publish` command | Part 2 chapters, `harness-connected` seed |
+| `master` | `master-agent`, `master-skill`, `notes/ideas` | Part 4 `backstage-init` |
+| `cli-external` | `link-validation/hijoA` + `hijoB` | Part 5 `reference-paths` |
+
+## Edits (append fragments)
+
+`edit <id>` appends fragment files to a target (after a one-time
+`prefix`). A `requiresKind` on a fragment (or on the edit's target
+kind) drops it on a provider that does not claim that kind.
+
+| Edit | Target | Fragments |
+|---|---|---|
+| `todo-connectors` | `notes/todo.md` | five hub bullets (agent / command / skill gated by kind) |
+| `agents-hub` | `AGENTS.md` | the two handbook hub bullets |
+| `content-editor-style` | `<provider_dir>/agents/content-editor.md` | the style-guide reference line (agent target, so skipped on agent-skills) |
+
+## Seeds (fast-forward snapshots)
+
+`seed <id>` composes sets + edits + drops to fast-forward into a part
+entered out of order.
+
+| Seed | Lays | Edits | Drops |
+|---|---|---|---|
+| `prologue-built` (Part 5) | `prologue` | `todo-connectors` | `notes/private-credentials.md` |
+| `harness-built` (Part 2) | `portfolio` | , | , |
+| `harness-connected` (Part 3) | `portfolio` + `harness` | `agents-hub`, `content-editor-style` | , |
+
+## Footprints (what `clear` and `wipe` remove)
+
+`manifest.json#footprints` lists the full on-disk reach of each
+fixture, INCLUDING files a part's later chapters add (the daily loop's
+`public/style.css` + generated pages, the renamed `new-page` command,
+`AGENTS.sm`; the portfolio's `DEPLOYMENT.md` rename). `fixtures.js clear <footprint>` (part-entry resets) and
+`state.js wipe` (start-over) both read it, so the per-fixture path list
+lives in ONE place. Add or drop a harness file there.
+
+## Changing a fixture
+
+Edit the data file under `fixtures-data/`; the chapter that teaches it
+reads the same file (the agent lays it with `fixtures.js`, or shows it
+to the tester with `fixtures.js cat <set> --file <relpath>`). There is
+no second copy to keep in sync. After any change, rebuild
+(`pnpm --filter @skill-map/cli build`) so the byte-for-byte payload
+test sees the new bytes.
+
+## Authoring notes (still apply)
+
+- **A `command` node's H1 is a plain title (`# publish`), never the
+  slash form (`# /publish`).** The `slash` extractor reads a `/name`
+  token anywhere in the body (the H1 included) as an `invoke`, so
+  `# /publish` makes the command invoke itself and `sm check` emits a
+  spurious `core/link-self-loop`. Holds for every command fixture
+  (`demo-command`, `publish`, the daily-loop `init`).
+- **No backtick-wrapped relative `.md` paths in `AGENTS.md`'s body.**
+  `core/backtick-path` turns a `` `docs/STYLE.md` `` in a code span
+  into a `points` link; at kickoff (before `docs/` exists) that lands
+  as a broken reference and breaks the "one lonely node" beat. Name
+  the docs in prose, never as backticked paths.

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

@@ -282,5 +282,4 @@ Mark `authoring-6-upgrade: done`.
 >
 > Anything weird worth logging? If not, back to the menu.
 
-Mark the authoring chapters done in `tutorial-state.yml`, update
-the matching harness task, return to the menu in `SKILL.md`.
+Mark the chapters done (rule #4) and return to the menu in `SKILL.md`.

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

@@ -92,7 +92,13 @@ Mark `annotations`: done.
 
 **Context**: until now the map saw only files inside the cwd. In real projects a repo often links to files in a sibling repo (a specs project, a sibling package in a monorepo). Skill-map only scans from its cwd downwards, so a link to `../sibling/file.md` shows up as broken. The fix is to declare the external folders in `scan.referencePaths`, which lets the `reference-broken` analyzer validate path-style links against those extra roots **without indexing their files as nodes**. The folders are checked, not walked as part of the map.
 
-**Setup (you, silent)**: write the fixture under the tutorial cwd so both sub-projects are siblings of each other but children of the tutorial root. The agent does this with `Write`, no confirmation beat needed, the tester learns about the files in the next message.
+**Setup (you, silent)**: lay the fixture under the tutorial cwd so both sub-projects are siblings of each other but children of the tutorial root (its content + translation live in `fixtures-data/`). No confirmation beat needed, the tester learns about the files in the next message. Backstage (silent):
+
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay cli-external --provider <provider> --lang <lang>
+```
+
+The fixture lays:
 
 ```
 link-validation/
@@ -102,35 +108,6 @@ link-validation/
     └── spec.md                      ← the real target file
 ```
 
-`link-validation/hijoA/note-with-external-link.md`:
-```markdown
----
-name: note-with-external-link
-description: |
-  Demo note that links out to a sibling project (hijoB) sitting
-  next to this one. Used to teach scan.referencePaths.
----
-
-# Note with external link
-
-See the [spec](../hijoB/spec.md) for the agreed format.
-```
-
-`link-validation/hijoB/spec.md`:
-```markdown
----
-name: spec
-description: |
-  Target of the cross-folder link. Lives outside hijoA's scan
-  scope on purpose: that is precisely what scan.referencePaths
-  is designed to bridge.
----
-
-# External spec
-
-Anything that hijoA points at lives here.
-```
-
 Once the files are in place, tell the tester:
 
 > I just dropped two sibling folders inside the tutorial cwd:

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

@@ -6,25 +6,12 @@ This is the wiring part. Part 1 grew a small set of standalone nodes around the
 
 **Context**: the harness needs a guard that runs before publishing: a skill that walks every page and checks the internal links resolve. We only create it here (its first standalone `skill` node); the `publish` command in the next chapter is what invokes it.
 
-`Write` `.claude/skills/check-links/SKILL.md` (substitute `<provider_dir>` per `_core.md`; this kind exists on every provider, so no skip):
+Lay the `check-links` skill (its content + translation live in
+`fixtures-data/`; this kind exists on every provider, so no skip).
+Backstage (silent):
 
-```markdown
----
-name: check-links
-description: |
-  Validates the portfolio's internal links before publishing. Walks
-  every generated page and reports any link whose target is missing.
----
-
-# check-links
-
-The last gate before the site goes out.
-
-## Steps
-1. List every HTML file under `public/`.
-2. For each page, collect its internal links (every `href` to `/` or to a `.html` file).
-3. Check the target exists under `public/` (treat `/` as `public/index.html`).
-4. Report any link whose target is missing; if none, report "0 broken links".
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay harness --only "__PROVIDER__/skills/check-links/SKILL.md" --provider <provider> --lang <lang>
 ```
 
 Tell the tester:
@@ -45,7 +32,7 @@ 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. 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` or `description`.
+Tell the tester to create the file themselves (it is their project's file, Inviolable rule #2). Substitute `<provider_dir>` per `_core.md` in the path you give them. Backstage, get the content: `node .claude/skills/sm-tutorial/scripts/fixtures.js cat harness --file "__PROVIDER__/commands/publish.md" --provider <provider> --lang <lang>`, then render it as a **top-level fenced code block**: at column 0, NOT inside the `> ` blockquote and with NO leading indentation, so the tester's copy keeps every line flush left. The frontmatter fences (`---`) MUST land on column 0. If the block is rendered (or pasted) indented, the opening and closing `---` shift off column 0, the YAML never parses, and the `publish` node loads body-only without its `name` / `description` (`sm check` then warns `frontmatter-malformed`). Present the block below exactly as written.
 
 > Create `.claude/commands/publish.md` with exactly this content (the first line is `---`, nothing before it):
 
@@ -91,25 +78,20 @@ Continue the tester message:
 >
 > Did the three arrows appear?
 
-Wait for confirmation. You MAY use `Read` on the file afterwards to verify it landed. Mark `publish`: done.
+Wait for confirmation. You MAY use `Read` on the file afterwards to verify it landed, in particular that the opening and closing `---` are flush at column 0. If a later `sm check` flags `frontmatter-malformed` on `publish.md`, the fences got indented on paste: have the tester re-align every line flush left (strip the leading spaces so `---` is at column 0), then the next scan reads it clean. Mark `publish`: done.
 
 ## Chapter `links` - The handbook becomes the hub (~4 min)
 
 **Context**: the handbook (`AGENTS.md`) has been a lonely node since Part 1. Here it becomes the hub: we add two bullets so it mentions the content editor and invokes the publish command. We also give the content editor a reference to the style guide it follows. Several connectors land, and we recap the three link kinds and which syntax produced each.
 
-Apply both edits with `Edit` (do not rewrite the files).
+Apply both edits (their content + translation live in `fixtures-data/`).
+The first appends the two hub bullets to `AGENTS.md`; the second adds
+the style-guide reference line to the content-editor (an agent target,
+so it folds away on `agent-skills`). Backstage (silent):
 
-**Edit `AGENTS.md`**: append these two bullets at the end of the body (substitute `<provider_dir>` only in prose, the link tokens below stay as written):
-
-```markdown
-- When a page needs writing or fixing, brief @content-editor.
-- When the site is ready to go out, run /publish.
 ```
-
-**Edit `.claude/agents/content-editor.md`**: add this line at the end of the body, after the `Rules:` line (substitute `<provider_dir>` per `_core.md`):
-
-```markdown
-Every page follows the [style guide](../../docs/STYLE.md).
+node .claude/skills/sm-tutorial/scripts/fixtures.js edit agents-hub --provider <provider> --lang <lang>
+node .claude/skills/sm-tutorial/scripts/fixtures.js edit content-editor-style --provider <provider> --lang <lang>
 ```
 
 Tell the tester:
@@ -140,7 +122,7 @@ 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 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.
+**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 `@demo-guideline` reference skill-map could not resolve, drawn as no arrow and flagged `reference-broken` at 0.50, then resolved by hand with `.md`). 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.
 
@@ -165,14 +147,13 @@ 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 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**.
+> does a link that does NOT resolve look like? You met one back in the
+> prologue: `@demo-guideline` was a reference skill-map could not
+> resolve, it had nothing to land on, so skill-map drew no arrow and
+> flagged it as a **broken reference**, its confidence knocked down to
+> **0.50** by the broken penalty. The fix was one character: adding
+> `.md` (`@demo-guideline.md`) turned it into a file reference to the
+> real `demo-guideline.md`, and it drew a solid arrow at **1.00**.
 >
 > 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