@skill-map/cli 0.67.0 → 0.68.0

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

@@ -0,0 +1,140 @@
+# Part 1 (basic track): The project from zero (step library, `kickoff-*` ids)
+
+The campaign turns real here for the **basic track** (the open-standard family:
+`agent-skills`, `antigravity`). After the abstract prologue, the tester starts an
+actual project: a tiny personal **portfolio website**, fully static, served by a
+~15-line Express server, plus the `.agents/skills/` **harness** that maintains
+it. skill-map maps the harness (the `.md` assets and how they reference each
+other); the site itself is plain HTML the harness produces (the daily loop, Part
+3, runs and ships it). This lens authors only **skills** and **markdown notes**,
+and they connect by **markdown references** (`[text](path)`). `pace: per-step`,
+`preflight: portfolio-init`. Shared conventions live in `_core.md`. Narrate with
+`<provider_dir>` = `.agents/skills`.
+
+The orchestrator's `portfolio-init` pre-flight (backstage, silent) has already
+laid the bare skeleton before the tester runs `sm init`: `server.js`,
+`package.json`, `public/index.html` (none `.md`, so the scan ignores them), the
+portfolio `.skillmapignore`, and the handbook `AGENTS.md` (the one boot node).
+The chapters grow the harness from there.
+
+## Chapter `kickoff` - Start the portfolio (~2 min)
+
+**Context**: same `sm init` from the prologue, now on a real project. The map
+shows the project's harness, not throwaway demo nodes.
+
+If the prologue (`basic-fundamentals`) ran first here, `portfolio-init` already
+cleared the demo fixture during pre-flight, so the tester sees only the
+portfolio. If anything demo lingers, mention it once and move on.
+
+The project carries a `.agents/` marker (the open-standard skill home where the
+tutorial itself lives), so `sm init` auto-detects the `<provider>` lens with no
+prompt. The root `AGENTS.md` is the vendor-neutral handbook, NOT a lens marker.
+
+```bash
+sm init
+sm
+```
+
+Tell the tester:
+
+> This is a real project now: a small **portfolio website**. It's static HTML
+> served by a tiny Express server (`server.js`), and the `.agents/skills/` folder
+> is the **harness** (the helpers that maintain the site). skill-map maps that
+> harness.
+>
+> Run `sm init`, it auto-detects your `<provider>` lens from the `.agents/`
+> folder. 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 `.md`, so skill-map leaves them out, it maps
+> the harness, not the served files.
+>
+> See the handbook node? Then we start building.
+
+Wait for confirmation. Mark `kickoff`: done.
+
+## Chapter `manual` - The handbook and an entry pointer (~2 min)
+
+**Context**: the first connector on the real project. A project often keeps a
+short entry file that points readers (and tools) at the handbook. On this lens
+that pointer is a plain **markdown link**, the only connector the open standard
+defines, and it is the tester's first real reference here.
+
+Tell the tester to create the file themselves (their project's file, Inviolable
+rule #2):
+
+> Create a file called `CLAUDE.md` at the project root with exactly this content:
+>
+> ```markdown
+> See the [handbook](AGENTS.md).
+> ```
+>
+> Save it. Watch the map: a new `CLAUDE.md` node appears with a `references`
+> connector pointing at `AGENTS.md`, solid at 1.00. The markdown link
+> `[handbook](AGENTS.md)` is a file pointer (the same kind of reference you met
+> in the prologue), and since the handbook is right there the link resolves with
+> full confidence. It tells anyone (and skill-map) that this file defers to the
+> handbook.
+>
+> Did the connector light up?
+
+Wait for confirmation. Mark `manual`: done.
+
+## Chapter `first-skill` - The first harness skill (~2 min)
+
+Lay the first harness skill (content lives in `fixtures-data/`; the `skill` kind
+exists on every lens, so no skip). Backstage (silent):
+
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay portfolio --only "__PROVIDER__/skills/content-editor/SKILL.md" --provider <provider> --lang <lang>
+```
+
+Tell the tester:
+
+> I added the first real member of your harness: a skill called `content-editor`
+> (its job is to write the site's pages). A new `skill` node appeared on the map.
+> Right now it stands alone; in the next part we wire it to the handbook and the
+> style guide.
+>
+> 💡 Tip: I create these harness files for you. If you'd like to see what's
+> inside, open `<provider_dir>/content-editor/SKILL.md` in your editor, and feel
+> free to peek at the files I add in the coming chapters too.
+>
+> See the new skill node?
+
+Wait for confirmation. Mark `first-skill`: done.
+
+## Chapter `real-kinds` - The kinds in context (~2 min)
+
+**Context**: the prologue showed this lens's two kinds on abstract demo nodes.
+Now name them on the real project, and add the two markdown docs the harness
+references later (the style guide and the deploy runbook), so the daily loop's
+maintenance beats have something to point at.
+
+Lay the two docs (content lives in `fixtures-data/`). Backstage (silent):
+
+```
+node .claude/skills/sm-tutorial/scripts/fixtures.js lay portfolio --only "docs/STYLE.md,docs/DEPLOY.md" --provider <provider> --lang <lang>
+```
+
+Tell the tester:
+
+> Two more nodes joined the map, both `markdown` (the catch-all kind for `.md`
+> files that are not a skill): `docs/STYLE.md` (the style guide) and
+> `docs/DEPLOY.md` (the deploy runbook). So now you have your lens's two kinds in
+> front of you:
+>
+> - **skill**: `content-editor` (does work on your behalf).
+> - **markdown**: `AGENTS.md`, `CLAUDE.md`, the two docs (plain notes and
+>   manuals).
+>
+> Your lens authors exactly these two; Claude and Codex projects add `agent` and
+> `command` kinds on top. Your handbook now has a real harness around it: a
+> `content-editor` skill plus its docs, all on the map.
+>
+> See the skill and the docs in the map?
+
+Wait for confirmation. Mark `real-kinds`: done. Last chapter of the part: apply
+§Closing a part (name the part by its title, route back to the menu; do NOT lead
+into the next part from here).

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

@@ -2,6 +2,11 @@
 
 This is the wiring part. Part 1 grew a small set of standalone nodes around the handbook (the portfolio harness); here the tester turns that scatter of dots into a connected graph: a link checker, a publish command that pulls three pieces together, the handbook becoming a real hub, and a close-up on how sure skill-map is of each connection. `pace: auto-advance` (walk straight into the next chapter once one is marked done), `preflight: seed` (it builds on the portfolio harness from Part 1, 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.
 
+**Codex deltas (rich track).** When `tutorial.provider == codex`, the bodies below are written in the claude shape; apply per chapter (the `/` invocation and `@` mention both resolve on Codex, so the lessons and the graph are identical, only the kind / path of the `publish` node changes):
+
+- `publish`: Codex has no `command` kind, so the tester creates a **skill** at `.agents/skills/publish/SKILL.md` instead of `.claude/commands/publish.md`. The body is the Codex one (same `/check-links` + `@content-editor` + deploy reference); fetch it with `fixtures.js cat harness --file "__PROVIDER__/skills/publish/SKILL.md" --provider codex --lang <lang>`. Tell the tester they are creating a `skill` (one node, three connectors, same as the claude command). The fixture lays no `publish` for codex in this chapter (the tester authors it), so the `cat` is the source.
+- `links`: the `content-editor-style` reference is baked into the Codex content-editor's TOML (`developer_instructions`) at lay time, so the `edit content-editor-style` step is a no-op on Codex, the `content-editor -> docs/STYLE.md` arrow is already drawn from Part 1. Run only `edit agents-hub` and narrate the two `AGENTS.md` arrows; mention the style-guide arrow as already present.
+
 ## Chapter `check-links` - The link checker (~3 min)
 
 **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.
@@ -30,8 +35,6 @@ Wait for confirmation. Mark `check-links`: done.
 
 **Context**: this is the chapter where the graph comes alive. The `/publish` command ties three pieces together in one body: it invokes the link checker, mentions the content editor, and references the deploy runbook. Three connectors light up from a single new node, one per link syntax.
 
-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. 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):
@@ -86,8 +89,7 @@ Wait for confirmation. You MAY use `Read` on the file afterwards to verify it la
 
 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):
+the style-guide reference line to the content-editor. Backstage (silent):
 
 ```
 node .claude/skills/sm-tutorial/scripts/fixtures.js edit agents-hub --provider <provider> --lang <lang>

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

@@ -18,11 +18,25 @@ what the tester names their portfolio. Persist the answer with
 `state.js set-identity --name "<name>" --tagline "<tagline>"` (it records
 `tester.site_identity` in `tutorial-state.json`).
 
-**Provider note (read once).** Substitute `.claude/` with the detected
-`<provider_dir>`. On `agent-skills` / Antigravity the `content-editor` is a
-**skill**, not an agent (invoke it as a skill); there is no `command` kind, so
-the `reserved` chapter is skipped and the `broken-ref` / `publish` chapters use
-their agent-skills variant (notes inline).
+**Provider note (read once).** This is the rich track; the bodies below are the
+`claude` layout (`.claude/`). The open-standard family (agent-skills /
+antigravity) walks its own `basic-daily` part. **Codex deltas** (when
+`tutorial.provider == codex`): the `content-editor` is a TOML agent at
+`.codex/agents/content-editor.toml`, and Codex has no `command` kind, so
+`publish` is a **skill** at `.agents/skills/publish/SKILL.md`. The `@`/`/`
+connectors all resolve on Codex, so every beat lands the same; only the path /
+kind of those two nodes changes. Per chapter:
+
+- `add-page`: invoke the `content-editor` TOML agent via the Task tool (same flow).
+- `broken-ref`: the deploy link that breaks lives in the `publish` SKILL; fix it
+  in `.agents/skills/publish/SKILL.md` (not a `.claude/commands/` file).
+- `reserved`: Codex has no command, so create a SKILL with a reserved name
+  instead, `Write` `.agents/skills/config/SKILL.md` named `config` (it shadows
+  the open-standard `COMMONS_RESERVED_NAMES`); clear it by renaming the folder +
+  `frontmatter.name` to `new-page`, exactly like the basic track's `reserved`
+  chapter, on a skill.
+- `publish`: run the `publish` SKILL's steps for real (same `/check-links` +
+  `@content-editor` + deploy runbook).
 
 **Real-execution contract (read once).** When invoking the `content-editor` via
 the Task tool, instruct it explicitly to write ONLY `.html` files under
