@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/api/upgrade/upgrade.type.mjs

@@ -4,17 +4,17 @@
  * @file Colocated types for the `upgrade` command — source of truth for the
  * upgrade command JSON responses. Re-exported by `types/upgrade.d.ts`.
  *
- * Invocation                                 -> type discriminator
+ * Invocation                                   -> type discriminator
  * ------------------------------------------------------------------
- * xds --json upgrade --list                 -> upgrade.list
- * xds --json upgrade [--apply]              -> upgrade.run
- * xds --json upgrade --registry [--apply]   -> upgrade.registry
- * xds --json upgrade (status short-circuit) -> upgrade.status
- * (version detection failure)               -> CLIError
+ * astryx --json upgrade --list                 -> upgrade.list
+ * astryx --json upgrade [--apply]              -> upgrade.run
+ * astryx --json upgrade --registry [--apply]   -> upgrade.registry
+ * astryx --json upgrade (status short-circuit) -> upgrade.status
+ * (version detection failure)                  -> CLIError
  */
 
 /**
- * xds --json upgrade --list
+ * astryx --json upgrade --list
  * @typedef {object} UpgradeListResponse
  * @property {'upgrade.list'} type
  * @property {UpgradeListEntry[]} data
@@ -88,14 +88,14 @@
  */
 
 /**
- * xds --json upgrade --registry [--apply]
+ * astryx --json upgrade --registry [--apply]
  * @typedef {object} UpgradeRegistryResponse
  * @property {'upgrade.registry'} type
  * @property {RegistryCompositionSummary} data
  */
 
 /**
- * xds --json upgrade [--apply]
+ * astryx --json upgrade [--apply]
  * @typedef {object} UpgradeRunResponse
  * @property {'upgrade.run'} type
  * @property {object} data
@@ -112,7 +112,7 @@
  */
 
 /**
- * xds --json upgrade — short-circuit status results.
+ * astryx --json upgrade — short-circuit status results.
  *
  * - `up_to_date`: `--from` is >= installed target and `--force` was not passed.
  * - `no_codemods`: no codemods (core or integration) apply to the range.
@@ -135,7 +135,7 @@
  * @property {boolean} [force] Run codemods even if `from` >= installed.
  * @property {string} [codemod] Run a single named transform.
  * @property {string[]} [skipCodemod] Exclude named codemods (re-run past a failure).
- * @property {string[]} [integration] Explicit integration package names / file paths.
+ * @property {string[]} [integration] Explicit integration specifiers resolved beneath node_modules; absolute paths and `.` or `..` segments are rejected.
  * @property {string} [path] Source directory to scan (default `./src`).
  * @property {boolean} [installDeps] Auto-install jscodeshift without prompting.
  * @property {boolean} [registry] Reconcile only ShadCN-copied compositions; `from` is not required.

package/assets/codemods/integration-discovery.mjs

@@ -32,6 +32,40 @@ import {semverCompare} from '../../foundation/env/semver.mjs';
 /** File extensions recognized as codemod modules. */
 const CODEMOD_EXTENSIONS = ['.ts', '.mjs', '.js'];
 
