@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

package/api/template/copy/copy.mjs

@@ -74,7 +74,7 @@ export function templateCopy(match, {targetPath, cwd, overwrite = false}) {
   if (!overwrite && fs.existsSync(outputFilePath)) {
     const rel = path.relative(cwd, outputFilePath) || outputFilePath;
     throw new AstryxError(
-      `Refusing to overwrite existing file ${rel}. Re-run with overwrite to replace it.`,
+      `Refusing to overwrite existing file ${rel}. Re-run with --overwrite (or -f) to replace it.`,
       undefined,
       ERROR_CODES.ERR_FILE_EXISTS,
     );

package/api/template/copy/copy.test.mjs

@@ -35,6 +35,15 @@ describe('template.copy — overwrite + path safety', () => {
     expect(fs.readFileSync(path.join(dir, 'mine.tsx'), 'utf-8')).toBe('USER CODE');
   }, SLOW);
 
+  it('names the flag that replaces the file, as swizzle and theme add do', async () => {
+    fs.writeFileSync(path.join(dir, 'mine.tsx'), 'USER CODE');
+    await expect(
+      template('blank', {targetPath: './mine.tsx', cwd: dir}),
+    ).rejects.toThrow(
+      'Refusing to overwrite existing file mine.tsx. Re-run with --overwrite (or -f) to replace it.',
+    );
+  }, SLOW);
+
   it('overwrites when overwrite:true is passed', async () => {
     fs.writeFileSync(path.join(dir, 'mine.tsx'), 'USER CODE');
     const res = await template('blank', {targetPath: './mine.tsx', overwrite: true, cwd: dir});

package/api/template/template-integration.test.mjs

@@ -19,6 +19,7 @@ import {
 } from './template.mjs';
 import {search} from '../search/search.mjs';
 import {build} from '../build/build.mjs';
+import {layoutExpand} from '../layout/layout.mjs';
 import {runCli} from '../../test-utils/run-cli.mjs';
 
 let tmpDir;
@@ -517,7 +518,53 @@ describe('integration template discovery', () => {
     });
   });
 
-  it('resolves chained block aliases consistently in template', async () => {
+  it('resolves a replacement block through the layout alias', async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'acme-card-callout', {
+      kind: 'block',
+      source:
+        'export default function AcmeCardCallout() { return <span>Acme replacement block</span>; }\n',
+    });
+    declareReplaces(pkgDir, {
+      'acme-card-callout': 'CardCallout',
+    });
+
+    const accidental = path.join(tmpDir, 'node_modules', '@acme', 'extra');
+    fs.mkdirSync(path.join(accidental, 'templates'), {recursive: true});
+    fs.writeFileSync(
+      path.join(accidental, 'package.json'),
+      JSON.stringify({name: '@acme/extra', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(accidental, 'astryx.integration.mjs'),
+      `export default {templates: './templates'};\n`,
+    );
+    writeTemplate(accidental, 'CardCallout', {
+      kind: 'block',
+      body: `export default {type: 'block', name: 'ZZZ accidental block', description: 'collision'};\n`,
+      source:
+        'export default function Accidental() { return <span>Accidental block</span>; }\n',
+    });
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      `export default { integrations: ['@acme/widgets', '@acme/extra'] };\n`,
+    );
+
+    const result = await layoutExpand('C{card-callout}', {
+      name: 'ReplacementLayout',
+      cwd: tmpDir,
+    });
+
+    expect(result.data.code).toContain('Acme replacement block');
+    expect(result.data.code).not.toContain('Accidental block');
+    expect(result.data.blocksReferenced).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({name: 'CardCallout', mode: 'splice'}),
+      ]),
+    );
+  }, 30_000);
+
+  it('resolves chained block aliases consistently in template and layout', async () => {
     const [firstTarget, secondTarget] = (await discoverCoreTemplates()).filter(
       candidate => candidate.type === 'block',
     );
@@ -545,12 +592,29 @@ describe('integration template discovery', () => {
       cwd: tmpDir,
     });
     expect(firstTemplate.data.source).toContain('First chain replacement');
+    const layoutId = id =>
+      id.replace(/([a-z0-9])([A-Z])/gu, '$1-$2').toLowerCase();
+    const firstLayout = await layoutExpand(
+      `C{${layoutId(firstTarget.dirName)}}`,
+      {
+        cwd: tmpDir,
+      },
+    );
+    expect(firstLayout.data.code).toContain('First chain replacement');
+    expect(firstLayout.data.code).not.toContain('Final chain replacement');
 
     const secondTemplate = await template(secondTarget.dirName, {
       show: true,
       cwd: tmpDir,
     });
     expect(secondTemplate.data.source).toContain('Final chain replacement');
+    const secondLayout = await layoutExpand(
+      `C{${layoutId(secondTarget.dirName)}}`,
+      {
+        cwd: tmpDir,
+      },
+    );
+    expect(secondLayout.data.code).toContain('Final chain replacement');
   }, 30_000);
 
   it('keeps the old discovery behavior when no replacement is declared', async () => {

package/api/template/template.doc.mjs

@@ -102,6 +102,7 @@ export const doc = {
       type: 'string',
       description:
         'Directory to discover templates and resolve the target path from.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -134,7 +135,7 @@ export const doc = {
   throws: [
     {
       code: 'ERR_UNKNOWN_TEMPLATE',
-      when: 'the named template does not exist, or --skeleton is run without a name',
+      when: 'the named template does not exist, or options.skeleton is set without a name',
     },
     {
       code: 'ERR_AMBIGUOUS_TEMPLATE',

package/api/template/template.mjs

@@ -8,7 +8,7 @@
  * the requested one, and routes to a leaf (list/show/skeleton/copy/cdn). The shared
  * discovery/IO + cross-command helpers live in `foundation/discovery/template-adapter.mjs` and are
  * RE-EXPORTED here so external import paths (`api/template/template.mjs`) —
- * used by component, search, init, discover, Doctor integration, and
+ * used by component, layout, search, init, discover, Doctor integration, and
  * lib/project — keep resolving unchanged.
  *
  * @position api/template — the template dispatcher + barrel; leaves live under

package/api/theme/generateTonalPalette.doc.mjs

@@ -29,7 +29,7 @@ export const doc = {
       name: 'input',
       type: 'TonalPaletteGenerationInput',
       description:
-        'Families and seeds plus optional modes, shared stops, anchors, vibrancy from 0 to 100 (default 50), and neutral profile. Only generate an accent family when one is explicitly requested; clarify whether an ambiguous accent means one theme value or a tonal family.',
+        'Families and seeds plus optional modes, shared stops, anchors, vibrancy from 0 to 100 (default 50), and neutral profile.',
       required: true,
     },
   ],
@@ -72,6 +72,5 @@ export const doc = {
       code: "generateTonalPalette({stops: [12.5, 50], families: [{id: 'blue', seed: '#0074e2'}]});",
     },
   ],
-  command: 'theme palette generate',
   related: ['themePaletteGenerate'],
 };

package/api/theme/listThemes.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   displayName: 'listThemes()',
   summary: 'Read the CLI bundled-theme descriptors.',
   description:
-    'Reads the typed same-stem descriptors under templates/themes and returns normalized entries synchronously. This low-level helper keeps its historical bundled-only contract; project-aware themeList() and themeAdd() also discover source themes from installed integrations.',
+    "Synchronously returns the themes bundled with the CLI, including each one's entry file, export name and file list. Bundled themes only; use themeListAvailable() to include themes from installed integrations.",
   importPath: '@astryxdesign/cli/api',
   signature: 'listThemes(): BundledTheme[]',
   keywords: ['theme', 'themes', 'descriptor', 'bundled', 'adapter', 'list'],

package/api/theme/themeAdd.doc.mjs

@@ -44,6 +44,7 @@ export const doc = {
       type: 'string',
       description:
         'Project directory used for integration discovery and target paths.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.package',
@@ -57,11 +58,6 @@ export const doc = {
       description:
         'Copy receipt with slug, displayName, maintained flag, owner package, outputDir, entry, exportName, and files.',
     },
-    {
-      type: 'theme.list',
-      description:
-        'The CLI list affordance routes a bare `astryx theme add` or `--list` to themeListAvailable() and returns every available theme with its owner.',
-    },
   ],
   throws: [
     {
@@ -74,7 +70,10 @@ export const doc = {
       when: 'the selected installed package has a blocking integration or theme-descriptor error',
     },
     {code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'},
-    {code: 'ERR_NO_SOURCE', when: 'a theme file to copy is missing'},
+    {
+      code: 'ERR_NO_SOURCE',
+      when: 'the bundled theme descriptors cannot be read, or a theme file to copy is missing',
+    },
     {
       code: 'ERR_FILE_EXISTS',
       when: 'a destination exists and overwrite is not set',
@@ -82,12 +81,12 @@ export const doc = {
     {code: 'ERR_WRITE_FAILED', when: 'writing files fails'},
   ],
   examples: [
-    {label: 'Copy a bundled theme', code: "await themeAdd('ocean');"},
+    {label: 'Copy a bundled theme', code: "await themeAdd('butter');"},
     {
-      label: 'Copy an integration theme',
-      code: "await themeAdd('ocean', {package: '@acme/themes'});",
+      label: 'Name the owner package and the destination',
+      code: "await themeAdd('butter', {package: '@astryxdesign/cli', targetPath: 'src/brand-theme'});",
     },
   ],
   command: 'theme add',
-  related: ['themeList', 'listThemes'],
+  related: ['themeListAvailable', 'themeTemplate', 'listThemes'],
 };

package/api/theme/themeBuild.doc.mjs

@@ -14,14 +14,13 @@ export const doc = {
   name: 'themeBuild',
   namespace: 'cli/api',
   displayName: 'themeBuild()',
-  summary: 'Compile a defineTheme file to CSS + JS + type declarations.',
+  summary:
+    'Compile a defineTheme() file to scoped CSS, a JS module, and type declarations, or check committed outputs for drift in CI.',
   description:
-    'The compiler behind `astryx theme build`. Reads a file that calls defineTheme() and, ' +
-    "via @astryxdesign/core's shared generator (the single source of truth, so the build " +
-    'emits the exact CSS the <Theme> runtime does), writes a scoped CSS file, a JS module ' +
-    'that re-exports the built theme, and a .d.ts (plus an optional .variants.d.ts when the ' +
-    'theme adds custom prop values). When another build step emits the icon registry, ' +
-    '{iconsSpecifier} declares the fully specified module path for the generated JS import. ' +
+    'The compiler behind `astryx theme build`. Reads a file that calls defineTheme() and ' +
+    'writes a scoped CSS file, a JS module that re-exports the built theme, and a .d.ts ' +
+    '(plus an optional .variants.d.ts when the theme adds custom prop values). It uses ' +
+    "@astryxdesign/core's own generator, so the CSS matches what the <Theme> runtime emits. " +
     'With {check: true} it writes nothing and instead compares ' +
     'each output against disk, returning the drift: the CI guard for committed, generated theme CSS.',
   importPath: '@astryxdesign/cli/api',
@@ -48,7 +47,7 @@ export const doc = {
       name: 'options.out',
       type: 'string',
       description:
-        'Override the output CSS path; the sibling .js and .d.ts derive from it. A relative path must stay within cwd.',
+        'Override the output CSS path. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file. A relative path must stay within cwd.',
     },
     {
       name: 'options.check',
@@ -61,13 +60,14 @@ export const doc = {
       name: 'options.iconsSpecifier',
       type: 'string',
       description:
-        'Override the icon-registry import specifier in the generated JS module, for example ./icons.mjs. When omitted, the source specifier is preserved.',
+        'Override the import specifier of the icon registry in the generated JS module, for example ./icons.mjs. Takes effect only when the theme sets icons: to a named import; when omitted, the source specifier is kept.',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description:
-        'Directory the theme file and @astryxdesign/core resolve against.',
+        'Directory the theme file, a relative out path, and the returned output paths resolve against.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -79,7 +79,7 @@ export const doc = {
     {
       type: 'theme.build.check',
       description:
-        'The {check: true} receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: "missing" | "outdated"}), and the full list of checked paths. Writes nothing.',
+        'The {check: true} receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: "missing" | "outdated"}), and the full list of checked paths. Writes nothing. Resolves to null, like a normal build, when the theme produces no CSS.',
     },
   ],
   throws: [
@@ -102,7 +102,7 @@ export const doc = {
     },
     {
       code: 'ERR_CORE_INCOMPATIBLE',
-      when: 'the selected theme carries ordered-adaptation intent but the installed @astryxdesign/core does not export generateAdaptationCSS (upgrade core)',
+      when: 'the installed @astryxdesign/core does not export generateAdaptationCSS and the theme either declares ordered adaptations or has lineage whose adaptation use could not be observed (upgrade core)',
     },
     {
       code: 'ERR_WRITE_FAILED',
@@ -124,5 +124,5 @@ export const doc = {
     },
   ],
   command: 'theme build',
-  related: ['themeAdd', 'themeList', 'listThemes'],
+  related: ['themeTemplate', 'themeAdd', 'themeListAvailable', 'listThemes'],
 };

package/api/theme/themeList.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   displayName: 'themeList()',
   summary: 'List themes bundled with this CLI build.',
   description:
-    'Projects the bundled typed theme descriptors into a synchronous theme.list envelope. This preserves the original programmatic API contract. The CLI command uses themeListAvailable() so installed integrations also appear.',
+    'Synchronous list of the themes bundled with the CLI. It does not include themes from installed integrations; use themeListAvailable() for the list `astryx theme list` shows.',
   importPath: '@astryxdesign/cli/api',
   signature: 'themeList(): ThemeListResponse',
   keywords: ['theme', 'list', 'themes', 'bundled', 'available'],

package/api/theme/themeListAvailable.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   displayName: 'themeListAvailable()',
   summary: 'List bundled and installed integration themes.',
   description:
-    'Loads Project for the requested directory, combines the CLI bundle with source themes from installed integrations, and projects each entry with its owner package. An unreadable project configuration degrades to the bundled descriptors.',
+    'Lists the bundled themes plus source themes from integrations installed in cwd, each with its owner package. If the project configuration cannot be read, it falls back to the bundled themes.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeListAvailable(options?: {cwd?: string, package?: string}): Promise<ThemeListResponse>',
@@ -24,6 +24,7 @@ export const doc = {
       type: 'string',
       description:
         'Project directory whose installed integrations contribute themes.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.package',

package/api/theme/themePaletteGenerate.doc.mjs

@@ -27,30 +27,34 @@ export const doc = {
     {
       name: 'configPath',
       type: 'string',
-      description: 'JSON generation request, resolved within cwd.',
+      description:
+        'Path to a JSON file holding a TonalPaletteGenerationInput (the object generateTonalPalette() takes), resolved within cwd.',
       required: true,
     },
     {
       name: 'options.out',
       type: 'string',
       description:
-        'Optional candidate JSON destination. A sibling .receipt.json path is derived from it.',
+        'Where to write the candidate: a path ending in .ts (a TypeScript module) or .json. A sibling <name>.receipt.json is written next to it.',
     },
     {
       name: 'options.preview',
       type: 'string',
-      description: 'Optional path for a self-contained HTML review artifact.',
+      description:
+        'Optional path, ending in .html, for a self-contained HTML review page.',
     },
     {
       name: 'options.overwrite',
       type: 'boolean',
-      description: 'Replace existing candidate and receipt files.',
+      description:
+        "Replace existing candidate, receipt and preview files. Without it, if any target exists, nothing is written and the result has written: false, reason: 'exists'.",
       default: 'false',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description: 'Directory used to resolve the input and output paths.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -64,17 +68,20 @@ export const doc = {
     {code: 'ERR_FILE_NOT_FOUND', when: 'the config file does not exist'},
     {
       code: 'ERR_PALETTE_GENERATION',
-      when: 'the request, seed, stop layout, mode, or anchor constraint is invalid',
+      when: 'the config is not valid JSON; the request, seed, stop layout, mode or anchor is invalid; out does not end in .ts or .json; or preview does not end in .html',
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
       when: 'an input or output path escapes cwd, or output would replace input',
     },
-    {code: 'ERR_WRITE_FAILED', when: 'the candidate pair cannot be written'},
+    {
+      code: 'ERR_WRITE_FAILED',
+      when: 'the candidate, receipt or preview file cannot be written',
+    },
   ],
   examples: [
     {
-      label: 'Preview a candidate',
+      label: 'Generate a candidate without writing files',
       code: "themePaletteGenerate('palette.config.json');",
     },
     {
@@ -83,5 +90,5 @@ export const doc = {
     },
   ],
   command: 'theme palette generate',
-  related: ['themeBuild', 'themeTemplate'],
+  related: ['generateTonalPalette', 'themeBuild', 'themeTemplate'],
 };

package/api/theme/themeTargets.doc.mjs

@@ -22,7 +22,7 @@ export const doc = {
     'Same source as the Theming table `astryx component <Name>` prints ' +
     '(the component docs), so the list cannot drift from the components, and `theme build` ' +
     'validates overrides against this exact set. A filter naming a component gives that ' +
-    "component's set; anything else is a substring search over the keys.",
+    "component's set; anything else is a case-insensitive substring search over each target's key, class and component.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeTargets(filter?: string, ctx?: {cwd?: string}): Promise<ThemeTargetsResponse>',
@@ -41,13 +41,14 @@ export const doc = {
       name: 'filter',
       type: 'string',
       description:
-        'A component name (exact, case-insensitive) or a substring of a target key. Omit for the whole surface.',
+        'A component name (exact, case-insensitive), or a substring of a target key, class or component. Omit for the whole surface.',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description:
         "Directory the project's @astryxdesign/core is resolved from.",
+      default: 'process.cwd()',
     },
   ],
   returns: [

package/api/theme/themeTemplate.doc.mjs

@@ -43,6 +43,7 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory the target path resolves against.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -64,5 +65,5 @@ export const doc = {
     },
   ],
   command: 'theme template',
-  related: ['themeAdd', 'themeBuild', 'themeList'],
+  related: ['themeAdd', 'themeBuild', 'themeListAvailable', 'themeTargets'],
 };

package/api/upgrade/run/run.mjs

@@ -114,7 +114,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
   // Resolve the source dir against the API's cwd (not process.cwd()) so a
   // programmatic caller in another directory scans the right tree. Confine it to
   // cwd: --apply rewrites files in place, so a `..`-escaping or out-of-tree
-  // absolute --path must be rejected (parity with template/theme/swizzle,
+  // absolute --path must be rejected (parity with template/theme/swizzle/layout,
   // and this is the most destructive command). allowAbsolute permits an absolute
   // path that still resolves inside cwd.
   let path_;

package/api/upgrade/upgrade.doc.mjs

@@ -13,19 +13,16 @@ export const doc = {
   name: 'upgrade',
   namespace: 'cli/api',
   displayName: 'upgrade()',
-  summary: 'Run version migrations and reconcile copied compositions.',
+  summary:
+    'After bumping @astryxdesign/core, migrate project source with codemods and update copied compositions.',
   description:
-    'Migrates project source from a previous Astryx version to the currently ' +
-    'installed one by running the registered codemods, and compares the fully ' +
-    'rendered managed agent-docs block on every migration path, including ' +
-    'same-Core integration guidance changes; list and registry-only modes do not ' +
-    'run migration reconciliation. Dry-run previews without writing; `apply` ' +
-    'writes the prepared block only after selected codemods and hooks succeed. ' +
-    'Core codemods run before ' +
-    'the config is loaded so a config codemod can repair an otherwise-invalid ' +
-    'astryx.config. Copied compositions carry adjacent receipts with exact canonical and format-specific install bases; upgrade ' +
-    'compares those installed bases with the matching registry release, updates pristine ' +
-    'files, merges non-overlapping edits, and leaves conflicting originals untouched.',
+    'Runs the codemods between `from` and the installed Core version, then refreshes the ' +
+    'managed agent-docs block. Dry-run by default; `apply` writes changes only after the ' +
+    'selected codemods and hooks succeed. Config codemods run before astryx.config is ' +
+    'loaded, so they can repair an invalid config. Also updates copied compositions from ' +
+    'their install receipts: unchanged files are updated, non-overlapping edits are merged, ' +
+    'and conflicts are left untouched. `list` only lists codemods; `registry` only updates ' +
+    'copied compositions.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'upgrade(options?: UpgradeOptions, ctx?: {cwd?: string}): Promise<UpgradeListResponse | UpgradeRegistryResponse | UpgradeStatusResponse | UpgradeRunResponse>',
@@ -42,7 +39,7 @@ export const doc = {
       name: 'options.from',
       type: 'string',
       description:
-        'Version before the dependency bump. Required unless `list` or `registry` is set.',
+        'Version before the dependency bump; the target is the installed @astryxdesign/core (or legacy @xds/core). Required unless `list` or `registry` is set.',
     },
     {
       name: 'options.apply',
@@ -55,11 +52,13 @@ export const doc = {
       type: 'boolean',
       description:
         'Run codemods even when `from` is at/after the installed version.',
+      default: 'false',
     },
     {
       name: 'options.codemod',
       type: 'string',
-      description: 'Run a single named transform instead of the full set.',
+      description:
+        'Run only this codemod. Optional codemods run only when named here. Setting it also skips copied-composition reconciliation.',
     },
     {
       name: 'options.skipCodemod',
@@ -83,23 +82,26 @@ export const doc = {
       type: 'boolean',
       description:
         'Install jscodeshift when it is missing; otherwise a missing jscodeshift throws ERR_DEP_MISSING.',
+      default: 'false',
     },
     {
       name: 'options.registry',
       type: 'boolean',
       description:
-        'Reconcile copied compositions from their install receipts without requiring `from`.',
+        'Only reconcile copied compositions from their install receipts; `from` is not required. Cannot be combined with `list`, `from`, `force`, `codemod`, `skipCodemod`, `integration` or `installDeps`.',
       default: 'false',
     },
     {
       name: 'options.list',
       type: 'boolean',
       description: 'Return the available codemods instead of running any.',
+      default: 'false',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description: 'Directory to run the upgrade in.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -116,36 +118,36 @@ export const doc = {
     {
       type: 'upgrade.status',
       description:
-        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). Each carries the agent-docs summary and, when found, the copied-composition registry summary.',
+        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). up_to_date and no_codemods carry the agent-docs summary and, when receipts are found, the copied-composition summary; config_fixable carries configError, configCodemods, suggestedCommand, message, note, and the agent-docs summary.',
     },
     {
       type: 'upgrade.run',
       description:
-        'The terminal run receipt: from/to versions, codemod count, integrations processed, agent-docs and registry summaries, modifiedFiles, protectedFiles, declinedCandidates, and completion state. A protected required change returns complete: false with ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
+        'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), filesChanged, transformsApplied, modifiedFiles, protectedFiles, declinedCandidates, errors, and complete. When a protected file still requires a change, complete is false and errorCode is ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
     },
   ],
   throws: [
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: '`from` is missing (and neither `list` nor `registry` is set), or the project config fails strict validation and no pending config codemod can repair it',
+      when: '`from` is missing (and neither `list` nor `registry` is set); `list` and `registry` are both set; `registry` is combined with `from`, `force`, `codemod`, `skipCodemod`, `integration` or `installDeps`; an `integration` specifier is invalid or not installed; or astryx.config fails to load or validate and no pending config codemod repairs it',
     },
     {code: 'ERR_INVALID_VERSION', when: '`from` is not a valid semver string'},
     {code: 'ERR_PATH_TRAVERSAL', when: '`path` resolves outside cwd'},
     {
       code: 'ERR_VERSION_DETECT',
-      when: 'the installed @astryxdesign/core version cannot be detected',
+      when: 'neither @astryxdesign/core nor legacy @xds/core is installed in cwd; with `registry`, only when copied-composition receipts exist and @astryxdesign/core is not installed',
     },
     {
       code: 'ERR_DEP_MISSING',
-      when: 'jscodeshift is required but could not be installed',
+      when: 'jscodeshift is missing and `installDeps` is not set, or installing it failed',
     },
     {
       code: 'ERR_UNKNOWN_CODEMOD',
-      when: 'a `codemod` name matches no registered codemod',
+      when: 'the version range has codemods but none remain selected: `codemod` names no codemod in the range, or `skipCodemod` excludes all of them',
     },
     {
       code: 'ERR_CODEMOD_FAILED',
-      when: 'one or more codemods failed, or a post-codemod hook failed',
+      when: 'one or more codemods failed, or a post-codemod hook failed, and no protected file still needs a change (otherwise an upgrade.run receipt with complete: false is returned)',
     },
     {
       code: 'ERR_CODEMOD_PROTECTION_SOURCE',

package/assets/docs/README.md

@@ -21,13 +21,15 @@ Someone building a product with Astryx. Their questions:
 ## Tells that you are writing for us instead
 
 - second person aimed at the wrong reader — "reviewers should…", "before promoting a component…", "attach evidence for…"
-- **rubric, readiness, gate, audit, checklist, sign-off, promotion, evidence** as things the reader must produce
+- an internal rubric, readiness gate, audit checklist, or sign-off that the reader must satisfy for Astryx maintainers
 - a table of things to verify rather than things to use
 - anything about lab → core, which is our lifecycle, not theirs
 - Storybook, Playwright, CI or the Simulator named as tools the reader runs
 
 One subtlety: a statement about the **system's behavior** is caller-facing even when it sounds like process. "A component's theme targets are stable once published" tells a caller what they can rely on; "reviewers must check that theme targets are stable" is ours. Same fact, different reader — **rewrite it rather than move it**.
 
+A public authoring-quality rubric is also caller-facing when it helps someone evaluate an artifact they create through Astryx. It must be complete and actionable from public inputs. It must not include Astryx's internal approval, promotion, evidence-publication, or CI process. A current system spec must assign the shipped guide as the rubric's owner.
+
 ## Where the rest goes
 
 The material is usually good; the finding is placement, not quality. It goes in the [wiki](https://github.com/facebook/astryx/wiki) — **as a section on the page that already covers it, not a new page.** The wiki is at nearly 60 pages, several of them overlapping, because every stray section got its own.
@@ -55,5 +57,5 @@ Worked example: a responsive-and-interaction readiness rubric is grading criteri
 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
+a key. Keep each section small enough to read on its own: `astryx doctor` warns on
 any section over 32 KB.