@@ -225,8 +239,8 @@ Tell the tester:
 > page.
 
 When the tester answers, invoke the project's `content-editor` (the
-`<provider_dir>/agents/content-editor.md` agent, or the skill on `agent-skills`)
-via the Task tool, honouring the real-execution contract above: write ONE new
+`.claude/agents/content-editor.md` agent) via the Task tool, honouring the
+real-execution contract above: write ONE new
 `.html` page under `public/` named after the topic (default `public/projects.html`),
 following the agent's own steps and `docs/STYLE.md` (the shared shell, link
 `/style.css`, one `<h1>`, a nav link back to Home), and add the new page to the
@@ -259,10 +273,6 @@ Wait for confirmation. Mark `add-page`: done. Auto-advance to `broken-ref`.
 its keep. You rename a doc, and a link that pointed at the old name goes stale.
 skill-map catches it the moment you re-scan.
 
-On `agent-skills` / Antigravity there is no `/publish` command holding the deploy
-link; use the variant in the note at the end of this chapter (rename
-`docs/STYLE.md` to break the `content-editor`'s style-guide reference instead).
-
 **Preparation**: none (the tester drives). Everything here is watched live on
 the Map; no `sm` commands.
 
@@ -293,23 +303,12 @@ Wait for confirmation. The harness MUST be clean again (the red marker gone)
 before Act C (the real `/publish` later follows this runbook). Mark `broken-ref`:
 done. Auto-advance to `reserved`.
 
-On `agent-skills` / Antigravity (no `command` kind), run the same beat on a link
-that exists there: `mv docs/STYLE.md docs/STYLE-GUIDE.md`, which breaks the
-`content-editor` skill's `[style guide]` reference; the Map flags the broken
-reference on the `content-editor`; fix the link in the skill body and watch it
-clear.
-
 ## Chapter `reserved` - A reserved name collides (~2 min)
 
 **Context**: you add a quick command to scaffold new pages and, without
 thinking, name it `init`, a name Claude Code already owns for its own slash
 command. skill-map warns you before the runtime silently ignores your file.
 
-On `agent-skills` / Antigravity there is no `command` kind: **skip this chapter**
-and fold a one-line mention ("skill-map also warns when a file's name collides
-with a runtime built-in") into the close of the previous chapter. Adjust the
-section's chapter count accordingly.
-
 **Preparation**: `Write` `.claude/commands/init.md`:
 ```markdown
 ---
@@ -359,10 +358,6 @@ checker over your pages, briefs the `content-editor` if anything needs a fix,
 then follows the deploy runbook. This is the same Layer 1 / Layer 2 split, the
 pages are output, so the Map stays put while the pipeline runs.
 
-On `agent-skills` / Antigravity there is no `/publish` command: run the
-`check-links` skill directly over `public/`, then follow `docs/DEPLOYMENT.md` by
-hand. Everything else in this chapter is identical.
-
 **Preparation**: make sure the pages exist (`index`, `about`, `projects` from the
 earlier chapters; lay any that are missing from the templates in `setup`). When the tester asks to publish, **execute the publish flow for real**
 by following `.claude/commands/publish.md`: run the `check-links` logic over

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

@@ -2,6 +2,13 @@
 
 The live-UI prologue: the tester runs `sm init`, opens the browser, and watches the map update in real time as files are written and edited. `pace: per-step` (one chapter per exchange; the chapter's own confirmation advances to the next, NO separate "¿seguimos?"), `preflight: taught-init` (the tester runs `sm init` as the first taught step, not pre-flight), and the chapters lay the basics fixture progressively, one node at a time. Shared conventions (tone, provider detection / substitution, the `> ` rendering rule, the per-step cycle) live in `_core.md`; do not restate them here.
 
+**Codex deltas (rich track).** When `tutorial.provider == codex` the lay commands are unchanged (the `--only` ids match the Codex overlay), but the on-disk shapes differ; substitute in the tester-facing prose:
+
+- `init`: the boot node `demo-agent` is a **TOML agent** at `.codex/agents/demo-agent.toml`.
+- `kinds`: the node list reads `.codex/agents/demo-agent.toml` (agent), `.agents/skills/demo-command/SKILL.md` (Codex has no `command`, so this node is a **skill**), `.agents/skills/demo-skill/SKILL.md` (skill), and the `notes/*.md`. Name the kinds as agent + skill + markdown.
+- `first-edit`: the description to edit lives in `.codex/agents/demo-agent.toml` (the `description = "…"` TOML field, not YAML frontmatter).
+- `connectors` onward: identical, the `@`/`/` bullets resolve the same on Codex; only the `ignore` chapter's directory tree shows `.codex/agents/` + `.agents/skills/` instead of `.claude/`.
+
 ## Chapter `init` - Your first node (~2 min)
 
 Agent background (do NOT render this as a separate context paragraph; the tester-facing version is folded into the message below): `sm init` creates a hidden `.skill-map/` folder in the cwd holding the database where skill-map stores what it learns about the project, and runs an initial scan (mandatory first step). Typing `sm` alone (no arguments) in an initialised dir then starts the UI server with the watcher built in (it is just an alias of `sm serve` with all defaults; the moment you need any flag you write `sm serve --flag ...` explicitly). One process, one terminal: it boots the server, scans the `.md` files, detects changes, and pushes events over WebSocket to the live UI. The next chapters all run against this same `sm` session, you boot it here and keep it alive through the `ignore` chapter.
@@ -38,7 +45,7 @@ Wait for confirmation. Mark `init`: done.
 
 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 nodes 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).
 
-Lay these five files in one go (their content + translation live in `fixtures-data/`). The script resolves `__PROVIDER__` and auto-skips kinds the provider does not claim (`agent-skills` / Antigravity: both `demo-agent` and `demo-command` fold away, only the skill + the three markdown notes remain), so read the actual node count from the summary's `nodeCount`. Backstage (silent):
+Lay these five files in one go (their content + translation live in `fixtures-data/`). The script resolves `__PROVIDER__` to the claude layout (this is the rich track). Backstage (silent):
 
 ```
 node .claude/skills/sm-tutorial/scripts/fixtures.js lay prologue --only "__PROVIDER__/skills/demo-skill/SKILL.md,__PROVIDER__/commands/demo-command.md,notes/todo.md,notes/demo-guideline.md,notes/demo-guideline2.md" --provider <provider> --lang <lang>
@@ -109,7 +116,7 @@ You edit `notes/todo.md` so it becomes the **hub** that points to each of the ot
 
 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 the hub bullets (their content + translation live in `fixtures-data/`). The edit appends after the `# Pending` heading; the script drops any bullet whose target kind the provider does not claim (on `agent-skills` / Antigravity there is no agent and no command → the `@demo-agent` and `/demo-command` bullets fold away; 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). Backstage (silent):
+Apply the hub bullets (their content + translation live in `fixtures-data/`). The edit appends after the `# Pending` heading. Backstage (silent):
 
 ```
 node .claude/skills/sm-tutorial/scripts/fixtures.js edit todo-connectors --provider <provider> --lang <lang>
@@ -223,14 +230,12 @@ Once they confirm, the second edit fixes the broken reference. Tell the tester:
 >
 > Confirm when the new arrow is in and the red marker is gone.
 
-You verify by reading `notes/todo.md` to confirm both edits landed (the `@demo-agent` bullet gone, `@demo-guideline` now `@demo-guideline.md`); the prologue's broken reference is now resolved. (On `agent-skills`, where the `@demo-agent` bullet was never created in the `connectors` chapter, ask the tester to remove the only bullet they did add for the first edit; the `.md` fix on `@demo-guideline` is identical.) Once they confirm, leave the server running, the next chapter reuses it. Mark `edit-link`: done.
+You verify by reading `notes/todo.md` to confirm both edits landed (the `@demo-agent` bullet gone, `@demo-guideline` now `@demo-guideline.md`); the prologue's broken reference is now resolved. Once they confirm, leave the server running, the next chapter reuses it. Mark `edit-link`: done.
 
 ## Chapter `workspace` - Navigate the workspace (files, search, isolate) (~2 min)
 
 **Context**: you've built the graph and understood it; this beat is about *moving around* it. The workspace has two halves: the **Map** you've been working in, and a **Files** panel, a folder tree of every node. You'll open that tree and filter it with the search box. The same `sm` session you booted back in the `init` chapter is still running.
 
-Per §Provider detection, on `agent-skills` / Antigravity the fixture has fewer nodes (`demo-skill` plus the two `notes/` files), so swap the node names below for ones that exist in that set; the gestures are identical.
-
 Walk the three tester actions below one at a time (open the Files
 panel, then search, then isolate); each ends with its own
 confirmation, so present one and wait for the tester before the next.

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

@@ -27,12 +27,9 @@ an external service, not a file on disk). If several harness members
 named the same server, skill-map would draw a single shared
 `mcp://images` node, not one per caller.
 
-**Preparation**: `Edit` `<provider_dir>/agents/content-editor.md`
-(substitute `<provider_dir>` per `_core.md`; on `agent-skills` /
-Antigravity the editor is a `skill` instead, edit that file's
-frontmatter the same way). Do NOT rewrite the file. Change only the
-`tools:` line in the frontmatter so the MCP tool joins the existing
-two:
+**Preparation**: `Edit` `.claude/agents/content-editor.md`. Do NOT
+rewrite the file. Change only the `tools:` line in the frontmatter so
+the MCP tool joins the existing two:
 
 ```yaml
 tools: [Read, Write, mcp__images__search]

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

@@ -16,6 +16,25 @@ which are `.md`, so the scan ignores them), the portfolio
 `.skillmapignore`, and the handbook `AGENTS.md` (the one boot node).
 The chapters grow the harness from there.
 
+**Codex deltas (rich track).** When `tutorial.provider == codex`:
+
+- `kickoff` / `manual`: identical. A `.codex/` project resolves the `codex`
+  lens; `CLAUDE.md`'s `@AGENTS.md` reference resolves the same (Codex has the
+  `@`-directive). `AGENTS.md` is still the one boot node.
+- `first-agent`: the `content-editor` is a **TOML agent** at
+  `.codex/agents/content-editor.toml`, not a `.claude/agents/*.md` file; point
+  the tester at the `.toml` if they want to peek. Its body references the style
+  guide from the start (baked into `developer_instructions`), so lay
+  `docs/STYLE.md` together with it (`fixtures.js lay portfolio --only
+  "__PROVIDER__/agents/content-editor.md,docs/STYLE.md" --provider codex …`,
+  the `--only` matches the TOML overlay by node id) so the
+  `content-editor -> docs/STYLE.md` arrow resolves immediately instead of
+  showing a transient broken-reference.
+- `real-kinds`: Codex's kinds are `agent` (TOML) + `skill` + `markdown`, there is
+  no `command`. Lay only `docs/DEPLOY.md` here (STYLE landed in `first-agent`),
+  and name the kinds as agent + skill + markdown (the skill + the publish piece
+  arrive in Part 2 as skills).
+
 ## Chapter `kickoff` - Start the portfolio (~2 min)
 
 **Context**: same `sm init` the tester learned in the prologue, but
@@ -28,14 +47,13 @@ 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.** This
-project has a root `AGENTS.md` (the `codex`/Codex marker) sitting next
-to the `.claude/` folder (the `claude` marker, where the tutorial skill
-itself lives). `codex` is **experimental** (ships disabled), though, so auto-detect
-ignores its marker and `sm init` resolves the lens to `claude`
-silently, exactly like the prologue: only `claude` is selectable today,
-so there is no ambiguity and no prompt. Do not promise the tester a
-lens prompt here.
+**Context (agent, do not narrate the plumbing): the lens.** The skill
+was scaffolded under `.claude/` (the `claude` marker, where the tutorial
+skill itself lives), so `sm init` auto-detects the `claude` lens with no
+prompt. The root `AGENTS.md` is the vendor-neutral handbook, NOT a lens
+marker, so it never forces an ambiguous prompt. (This is the rich track;
+a Codex project resolves the `codex` lens the same way from its
+`.codex/` marker.) Do not promise the tester a lens prompt here.
 
 ```bash
 sm init
@@ -49,9 +67,8 @@ Tell the tester:
 > `.claude/` folder is the **harness** (the helpers that maintain the
 > site). skill-map maps that harness.
 >
-> Run `sm init`, it auto-detects the `claude` lens (this is a Claude
-> project; the other lenses are experimental). Then run `sm` to boot the
-> live UI.
+> Run `sm init`, it auto-detects the `claude` lens from the `.claude/`
+> folder. 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).
@@ -99,9 +116,7 @@ Wait for confirmation. Mark `manual`: done.
 ## Chapter `first-agent` - The first harness agent (~2 min)
 
 Lay the first harness agent (its content + translation live in
-`fixtures-data/`). The script resolves `__PROVIDER__`; on
-`agent-skills` / Antigravity, which has no `agent` kind, adjust the
-prose to the skill the set lays there. Backstage (silent):
+`fixtures-data/`). Backstage (silent):
 
 ```
 node .claude/skills/sm-tutorial/scripts/fixtures.js lay portfolio --only "__PROVIDER__/agents/content-editor.md" --provider <provider> --lang <lang>

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

@@ -125,16 +125,19 @@ Mark `settings-2-resolve: done`.
 
 **Context**: the single most consequential setting, the lens that
 decides which provider types the project's files. It auto-detects and
-never touches your `.md` files.
+never touches your `.md` files. (Agent: substitute `<provider>` with
+`tutorial.provider`, the lens this run was scaffolded for.)
 
 > One setting earns its own step: the **active provider lens**. A
 > skill-map project reads its files through exactly **one** provider
 > at a time, and that lens decides how each file is interpreted, so
 > the same files can read differently depending on which lens is active.
 
-> The lens auto-detects on the first scan from your project's layout
-> (a `.claude/` folder selects the `claude` lens). Scan once and check
-> where it landed:
+> The lens auto-detects on the first scan from the project's layout. A
+> marker folder selects its lens: `.claude/` → `claude`, `.codex/` →
+> `codex`, `.agent/workflows/` → `antigravity`; a project with only
+> `.agents/skills/` and no vendor marker falls back to the open-standard
+> `agent-skills` lens. Scan once and check where it landed:
 
 ```bash
 sm scan
@@ -142,17 +145,18 @@ sm config get activeProvider
 ```
 
 Expected: the scan prints a line like `Auto-detected activeProvider
-= claude from filesystem markers; persisted to
-.skill-map/settings.json`, and `get` then reports `claude`. The lens
+= <provider> from filesystem markers; persisted to
+.skill-map/settings.json`, and `get` then reports `<provider>`. The lens
 is just a key in `settings.json`, persisted like any other setting.
 
-> Other lenses exist in the engine (`codex` for Codex,
-> `agent-skills`, `antigravity`), but they are **experimental** (ship
-> disabled by default): today we demo the `claude` lens only. The idea to keep is
-> the one above, one project reads through exactly one provider at a
-> time, chosen by `activeProvider`. The lens is cheap to change later
-> because the graph is always rebuilt from your files, never the
-> other way around.
+> The other lenses are just as real: `claude` and the open-standard
+> `agent-skills` are stable; `codex` (OpenAI) and `antigravity` (Google)
+> are beta but ship enabled and auto-detect their own marker. The open
+> `agent-skills` lens is the default a project falls back to when no
+> vendor marker is present. The idea to keep: one project reads through
+> exactly one lens at a time, chosen by `activeProvider`, and it is cheap
+> to change later because the graph is always rebuilt from your files,
+> never the other way around.
 
 Mark `settings-3-lens: done`.
 

package/dist/cli/tutorial/sm-tutorial/scripts/fixtures.js

@@ -34,7 +34,8 @@ import { parseArgs } from './lib/args.js';
 import { emit, succeed, die } from './lib/io.js';
 import { loadFixturesManifest, fixturesDir, resolveFootprint } from './lib/fixtures-manifest.js';
 import {
-  providerDir, kindsFor, resolveTargetPath, kindForPath, PROVIDER_TOKEN,
+  providerDir, kindsFor, resolveTargetPath, kindForPath, nodeIdForTokenPath, overlayKey,
+  fragmentKindsFor, PROVIDER_TOKEN,
 } from './lib/paths.js';
 
 function opts(args) {
@@ -68,38 +69,76 @@ function writeFileEnsuring(abs, content) {
 
 /**
  * Lay one set's files for the given lang + provider. `only` (a Set of
- * token-form relpaths) restricts to those files, for the prologue's
- * progressive reveal where each chapter lands its own nodes.
+ * token-form relpaths, claude-shaped and lens-agnostic) restricts to those
+ * nodes, for the prologue's progressive reveal where each chapter lands its
+ * own nodes; matching is by logical node id so a claude-shaped `--only`
+ * entry still selects the agent-skills skill overlay of the same node.
+ *
+ * Tiers, in lay order (later wins): lang-invariant `shared/`, the language
+ * tier, then the per-provider overlay (`providers/<provider>/{shared,<lang>}/`).
+ * The overlay carries the skill-shaped variants of nodes a lens renders
+ * differently (e.g. the `content-editor` agent becomes a skill on
+ * agent-skills); claude declares no overlay because the base IS its shape.
  */
 function laySet(manifest, set, o, only = null) {
   const { kinds } = pdirAndKinds(o);
   if (!manifest.sets.includes(set)) die('unknown-set', `set '${set}' is not in the manifest.`);
   const base = join(fixturesDir(), 'sets', set);
   const langDir = existsSync(join(base, o.lang)) ? o.lang : (manifest.defaultLang ?? 'en');
+  const onlyIds = only ? new Set([...only].map(nodeIdForTokenPath)) : null;
+  const oKey = overlayKey(o.provider);
   const laid = [];
+  const laidIds = new Set();
   const skipped = [];
-  // Lang-invariant `shared/` tier first, then the language tier.
-  for (const tier of ['shared', langDir]) {
-    const tierRoot = join(base, tier);
+  const tiers = [
+    join(base, 'shared'),
+    join(base, langDir),
+    join(base, 'providers', oKey, 'shared'),
+    join(base, 'providers', oKey, langDir),
+  ];
+  for (const tierRoot of tiers) {
     for (const rel of walk(tierRoot)) {
       // `rel` is the token-form target path (e.g. __PROVIDER__/agents/x.md).
-      if (only && !only.has(rel)) continue;
+      if (onlyIds && !onlyIds.has(nodeIdForTokenPath(rel))) continue;
       const kind = kindForPath(rel);
       if (!kinds.has(kind)) { skipped.push({ path: rel, kind }); continue; }
       const target = resolveTargetPath(rel, o.provider);
       writeFileEnsuring(join(process.cwd(), target), readFileSync(join(tierRoot, rel)));
       laid.push(target);
+      laidIds.add(nodeIdForTokenPath(rel));
     }
   }
-  return { laid, skipped };
+  // Drop from `skipped` any node that the overlay laid under another kind
+  // (the claude-shaped agent file is skipped, but its skill overlay landed),
+  // so the report only flags nodes genuinely absent on this lens.
+  const netSkipped = skipped.filter((s) => !laidIds.has(nodeIdForTokenPath(s.path)));
+  return { laid, skipped: netSkipped };
 }
 
-const nodeCount = (paths) => paths.filter((p) => p.endsWith('.md')).length;
+// Count UNIQUE `.md` targets: a per-provider overlay can overwrite a base
+// file (e.g. the open-standard `AGENTS.md` handbook), so `laid` may list the
+// same target twice; the node count is the on-disk reality, not the write count.
+const nodeCount = (paths) => new Set(paths.filter((p) => p.endsWith('.md'))).size;
 
-/** Resolve a fragment file path, falling back to the default language. */
-function fragmentPath(manifest, id, lang, file) {
-  const langTry = join(fixturesDir(), 'edits', id, lang, file);
-  return existsSync(langTry) ? langTry : join(fixturesDir(), 'edits', id, manifest.defaultLang ?? 'en', file);
+/**
+ * Resolve a fragment file path. A per-provider overlay
+ * (`edits/<id>/providers/<provider>/<lang>/`) wins when present, mirroring
+ * the set overlay, a fragment with a relative link to a provider-dir file
+ * is depth-sensitive (the content-editor lives one level deeper as a skill
+ * under agent-skills), so its link text differs per lens. Falls back to the
+ * shared fragment, then to the default language for either tier.
+ */
+function fragmentPath(manifest, id, o, file) {
+  const def = manifest.defaultLang ?? 'en';
+  const dir = join(fixturesDir(), 'edits', id);
+  const oKey = overlayKey(o.provider);
+  const candidates = [
+    join(dir, 'providers', oKey, o.lang, file),
+    join(dir, 'providers', oKey, def, file),
+    join(dir, o.lang, file),
+    join(dir, def, file),
+  ];
+  return candidates.find((c) => existsSync(c)) ?? candidates[candidates.length - 1];
 }
 
 /** Apply one manifest edit (append fragments) honoring requiresKind. */
@@ -107,14 +146,30 @@ function applyEdit(manifest, id, o) {
   const { kinds } = pdirAndKinds(o);
   const def = manifest.edits?.[id];
   if (!def) die('unknown-edit', `edit '${id}' is not in the manifest.`);
-  const target = resolveTargetPath(def.target, o.provider);
-  // Skip the whole edit if the target's own kind is unsupported (e.g. a
-  // content-editor agent does not exist on agent-skills).
-  if (!kinds.has(kindForPath(def.target))) return { target, appended: [], skipped: true };
+  // Resolve the target to the shape this provider actually laid. When the
+  // declared (claude-shaped) target's kind is unclaimed, fall back to the
+  // skill-overlay path for the same node id, agent-skills renders the
+  // content-editor agent as a skill, so the style fragment must append to
+  // that skill body. Only genuinely-absent nodes skip the edit.
+  let targetTok = def.target;
+  if (!kinds.has(kindForPath(targetTok))) {
+    const skillTok = `${PROVIDER_TOKEN}/skills/${nodeIdForTokenPath(def.target)}/SKILL.md`;
+    const skillAbs = join(process.cwd(), resolveTargetPath(skillTok, o.provider));
+    if (kinds.has('skill') && existsSync(skillAbs)) {
+      targetTok = skillTok;
+    } else {
+      return { target: resolveTargetPath(def.target, o.provider), appended: [], skipped: true };
+    }
+  }
+  const target = resolveTargetPath(targetTok, o.provider);
   const targetAbs = join(process.cwd(), target);
   if (!existsSync(targetAbs)) die('edit-target-missing', `edit '${id}' target not found: ${target}`);
 
-  const fragments = (def.fragments ?? []).filter((f) => !f.requiresKind || kinds.has(f.requiresKind));
+  // Fragment gating is by TRACK, not the base-tier `kinds`: a rich provider
+  // (codex) links to agent / command roles it renders via overlay (TOML agent,
+  // command-as-skill), so those bullets apply even though its base kinds omit them.
+  const fragKinds = fragmentKindsFor(o.provider);
+  const fragments = (def.fragments ?? []).filter((f) => !f.requiresKind || fragKinds.has(f.requiresKind));
   if (fragments.length === 0) return { target, appended: [] };
 
   let content = readFileSync(targetAbs, 'utf8');
@@ -122,7 +177,7 @@ function applyEdit(manifest, id, o) {
   if (def.prefix) content += def.prefix;
   const appended = [];
   for (const frag of fragments) {
-    content += readFileSync(fragmentPath(manifest, id, o.lang, frag.file), 'utf8');
+    content += readFileSync(fragmentPath(manifest, id, o, frag.file), 'utf8');
     appended.push(frag.file);
   }
   writeFileSync(targetAbs, content);
@@ -207,7 +262,15 @@ const VERBS = {
     const langDir = existsSync(join(base, o.lang)) ? o.lang : (manifest.defaultLang ?? 'en');
     // Accept a resolved path (`.claude/...`) or token form; normalise to token.
     const tokenForm = file.startsWith(`${pdir}/`) ? PROVIDER_TOKEN + file.slice(pdir.length) : file;
-    const found = [join(base, langDir, tokenForm), join(base, 'shared', tokenForm)].find((c) => existsSync(c));
+    // Prefer the per-provider overlay (so codex / agent-skills get their own
+    // shape, e.g. the publish skill or the TOML agent) before the base.
+    const oKey = overlayKey(o.provider);
+    const found = [
+      join(base, 'providers', oKey, langDir, tokenForm),
+      join(base, 'providers', oKey, 'shared', tokenForm),
+      join(base, langDir, tokenForm),
+      join(base, 'shared', tokenForm),
+    ].find((c) => existsSync(c));
     if (!found) {
       emit({ ok: false, code: 'not-found', error: `file '${file}' not found in set '${set}'.` });
       process.exit(1);
@@ -234,5 +297,5 @@ function main() {
 }
 
 main();
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7deeaba5-0c50-5d6e-93cc-ad31c6b5a37c")}catch(e){}}();
-//# debugId=7deeaba5-0c50-5d6e-93cc-ad31c6b5a37c
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9e366749-efd9-5bc5-bba4-41147eabf625")}catch(e){}}();
+//# debugId=9e366749-efd9-5bc5-bba4-41147eabf625