@radicool/throughline 0.12.0

package/references/scaling-up-handoff.md

@@ -0,0 +1,61 @@
+# Scaling up: when a step outgrows a single skill
+
+ThroughLine skills are built for **bounded design-system work** — author tokens,
+build a component, scaffold a repo. Sometimes a step inflates into **open-ended
+engineering** with real architectural risk: retrofitting an existing app onto a
+new component library (e.g. → shadcn), migrating a whole motion/interaction layer,
+a multi-package refactor — anything where "build the component" has quietly become
+"re-architect the system." When that happens, **do not just start building.**
+
+The valuable behavior here is **recognizing the inflection and planning before
+building** — that behavior is ThroughLine's, and it works whether or not any other
+plugin is installed. Handing off to a planning partner (below) is an *enhancement*
+of that behavior, never a requirement for it.
+
+## Recognize the inflection
+
+Signs the work has outgrown the skill:
+
+- The user wants to **retrofit or migrate an existing codebase**, not start clean.
+- The change touches **many files / packages / systems at once**.
+- There are **real risks** to name — breaking existing behavior, a custom layer to
+  preserve (e.g. bespoke cursors, magnetic buttons, a motion system), a framework
+  migration, design↔code drift.
+- The honest answer to "can this be done in a few well-understood steps?" is no.
+
+## What to do at the inflection (the portable behavior)
+
+1. **Stop and surface the shape.** Lay out the **risks** and the **major parts** of
+   the work before touching code. Make the scope visible to the user.
+2. **Confirm the scope.** "This is now a real project — do you want to take on all
+   of it, or a slice first?" Let the user choose the bite size.
+3. **Switch into structured brainstorm → plan before building.** Big, ambiguous
+   work needs a plan, not improvisation.
+
+## Where the plan comes from (degrade gracefully — no hard dependency)
+
+- **If the Superpowers skills are available** — check the available-skills list for
+  `superpowers:brainstorming` and `superpowers:writing-plans` — **hand off to
+  them.** They are purpose-built for open-ended engineering: brainstorm the
+  approach, then write an executable plan. Announce the handoff so the user
+  understands the switch and why.
+- **If Superpowers is not installed** — do **not** stall and do **not** require it.
+  Run ThroughLine's own `brainstorm-before-build.md` protocol, scaled to the larger
+  scope, and produce a written plan (goals, risks, major parts, ordered steps,
+  checkpoints) before building. You may note **once** that Superpowers is a great
+  optional partner for this kind of work — then proceed. Never nag, never block.
+
+ThroughLine must be able to complete the work **with or without** Superpowers.
+Superpowers makes the big-scope path better; it is never a prerequisite.
+
+## The routing rule (keep both directions consistent)
+
+This is one rule with two directions — getting one right but not the other is how
+the wrong skill ends up driving:
+
+- **Bounded design-system work** (tokens, icons, a single component, repo scaffold)
+  → ThroughLine owns it directly. Do **not** hand a simple setup prompt off to a
+  generic brainstorming skill — that is the inverse mistake (see the priority note
+  in `figma-environment-setup`).
+- **Open-ended engineering** (retrofits, migrations, app builds) → brainstorm and
+  plan first; hand off to Superpowers if present, else plan natively.

package/references/sync-adapters.md