+/**
+ * Directories never walked for codemods: a test directory beside a transform is
+ * the natural place to put its test, and every file found here is loaded and
+ * validated as a codemod.
+ */
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '__tests__',
+  '__fixtures__',
+]);
+
+/**
+ * Whether a file name is a test or fixture rather than a codemod.
+ *
+ * The trap this closes: EVERY `.ts`/`.mjs`/`.js` under a version folder used to
+ * be loaded as a codemod, so a test file colocated with its transform failed
+ * validation and — because a definition error is a hard error — took every
+ * codemod in that package's version with it. `astryx upgrade` then applied no
+ * transforms and reported success, which is the worst shape a failure can take.
+ *
+ * Core's own codemods never hit this: they are enumerated in a registry, and
+ * their colocated tests are simply not in it. Only integrations are discovered
+ * by walking a directory, so only integrations carry the landmine — which is why
+ * this is a loader fix and not a documentation one. It protects the integrations
+ * that already exist, which no authoring tool can reach.
+ *
+ * @param {string} name a file's base name
+ * @returns {boolean}
+ */
+function isTestFile(name) {
+  return /\.(test|spec)\.[^.]+$/.test(name) || /\.fixture\.[^.]+$/.test(name);
+}
+
 /**
  * Recursively collect codemod module files under a version folder. Returns
  * entries of {id, file} where id is the extension-less relative path
@@ -49,14 +83,18 @@ function collectCodemodFiles(versionDir) {
     for (const entry of entries) {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) {
-        if (entry.name === 'node_modules' || entry.name === '.git') continue;
+        if (SKIP_DIRS.has(entry.name)) continue;
         walk(full);
         continue;
       }
       const ext = path.extname(entry.name);
       if (!CODEMOD_EXTENSIONS.includes(ext)) continue;
+      if (isTestFile(entry.name)) continue;
       const rel = path.relative(versionDir, full);
-      const id = rel.slice(0, rel.length - ext.length).split(path.sep).join('/');
+      const id = rel
+        .slice(0, rel.length - ext.length)
+        .split(path.sep)
+        .join('/');
       out.push({id, file: full});
     }
   }

package/assets/codemods/integration-discovery.test.mjs

@@ -221,3 +221,61 @@ describe('integration codemod discovery', () => {
     ).rejects.toThrow(/across versions/i);
   });
 });
+
+describe('test files beside a codemod', () => {
+  // The incident this closes: every .ts/.mjs/.js under a version folder was
+  // loaded AND VALIDATED as a codemod, so a test file colocated with its
+  // transform failed validation — and because a definition error is a hard
+  // error, it took every codemod in that version with it. `astryx upgrade`
+  // then applied nothing and reported success. Core is immune because its own
+  // codemods are enumerated in a registry rather than discovered by walking a
+  // directory, so its colocated tests are simply never visited. Only
+  // integrations carry the landmine.
+  const TRANSFORM = `
+    export default {
+      type: 'code',
+      title: 'Drop foo',
+      transform: (file) => file.source.replace(/foo/g, 'bar'),
+    };
+  `;
+  // Not a codemod: no default export of the right shape. Loading it throws.
+  const A_TEST = `
+    import {describe, it, expect} from 'vitest';
+    describe('drop-foo', () => {
+      it('drops foo', () => expect(1).toBe(1));
+    });
+  `;
+
+  it.each([
+    ['a .test. sibling', '0.2.0/drop-foo.test.mjs'],
+    ['a .spec. sibling', '0.2.0/drop-foo.spec.mjs'],
+    ['a fixture sibling', '0.2.0/drop-foo.fixture.mjs'],
+    ['a __tests__ directory', '0.2.0/__tests__/drop-foo.mjs'],
+    ['a __fixtures__ directory', '0.2.0/__fixtures__/input.mjs'],
+  ])('ignores %s and still discovers the codemod', async (_label, testPath) => {
+    scaffold({'0.2.0/drop-foo.mjs': TRANSFORM, [testPath]: A_TEST});
+
+    const project = await Project.load(tmpDir);
+    const byVersion = await discoverIntegrationCodemods(
+      project.loadedIntegrations,
+    );
+
+    expect([...byVersion.keys()]).toEqual(['0.2.0']);
+    expect(byVersion.get('0.2.0').map(entry => entry.id)).toEqual(['drop-foo']);
+  });
+
+  it('a nested helper directory is still walked', async () => {
+    // Only test and fixture names are skipped. A package that organises its
+    // transforms into subdirectories keeps working.
+    scaffold({'0.2.0/imports/drop-foo.mjs': TRANSFORM});
+
+    const project = await Project.load(tmpDir);
+    const byVersion = await discoverIntegrationCodemods(
+      project.loadedIntegrations,
+    );
+
+    expect(byVersion.get('0.2.0').map(entry => entry.id)).toEqual([
+      'imports/drop-foo',
+    ]);
+  });
+});

package/assets/codemods/transforms/v0.3.0/__tests__/unwrap-authoring-factories.test.mjs

@@ -3,7 +3,8 @@
 import {describe, it, expect} from 'vitest';
 
 async function applyTransform(source, path = 'test.ts') {
-  const {default: transform} = await import('../unwrap-authoring-factories.mjs');
+  const {default: transform} =
+    await import('../unwrap-authoring-factories.mjs');
   const jscodeshift = (await import('jscodeshift')).default;
   const j = jscodeshift.withParser('tsx');
   const api = {jscodeshift: j, stats: () => {}, report: () => {}};
@@ -18,7 +19,7 @@ export default createConfig({integrations: ['@acme/widgets']});
 `;
     const output = await applyTransform(input);
     expect(output).not.toContain('createConfig');
-    expect(output).toContain("export default {");
+    expect(output).toContain('export default {');
     expect(output).toContain("integrations: ['@acme/widgets']");
     expect(output).not.toContain('type:');
   });
@@ -132,13 +133,34 @@ export default createComponentDoc();
     expect(output).toContain("type: 'component'");
   });
 
+  it('leaves same-named factories from unrelated packages unchanged', async () => {
+    const input = `import {createConfig} from '@acme/eslint';
+export default createConfig({strict: true});
+`;
+    expect(await applyTransform(input)).toBe(input);
+  });
+
+  it('keeps an unrelated same-named import when another factory is migrated', async () => {
+    const input = `import {createConfig as createLintConfig} from '@acme/eslint';
+import {createDoc} from '@astryxdesign/cli/doc';
+export const lintConfig = createLintConfig({strict: true});
+export const doc = createDoc({name: 'Theming', description: 'How theming works.'});
+`;
+    const output = await applyTransform(input);
+    expect(output).toContain(
+      "import {createConfig as createLintConfig} from '@acme/eslint'",
+    );
+    expect(output).toContain('createLintConfig({strict: true})');
+    expect(output).not.toContain('createDoc');
+    expect(output).toContain("type: 'generic'");
+  });
+
   it('is a no-op when no authoring factory is imported', async () => {
     const input = `import {Button} from '@astryxdesign/core';
 export default Button;
 `;
-    const {default: transform} = await import(
-      '../unwrap-authoring-factories.mjs'
-    );
+    const {default: transform} =
+      await import('../unwrap-authoring-factories.mjs');
     const jscodeshift = (await import('jscodeshift')).default;
     const j = jscodeshift.withParser('tsx');
     const api = {jscodeshift: j, stats: () => {}, report: () => {}};

package/assets/codemods/transforms/v0.3.0/unwrap-authoring-factories.mjs

@@ -5,8 +5,9 @@
  *
  * v0.3.0 removes the authoring factories. Authoring is now types + parsers: an
  * author writes a plain object and stamps its `type` directly. This transform
- * rewrites every factory call to the plain object the factory used to return,
- * then drops the now-dead factory imports:
+ * rewrites factory calls imported from the retired Astryx authoring entrypoints
+ * to the plain object the factory used to return, then drops the now-dead
+ * factory imports:
  *
  *   createConfig(o) / createIntegration(o)        -> o        (no discriminant)
  *   createComponentDoc(o)                         -> { ...o, type: 'component' }
@@ -25,8 +26,9 @@
  *
  * Import aliases are followed (`import {createDoc as mk}` → calls to `mk`), and
  * the factory specifiers are removed afterward (the whole import statement goes
- * if nothing else was imported from it). Run this BEFORE
- * `migrate-authoring-imports`, which repoints the surviving type imports.
+ * if nothing else was imported from it). Same-named imports from other packages
+ * remain untouched. Run this BEFORE `migrate-authoring-imports`, which repoints
+ * the surviving type imports.
  */
 
 export const meta = {
@@ -35,13 +37,24 @@ export const meta = {
     'Rewrites createConfig/createIntegration/createComponentDoc/' +
     'createFunctionDoc/createDoc/createPageTemplate/createBlockTemplate/' +
     'createCodemod/createConfigCodemod calls to the plain object they returned ' +
-    "(stamping the doc/template/codemod `type` discriminant), and removes the " +
+    '(stamping the doc/template/codemod `type` discriminant), and removes the ' +
     'now-dead factory imports. Authoring is types + parsers in v0.3.0 — there ' +
     'are no factories.',
   pr: '#4612',
   fileExtensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'],
 };
 
+/** Legacy Astryx authoring entrypoints that exported the removed factories. */
+const AUTHORING_SOURCES = new Set([
+  '@astryxdesign/cli/config',
+  '@astryxdesign/cli/doc',
+  '@astryxdesign/cli/integration',
+  '@astryxdesign/cli/template',
+  '@astryxdesign/cli/codemod',
+  '@astryxdesign/core/authoring',
+  '@astryxdesign/core/config',
+]);
+
 /**
  * Factory name → the `type` discriminant it stamped, or `null` for the config /
  * integration factories, which were pure typed-identity (no discriminant).
@@ -108,6 +121,7 @@ export default function transformer(file, api) {
   /** @type {Map<string, string>} */
   const localToFactory = new Map();
   root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!AUTHORING_SOURCES.has(path.node.source.value)) return;
     for (const spec of path.node.specifiers ?? []) {
       if (spec.type !== 'ImportSpecifier') continue;
       const importedName = spec.imported?.name;
@@ -163,6 +177,7 @@ export default function transformer(file, api) {
   // Drop the now-dead factory import specifiers; remove any import statement
   // left empty.
   root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!AUTHORING_SOURCES.has(path.node.source.value)) return;
     const specs = path.node.specifiers ?? [];
     const kept = specs.filter(
       (/** @type {any} */ spec) =>

package/assets/docs/README.md

@@ -48,3 +48,12 @@ The material is usually good; the finding is placement, not quality. It goes in
 **Fits no row?** It is still not caller-facing. Default it to [Contributing](https://github.com/facebook/astryx/wiki/Contributing), or `CONTRIBUTING.md` when it is a step someone follows with the repo cloned. Never default it back to this directory.
 
 Worked example: a responsive-and-interaction readiness rubric is grading criteria → **Component-Audit-Rubric**, or **Component-Lifecycle** if it is a promotion gate.
+
+## Sections are read one at a time
+
+`astryx docs <topic> --index` lists a topic's sections, and readers then open
+one section by its key. A section's key is its `id`, or a key derived from its
+title when it has none. Give a section an `id` when its title may change, since
+readers and extensions link to the key. Two sections in one topic cannot share
+a key. Keep each section small enough to read on its own: `astryx doctor` fails
+any section over 32 KB.

package/assets/docs/authoring.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs authoring`: every authoring schema, one section each.
+ *
+ * Built from the self-docs colocated under packages/cli/authoring, so it cannot
+ * drift from the schemas it describes. `astryx doctor` names a self-doc this
+ * topic cannot reach.
+ */
+
+import {buildAuthoringTopic} from '../../foundation/discovery/authoring-self-docs.mjs';
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = await buildAuthoringTopic();

package/assets/docs/cli-integrations.doc.mjs

@@ -20,7 +20,11 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'The authoring CLI owns the integration file. The first `astryx integration add` creates `astryx.integration.mjs`; each later add declares its root only after writing a valid contribution behind it. Identity (name and version) still comes from package.json. For the consumer side, run `npx astryx docs getting-started`.',
+          text: 'The authoring CLI owns the integration file. The first `astryx integration add` creates `astryx.integration.mjs`; each later add declares its root only after writing a valid contribution behind it. Identity (name and version) still comes from package.json. For the consumer side, run `astryx docs getting-started`.',
+        },
+        {
+          type: 'prose',
+          text: 'Every file an integration author writes is documented field by field in `npx astryx docs authoring`: the manifest, astryx.config, codemods, identity, and each doc type. `npx astryx docs authoring --index` lists them, and `npx astryx docs authoring <key>` reads one.',
         },
         {
           type: 'prose',
@@ -48,7 +52,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Do not start by hand-editing a manifest. Add the contribution you mean to ship; Astryx creates the manifest, writes every required file, preserves an existing custom root, and updates an existing package.json files allowlist without creating one.',
+          text: 'Do not start by hand-editing a manifest. Add the contribution you mean to ship; Astryx creates the manifest, writes every required file, preserves an existing custom root, and updates an existing package.json files allowlist without creating one. Always run these commands from the locally installed CLI in the package (e.g. `node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs` or `pnpm astryx`), not `npx @astryxdesign/cli` — npx may resolve a stale registry version whose integration scaffolding does not match the installed one.',
         },
         {
           type: 'code',
@@ -80,17 +84,17 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'A useful theme package usually ships more than colors. Start with the source theme, then add the guides its consumers need. Each command writes a complete contribution and keeps the package manifest in sync.',
+          text: 'A useful theme package usually ships more than colors. Start with the source theme, author the palette request at `themes/ocean/palette.config.json`, then add the guides its consumers need. The `integration add` commands keep the package manifest in sync; add palette outputs to the theme catalog after generation.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'In the provider package',
-          code: 'astryx integration add theme ocean\nastryx theme palette generate palette.config.json --out themes/ocean/tokens/ocean.palette.ts\nastryx integration add doc brand-theme\nastryx integration add doc theme-migration\nastryx theme list --package @acme/brand-integration\nastryx docs brand-theme\nastryx integration pack --check\nnpm pack',
+          code: 'astryx integration add theme ocean\nastryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts\nastryx integration add doc brand-theme\nastryx integration add doc theme-migration\nastryx theme list --package @acme/brand-integration\nastryx docs brand-theme\nastryx integration pack --check\nnpm pack',
         },
         {
           type: 'prose',
-          text: 'Edit the generated theme and guide files before publishing. Palette generation writes an importable TypeScript candidate and a reproducibility receipt; import the candidate from the theme and list both nested files in that theme catalog entry. `integration pack --check` runs the real package lifecycle and compares local discovery with the npm tarball, so a missing source file or files allowlist entry fails before a consumer sees it.',
+          text: "Edit the generated theme and guide files before publishing. The shown palette command writes `themes/ocean/tokens/ocean.palette.ts` and its sibling `themes/ocean/tokens/ocean.palette.receipt.json`. The TypeScript candidate directly exports `black`, `white`, and `palette`; import what the theme uses from `./tokens/ocean.palette`. Keep the request at `themes/ocean/palette.config.json`, and list the theme source, request, candidate, and receipt in the catalog entry's `files` array. Add any optional wrapper, refs, icon, or preview modules only when you author them, and list each one too. `integration pack --check` runs the real package lifecycle and compares local discovery with the npm tarball, so a missing source file or files allowlist entry fails before a consumer sees it.",
         },
         {
           type: 'code',
@@ -104,6 +108,25 @@ export const docs = {
         },
       ],
     },
+    {
+      title: 'Contribution Kinds at a Glance',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Each contribution kind uses a different metadata suffix, type stamp, and discovery rule. The table below prevents the most common first-time authoring mistake — using the wrong file or export convention.',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: "Kind        Metadata suffix            type stamp     Source file\n────────    ─────────────────────────  ─────────────  ──────────────────────\nComponent   Name.doc.{ts,mjs,js}       'component'    Name.tsx (same stem)\nTemplate    Name.template.{ts,mjs,js}  'page'/'block' Name.tsx (same stem)\nDoc topic   topic.doc.{ts,mjs,js}      'generic'      (none — docs are prose)\nCodemod     <version>/<id>.{ts,mjs,js} 'code'/'config' (the codemod IS the source)\nTheme       manifest.json entry         —             <slug>/<entry>.ts",
+        },
+        {
+          type: 'prose',
+          text: 'The `type` stamp is how new docs should be authored — it routes parsing to the correct schema at the load boundary. Legacy docs without a stamp still load via shape-sniffing for backward compatibility, but unstamped docs rely on heuristics (presence of `props`, `params`, etc.) and may parse under the wrong schema if the shape is ambiguous. Always stamp new integration contributions.',
+        },
+      ],
+    },
     {
       title: 'The Integration File',
       category: 'guide',
@@ -129,7 +152,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a `.doc.{ts,mjs,js}` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.ts`.',
+          text: "Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a `.doc.{ts,mjs,js}` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.ts`. The doc file must default-export an object with `type: 'component'` — not `'generic'` (that is for reference docs) and not `'page'`/`'block'` (those are for templates).",
         },
         {
           type: 'prose',
@@ -138,7 +161,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'typescript',
-          code: "// AcmeCarousel.doc.ts\nexport default {\n  type: 'component',\n  name: 'AcmeCarousel',\n  description: 'A carousel that cycles through slides.',\n  // props, usage, examples, ...\n};",
+          code: "// AcmeCarousel.doc.ts\nexport default {\n  type: 'component',\n  name: 'AcmeCarousel',\n  description: 'A carousel that cycles through slides.',\n  // props, usage, examples, ...\n} satisfies import('@astryxdesign/cli/authoring').ComponentDoc;",
         },
       ],
     },
