npm - @skill-map/cli - Versions diffs - 0.54.0 → 0.56.0 - Mend

@skill-map/cli 0.54.0 → 0.56.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/dist/cli/tutorial/sm-tutorial/SKILL.md +22 -24
package/dist/cli/tutorial/sm-tutorial/references/_core.md +8 -7
package/dist/cli/tutorial/sm-tutorial/references/_manifest.yml +21 -42
package/dist/cli/tutorial/sm-tutorial/references/fixtures.md +15 -7
package/dist/cli/tutorial/sm-tutorial/references/part-authoring.md +2 -2
package/dist/cli/tutorial/sm-tutorial/references/part-cli.md +1 -1
package/dist/cli/tutorial/sm-tutorial/references/part-connect-harness.md +9 -10
package/dist/cli/tutorial/sm-tutorial/references/part-daily-loop.md +563 -0
package/dist/cli/tutorial/sm-tutorial/references/part-mcp.md +5 -1
package/dist/cli/tutorial/sm-tutorial/references/part-plugins.md +7 -7
package/dist/cli/tutorial/sm-tutorial/references/part-project-kickoff.md +24 -12
package/dist/cli/tutorial/sm-tutorial/references/part-settings.md +2 -2
package/dist/cli.js +1785 -1102
package/dist/index.js +148 -14
package/dist/kernel/index.d.ts +229 -97
package/dist/kernel/index.js +148 -14
package/dist/migrations/001_initial.sql +5 -0
package/dist/ui/chunk-4ITL7E6U.js +1 -0
package/dist/ui/chunk-DWBJCNC7.js +2 -0
package/dist/ui/{chunk-CXTU4HQV.js → chunk-GHOVZAAV.js} +1 -1
package/dist/ui/{chunk-GBKHMJ4B.js → chunk-H6O2DYVT.js} +13 -13
package/dist/ui/chunk-HDKR6XHG.js +917 -0
package/dist/ui/{chunk-GEI6INVH.js → chunk-JA4Z74I3.js} +1 -1
package/dist/ui/chunk-RS3ANRT5.js +1 -0
package/dist/ui/chunk-VUNP5KNI.js +3 -0
package/dist/ui/chunk-W3Z3CZL4.js +1844 -0
package/dist/ui/chunk-YHJL5LP3.js +913 -0
package/dist/ui/index.html +2 -2
package/dist/ui/{main-HP3MOLI2.js → main-PL3BEVQI.js} +3 -3
package/dist/ui/{styles-4SNVM34O.css → styles-RHEEXRHQ.css} +1 -1
package/migrations/001_initial.sql +5 -0
package/package.json +2 -2
package/dist/cli/tutorial/sm-tutorial/references/part-live-site.md +0 -155
package/dist/cli/tutorial/sm-tutorial/references/part-maintain.md +0 -284
package/dist/cli/tutorial/sm-tutorial/references/part-run-harness.md +0 -181
package/dist/ui/chunk-4CXAL43H.js +0 -1
package/dist/ui/chunk-BUNPMGDX.js +0 -2205
package/dist/ui/chunk-DSNBKMYU.js +0 -2
package/dist/ui/chunk-JXRIGHET.js +0 -552
package/dist/ui/chunk-MVRQGDZJ.js +0 -123
package/dist/ui/chunk-WFLPMCK4.js +0 -392

package/migrations/001_initial.sql CHANGED Viewed

