@skill-map/cli 0.67.0 → 0.68.0

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

@@ -242,12 +242,18 @@ All commands below are backstage (silent); fill `<provider>` and
 `<lang>` from `tutorial.{provider,lang}`. The fixture scripts resolve
 the `__PROVIDER__` token and skip kinds the provider does not claim.
 
-- **`taught-init`** (Part 0 `fundamentals`): the prologue reveals its
-  fixture progressively, so on entry lay ONLY the boot node, just
-  before the tester's `sm init` in the `init` chapter:
+- **`taught-init`** (Part 0 `fundamentals` rich / `basic-fundamentals`
+  basic): the prologue reveals its fixture progressively, so on entry
+  lay ONLY the boot node, just before the tester's `sm init` in the
+  `init` chapter. The boot node is the lens's first authored kind, an
+  `agent` on the rich track, a `skill` on the basic track (where the
+  agent kind folds away):
 
   ```bash
+  # rich track (claude / codex)
   node .claude/skills/sm-tutorial/scripts/fixtures.js lay prologue --only "__PROVIDER__/agents/demo-agent.md" --provider <provider> --lang <lang>
+  # basic track (agent-skills / antigravity)
+  node .claude/skills/sm-tutorial/scripts/fixtures.js lay prologue --only "__PROVIDER__/skills/demo-skill/SKILL.md" --provider <provider> --lang <lang>
   ```
 
   The universal `.skillmapignore` is already on disk, so the first
@@ -304,11 +310,13 @@ the `__PROVIDER__` token and skip kinds the provider does not claim.
   2. Seed: `fixtures.js seed <harness-built|harness-connected> --provider <provider> --lang <lang>`
      (`harness-built` for `connect-harness`, `harness-connected` for
      `daily-loop`).
-  3. Provision the lens: the seeded portfolio has a root `AGENTS.md`
-     (the `codex`/Codex marker) next to `.claude/`, but `codex` is
-     experimental (ships disabled), so auto-detect ignores it and a plain `sm init`
-     resolves the `claude` lens with no prompt. Run `sm init`, then
-     `sm scan`. (If `.skill-map/` already exists, just `sm scan`.)
+  3. Provision the lens: the seeded portfolio carries the scaffold
+     marker (`.claude/` on the rich track, `.agents/` on the basic
+     track), so a plain `sm init` resolves the matching lens with no
+     prompt. (The root `AGENTS.md` is the vendor-neutral agents.md file,
+     NOT a marker, so it never forces an ambiguous prompt.) Run `sm
+     init`, then `sm scan`. (If `.skill-map/` already exists, just
+     `sm scan`.)
   4. Mark the skipped predecessors: `state.js set-part <predecessor> skipped`
      for each (they stay in the menu). Then emit exactly ONE
      tester-facing line:

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/agents-hub/providers/agent-skills/en/agents-hub.md

@@ -0,0 +1,2 @@
+- When a page needs writing or fixing, hand it to the [content-editor](.agents/skills/content-editor/SKILL.md).
+- When the site is ready to go out, run [publish](.agents/skills/publish/SKILL.md).

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/agents-hub/providers/agent-skills/es/agents-hub.md

@@ -0,0 +1,2 @@
+- Cuando una página necesita escribirse o arreglarse, pasásela al [content-editor](.agents/skills/content-editor/SKILL.md).
+- Cuando el sitio esté listo para salir, corré [publish](.agents/skills/publish/SKILL.md).

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/content-editor-style/providers/agent-skills/en/content-editor-style.md

@@ -0,0 +1 @@
+Every page follows the [style guide](../../../docs/STYLE.md).

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/content-editor-style/providers/agent-skills/es/content-editor-style.md

@@ -0,0 +1 @@
+Cada página sigue la [guía de estilo](../../../docs/STYLE.md).

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/agent-skills/en/todo-bullet-guideline.md

@@ -0,0 +1 @@
+- [ ] Follow the [demo-guideline](demo-guideline) when the conventions change.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/agent-skills/en/todo-bullet-guideline2.md