@@ -0,0 +1,141 @@
+# Token sync adapters
+
+An **adapter** is a coherent preset that turns the normalized DTCG token JSON
+into framework-specific output. Each adapter bundles **four conventions** that
+always travel together — getting them as a unit is what prevents incoherent
+combinations (e.g. "preserve references" + "iOS Swift", which is impossible
+because Swift constants can't do runtime indirection):
+
+1. **Where values live** — CSS vars + Tailwind preset, a JS theme object, a
+   Swift enum/asset catalog, etc.
+2. **How modes are expressed** — `:root` + `.dark` selectors, MUI palette
+   objects, asset-catalog light/dark variants, resource qualifiers.
+3. **Whether semantic→primitive references are preserved or flattened** — web
+   adapters preserve (runtime themeable via CSS var indirection); native
+   adapters flatten (compile-time constants).
+4. **Naming convention** — `--background` (shadcn), `palette.primary.main`
+   (MUI), `Color.backgroundPrimary` (Swift), etc.
+
+The DTCG JSON is the **universal input**; the adapter is the **universal output
+contract**. Adding a platform = adding an adapter, never re-authoring Figma.
+
+## The two tiers: curated and generated
+
+Adapters come in two tiers, and **the skill always tells the user which tier
+they're on** — this manages expectations honestly.
+
+### Tier 1 — curated adapters (vetted presets)
+
+Five built-in adapters ship with framework-specific knowledge baked in. When the
+user names one of these, use the vetted preset — high confidence, no guessing.
+
+| Adapter | Values live in | Modes via | Sem→prim refs | Naming |
+|---|---|---|---|---|
+| `shadcn` | CSS vars + tailwind preset | `:root` + `.dark` | preserved | `--background` |
+| `tailwind` | tailwind theme config | `dark:` variant / class strategy | preserved (via CSS vars) | `colors.background` |
+| `mui` | JS theme object | `createTheme` palettes | preserved (object refs) | `palette.primary.main` |
+| `vanilla-css` | one CSS file | `:root` + `[data-theme]` | preserved | `--color-bg-default` |
+| `ios-swift` | Swift enum / asset catalog | light/dark asset variants | flattened | `Color.backgroundPrimary` |
+
+These five were chosen for coverage of this plugin's web-first, design-led
+audience: three React framework adapters (shadcn — the dominant new-project
+choice; standalone Tailwind — for the large Tailwind-without-shadcn population;
+MUI — the enterprise/Material standard), the universal `vanilla-css` escape
+hatch (plain CSS custom properties, no framework), and one native slot
+(`ios-swift`, the more standardized native pattern). Everything else —
+Ant Design, Chakra, HeroUI, Android/Kotlin, Flutter, React Native, etc. — is
+fully supported via Tier 2.
+
+`shadcn` vs `tailwind`: shadcn emits CSS vars *plus* the specific var names
+shadcn components expect; `tailwind` targets Tailwind used on its own, mapping
+tokens into the Tailwind theme config. Related but distinct targets.
+
+### Tier 2 — generated adapters (any other framework)
+
+When the user names a framework **not** in the curated five, the skill does NOT
+refuse and does NOT pretend it's curated. It **generates an adapter** via a
+structured protocol:
+
+1. Tell the user plainly this is a generated (not curated) adapter: "Chakra
+   isn't one I have a vetted preset for — I'll generate one from its token
+   conventions, and we'll verify it against a real component before relying on
+   it."
+2. Establish the **four conventions** (the checklist above) for the target
+   framework — research its token/theme conventions and confirm with the user
+   via the brainstorm-before-build protocol.
+3. Draft the Style Dictionary config + any custom transforms/formats.
+4. **Validate before trusting**: generate output and check it against a sample
+   component in that framework — does the framework actually consume these
+   tokens cleanly? A generated adapter is unverified until this passes.
+
+### Saving validated generated adapters
+
+Once a generated adapter is validated, **save it to the repo** at
+`packages/tokens/adapters/<name>/` so future syncs reuse it instead of
+regenerating. Over time the user accumulates their own vetted adapters. Record
+saved custom adapters in the manifest (`sync.customAdapters`). (A validated
+adapter could also be contributed back to the curated set in a future plugin
+version, but that's not required.)
+
+## How an adapter is implemented
+
+Each adapter is a **Style Dictionary v4 config preset** plus any custom
+transforms/formats it needs. Style Dictionary v4 ingests DTCG natively, so most
+of the work is: register the platform, set the transform group, set the format,
+and (for web adapters) configure `outputReferences: true` so semantic tokens
+emit as references to primitive vars rather than flattened literals.
+
+- **Web adapters** (`shadcn`, `tailwind`, `mui`, `vanilla-css`): set
+  `outputReferences: true` so `--color-bg-default: var(--color-gray-50)` is
+  emitted, preserving the cascade. Modes map to selectors per axis: theme
+  overrides (from `Color/Semantic`) under `.dark` / `[data-theme="..."]`, and
+  **brand overrides (from the multi-mode `_Color/Primitive`)** under a
+  `[data-brand="..."]` selector. Single-mode collections emit flat values in
+  `:root` with no theme selector. The
+  `shadcn` adapter additionally emits a Tailwind preset mapping the CSS vars to
+  Tailwind tokens; the standalone `tailwind` adapter maps tokens into the
+  Tailwind theme config directly; `mui` emits a JS theme object whose palette
+  references preserve the cascade through object structure.
+- **Native adapters** (`ios-swift`, and generated native targets like
+  Android/Kotlin): `outputReferences: false` — references resolve to literal
+  values at build time, because the target language has no runtime var
+  indirection. Modes map to the platform's native mechanism (asset catalog
+  variants, resource qualifiers).
+
+## Brownfield value transforms
+
+On a retrofit, the values flowing into the adapters get three extra transforms (the
+opacity 0–100→0–1 normalization happens earlier, at extraction). These affect what the
+web adapters emit; native adapters resolve to literals so the channel/`color-mix` forms
+apply to web targets. Full rationale: the 7 guardrails in
+`${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md`.
+
+- **Channel alpha (web).** Color tokens emit as space-separated channels
+  (`--color-bg-default: 239 68 68;`) consumed via
+  `rgb(var(--color-bg-default) / <alpha-value>)`, so Tailwind's `/opacity` modifiers
+  keep working. A finished `rgba(...)` would break them.
+- **`/opacity` → `color-mix` (web).** A `/opacity` modifier on a var-based token can't
+  fold its alpha into the var; emit `color-mix(in srgb, var(--token) NN%, transparent)`
+  instead (or the channel-alpha form).
+- **Float32 rounding at the export boundary.** Round values as they leave the pipeline
+  (`Math.round(v*100)/100`) — normalizing inside Figma is a no-op because Figma
+  re-quantizes to float32 on store.
+
+These are applied in `token-sync-layer`'s extraction/transform step (its "Brownfield
+transforms" subsection), not in the adapter presets.
+
+## Output location
+
+All adapter output lands in `packages/tokens/` in the monorepo, organized by
+platform (e.g. `packages/tokens/css/`, `packages/tokens/swift/`). These are
+**build artifacts** — never hand-edited, regenerated every sync. The
+`packages/tokens/package.json` exports them for consumers (the UI package,
+Storybook, a future app).
+
+## Multiple platforms at once
+
+A user can target several platforms (recorded in `sync.platforms`). Generating
+each platform's output is independent and verifiable, which makes it a good fit
+for **parallel subagent generation** — one subagent per adapter, each producing
+and validating its platform's files, reviewed before the combined result is
+landed in a PR. See the token-sync skill for the execution model.

package/scripts/README.md

@@ -0,0 +1,78 @@
+# ThroughLine scripts
+
+The executable analog of `references/`: canonical, vetted, **zero-dependency** Node
+(ESM) scripts that the brownfield skills install into a user's monorepo. Authored and
+tested here; copied verbatim by `token-crosswalk-builder` into the user's
+`packages/tokens/scripts/`.
+
+| Script | Purpose | Installed as |
+| --- | --- | --- |
+| `validate-crosswalk.mjs` | Resolve every `newToken` against the DTCG token source; assert resolved value == `newValue`, N/N. The CI gate. | `tokens:validate` |
+| `build-reverse-index.mjs` | Emit a `codeToken -> newToken` map from the crosswalk to semi-automate SCSS/Tailwind swaps. | `tokens:reverse-index` |
+| `guard-token-removal.mjs` | Grep `.ts/.tsx` (minus generated + tests) for about-to-be-deleted symbols; blocks cleanup until zero references remain. | run during the cleanup phase |
+| `lib/crosswalk.mjs` | Shared loader + structural validation for `crosswalk.json` (used by the validator and reverse-index). | copied alongside |
+| `crosswalk.schema.json` | The finalized JSON Schema for `crosswalk.json` (contract + editor support). | copied beside `crosswalk.json` |
+
+The crosswalk contract is documented in
+`${CLAUDE_PLUGIN_ROOT}/references/crosswalk-schema.md`.
+
+## Usage
+
+```bash
+node validate-crosswalk.mjs --crosswalk crosswalk.json --tokens dtcg/tokens.json
+node build-reverse-index.mjs --crosswalk crosswalk.json --out crosswalk.reverse.json
+node guard-token-removal.mjs --root . --symbols symbols-to-remove.txt
+```
+
+Exit codes: `0` success, `1` validation/guard failure (mismatch, missing token,
+conflict, or remaining reference), `2` bad CLI arguments.
+
+## How the skill installs these
+
+`token-crosswalk-builder` copies `lib/crosswalk.mjs`, `validate-crosswalk.mjs`,
+`build-reverse-index.mjs`, `guard-token-removal.mjs`, and `crosswalk.schema.json`
+into the user's `packages/tokens/scripts/` (schema beside `crosswalk.json`), then
+wires `packages/tokens/package.json`:
+
+```jsonc
+"scripts": {
+  "tokens:validate": "node scripts/validate-crosswalk.mjs --crosswalk crosswalk.json --tokens dtcg/tokens.json",
+  "tokens:reverse-index": "node scripts/build-reverse-index.mjs --crosswalk crosswalk.json --out crosswalk.reverse.json"
+}
+```
+
+The scripts version with the user's repo so their CI runs them locally — a path
+inside the plugin install would not be reachable from the user's CI.
+
+## Tests
+
+Run the suite from the repo root (no install step — uses only Node built-ins):
+
+```bash
+node --test
+```
+
+This auto-discovers every `**/*.test.mjs` recursively (31 tests). Don't use
+`node --test scripts/` — a directory positional is treated as a test name on
+Node >=21 and errors; a `scripts/*.test.mjs` glob silently skips `scripts/lib/`.
+
+## Multi-agent adapters (`scripts/adapters/`)
+
+`SKILL.md`/`commands`/`.mcp.json` are the canonical source. Generated Cursor,
+Codex, and generic-AGENTS.md adapters live in `adapters/<target>/` and are
+committed. After editing any skill or command, regenerate:
+
+    node scripts/adapters/generate.mjs
+
+CI runs `node scripts/adapters/generate.mjs --check` and fails if the committed
+`adapters/` tree is stale. Never hand-edit files under `adapters/` — edit the
+source and regenerate.
+
+Users install a target into their own project with the installer, which copies
+the committed `adapters/<target>/` tree plus the runtime payload
+(`references/` + `scripts/`, minus `scripts/adapters/`) into `.throughline/`,
+rewriting `${CLAUDE_PLUGIN_ROOT}` → `.throughline`:
+
+    npx @radicool/throughline init --target=cursor|codex|generic
+
+See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).