@@ -38,6 +38,11 @@ CREATE TABLE scan_nodes (
   -- inspector can list every external URL without a second round-trip.
   external_refs_json TEXT,
   scanned_at INTEGER NOT NULL,
+  -- File modification time (`mtime`) in Unix ms, captured at scan time
+  -- from the walker's `lstat`. NULL for virtual / derived nodes (no
+  -- backing file). Drives the UI "last modified" sortable column; never
+  -- participates in `body_hash` / `frontmatter_hash`.
+  modified_at_ms INTEGER,
   -- Sidecar denormalisation (Step 9.6.2 — Decision #3, option (a)):
   --   - `sidecar_present` — 1 when a co-located `.sm` file accompanies
   --     this node, 0 otherwise.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@skill-map/cli",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "description": "skill-map reference implementation — kernel + CLI + adapters.",
   "license": "MIT",
   "type": "module",
@@ -61,7 +61,7 @@
     "smol-toml": "1.6.1",
     "typanion": "3.14.0",
     "ws": "8.21.0",
-    "@skill-map/spec": "0.48.0"
+    "@skill-map/spec": "0.50.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",

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

@@ -1,155 +0,0 @@
-# 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
-operate it exactly as it was designed: you drive the `/publish` command
-end to end, the way the handbook says to ship, and put a richer
-multi-page site live next to the full graph. Pace `auto-advance`,
-preflight `seed` (`harness-connected`), so a tester can jump straight
-here. Two chapters, in order: `pipeline` (run `/publish`: check the
-links, brief the editor, follow the deploy runbook) then `golive` (run
-the server and click through the finished site). Shared conventions
-live in `_core.md`.
-## Chapter `pipeline` - Run /publish end to end (check-links, brief, deploy runbook) (~4 min)
-**Context**: the harness is not just a picture, it is a set of
-instructions, and `/publish` is the one that ties them together. Its
-body says: run `/check-links`, brief `@content-editor` on any fix, then
-follow the deploy runbook. Here the tester (playing the harness) walks
-exactly those steps on a richer site. This is still Layer 1 vs Layer 2:
-the pages are output, so the Map stays put while the files change, same
-as Part 3, no need to re-teach it, just do not call it a bug if they
-notice.
-**Preparation** (the agent does this, playing `content-editor`):
-1. Ensure the two base pages exist. If they are not already on disk
-   from Part 3 (a tester can land here via the seed), lay
-   `public/index.html` and `public/about.html` exactly as in
-   part-run-harness.md, chapter `generate`. They are the single source
-   for those two pages; do not restate their markup, copy it from
-   there.
-2. Add a **Projects** link to the home nav. `Edit` `public/index.html`,
-   turning the About line of the nav into:
-```html
-      <a href="/about.html">About</a> ·
-      <a href="/projects.html">Projects</a>
-```
-3. `Write` the new page `public/projects.html` (plain markup, links
-   back home, per the style guide):
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Projects</title>
-  </head>
-  <body>
-    <h1>Projects</h1>
-    <p>A few small things I have shipped.</p>
-    <nav>
-      <a href="/">Home</a>
-    </nav>
-  </body>
-</html>
-```
-```bash
-# Still nothing to run in the terminal. The publish steps below are
-# you walking the harness; the server comes in the next chapter.
-```
-Tell the tester:
-> Time to ship it the way your handbook says to. Open
-> `.claude/commands/publish.md` and look at its steps: that command is
-> the recipe, and you are about to run it by hand, the way the agent
-> would. Three pages now live under `public/`: home, about, and a new
-> projects page, with the home nav linking all three.
->
-> **Step 1, check the links** (`/check-links`). Walk the three pages
-> and follow every internal link: `/` resolves to the home page,
-> `/about.html` and `/projects.html` to files that exist, and each
-> page links back home. Nothing points at a missing file, so the link
-> check is clean.
->
-> **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. (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
-> server (next chapter). You have walked the whole `/publish` flow.
->
-> Glance at the Map one more time: it did not move while you added a
-> page and ran the pipeline. The pages are Layer 2 output; the harness
-> on the canvas is Layer 1, and that is what skill-map maps.
->
-> Ready to put it live?
-Wait for confirmation. You MAY `Read` the three files in `public/`
-afterwards to confirm the edit and the new page landed. Mark
-`pipeline`: done. Auto-advance to `golive`.
-## Chapter `golive` - Ship it: the richer site live next to the full graph (~3 min)
-**Context**: the climax. The tester starts the tiny Express server the
-pre-flight left in `server.js` and clicks through the three-page site,
-ending with the running portfolio on one side and the full skill-map
-graph of the harness that built it on the other. This is one of the
-few chapters where the tester runs non-`sm` commands themselves
-(`npm install`, `node server.js`); guide them, do not run it for them.
-`npm install` is idempotent, so it is safe whether or not they already
-ran it in Part 3.
-**Preparation**: none. `server.js` and `package.json` exist from the
-kickoff pre-flight; the three pages exist from the `pipeline` chapter.
-The tester runs everything here.
-```bash
-npm install
-node server.js
-```
-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 earlier it just confirms it is
-> there. Then `node server.js` starts the server; it prints a line
-> like `Listening on http://localhost:3000`.
->
-> Open `http://localhost:3000`. Click **About**, **Projects**, and
-> **Home** to move between all three pages. Those are the pages your
-> harness produced, shipped through the publish flow you just ran by
-> hand.
->
-> 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, 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.
->
-> Does the site load, and can you click between Home, About and
-> Projects?
-Wait for confirmation. The tester runs the commands; do not run them
-for them. If `npm install` fails, check they are in the project root
-and Node is on PATH (`node --version` should print 24 or higher). If
-the port is busy, stop the server with Ctrl+C and apply the ports edge
-case. Remind them the server stays running until they press Ctrl+C.
-This is the campaign finale. Congratulate them plainly: they went from
-an empty directory to a real, running portfolio plus a complete map of
-its harness. Mark `golive`: done. Last chapter of the part: apply
-§Closing a part (name the part by its title; since this closes the
-campaign spine, if every active part is now done route to the §Final
-wrap-up instead of the menu).

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

@@ -1,284 +0,0 @@
-# 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.
-## Chapter `broken-ref` - A link breaks (~3 min)
-**Context**: the most common kind of decay in a real project is a link that points at a file someone renamed or moved. Here the tester renames `docs/DEPLOY.md`, which breaks the `/publish -> docs/DEPLOY.md` reference from Part 2, and `sm check` surfaces it as `core/reference-broken`. Then they fix it by updating the link. Same watcher / live-UI loop they already know, plus the CLI verb that catalogues the issue.
-This chapter is the tester's hands the whole way (renaming and editing their own files, Inviolable rule #2). Tell the tester to start the server again first if it is not running:
-```bash
-sm
-```
-This part is the first time the live server and one-off `sm` commands run side by side, so give the tester the third-terminal heads-up below (substitute `<cwd>` with the tester's actual cwd, same substitution as every other `<cwd>` mention):
-> ⚠️ Heads up: from here you run one-off commands (`sm scan`, `sm
-> check`, the `mv` below) **while the `sm` server keeps running**. The
-> server holds its terminal until you Ctrl+C it, so open a **third
-> terminal** and anchor it to this same folder, that is where every
-> one-off command from here on goes:
-```bash
-cd <cwd>
-```
-> Three terminals now: this chat, the one running the live `sm` server
-> (leave it alone), and this new one for the one-off commands.
-> Open the URL `sm` prints, same as before. Now break something on
-> purpose. Rename your deploy runbook from `docs/DEPLOY.md` to
-> `docs/DEPLOYMENT.md` (just change the filename, leave the contents
-> alone). On most systems that is one command in the terminal:
->
-> ```bash
-> mv docs/DEPLOY.md docs/DEPLOYMENT.md
-> ```
->
-> Watch the **Map**: the `publish -> docs/DEPLOY.md` arrow can no
-> longer find its target, because nothing called `docs/DEPLOY.md`
-> exists anymore. The link is now dangling.
-After they confirm the rename, have them ask skill-map about it:
-```bash
-sm scan
-sm check
-```
-> `sm scan` refreshes what skill-map knows from disk, then `sm check`
-> reports the problem: an issue from the `core/reference-broken`
-> analyzer (a rule that flags links pointing at files that do not
-> exist), naming the link `../../docs/DEPLOY.md` inside your `/publish`
-> command. That is the broken reference you just created.
->
-> Now fix it. Open `.claude/commands/publish.md` in your editor and
-> change the deploy-runbook link so it points at the new filename:
-> `[deploy runbook](../../docs/DEPLOYMENT.md)`. Save, then re-check:
->
-> ```bash
-> sm scan
-> sm check
-> ```
->
-> `sm check` should print `✓ No issues` and the arrow comes back on
-> the **Map**. (If you would rather not keep the new name, renaming
-> the file back to `docs/DEPLOY.md` clears it just as well, but the
-> link edit is the more realistic fix.)
->
-> Did the issue surface and then clear?
-Wait for confirmation. You MAY use `Read` on `.claude/commands/publish.md` to verify the link edit landed. Leave the server running, the next chapters reuse it. Mark `broken-ref`: done.
-## Chapter `analyzers` - The analyzer catalogue (~3 min)
-**Context**: `reference-broken` was just one rule. `sm check` runs a catalogue of around 16 deterministic analyzers, each catching a different family of problem. This chapter names a few and shows how to focus on one with `--analyzers`. No fixture changes, the tester just runs the verb against the clean harness.
-No file edits in this chapter.
-Tell the tester:
-> The broken-ref you just saw is one rule out of a catalogue. `sm
-> check` runs roughly 16 deterministic analyzers (each one a small
-> rule that scans your harness for a specific kind of problem). A few
-> of the families:
->
-> - `core/reference-broken`: a link points at a file that does not
->   exist (the one you just triggered).
-> - `core/name-reserved`: a file is named after a built-in the vendor
->   runtime owns, so that runtime would ignore it (you will see this
->   one live in a couple of chapters).
-> - `core/link-self-loop`: a node links to itself.
-> - `core/reference-redundant`: the same body points at the same
->   target twice.
-> - `core/signal-collision`: two analyzers disagreed about the same
->   slice of a file, and the warning explains who won and why.
->
-> When you only care about one, focus on it:
->
-> ```bash
-> sm check
-> sm check --analyzers reference-broken
-> ```
->
-> The first runs the whole catalogue; the second narrows the report to
-> just the reference-broken rule. Your harness is clean right now, so
-> both print `✓ No issues`, but the same `--analyzers <id>` pattern
-> works for every rule in the catalogue.
->
-> Paste me the output (or just an OK).
-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; 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:
-```markdown
----
-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.
----
-# Draft page
-Notes for a page that is not ready to link from anywhere yet.
-```
-Confirm the new `docs/draft` node appears on the **Map** as a floating dot with no arrows in or out.
-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**. Click the dot, the inspector shows no
-> connections in or out.
->
-> You can confirm the same thing from the CLI:
->
-> ```bash
-> sm show docs/draft.md
-> ```
->
-> 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, 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
->   `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. 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 `docs/draft` land as a floating dot, with `sm show` confirming
-> no links in?
-Wait for confirmation. Mark `orphans`: done.
-## Chapter `reserved` - A reserved name collides (~3 min)
-**Context**: vendor runtimes own certain names (`/init`, `/help`, `/clear`, and friends). If the tester names a command after one of those, the runtime ignores their file and skill-map raises a `core/name-reserved` warning to say so. We create the collision, see the warning, then rename to clear it.
-`Write` `.claude/commands/init.md` (substitute `<provider_dir>` per `_core.md`; on `agent-skills` / Antigravity there is no `command` kind, so skip this whole chapter), deliberately named after the built-in `/init`:
-```markdown
----
-name: init
-description: |
-  Bootstraps a fresh portfolio scaffold. Named init on purpose, to
-  collide with the runtime built-in and trigger name-reserved.
----
-# init
-Sets up the empty folders a new portfolio needs.
-```
-Confirm the new `init` command node appears on the **Map**.
-Tell the tester:
-> I added a command called `/init` to your harness. There is a catch:
-> `/init` is a name the vendor runtime already owns for its own
-> built-in, so the runtime would quietly ignore your file and never
-> run it. Skill-map flags exactly that:
->
-> ```bash
-> sm scan
-> sm check
-> ```
->
-> You will see a `core/name-reserved` warning naming the `init`
-> command. It is not skill-map being fussy, it is telling you "the
-> runtime will never invoke this file, pick another name". On the
-> **Map**, any link into a shadowed node is drawn faint for the same
-> reason.
->
-> The fix is just to rename it. Rename `.claude/commands/init.md` to
-> something that is not reserved, for example
-> `.claude/commands/scaffold.md` (and update the `name:` in its
-> frontmatter to `scaffold`). On most systems:
->
-> ```bash
-> mv .claude/commands/init.md .claude/commands/scaffold.md
-> ```
->
-> Then re-check:
->
-> ```bash
-> sm scan
-> sm check
-> ```
->
-> The warning should be gone. A reserved name is one of the rare
-> mistakes skill-map can catch before the runtime ever bites you.
->
-> Did the warning appear and then clear after the rename?
-Wait for confirmation. You MAY use `Read` to verify the rename landed. Mark `reserved`: done.
-## Chapter `sidecar` - The .sm companion file and its consent prompt (~3 min)
-**Context**: every `.md` skill-map tracks can get a sibling **companion file** with extension `.sm` that carries all of the tool's metadata about that markdown (version, history, tags, annotations), so the `.md` stays clean and only holds the content you write. The `.md` is yours; the `.sm` is bookkeeping the tool writes. The first time skill-map wants to create one in a project it asks for consent, and the choice is remembered in `settings.local.json`. We demonstrate on the handbook.
-This is a CLI beat, the tester runs everything. **Reset any prior consent first** so the `[Y/n]` prompt actually appears (an earlier session may have flipped the flag, in which case the verb would skip straight past it and the lesson would not land):
-```bash
-rm -f AGENTS.sm .skill-map/settings.local.json
-sm sidecar annotate AGENTS.md
-```
-> `sm sidecar annotate` creates a fresh `.sm` companion file next to a
-> markdown file. Because this is the first time skill-map wants to
-> write one here, it shows a short explanation and then a `[Y/n]`
-> prompt (capital Y is the default, so you can just press Enter to
-> accept). skill-map never writes a `.sm` to your project without your
-> OK.
->
-> After you accept, two things happen: a new `AGENTS.sm` file appears
-> next to `AGENTS.md` (carrying an `identity:` block and an empty
-> `annotations: {}` block), and your project remembers the choice in
-> `.skill-map/settings.local.json` so it never asks again. Take a look:
->
-> ```bash
-> cat AGENTS.sm
-> cat .skill-map/settings.local.json
-> ```
->
-> You will see `AGENTS.sm` holds the tool's bookkeeping for the
-> handbook, and `settings.local.json` now contains
-> `{ "allowEditSmFiles": true }`. That flag lives in the local config
-> layer (gitignored), so each contributor consents on their own
-> checkout and the choice never travels through git.
->
-> **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**.
->
-> 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. 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-run-harness.md DELETED Viewed

@@ -1,181 +0,0 @@
-# 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). 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`.
-These two HTML pages are the canonical site fixture: the full
-publish finale (`live-site`) lays the same `public/index.html` and
-`public/about.html` from here before adding its own extra page, so keep
-them in sync here only.
-## Chapter `generate` - The agent generates the HTML in public/ (~3 min)
-**Context**: the `content-editor` agent exists to write the site's
-pages, so now you (playing that agent) generate the actual HTML into
-`public/`. The honest beat the tester must hear: writing HTML does NOT
-move the skill-map graph. The graph is Layer 1, the `.md` harness that
-builds the site; the HTML is Layer 2, the harness's OUTPUT, and
-skill-map does not map it (HTML is not `.md`). So the Map will sit
-still while real files land on disk, and that is correct, not a bug.
-Keep the markup plain per the style guide: no framework, no client JS,
-one H1 per page, every page links back home.
-**Preparation**: `Write` two static pages into `public/`. The
-pre-flight already left a placeholder `public/index.html`; this
-overwrites it with the real home page and adds an about page. Keep the
-markup plain.
-`public/index.html`:
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>My Portfolio</title>
-  </head>
-  <body>
-    <h1>My Portfolio</h1>
-    <p>Hi, I build small, sturdy things on the web.</p>
-    <nav>
-      <a href="/">Home</a> ·
-      <a href="/about.html">About</a>
-    </nav>
-  </body>
-</html>
-```
-`public/about.html`:
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>About</title>
-  </head>
-  <body>
-    <h1>About</h1>
-    <p>A short page about the person behind the portfolio.</p>
-    <nav>
-      <a href="/">Home</a>
-    </nav>
-  </body>
-</html>
-```
-```bash
-# Nothing for you to run yet. Look at both halves of your screen.
-```
-Tell the tester:
-> Your `content-editor` agent just did its real job: it wrote the
-> actual web pages. Two HTML files landed in your project under
-> `public/`: the home page (`public/index.html`) and an about page
-> (`public/about.html`), plain static markup that follows the style
-> guide you set up earlier.
->
-> Now glance at the Map. It did not change, and that is exactly
-> right. Everything you watched grow on the canvas is your harness:
-> the `.md` files and how they reference each other (call that
-> Layer 1). The HTML pages are Layer 2, what the harness PRODUCES.
-> skill-map maps the harness, not the pages it outputs (HTML is not
-> `.md`), so writing real site files leaves the graph untouched. Two
-> layers, one project: the graph that builds the site, and the site
-> itself.
->
-> Ready to see the site running?
-Wait for confirmation. Mark `generate`: done. Auto-advance to `serve`.
-## Chapter `serve` - node server.js: your portfolio, live next to the graph (~3 min)
-**Context**: the tester installs the single dependency (Express) and
-starts the tiny server that the pre-flight already left in
-`server.js`, then opens the site in the browser. They end with two
-things side by side: the real portfolio they can click through, and
-the skill-map graph of the harness that built it. Express runs on
-Node, which the tester has from pre-flight (Node 24+), so no new
-install beyond `npm install`. This chapter is one of the few where the
-tester runs a non-`sm` command themselves (`npm install`,
-`node server.js`); guide them, do not run it for them.
-**Preparation**: none. `server.js` and `package.json` already exist
-from the kickoff pre-flight; the pages exist from the `generate`
-chapter. The tester runs everything in this chapter.
-```bash
-npm install
-node server.js
-```
-Tell the tester:
-> You have the pages; now let's serve them. In your terminal, run
-> these two commands:
->
-> The first, `npm install`, downloads the one small library the
-> server needs (Express, a tiny web server). It runs on Node, which
-> you already installed at the very start, so there is nothing new to
-> set up.
->
-> The second, `node server.js`, starts the server. It prints a line
-> telling you it is listening, something like `Listening on
-> http://localhost:3000`.
->
-> Open `http://localhost:3000` in your browser. There it is: your
-> portfolio, live. Click the **About** link, then the **Home** link
-> to come back. Those are the very pages your harness produced.
->
-> Take a second to look at both halves: on one side the running site
-> you can click through, on the other the skill-map graph of the
-> harness that built it. You built the harness, wired it, and now you
-> have run it once end to end.
->
-> Does the site load, and can you click between Home and About?
-Wait for confirmation. The tester runs the commands; do not run them
-for them. If `npm install` fails, check they are in the project root
-(the cwd they have used all along) and that Node is on PATH (`node
---version` should print 24 or higher). If the port is busy, they can
-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. 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).