@@ -148,7 +171,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a plain object stamped with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) in a `.template.{ts,mjs,js}` file next to the source, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.template.ts`.",
+          text: "Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a plain object with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) as its default export in a `.template.{ts,mjs,js}` file next to the source, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.template.ts`. Do not use the `.doc.{ts,mjs,js}` suffix — that is for component docs and reference docs.",
         },
         {
           type: 'prose',
@@ -161,7 +184,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'The CLI needs both files at consume time. `integration add` includes the templates root when package.json already has a files allowlist. It never creates an exports map, because doing that can make previously-open deep imports private; when a map already exists, it adds the generated source subpath without replacing author-owned entries. `integration pack --check` proves the source and metadata survive the tarball and verifies every component through the public import its metadata advertises.',
+          text: 'The CLI needs both files at consume time. `integration add` includes the templates root when package.json already has a files allowlist. It never creates an exports map, because doing that can make previously-open deep imports private; when a map already exists, it adds the generated source subpath without replacing author-owned entries. Use consumer-safe extensionless subpaths in the exports map (e.g. `"./templates/AcmeDashboard"` instead of `"./templates/AcmeDashboard.tsx"`), so consumers import without knowing the file extension. `integration pack --check` proves the source and metadata survive the tarball and verifies every component through the public import its metadata advertises.',
         },
       ],
     },