@@ -0,0 +1 @@
+- [ ] Follow the [demo-guideline2](demo-guideline2.md) for the rest.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/agent-skills/en/todo-bullet-skill.md

@@ -0,0 +1 @@
+- [ ] See the [demo-skill](../.agents/skills/demo-skill/SKILL.md) for the steps.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/agent-skills/es/todo-bullet-guideline.md

@@ -0,0 +1 @@
+- [ ] Seguí la [demo-guideline](demo-guideline) cuando cambien las convenciones.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/agent-skills/es/todo-bullet-guideline2.md

@@ -0,0 +1 @@
+- [ ] Seguí la [demo-guideline2](demo-guideline2.md) para el resto.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/edits/todo-connectors/providers/agent-skills/es/todo-bullet-skill.md

@@ -0,0 +1 @@
+- [ ] Mirá la [demo-skill](../.agents/skills/demo-skill/SKILL.md) para los pasos.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/manifest.json

@@ -7,8 +7,10 @@
   "footprints": {
     "prologue": [
       "__PROVIDER__/agents/demo-agent.md",
+      ".codex/agents/demo-agent.toml",
       "__PROVIDER__/skills/demo-skill",
       "__PROVIDER__/commands/demo-command.md",
+      "__PROVIDER__/skills/demo-command",
       "notes/todo.md",
       "notes/demo-guideline.md",
       "notes/demo-guideline2.md",
@@ -28,12 +30,18 @@
       "docs/DEPLOY.md",
       "docs/DEPLOYMENT.md",
       "__PROVIDER__/agents/content-editor.md",
+      ".codex/agents/content-editor.toml",
+      "__PROVIDER__/skills/content-editor",
       "__PROVIDER__/skills/check-links",
       "__PROVIDER__/commands/publish.md",
-      "__PROVIDER__/commands/new-page.md"
+      "__PROVIDER__/skills/publish",
+      "__PROVIDER__/commands/new-page.md",
+      "__PROVIDER__/skills/new-page"
     ],
     "master": [
       "__PROVIDER__/agents/master-agent.md",
+      ".codex/agents/master-agent.toml",
+      "__PROVIDER__/skills/master-agent",
       "__PROVIDER__/skills/master-skill",
       "notes/ideas.md"
     ],

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/harness/providers/agent-skills/en/__PROVIDER__/skills/publish/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: publish
+description: |
+  Publishes the portfolio: runs the link check, hands off to the
+  content editor for any last fixes, then follows the deploy runbook.
+---
+
+# publish
+
+The one skill you run when the site is ready to go out.
+
+## Steps
+1. Run the [check-links](../check-links/SKILL.md) skill on the pages in public/. If it reports broken links, stop and fix them first.
+2. If a page needs a content fix, hand the change to [content-editor](../content-editor/SKILL.md).
+3. Follow the [deploy runbook](../../../docs/DEPLOY.md): regenerate pages, run the link check, start the server.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/harness/providers/agent-skills/es/__PROVIDER__/skills/publish/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: publish
+description: |
+  Publica el portfolio: corre el chequeo de enlaces, le pasa al
+  content editor los últimos arreglos, y luego sigue el runbook de
+  despliegue.
+---
+
+# publish
+
+La única skill que corres cuando el sitio está listo para salir.
+
+## Pasos
+1. Corre la skill [check-links](../check-links/SKILL.md) sobre las páginas en public/. Si reporta enlaces rotos, frena y arréglalos primero.
+2. Si una página necesita un arreglo de contenido, pasale el cambio a [content-editor](../content-editor/SKILL.md).
+3. Sigue el [runbook de despliegue](../../../docs/DEPLOY.md): regenera las páginas, corre el chequeo de enlaces, inicia el servidor.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/harness/providers/codex/en/__PROVIDER__/skills/publish/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: publish
+description: |
+  Publishes the portfolio: runs the link check, hands off to the
+  content editor for any last fixes, then follows the deploy runbook.
+---
+
+# publish
+
+The one skill you run when the site is ready to go out.
+
+## Steps
+1. Run /check-links on the pages in public/. If it reports broken links, stop and fix them first.
+2. If a page needs a content fix, brief @content-editor with the change.
+3. Follow the [deploy runbook](../../../docs/DEPLOY.md): regenerate pages, run the link check, start the server.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/harness/providers/codex/es/__PROVIDER__/skills/publish/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: publish
+description: |
+  Publica el portfolio: corre el chequeo de enlaces, le pasa al
+  content editor los últimos arreglos, y luego sigue el runbook de
+  despliegue.
+---
+
+# publish
+
+La única skill que corres cuando el sitio está listo para salir.
+
+## Pasos
+1. Corre /check-links sobre las páginas en public/. Si reporta enlaces rotos, frena y arréglalos primero.
+2. Si una página necesita un arreglo de contenido, dale el cambio a @content-editor.
+3. Sigue el [runbook de despliegue](../../../docs/DEPLOY.md): regenera las páginas, corre el chequeo de enlaces, inicia el servidor.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/providers/agent-skills/en/__PROVIDER__/skills/master-agent/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: master-agent
+description: |
+  Example skill used by the advanced tutorial. Declares a couple of
+  tools so the `core/tools-counter` extractor emits a count.
+allowed-tools: Read Bash Edit
+---
+
+# 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.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/providers/agent-skills/es/__PROVIDER__/skills/master-agent/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: master-agent
+description: |
+  Skill de ejemplo que usa el tutorial avanzado. Declara un par de
+  herramientas para que el extractor `core/tools-counter` emita un
+  conteo.
+allowed-tools: Read Bash Edit
+---
+
+# master-agent
+
+Recorre las salidas de master-skill y reporta hallazgos. Se usa como
+el nodo objetivo cuando ejercitamos extractors, analyzers y el flujo
+de autoría de plugins.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/providers/codex/en/.codex/agents/master-agent.toml

@@ -0,0 +1,10 @@
+name = "master-agent"
+description = "Example agent used by the advanced tutorial. The target node when we exercise extractors, analyzers, and the plugin-authoring flow."
+model = "gpt-5-codex"
+developer_instructions = """
+# 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.
+"""

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/master/providers/codex/es/.codex/agents/master-agent.toml

@@ -0,0 +1,10 @@
+name = "master-agent"
+description = "Agente de ejemplo que usa el tutorial avanzado. Es el nodo objetivo cuando ejercitamos extractors, analyzers y el flujo de autoría de plugins."
+model = "gpt-5-codex"
+developer_instructions = """
+# master-agent
+
+Recorre las salidas de master-skill y reporta hallazgos. Se usa como
+el nodo objetivo cuando ejercitamos extractors, analyzers y el flujo
+de autoría de plugins.
+"""

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/providers/agent-skills/en/AGENTS.md

@@ -0,0 +1,7 @@
+# Portfolio handbook
+
+A small static portfolio site, served by Express (`server.js`). The
+`.agents/skills/` harness maintains it: a content-editor skill writes
+the pages, a check-links skill checks the links, a publish skill ships
+them. The conventions live in the style guide; the deploy steps in the
+deploy runbook.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/providers/agent-skills/en/__PROVIDER__/skills/content-editor/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: content-editor
+description: |
+  Writes and edits the portfolio's pages. Reads a brief, follows the
+  style guide, and emits the HTML into public/.
+allowed-tools: Read Write
+---
+
+# content-editor
+
+Turns a short brief into a finished portfolio page.
+
+## How to write a page
+1. Read the style guide and the shared stylesheet in public/.
+2. Write one HTML file under public/, named after the page (a projects page becomes `public/projects.html`).
+3. Start from `<!doctype html>`, link the stylesheet with `<link rel="stylesheet" href="/style.css">`, and set a `<title>`.
+4. Use one `<h1>`, group sections under `<h2>`, and reuse the shared header, nav, and footer so every page matches.
+5. Add a link back to Home, and link the new page from the home nav.
+
+Rules: plain static HTML, no framework, no client JS, one page per file. If a page needs an image, use a free placeholder from https://placekittens.com/ (e.g. `https://placekittens.com/400/300`) so the `<img>` never points at a missing file.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/providers/agent-skills/es/AGENTS.md

@@ -0,0 +1,7 @@
+# Manual del portfolio
+
+Un sitio de portfolio estático y chico, servido por Express
+(`server.js`). El harness en `.agents/skills/` lo mantiene: una skill
+content-editor escribe las páginas, una skill check-links revisa los
+enlaces, una skill publish las publica. Las convenciones viven en la
+guía de estilo; los pasos de despliegue en el runbook de despliegue.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/providers/agent-skills/es/__PROVIDER__/skills/content-editor/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: content-editor
+description: |
+  Escribe y edita las páginas del portfolio. Lee un brief, sigue la
+  guía de estilo y emite el HTML en public/.
+allowed-tools: Read Write
+---
+
+# content-editor
+
+Convierte un brief corto en una página de portfolio terminada.
+
+## Cómo escribir una página
+1. Lee la guía de estilo y la hoja de estilos compartida en public/.
+2. Escribe un archivo HTML en public/, nombrado según la página (una página de proyectos pasa a ser `public/projects.html`).
+3. Empieza desde `<!doctype html>`, enlaza la hoja de estilos con `<link rel="stylesheet" href="/style.css">` y define un `<title>`.
+4. Usa un solo `<h1>`, agrupa las secciones bajo `<h2>` y reutiliza el header, la nav y el footer compartidos para que todas las páginas coincidan.
+5. Agrega un enlace de vuelta a Home, y enlaza la nueva página desde la nav de inicio.
+
+Reglas: HTML estático plano, sin framework, sin JS de cliente, una página por archivo. Si una página necesita una imagen, usa un placeholder gratuito de https://placekittens.com/ (por ejemplo `https://placekittens.com/400/300`) para que el `<img>` nunca apunte a un archivo inexistente.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/providers/agent-skills/shared/CLAUDE.md

@@ -0,0 +1 @@
+See the [handbook](AGENTS.md).

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/providers/codex/en/.codex/agents/content-editor.toml

@@ -0,0 +1,19 @@
+name = "content-editor"
+description = "Writes and edits the portfolio's pages. Reads a brief, follows the style guide, and emits the HTML into public/."
+model = "gpt-5-codex"
+developer_instructions = """
+# content-editor
+
+Turns a short brief into a finished portfolio page.
+
+## How to write a page
+1. Read the style guide and the shared stylesheet in public/.
+2. Write one HTML file under public/, named after the page (a projects page becomes `public/projects.html`).
+3. Start from `<!doctype html>`, link the stylesheet with `<link rel="stylesheet" href="/style.css">`, and set a `<title>`.
+4. Use one `<h1>`, group sections under `<h2>`, and reuse the shared header, nav, and footer so every page matches.
+5. Add a link back to Home, and link the new page from the home nav.
+
+Rules: plain static HTML, no framework, no client JS, one page per file.
+
+Every page follows the [style guide](../../docs/STYLE.md).
+"""

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/portfolio/providers/codex/es/.codex/agents/content-editor.toml

@@ -0,0 +1,19 @@
+name = "content-editor"
+description = "Escribe y edita las páginas del portfolio. Lee un brief, sigue la guía de estilo y emite el HTML en public/."
+model = "gpt-5-codex"
+developer_instructions = """
+# content-editor
+
+Convierte un brief corto en una página de portfolio terminada.
+
+## Cómo escribir una página
+1. Lee la guía de estilo y la hoja de estilos compartida en public/.
+2. Escribe un archivo HTML en public/, nombrado según la página (una página de proyectos pasa a ser `public/projects.html`).
+3. Empieza desde `<!doctype html>`, enlaza la hoja de estilos con `<link rel="stylesheet" href="/style.css">` y define un `<title>`.
+4. Usa un solo `<h1>`, agrupa las secciones bajo `<h2>` y reutiliza el header, la nav y el footer compartidos para que todas las páginas coincidan.
+5. Agrega un enlace de vuelta a Home, y enlaza la nueva página desde la nav de inicio.
+
+Reglas: HTML estático plano, sin framework, sin JS de cliente, una página por archivo.
+
+Cada página sigue la [guía de estilo](../../docs/STYLE.md).
+"""

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/providers/codex/en/.codex/agents/demo-agent.toml

@@ -0,0 +1,13 @@
+name = "demo-agent"
+description = "Example agent that handles read and shell tasks. Solo node at boot; gets connected to the rest of the demo fixture during the Live UI step."
+model = "gpt-5-codex"
+developer_instructions = """
+# demo-agent
+
+Processes inputs and logs every action to stderr. Will be wired up
+to the rest of the demo fixture later in the walkthrough.
+
+Rules:
+- Never run destructive commands without confirmation.
+- Log every action to stderr.
+"""

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/providers/codex/en/__PROVIDER__/skills/demo-command/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: demo-command
+description: |
+  Example skill that wraps the demo-skill. On Codex the prologue's
+  command-kind node renders as a skill (Codex has no command kind).
+---
+
+# demo-command
+
+Quick entry point for running the demo flow on a target file.
+Connectors land in the next sub-step.

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/providers/codex/es/.codex/agents/demo-agent.toml

@@ -0,0 +1,13 @@
+name = "demo-agent"
+description = "Agente de ejemplo que maneja tareas de lectura y shell. Nodo solo al arranque; se conecta al resto del fixture demo durante el paso de UI en vivo."
+model = "gpt-5-codex"
+developer_instructions = """
+# demo-agent
+
+Procesa entradas y registra cada acción en stderr. Se conectará al
+resto del fixture demo más adelante en el recorrido.
+
+Reglas:
+- Nunca corras comandos destructivos sin confirmación.
+- Registrá cada acción en stderr.
+"""

package/dist/cli/tutorial/sm-tutorial/fixtures-data/sets/prologue/providers/codex/es/__PROVIDER__/skills/demo-command/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: demo-command
+description: |
+  Skill de ejemplo que envuelve a demo-skill. En Codex el nodo de
+  kind command del prólogo se renderiza como skill (Codex no tiene
+  kind command).
+---
+
+# demo-command
+
+Punto de entrada rápido para correr el flujo demo sobre un archivo.
+Los conectores llegan en el próximo sub-paso.

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

@@ -251,54 +251,103 @@ first kind quoted, the second kind never.
    command blocks assume the second terminal is anchored to the
    fixture folder.
 
-## Provider detection
-
-Skill-map ships built-in vendor providers, each walking its own
-on-disk convention:
-
-| Provider       | Base dir          | Kinds it claims             | Detect via env var(s)                                  |
-|----------------|-------------------|-----------------------------|--------------------------------------------------------|
-| `claude`       | `.claude/`        | `agent`, `command`, `skill` | `CLAUDECODE=1` OR `AI_AGENT` starts with `claude-code` |
-| `agent-skills` | `.agents/skills/` | `skill` only (vendor-neutral; also the on-disk home for Google's Antigravity CLI, which replaced the Gemini CLI on 2026-05-19 and adopted this open standard) | experimental (ships disabled; `sm tutorial --experimental` to offer it) |
-| `codex`       | `.codex/`         | `agent` (`.codex/agents/*.toml`) | experimental (ships disabled by default) |
-
-**Decision logic, applied silently during pre-flight**: the tutorial
-demonstrates the `claude` provider only. `agent-skills` and `codex`
-are **experimental** (ship disabled by default) and are not selectable
-here, so there is no runtime to detect or opt into.
-
-1. `provider = claude`, `<provider_dir> = .claude`, kinds =
-   `{agent, command, skill}`. Always.
-2. Do NOT offer Antigravity / agent-skills / codex as an alternative,
-   and do NOT ask the tester which runtime hosts them. If a tester
-   says they use another runtime, acknowledge it briefly and explain
-   that those providers are experimental, the tutorial demos `claude`
-   (`.claude/`) today:
-
-   > Heads up: skill-map also reads Antigravity, agent-skills and
-   > Codex projects, but those providers are experimental in this
-   > tutorial. We'll demo skill-map's Claude provider (`.claude/`)
-   > today.
-
-Persist `provider` into the state file (`tutorial.provider`) so a
-resumed session does not re-detect. (It is always `claude` for now.)
+## Provider detection (and the track it selects)
+
+A skill-map project reads its files through exactly ONE active lens
+(provider). The built-in providers and what each claims:
+
+| Provider       | Asset layout                              | Kinds                          | Connectors that form           | Marker             | Stability        | Track   |
+|----------------|-------------------------------------------|--------------------------------|--------------------------------|--------------------|------------------|---------|
+| `claude`       | `.claude/` (agents, commands, skills)     | agent, command, skill, markdown| `/` invokes, `@` mentions, refs| `.claude/`         | stable           | rich    |
+| `codex`        | `.codex/agents/*.toml` + `.agents/skills/`| agent (TOML), skill, markdown  | `/` invokes, `@` mentions, refs| `.codex/`          | beta             | rich    |
+| `antigravity`  | `.agents/skills/`                         | skill, markdown                | `/` invokes, refs              | `.agent/workflows/`| beta             | basic   |
+| `agent-skills` | `.agents/skills/`                         | skill, markdown                | refs only                      | `.agents/`         | stable (default) | basic   |
+
+`core/markdown` classifies every orphan `.md` under whatever lens is
+active; it is the universal base, never a selectable lens.
+
+**Two tracks, by capability** (the axis is "does the lens have an
+`agent` kind?"):
+
+- **rich** (`claude`, `codex`): agents + skills (+ commands on claude),
+  wired with `/` invocations and `@` mentions plus markdown references.
+- **basic** (`agent-skills`, `antigravity`): the open-standard family,
+  `skill` + `markdown` only, wired with **markdown references**
+  (`[text](path)`), the one connection the Agent Skills standard
+  documents. No `@`. `/` invocation is an Antigravity-only bonus, it is
+  NOT part of the neutral standard, so under the `agent-skills` lens only
+  references form.
+
+Why references and not slash on the open standard: the Agent Skills
+spec (agentskills.io) activates a skill by its `description` and
+connects files by relative markdown links; it has no `/`-invocation
+syntax. claude/codex add `/` and `@` as vendor features on top.
+
+**Decision logic, applied silently at pre-flight:**
+
+1. The provider is the lens the scaffold set up. Check the vendor markers
+   FIRST (they ride on top of the shared `.agents/skills/` skill home), then
+   the skill home itself:
+   - a `.codex/` dir present (the marker `sm tutorial --for codex` drops) →
+     `provider = codex`, `track = rich`.
+   - else a `.agent/workflows/` dir present → `provider = antigravity`,
+     `track = basic`.
+   - else skill under `.claude/skills/sm-tutorial/` → `provider = claude`,
+     `<provider_dir> = .claude`, `track = rich`.
+   - else skill under `.agents/skills/sm-tutorial/` → `provider = agent-skills`,
+     `<provider_dir> = .agents/skills`, `track = basic`.
+   **Lens ambiguity for codex / antigravity**: both adopt the open
+   `.agents/skills/` layout, so their own marker (`.codex/` or
+   `.agent/workflows/`) coexists with the `agent-skills` marker (`.agents/`)
+   and a plain `sm scan --yes` reports the lens as ambiguous. For those two,
+   set it explicitly once before the first scan, `sm config set
+   activeProvider <codex|antigravity> --yes`, then the book runs unchanged
+   (the fixture engine renders the right shape: codex its TOML agents +
+   command-as-skill, antigravity reuses the `agent-skills` overlays).
+2. `state.js init --provider <p>` persists `provider` plus the derived
+   `track`, so a resumed session never re-detects.
+3. Render only the parts whose `track` is `tutorial.track` (or `both`).
+   Never offer a rich-only part under the basic track, or vice versa.
 
 **Global substitution rule**: the fixture scripts do the file-level
 work. You pass `--provider <p>` (the value persisted in
 `tutorial.provider`) and `--lang <l>`, and they resolve the
-`__PROVIDER__` path token, skip files whose kind the provider does
-not claim, and report the adjusted `nodeCount` plus the `skipped`
-list in their summary. Today `provider` is always `claude`, so the
-narration uses `.claude/` throughout; the `--provider` plumbing stays
-wired so the coming-soon providers (`agent-skills` / Antigravity,
-`codex`) drop in later without a narrative rewrite. The campaign
-cross-link chapters target `claude` today (see the reality check
-below).
-
-**Reality check (don't mention to the tester)**: this skill ships
-at `.claude/skills/sm-tutorial/`, so Claude Code is the only host
-today. The detection wiring is here so mirrored skills at
-`.agents/skills/sm-tutorial/` reuse it as-is.
+`__PROVIDER__` path token, skip files whose kind the provider does not
+claim, lay any per-provider skill overlay (the open standard renders an
+agent/command as a `skill`), and report the adjusted `nodeCount` plus
+the `skipped` list. Narrate with `<provider_dir>` resolved to the value
+above, never a hard-coded `.claude/`.
+
+**Reality check (don't mention to the tester)**: the source skill ships
+at `.claude/skills/sm-tutorial/` (this repo is itself a Claude project);
+`sm tutorial` materializes it under `.claude/skills/` (rich) or
+`.agents/skills/` (basic). Both are real, walkable books.
+
+### Rendering the rich book on Codex
+
+The rich track has two lenses, `claude` and `codex`. They teach the SAME
+lessons with the SAME connectors (`/` invocations, `@` mentions, markdown
+references all resolve on both), so the rich part bodies are written in the
+`claude` shape; when `tutorial.provider == codex`, apply these substitutions:
+
+- **Agents are TOML.** A Codex agent is a single `.codex/agents/<name>.toml`
+  file (the prompt lives in its `developer_instructions` field), NOT a
+  `.claude/agents/<name>.md`. The fixtures lay them, so when a chapter says
+  "open the agent file" point at the `.toml`; a chapter that has the tester
+  read or tweak an agent works on the TOML frontmatter / `developer_instructions`.
+- **No `command` kind.** Where the claude book authors a `command` (the
+  `/publish` command, the reserved-name chapter's `init` command), Codex uses a
+  **skill** at `.agents/skills/<name>/SKILL.md`. The body is identical (same
+  `/check-links` + `@content-editor` + deploy reference); only the kind and path
+  change. `cat <set> --file … --provider codex` already returns the Codex skill
+  body, so the create-the-file block stays a copy-paste. The reserved-name beat
+  uses a skill named with a reserved verb (Codex inherits the open-standard
+  `COMMONS_RESERVED_NAMES`, e.g. `config`), exactly like the basic track's
+  `reserved` chapter, on a skill instead of a command.
+- **Skills** live under `.agents/skills/<name>/SKILL.md` (the open layout Codex
+  adopted), same as the basic family.
+- Everything else (the `@`/`/` syntax, the confidence numbers, the hub, the
+  broken-reference contrast) is identical to claude; the graph topology matches.
 
 ## Per-step cycle (inside a chapter)
 
@@ -357,10 +406,14 @@ For every chapter:
   parts with a `✓` in their description line, not on the title (see
   §Menu format).
 - **Which parts to list**: parts in `order`, `status: active` only
-  (`planned` parts are hidden). A part with a `seed` (the campaign
-  parts plus `cli`) is always shown, even out of order, its
-  `preflight: seed` fast-forwards the project into it (SKILL.md
-  §Entering a part). A part with a `prereq` but NO `seed` would be
+  (`planned` parts are hidden), AND **matching the active track**, a
+  part whose `track` is `tutorial.track` (`rich` or `basic`) or `both`.
+  The rich and basic campaigns share titles and `order`, so the track
+  filter is what keeps the menu showing exactly ONE book, never both;
+  list a part once, by the track the session resolved at pre-flight.
+  A part with a `seed` (the campaign parts plus `cli`) is always shown,
+  even out of order, its `preflight: seed` fast-forwards the project
+  into it (SKILL.md §Entering a part). A part with a `prereq` but NO `seed` would be
   shown only once its `prereq` is `done`; no active part is in that
   state today (`cli` used to be, now it self-seeds).
 - **After the tester picks**: walk that part; when it ends, run