@skill-map/cli 0.67.0 → 0.68.1

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

package/dist/cli/tutorial/sm-tutorial/scripts/lib/paths.js

@@ -7,14 +7,22 @@
 export const PROVIDER_TOKEN = '__PROVIDER__';
 
 export function providerDir(provider) {
-  // agent-skills and Antigravity share the open `.agents/skills/` layout.
-  return provider === 'agent-skills' || provider === 'antigravity'
+  // agent-skills, Antigravity and Codex all keep their SKILLS under the
+  // open `.agents/skills/` layout. (Codex additionally has TOML agents under
+  // `.codex/agents/`, supplied by the codex overlay's literal paths, not this
+  // single base dir.)
+  return provider === 'agent-skills' || provider === 'antigravity' || provider === 'codex'
     ? '.agents/skills'
     : '.claude';
 }
 
 export const PROVIDER_KINDS = {
   claude: new Set(['agent', 'command', 'skill', 'markdown']),
+  // Codex authors its agents as TOML under `.codex/agents/` (a different shape
+  // than the base `__PROVIDER__/agents/*.md`), so the base tier lays only its
+  // shared skill + markdown nodes; the codex overlay supplies the TOML agents
+  // and the command-as-skill nodes (Codex has no `command` kind).
+  codex: new Set(['skill', 'markdown']),
   'agent-skills': new Set(['skill', 'markdown']),
   antigravity: new Set(['skill', 'markdown']),
 };
@@ -23,6 +31,44 @@ export function kindsFor(provider) {
   return PROVIDER_KINDS[provider] ?? PROVIDER_KINDS.claude;
 }
 
+/**
+ * Tutorial track for a provider, by the "does this lens have an `agent`
+ * kind?" axis (see `_core.md` §Provider detection):
+ *   - `rich`  (agent + skill + slash + `@`): `claude`, `codex`.
+ *   - `basic` (skill + markdown, connected by markdown references): the
+ *     open-standard family `agent-skills`, `antigravity`.
+ * The book renders the track's parts; the same lens always resolves to
+ * the same track, so a resumed session never re-derives it.
+ */
+export function trackFor(provider) {
+  return provider === 'claude' || provider === 'codex' ? 'rich' : 'basic';
+}
+
+/**
+ * The provider whose fixture overlays a given provider reuses. The
+ * open-standard family (`agent-skills`, `antigravity`) shares one on-disk
+ * shape (`.agents/skills/`, skill + markdown, connected by markdown
+ * references), so `antigravity` reuses the canonical `agent-skills`
+ * overlays rather than duplicating them. Every other provider keys its own.
+ */
+export function overlayKey(provider) {
+  return provider === 'antigravity' ? 'agent-skills' : provider;
+}
+
+/**
+ * Kinds whose edit fragments (the todo-connectors hub bullets, etc.) apply for
+ * a provider, keyed by TRACK, not by the base-tier kinds. A rich provider links
+ * to every node role even when it renders some differently, Codex's agent is a
+ * TOML overlay and its command-node is a skill, but an `@agent` mention and a
+ * `/command` invocation still resolve, so every bullet applies. A basic
+ * provider only has skill + markdown, so the agent / command bullets fold away.
+ */
+export function fragmentKindsFor(provider) {
+  return trackFor(provider) === 'rich'
+    ? new Set(['agent', 'command', 'skill', 'markdown'])
+    : new Set(['skill', 'markdown']);
+}
+
 /**
  * Per-provider kind directories. The token path is always written in
  * the claude shape (`__PROVIDER__/skills/<name>/...`); resolving it is
@@ -31,6 +77,7 @@ export function kindsFor(provider) {
  */
 const KIND_DIRS = {
   claude: { agents: '.claude/agents', commands: '.claude/commands', skills: '.claude/skills' },
+  codex: { skills: '.agents/skills' },
   'agent-skills': { skills: '.agents/skills' },
   antigravity: { skills: '.agents/skills' },
 };
@@ -64,5 +111,28 @@ export function kindForPath(tokenRelPath) {
   if (tokenRelPath.startsWith(`${PROVIDER_TOKEN}/skills/`)) return 'skill';
   return 'markdown';
 }