@@ -171,7 +194,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object stamped `type: 'generic'`, the same shape core's own topics use.",
+          text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object with `type: 'generic'` as its default export — not `'component'` (that is for component docs with a same-stem source file). This is the same shape core's own topics use.",
         },
         {
           type: 'code',
@@ -189,7 +212,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "`extends: 'x'` merges onto a topic instead of owning it: a section whose title matches one in the base replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
+          text: "`extends: 'x'` merges onto a topic instead of owning it: a section with the same key as one in the base (its `id`, or the key its title derives) or the same title replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
         },
         {
           type: 'list',
@@ -215,16 +238,33 @@ export const docs = {
         {
           type: 'code',
           lang: 'text',
-          code: 'themes/\n  manifest.json\n  ocean/\n    oceanTheme.ts',
+          code: 'themes/\n  manifest.json\n  ocean/\n    oceanTheme.ts\n    palette.config.json\n    tokens/\n      ocean.palette.ts\n      ocean.palette.receipt.json',
         },
         {
           type: 'prose',
-          text: "The root catalog uses the same entry contract as Astryx's bundled themes: `slug`, `displayName`, `description`, `maintained`, `entry`, `exportName`, and `files`. `entry` and every file are relative to `themes/<slug>/`; `exportName` identifies a named runtime export in the entry source. Astryx parses that source without executing it, requires every local static import and re-export to name a file in `files`, and rejects missing or type-only exports.",
+          text: 'The root catalog `manifest.json` must be `{ "version": 1, "themes": [...] }`. Each entry in the `themes` array requires every field shown below — omitting any one is a hard validation error:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`slug` — lowercase kebab-case starting with a letter (e.g. `"ocean"`). Must be unique within the catalog.',
+            '`displayName` — human-readable label (e.g. `"Ocean"`).',
+            '`description` — string description of the theme.',
+            '`maintained` — boolean indicating active maintenance.',
+            '`entry` — source file relative to `themes/<slug>/` (e.g. `"oceanTheme.ts"`).',
+            '`exportName` — a valid JS identifier naming the runtime export in the entry file (e.g. `"oceanTheme"`). Astryx parses the source without executing it and rejects missing or type-only exports.',
+            '`files` — non-empty array of filenames relative to `themes/<slug>/`. Must include the entry file and every local static import the entry source uses. Astryx validates that every listed file exists on disk and that every local import in the entry names a file in this list.',
+          ],
         },
         {
           type: 'code',
           lang: 'json',
-          code: '{\n  "version": 1,\n  "themes": [{\n    "slug": "ocean",\n    "displayName": "Ocean",\n    "description": "Ocean theme.",\n    "maintained": true,\n    "entry": "oceanTheme.ts",\n    "exportName": "oceanTheme",\n    "files": ["oceanTheme.ts"]\n  }]\n}',
+          code: '{\n  "version": 1,\n  "themes": [{\n    "slug": "ocean",\n    "displayName": "Ocean",\n    "description": "Ocean theme with OKLCH palettes.",\n    "maintained": true,\n    "entry": "oceanTheme.ts",\n    "exportName": "oceanTheme",\n    "files": [\n      "oceanTheme.ts",\n      "palette.config.json",\n      "tokens/ocean.palette.ts",\n      "tokens/ocean.palette.receipt.json"\n    ]\n  }]\n}',
+        },
+        {
+          type: 'prose',
+          text: 'The generated candidate is already importable: it exports `black`, `white`, `palette`, and a default palette value. Import it directly from `./tokens/ocean.palette`. A wrapper or palette-refs module is optional application code, not generator output; list it only if you create it.',
         },
         {
           type: 'prose',
@@ -267,10 +307,41 @@ export const docs = {
           type: 'prose',
           text: "Ship codemods so `astryx upgrade` can migrate consumers across breaking changes in your package. Point the integration file's `codemods` field at your codemods root, and author each one as a plain object stamped with `type: 'code'` (transforms source files) or `type: 'config'` (rewrites the consumer's `astryx.config`).",
         },
+        {
+          type: 'prose',
+          text: 'The codemods root uses a version-folder-first layout. Each folder name is an exact semver string (no `v` prefix) matching the version the codemod migrates TO. Each module under it is a kebab-case `.ts`, `.mjs`, or `.js` file whose default export is the codemod envelope:',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'codemods/\n  0.2.0/\n    rename-widget-prop.ts\n  0.3.0/\n    update-theme-import.ts\n    config/rename-integration.ts',
+        },
+        {
+          type: 'prose',
+          text: 'Codemod ids (the extension-less relative path under the version folder, e.g. `rename-widget-prop`, `config/rename-integration`) must be unique within a package across all versions. A duplicate id across versions is a hard error.',
+        },
+        {
+          type: 'prose',
+          text: 'The loader automatically skips test and fixture files so you can colocate tests with transforms. Reserved names: files matching `*.test.*`, `*.spec.*`, or `*.fixture.*`, and any file under a `__tests__/` or `__fixtures__/` directory. These are never loaded as codemods regardless of their extension.',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'codemods/\n  0.2.0/\n    rename-widget-prop.ts              # loaded as a codemod\n    rename-widget-prop.test.ts          # skipped (reserved name)\n    __tests__/\n      rename-widget-prop.test.ts        # skipped (reserved directory)',
+        },
         {
           type: 'code',
           lang: 'typescript',
-          code: "// codemods/v2-rename-prop.ts\nexport default {\n  type: 'code',\n  // title, description, transform, ...\n};",
+          code: "// codemods/0.2.0/rename-widget-prop.ts\nexport default {\n  type: 'code',\n  title: 'Rename AcmeWidget oldProp to newProp',\n  description: 'Updates JSX props in consumer source files.',\n  transform(file, api) {\n    // jscodeshift transform\n    return file.source;\n  },\n};",
+        },
+        {
+          type: 'prose',
+          text: "`astryx upgrade` is dry-run by default — it previews which codemods would run and what files would change, without writing anything. Pass `--apply` to write the changes. There is no `--dry-run` flag; omitting `--apply` is the dry run. The `--integration` flag resolves each value beneath the project's `node_modules` (for example, `--integration @acme/widgets`). Absolute paths and `.` or `..` segments are rejected; other slash-separated values remain beneath `node_modules`.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: '# Preview what would change (dry-run, the default)\nastryx upgrade --from 0.1.0\n\n# Apply the migration\nastryx upgrade --from 0.1.0 --apply',
         },
         {
           type: 'prose',

package/assets/docs/styling-libraries.doc.mjs

@@ -351,7 +351,7 @@ tokens: {
     },
   },
   shortcuts: {
-    'xds-card': 'bg-surface text-primary border border-border rounded-lg p-4',
+    'astryx-card': 'bg-surface text-primary border border-border rounded-lg p-4',
   },
 });`,
         },

package/assets/docs/working-with-ai.doc.mjs

@@ -182,7 +182,7 @@ astryx docs tokens --dense`,
           label: 'MCP config (same for all tools)',
           code: `{
   "mcpServers": {
-    "xds": {
+    "astryx": {
       "type": "url",
       "url": "https://astryx.atmeta.com/mcp"
     }

package/authoring/_shared/contract.ts

@@ -28,5 +28,27 @@ export type MutuallyAssignable<A, B> = [A] extends [B]
     : false
   : false;
 
+/**
+ * `T` without string or number index signatures, at every depth. A
+ * `.passthrough()` schema infers one and a hand-written interface never has
+ * one, so a lock drops them before comparing named fields. Recursive fields
+ * that a schema casts to their public type compare equal by construction.
+ */
+export type NamedFields<T> = T extends readonly (infer U)[]
+  ? NamedFields<U>[]
+  : T extends (...args: never[]) => unknown
+    ? T
+    : T extends object
+      ? {
+          [
+            K in keyof T as string extends K
+              ? never
+              : number extends K
+                ? never
+                : K
+          ]: NamedFields<T[K]>;
+        }
+      : T;
+
 /** Compiles only when `T` is exactly `true`; otherwise a type error. */
 export type Expect<T extends true> = T;

package/authoring/codemod/codemod.doc.mjs

@@ -63,11 +63,13 @@ export const doc = {
               name: 'file.path',
               type: 'string',
               description: 'Absolute path to the file being transformed.',
+              required: true,
             },
             {
               name: 'file.source',
               type: 'string',
               description: 'The current source contents of the file.',
+              required: true,
             },
           ],
         },
@@ -81,18 +83,21 @@ export const doc = {
               type: 'unknown',
               description:
                 'A jscodeshift instance configured with a parser for the file.',
+              required: true,
             },
             {
               name: 'api.stats',
               type: '(...args: unknown[]) => void',
               description:
                 'Report a statistic (no-op-friendly; provided for jscodeshift parity).',
+              required: true,
             },
             {
               name: 'api.report',
               type: '(...args: unknown[]) => void',
               description:
                 'Report progress (no-op-friendly; provided for jscodeshift parity).',
+              required: true,
             },
           ],
         },
@@ -100,7 +105,7 @@ export const doc = {
     },
     {
       name: 'type',
-      type: "'code'",
+      type: "'code' | 'config'",
       description:
         "Discriminant for the file-transforming variant. Use 'config' for a " +
         'codemod that rewrites astryx.config.* instead (see notes).',