package/scripts/adapters/emit-codex.mjs

@@ -0,0 +1,58 @@
+import { translateBody, firstSentence, applyPhrasing } from './translate.mjs';
+
+const BASE = '.throughline';
+
+function tomlValue(v) {
+  if (Array.isArray(v)) return `[${v.map((x) => JSON.stringify(x)).join(', ')}]`;
+  if (v && typeof v === 'object') {
+    return `{ ${Object.entries(v).map(([k, x]) => `${k} = ${JSON.stringify(x)}`).join(', ')} }`;
+  }
+  return JSON.stringify(v);
+}
+
+function mcpToToml(mcp) {
+  const servers = mcp.mcpServers || {};
+  const blocks = [];
+  for (const [name, cfg] of Object.entries(servers)) {
+    const lines = [`[mcp_servers.${name}]`];
+    for (const [k, v] of Object.entries(cfg)) lines.push(`${k} = ${tomlValue(v)}`);
+    blocks.push(lines.join('\n'));
+  }
+  return `${blocks.join('\n\n')}\n`;
+}
+
+function indexSection(title, items, note) {
+  const lines = [`## ${title}`, ''];
+  if (note) { lines.push(note, ''); }
+  for (const it of items) {
+    lines.push(`- \`${it.name}\` — ${applyPhrasing(firstSentence(it.description), 'codex')} → load \`prompts/${it.name}.md\`.`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function emitCodex(model) {
+  const files = [];
+  const agents = [
+    '# ThroughLine (Codex adapter)',
+    '',
+    'ThroughLine builds a design system end to end. Load the matching prompt for the task at hand.',
+    '',
+    indexSection('ThroughLine skills', model.skills),
+    indexSection('ThroughLine commands', model.commands),
+    '## MCP servers',
+    '',
+    'Figma access is provided by the `figma-console` MCP server. See `codex-mcp.toml` for the config to add to your Codex `mcp_servers`.',
+    '',
+  ].join('\n');
+  files.push({ path: 'AGENTS.md', content: agents });
+
+  for (const skill of model.skills) {
+    files.push({ path: `prompts/${skill.name}.md`, content: `${translateBody(skill.body, { baseDir: BASE, target: 'codex' })}\n` });
+  }
+  for (const cmd of model.commands) {
+    files.push({ path: `prompts/${cmd.name}.md`, content: `${translateBody(cmd.body, { baseDir: BASE, target: 'codex' })}\n` });
+  }
+  files.push({ path: 'codex-mcp.toml', content: mcpToToml(model.mcp) });
+  return files;
+}

package/scripts/adapters/emit-cursor.mjs

@@ -0,0 +1,26 @@
+import { translateBody, applyPhrasing } from './translate.mjs';
+
+const BASE = '.throughline';
+
+function oneLine(s) {
+  return s.replace(/\s+/g, ' ').trim();
+}
+
+function yamlString(s) {
+  return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+export function emitCursor(model) {
+  const files = [];
+  for (const skill of model.skills) {
+    const body = translateBody(skill.body, { baseDir: BASE, target: 'cursor' });
+    const content = `---\ndescription: ${yamlString(applyPhrasing(oneLine(skill.description), 'cursor'))}\nalwaysApply: false\n---\n${body}\n`;
+    files.push({ path: `.cursor/rules/${skill.name}.mdc`, content });
+  }
+  for (const cmd of model.commands) {
+    const body = translateBody(cmd.body, { baseDir: BASE, target: 'cursor' });
+    files.push({ path: `.cursor/commands/${cmd.name}.md`, content: `${body}\n` });
+  }
+  files.push({ path: '.cursor/mcp.json', content: `${JSON.stringify(model.mcp, null, 2)}\n` });
+  return files;
+}

package/scripts/adapters/emit-generic.mjs

@@ -0,0 +1,41 @@
+import { translateBody, firstSentence, applyPhrasing } from './translate.mjs';
+
+const BASE = '.throughline';
+
+function indexSection(title, items, ext) {
+  const lines = [`## ${title}`, ''];
+  for (const it of items) {
+    lines.push(`- \`${it.name}\` — ${applyPhrasing(firstSentence(it.description), 'generic')} → read \`${ext(it.name)}\`.`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function emitGeneric(model) {
+  const files = [];
+  const agents = [
+    '# ThroughLine (generic AGENTS.md adapter)',
+    '',
+    'ThroughLine builds a design system end to end. Read the matching skill file for the task at hand.',
+    '',
+    indexSection('ThroughLine skills', model.skills, (n) => `skills/${n}/SKILL.md`),
+    indexSection('ThroughLine commands', model.commands, (n) => `commands/${n}.md`),
+    '## MCP servers',
+    '',
+    'Add the following MCP server to your agent (Figma access):',
+    '',
+    '```json',
+    JSON.stringify(model.mcp, null, 2),
+    '```',
+    '',
+  ].join('\n');
+  files.push({ path: 'AGENTS.md', content: agents });
+
+  for (const skill of model.skills) {
+    files.push({ path: `skills/${skill.name}/SKILL.md`, content: `${translateBody(skill.body, { baseDir: BASE, target: 'generic' })}\n` });
+  }
+  for (const cmd of model.commands) {
+    files.push({ path: `commands/${cmd.name}.md`, content: `${translateBody(cmd.body, { baseDir: BASE, target: 'generic' })}\n` });
+  }
+  return files;
+}

package/scripts/adapters/generate.mjs

@@ -0,0 +1,73 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readSources } from './read-sources.mjs';
+import { emitCursor } from './emit-cursor.mjs';
+import { emitCodex } from './emit-codex.mjs';
+import { emitGeneric } from './emit-generic.mjs';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const OUT_ROOT = join(REPO_ROOT, 'adapters');
+
+export function generate(model) {
+  return { cursor: emitCursor(model), codex: emitCodex(model), generic: emitGeneric(model) };
+}
+
+export function writeTargets(outRoot, result) {
+  for (const [target, files] of Object.entries(result)) {
+    for (const file of files) {
+      const abs = join(outRoot, target, file.path);
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, file.content);
+    }
+  }
+}
+
+function walkFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === '.DS_Store') continue;
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkFiles(abs));
+    else out.push(abs);
+  }
+  return out;
+}
+
+// Returns a list of drift descriptions ([] === in sync) comparing result to disk.
+export function diffTargets(outRoot, result) {
+  const problems = [];
+  const expected = new Set();
+  for (const [target, files] of Object.entries(result)) {
+    for (const file of files) {
+      const abs = join(outRoot, target, file.path);
+      expected.add(abs);
+      if (!existsSync(abs)) { problems.push(`missing: ${target}/${file.path}`); continue; }
+      if (readFileSync(abs, 'utf8') !== file.content) problems.push(`changed: ${target}/${file.path}`);
+    }
+  }
+  for (const target of Object.keys(result)) {
+    for (const abs of walkFiles(join(outRoot, target))) {
+      if (!expected.has(abs)) problems.push(`orphan: ${abs.slice(outRoot.length + 1)}`);
+    }
+  }
+  return problems;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const result = generate(readSources(REPO_ROOT));
+  if (process.argv.includes('--check')) {
+    const problems = diffTargets(OUT_ROOT, result);
+    if (problems.length) {
+      console.error(`✗ adapters out of date (${problems.length}); run: node scripts/adapters/generate.mjs`);
+      for (const p of problems) console.error(`  ${p}`);
+      process.exit(1);
+    }
+    console.log('✓ adapters in sync');
+  } else {
+    writeTargets(OUT_ROOT, result);
+    const n = Object.values(result).reduce((a, f) => a + f.length, 0);
+    console.log(`✓ wrote ${n} adapter files to adapters/`);
+  }
+}

package/scripts/adapters/read-sources.mjs

@@ -0,0 +1,54 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+export function parseFrontmatter(text) {
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+  if (!m) return { attrs: {}, body: text };
+  const attrs = {};
+  for (const line of m[1].split('\n')) {
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    let v = kv[2].trim();
+    if (v.length >= 2 && v[0] === '"' && v[v.length - 1] === '"') v = v.slice(1, -1);
+    attrs[kv[1]] = v;
+  }
+  const body = text.slice(m[0].length).replace(/^\n+/, '');
+  return { attrs, body };
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function readSources(repoRoot) {
+  const plugin = readJson(join(repoRoot, '.claude-plugin', 'plugin.json'));
+  const mcp = readJson(join(repoRoot, '.mcp.json'));
+
+  const skillsDir = join(repoRoot, 'skills');
+  const skills = readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => {
+      const { attrs, body } = parseFrontmatter(readFileSync(join(skillsDir, d.name, 'SKILL.md'), 'utf8'));
+      return { name: attrs.name || d.name, description: attrs.description || '', body };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const cmdDir = join(repoRoot, 'commands');
+  const commands = readdirSync(cmdDir)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => {
+      const { attrs, body } = parseFrontmatter(readFileSync(join(cmdDir, f), 'utf8'));
+      return { name: f.replace(/\.md$/, ''), description: attrs.description || '', body };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  return { plugin, mcp, skills, commands };
+}
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const model = readSources(REPO_ROOT);
+  console.log(`skills: ${model.skills.length}, commands: ${model.commands.length}`);
+}

package/scripts/adapters/translate.mjs

@@ -0,0 +1,51 @@
+export function rewritePluginRoot(text, baseDir) {
+  return text.split('${CLAUDE_PLUGIN_ROOT}').join(baseDir);
+}
+
+// Small, reviewable substitution table. Only NAMED cross-skill references and a
+// few Claude-specific phrasings are rewritten; bare prose ("this skill") reads
+// fine on every target and is deliberately left alone.
+export const PHRASING_RULES = [
+  {
+    // "the `component-builder` skill" -> per-target noun
+    pattern: /the `([a-z][a-z-]*)` skill\b/g,
+    cursor: 'the `$1` rule',
+    codex: 'the `$1` prompt',
+    generic: 'the `$1` skill',
+  },
+  {
+    pattern: /\bthe plugin README\b/g,
+    cursor: 'the ThroughLine README',
+    codex: 'the ThroughLine README',
+    generic: 'the ThroughLine README',
+  },
+  {
+    pattern: /\bClaude Code\b/g,
+    cursor: 'Cursor',
+    codex: 'Codex',
+    generic: 'your coding agent',
+  },
+  {
+    pattern: /\bClaude\b/g,
+    cursor: 'Cursor',
+    codex: 'Codex',
+    generic: 'the agent',
+  },
+];
+
+export function applyPhrasing(text, target) {
+  let out = text;
+  for (const rule of PHRASING_RULES) {
+    out = out.replace(rule.pattern, rule[target]);
+  }
+  return out;
+}
+
+export function translateBody(text, { baseDir, target }) {
+  return applyPhrasing(rewritePluginRoot(text, baseDir), target);
+}
+
+export function firstSentence(text) {
+  const m = /^(.*?\.)(\s|$)/.exec(text.trim());
+  return (m ? m[1] : text).trim();
+}

package/scripts/build-reverse-index.mjs

@@ -0,0 +1,56 @@
+// Reverse-index generator: codeToken -> newToken, from crosswalk.json.
+// Semi-automates the SCSS/Tailwind swaps. Zero dependencies.
+//
+// Usage:
+//   node build-reverse-index.mjs --crosswalk crosswalk.json --out crosswalk.reverse.json
+import { writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { loadCrosswalk } from './lib/crosswalk.mjs';
+
+export function buildReverseIndex(crosswalk) {
+  const raw = {};
+  const conflicts = [];
+  for (const row of crosswalk.tokens) {
+    for (const code of row.codeTokens) {
+      if (code in raw && raw[code] !== row.newToken) {
+        conflicts.push({ codeToken: code, tokens: [raw[code], row.newToken] });
+      } else {
+        raw[code] = row.newToken;
+      }
+    }
+  }
+  // Sort keys longest-first so a literal find-and-replace can't clobber a longer
+  // symbol via a shorter substring (e.g. replace "$blue-100" before "$blue").
+  const index = {};
+  for (const key of Object.keys(raw).sort((a, b) => b.length - a.length || a.localeCompare(b))) {
+    index[key] = raw[key];
+  }
+  return { index, conflicts };
+}
+
+function main() {
+  const { values } = parseArgs({
+    options: {
+      crosswalk: { type: 'string' },
+      out: { type: 'string' },
+    },
+  });
+  if (!values.crosswalk || !values.out) {
+    console.error('usage: build-reverse-index.mjs --crosswalk <crosswalk.json> --out <reverse.json>');
+    process.exit(2);
+  }
+  const crosswalk = loadCrosswalk(values.crosswalk);
+  const { index, conflicts } = buildReverseIndex(crosswalk);
+  writeFileSync(values.out, JSON.stringify(index, null, 2) + '\n');
+  console.log(`reverse index: ${Object.keys(index).length} code symbol(s) -> ${values.out}`);
+  if (conflicts.length) {
+    console.error(`\n${conflicts.length} conflict(s) — one code symbol maps to multiple new tokens:`);
+    for (const c of conflicts) console.error(`  - ${c.codeToken}: ${c.tokens.join(' vs ')}`);
+    process.exit(1);
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}