-!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]="af99c74c-ee9a-5bf3-8daf-f0b9320a3e61")}catch(e){}}();
-//# debugId=af99c74c-ee9a-5bf3-8daf-f0b9320a3e61
+
+/**
+ * Logical, lens-agnostic node id for a token-form path. The SAME
+ * conceptual node renders in a different kind per lens (a `content-editor`
+ * is an `agent` on claude but a `skill` on agent-skills), so a `--only`
+ * filter or an edit target written in the claude shape must still match
+ * the agent-skills overlay. Agents / commands use the file stem; skills
+ * use the skill directory name; everything else (markdown, notes, docs)
+ * keeps its relpath verbatim. So both `__PROVIDER__/agents/content-editor.md`
+ * and `__PROVIDER__/skills/content-editor/SKILL.md` resolve to `content-editor`.
+ */
+export function nodeIdForTokenPath(tokenRelPath) {
+  const flat = tokenRelPath.match(/^__PROVIDER__\/(?:agents|commands)\/(.+)\.md$/);
+  if (flat) return flat[1];
+  const skill = tokenRelPath.match(/^__PROVIDER__\/skills\/([^/]+)\//);
+  if (skill) return skill[1];
+  // Codex renders an agent as a literal `.codex/agents/<name>.toml`; map it
+  // to the same id as the claude-shaped `__PROVIDER__/agents/<name>.md` so a
+  // `--only` filter (or the skipped-node dedup) matches across the two shapes.
+  const codexAgent = tokenRelPath.match(/^\.codex\/agents\/(.+)\.toml$/);
+  if (codexAgent) return codexAgent[1];
+  return tokenRelPath;
+}
+!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]="9a867c5a-0c61-500e-a583-7d7dd6c5ac92")}catch(e){}}();
+//# debugId=9a867c5a-0c61-500e-a583-7d7dd6c5ac92

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

@@ -31,7 +31,7 @@ import { rmSync, rmdirSync, readdirSync } from 'node:fs';
 import { parseArgs } from './lib/args.js';
 import { exists, readJson, writeJson, succeed, die } from './lib/io.js';
 import { loadManifest, findPart } from './lib/manifest.js';
-import { providerDir } from './lib/paths.js';
+import { providerDir, trackFor } from './lib/paths.js';
 import { loadFixturesManifest, resolveFootprint } from './lib/fixtures-manifest.js';
 
 const STATE_FILE = 'tutorial-state.json';
@@ -68,13 +68,18 @@ const VERBS = {
     if (exists(p) && !args.flags.force) {
       die('exists', `${STATE_FILE} already exists; pass --force to overwrite.`);
     }
+    const provider = args.flags.provider ?? 'claude';
     const state = {
       tutorial: {
         version: STATE_VERSION,
         started_at: now(),
         cwd: args.flags.cwd ?? process.cwd(),
         sm_version: args.flags['sm-version'] ?? null,
-        provider: args.flags.provider ?? 'claude',
+        provider,
+        // Derived from the provider (`_core.md` §Provider detection): the
+        // book renders this track's parts. `rich` = claude/codex,
+        // `basic` = the open-standard family (agent-skills/antigravity).
+        track: trackFor(provider),
         lang: args.flags.lang ?? 'en',
       },
       tester: { level: 2 },
@@ -148,8 +153,13 @@ const VERBS = {
   status() {
     const state = loadState();
     const manifest = loadManifest();
+    // Show only the active track's parts (plus `both`). The rich and basic
+    // campaigns share titles and order, so a session sees exactly one book,
+    // the track resolved at pre-flight (see `_core.md` §Routing + menu).
+    const track = state.tutorial?.track ?? 'rich';
     const parts = manifest.parts
       .filter((p) => p.status === 'active' || state.parts[p.id])
+      .filter((p) => !p.track || p.track === 'both' || p.track === track)
       .map((p) => {
         const tracked = state.parts[p.id];
         return {
@@ -221,8 +231,14 @@ function computeWipePaths(state) {
   const paths = new Set(['tutorial-state.json', 'findings.md', '.skillmapignore', '.skill-map']);
   const addFootprint = (name) => resolveFootprint(manifest, name, provider).forEach((p) => paths.add(p));
 
-  if (has('fundamentals')) addFootprint('prologue');
-  if (has('project-kickoff') || has('connect-harness') || has('daily-loop')) addFootprint('portfolio');
+  // Each footprint covers both tracks: the rich and basic prologues /
+  // campaigns lay the same fixtures (the basic one under the open-standard
+  // provider), so either part's presence means that fixture is on disk.
+  if (has('fundamentals') || has('basic-fundamentals')) addFootprint('prologue');
+  if (
+    has('project-kickoff') || has('daily-loop')
+    || has('basic-kickoff') || has('basic-daily')
+  ) addFootprint('portfolio');
   if (has('extend')) addFootprint('master');
   // `cli` seeds the prologue demo fixture plus its external-ref demo.
   if (has('cli')) { addFootprint('prologue'); addFootprint('cli-external'); }
@@ -258,5 +274,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]="547a8c8d-f962-571c-ae72-8edbb1fc756c")}catch(e){}}();
-//# debugId=547a8c8d-f962-571c-ae72-8edbb1fc756c
+!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]="3ef90c0e-0700-5a7b-a25f-c47aa19fd567")}catch(e){}}();
+//# debugId=3ef90c0e-0700-5a7b-a25f-c47aa19fd567