@astryxdesign/cli 0.6.3-canary.7ada42e → 0.6.3-canary.7ec7be0

package/clients/cli/commands/doctor-integration.test.mjs

@@ -2,9 +2,16 @@
 
 /**
  * @file Command-level coverage for `astryx doctor integration` authoring checks.
+ * @input Integration fixtures and the post-0.7 conflict projection.
+ * @output Assertions for human and typed command responses.
+ * @position CLI adapter coverage; 0.6.x API shape is verified separately.
  */
 
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+vi.mock('../../../foundation/discovery/template-conflict-release.mjs', () => ({
+  expandedTemplateConflictSchemaActive: () => true,
+}));
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {Command} from 'commander';
@@ -31,6 +38,8 @@ function writeIntegration({
   id,
   name = 'Integration template',
   missingRoot = false,
+  replacements,
+  type = 'page',
 }) {
   fs.writeFileSync(
     path.join(tmpDir, 'package.json'),
@@ -45,7 +54,7 @@ function writeIntegration({
   fs.mkdirSync(path.dirname(stem), {recursive: true});
   fs.writeFileSync(
     `${stem}.doc.mjs`,
-    `export default {type: 'page', name: ${JSON.stringify(name)}, description: 'fixture'};\n`,
+    `export default {type: '${type}', name: ${JSON.stringify(name)}, description: 'fixture'${replacements?.[id] == null ? '' : `, replaces: ${JSON.stringify(replacements[id])}`}};\n`,
   );
   fs.writeFileSync(
     `${stem}.tsx`,
@@ -249,6 +258,71 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBeUndefined();
   });
 
+  it('templates reports an intentional replacement and the Core-original command', async () => {
+    const core = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(core).toBeDefined();
+    writeIntegration({
+      id: 'acme-app-shell',
+      type: core.type,
+      replacements: {'acme-app-shell': core.dirName},
+    });
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      '--json',
+      'doctor',
+      'integration',
+      'templates',
+    ]);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.data.issues).toEqual([]);
+    expect(parsed.data.conflicts).toEqual([
+      expect.objectContaining({
+        id: 'acme-app-shell',
+        relationship: 'replaces',
+        replaces: core.dirName,
+        severity: 'info',
+      }),
+    ]);
+    expect(parsed.data.conflicts[0].command).toContain(
+      `--package @astryxdesign/core`,
+    );
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('templates exits 1 for a missing replacement target', async () => {
+    writeIntegration({
+      id: 'acme-app-shell',
+      replacements: {'acme-app-shell': 'missing-core-shell'},
+    });
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      '--json',
+      'doctor',
+      'integration',
+      'templates',
+    ]);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          severity: 'error',
+        }),
+      ]),
+    );
+    expect(process.exitCode).toBe(1);
+  });
+
   it('templates exits 1 when structural errors prevent a trustworthy check', async () => {
     writeIntegration({missingRoot: true});
     process.chdir(tmpDir);

package/clients/cli/commands/doctor.mjs

@@ -3,7 +3,12 @@
 /**
  * @file `astryx doctor` project health and integration-authoring diagnostics.
  * Human output uses plain stable tokens; every leaf also has a typed JSON
- * response. Exit 1 means a check found an error, while warnings remain exit 0.
+ * response. Template-conflict fields follow the package release boundary.
+ * Exit 1 means a check found an error, while warnings remain exit 0.
+ *
+ * @input Typed Doctor and integration-authoring API responses.
+ * @output Human-readable records or pass-through typed JSON.
+ * @position CLI presentation adapter for project and integration health.
  */
 
 import {runChecks} from '../../../api/doctor/doctor.mjs';
@@ -125,25 +130,41 @@ function printTemplateConflicts(data) {
     ),
     ...issueBlocks(data.issues),
   ];
-  if (data.conflicts.length === 0) {
+  if (data.conflicts.length === 0 && data.issues.length === 0) {
     output.push(text('[ok] No template ids conflict with Core.'));
-  } else {
+  } else if (data.conflicts.length > 0) {
+    const expanded = data.conflicts.some(
+      conflict => 'relationship' in conflict,
+    );
     output.push(
       records(data.conflicts, {
-        fields: [
-          'severity',
-          'id',
-          'integrationPackage',
-          'integrationType',
-          'integrationName',
-          'message',
-          'command',
-        ],
+        fields: expanded
+          ? [
+              'severity',
+              'relationship',
+              'id',
+              'replaces',
+              'integrationPackage',
+              'integrationType',
+              'integrationName',
+              'message',
+              'command',
+            ]
+          : [
+              'severity',
+              'id',
+              'integrationPackage',
+              'integrationType',
+              'integrationName',
+              'message',
+              'command',
+            ],
         format: {severity: statusToken},
       }),
       text(
-        `${data.conflicts.length} Core template conflict(s). ` +
-          'Renaming is recommended but optional; keep the package-qualified command if the overlap is intentional.',
+        expanded
+          ? `${data.conflicts.length} Core template relationship(s).`
+          : `${data.conflicts.length} Core template conflict(s). Renaming is recommended but optional; keep the package-qualified command if the overlap is intentional.`,
       ),
     );
   }
@@ -165,7 +186,13 @@ function printComponentConflicts(data) {
   } else {
     output.push(
       records(data.conflicts, {
-        fields: ['severity', 'name', 'integrationPackage', 'message', 'command'],
+        fields: [
+          'severity',
+          'name',
+          'integrationPackage',
+          'message',
+          'command',
+        ],
         format: {severity: statusToken},
       }),
       text(
@@ -187,6 +214,15 @@ function printDocConflicts(data) {
     ),
     ...issueBlocks(data.issues),
   ];
+  if (
+    !data.issues.some(
+      issue => issue.severity === 'error' || issue.code === 'invalid_doc_graph',
+    )
+  ) {
+    output.push(
+      text('[ok] The docs tree and every link in these docs check out.'),
+    );
+  }
   if (data.findings.length === 0) {
     output.push(text('[ok] No doc topics overlap with Core.'));
   } else {
@@ -272,7 +308,8 @@ async function runAuthoringCheck(program, pkg, kind) {
   const structuralErrors = summarizeIssues(result.data.issues).errors;
   const docErrors =
     result.type === 'integration.doc-conflicts'
-      ? result.data.findings.filter(finding => finding.severity === 'error').length
+      ? result.data.findings.filter(finding => finding.severity === 'error')
+          .length
       : 0;
   if (structuralErrors > 0 || docErrors > 0) process.exitCode = 1;
   return NO_RESULT_SET;

package/clients/cli/commands/integration-add.doc.mjs

@@ -50,6 +50,12 @@ export const doc = {
       description:
         'Existing doc topic this one extends (letters, digits, _ and -); only valid for doc and not with --replaces',
     },
+    {
+      flag: '--parent <namespace>',
+      param: 'options.parent',
+      description:
+        "Namespace of this package to place the doc in, as a guide in its `guides` slot; writes the namespace doc when it is missing, and declares the CLI that reads it as an optional `@astryxdesign/cli` peer. Only valid for doc, and not with --replaces or --extends",
+    },
     {
       flag: '--to <version>',
       param: 'options.to',
@@ -79,6 +85,10 @@ export const doc = {
       label: 'Extend a doc topic',
       cli: 'astryx integration add doc acme-theming --extends theme',
     },
+    {
+      label: 'Add a guide to the package\'s own docs section',
+      cli: 'astryx integration add doc deploying --parent acme',
+    },
     {
       label: 'Add a codemod',
       cli: 'astryx integration add codemod rename-widget --to 1.2.0',

package/clients/cli/commands/integration.mjs

@@ -58,6 +58,7 @@ export function registerIntegration(program) {
           templateType: options.type,
           replaces: options.replaces,
           extends: options.extends,
+          parent: options.parent,
           to: options.to,
         });
       } catch (error) {

package/clients/cli/commands/search.mjs

@@ -49,7 +49,7 @@ export function registerSearch(program) {
 
       try {
         const project = await Project.load(process.cwd());
-        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+        await warnOnIntegrationIssues(project, {json});
       } catch {
         // Never let the nudge break the command.
       }
@@ -115,7 +115,9 @@ export function registerSearch(program) {
       const fields = options.verbose
         ? [
             'name',
+            'section',
             'domain',
+            'package',
             'title',
             'displayName',
             'kind',
@@ -124,16 +126,20 @@ export function registerSearch(program) {
             'import',
             'description',
             'command',
+            'parent',
           ]
         : [
             'name',
+            'section',
             'domain',
+            'package',
             'title',
             'displayName',
             'kind',
             'import',
             'description',
             'command',
+            'parent',
           ];
 
       // The heading mirrors the JSON: `matchCount` is what matched, and the
@@ -145,7 +151,10 @@ export function registerSearch(program) {
             ? `Results for "${q}" (${results.length} of ${matchCount})`
             : `Results for "${q}" (${results.length})`,
         ),
-        records(results, {fields, format: {command: formatCliCommand}}),
+        records(results, {
+          fields,
+          format: {command: formatCliCommand, parent: formatCliCommand},
+        }),
       );
       return answered;
     },

package/clients/cli/commands/setup-nudge.test.mjs

@@ -89,6 +89,12 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
   });
 
+  it('is quiet in an integration package, which is not an app', async () => {
+    asProject();
+    write('astryx.integration.mjs', 'export default {};\n');
+    expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
+  });
+
   it('does not nudge for the installer command itself', async () => {
     asProject();
     expect((await runCli(['init'], tmp)).stderr).not.toMatch(NUDGE);

package/clients/cli/commands/template.doc.mjs

@@ -18,9 +18,11 @@ export const doc = {
   description:
     'One entry point for the template family: with no name it lists the discovered ' +
     'templates; with a name it shows the source or a layout skeleton, or scaffolds it ' +
-    'into the project at a target path. Narrow an ambiguous name with --type and/or --package. ' +
-    '--cdn writes the no-build-step CDN starter page, which ships as an asset rather than as ' +
-    'a discovered template.',
+    'into the project at a target path. A configured integration replacement is the ' +
+    'default for its Core id; use --package @astryxdesign/core for the original. ' +
+    'Narrow other ambiguous names with --type and/or --package. --cdn writes the ' +
+    'no-build-step CDN starter page, which ships as an asset rather than as a ' +
+    'discovered template.',
   fn: 'template',
   args: [
     {
@@ -55,7 +57,8 @@ export const doc = {
     {
       flag: '--package <pkg>',
       param: 'options.package',
-      description: 'Narrow to templates from a specific package',
+      description:
+        'Narrow to templates from a specific package. Use @astryxdesign/core to select an original hidden by an integration replacement.',
     },
     {
       flag: '--skeleton',
@@ -81,15 +84,29 @@ export const doc = {
   ],
   examples: [
     {label: 'List templates', cli: 'astryx template --json'},
+    {
+      label: 'List exact Core ids',
+      cli: 'astryx --json template --list --package @astryxdesign/core',
+    },
     {
       label: 'Scaffold into the app',
       cli: 'astryx template dashboard ./src/app',
     },
+    {
+      label: 'Select a replaced Core original',
+      cli: 'astryx template shell-side-nav ./src/app --package @astryxdesign/core',
+    },
     {label: 'CDN starter page', cli: 'astryx template --cdn'},
-    {label: 'CDN starter page, elsewhere', cli: 'astryx template --cdn public/demo.html'},
+    {
+      label: 'CDN starter page, elsewhere',
+      cli: 'astryx template --cdn public/demo.html',
+    },
   ],
   exitCodes: [
-    {code: 0, when: 'success, including a CDN page left untouched because it already exists'},
+    {
+      code: 0,
+      when: 'success, including a CDN page left untouched because it already exists',
+    },
     {
       code: 1,
       when: 'unknown or ambiguous template, no source, a path escape, or an existing target without --overwrite',

package/clients/cli/commands/template.mjs

@@ -4,12 +4,9 @@
  * @file template command — thin CLI wrapper around api/template.mjs
  */
 
-import * as path from 'node:path';
-import * as fs from 'node:fs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
 import {emit, section, text, records, code} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
-import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {template as templateApi} from '../../../api/template/template.mjs';
 import {Project} from '../../../foundation/config/project.mjs';
 import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
@@ -21,18 +18,6 @@ import {doc as templateFn} from '../../../api/template/template.doc.mjs';
 
 export {discoverTemplates, listTemplates} from '../../../api/template/template.mjs';
 
-/**
- * A template entry as produced by the discover* helpers in api/template.mjs.
- * The api layer returns these as `object[]`; this local shape captures the
- * fields the command consumes. Remove once api/template.mjs exports a precise
- * type for its discovered templates.
- * @typedef {object} DiscoveredTemplate
- * @property {'page' | 'block'} type
- * @property {string} dirName
- * @property {string} name
- * @property {string} filePath
- */
-
 /**
  * The discriminated response returned by the template API. The api layer
  * currently declares `{type: string, data: unknown}`; narrow it here to the
@@ -89,36 +74,11 @@ export function registerTemplate(program) {
       // doctor integration validate. Best-effort; suppressed in --json mode.
       try {
         const project = await Project.load(process.cwd());
-        await warnOnIntegrationIssues(
-          /** @type {Array<import('../../../foundation/integrations/integrations.mjs').LoadedIntegration>} */ (
-            project.loadedIntegrations
-          ),
-          {json},
-        );
+        await warnOnIntegrationIssues(project, {json});
       } catch {
         // Never let the nudge break the command.
       }
 
-      // Pre-flight overwrite check (only when we'd actually copy a file).
-      // The API resolves the destination; we need to mirror its logic
-      // narrowly enough to detect collisions before invoking it.
-      if (
-        name &&
-        targetPath &&
-        !options.list &&
-        !options.skeleton &&
-        !options.cdn
-      ) {
-        const collision = await detectTemplateCollision(name, targetPath);
-        if (collision && !options.overwrite) {
-          const rel = path.relative(process.cwd(), collision) || collision;
-          const msg =
-            `Refusing to overwrite existing file ${rel}. ` +
-            `Re-run with --overwrite (or -f) to replace it.`;
-          return cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
-        }
-      }
-
       /** @type {TemplateResponse} */
       let result;
       try {
@@ -156,12 +116,14 @@ export function registerTemplate(program) {
           // isn't the built-in core package.
           /** @param {import('../../../api/template/template.type.mjs').TemplateListEntry} t */
           const toRow = t => ({
+            id: t.id,
             name: t.isReady ? t.name : `${t.name} (WIP)`,
             description: t.description,
             package:
               t.package && t.package !== '@astryxdesign/core' ? t.package : '',
+            replaces: t.replaces ?? '',
           });
-          const fields = ['name', 'description', 'package'];
+          const fields = ['id', 'name', 'description', 'package', 'replaces'];
           emit(
             pages.length > 0 && section('Page Templates'),
             pages.length > 0 && records(pages.map(toRow), {fields}),
@@ -229,52 +191,3 @@ export function registerTemplate(program) {
     },
   });
 }
-
-/**
- * Mirror the destination-resolution logic in api/template.mjs so we can
- * detect a clobber before invoking the API.
- *
- * Returns the absolute destination file path if it already exists, or
- * `null` otherwise (template missing, no collision, or list/skeleton mode).
- *
- * Path-safety enforcement happens inside the API; here we only need
- * enough precision to check existence — a false negative just means the
- * API will catch the issue and abort.
- *
- * @param {string} name
- * @param {string} targetPath
- * @returns {Promise<string | null>}
- */
-async function detectTemplateCollision(name, targetPath) {
-  const {discoverTemplates} = await import('../../../api/template/template.mjs');
-  /** @type {DiscoveredTemplate[]} */
-  let templates;
-  try {
-    templates = /** @type {DiscoveredTemplate[]} */ (
-      await discoverTemplates(process.cwd())
-    );
-  } catch {
-    return null;
-  }
-  const match = templates.find(t => t.dirName === name);
-  if (!match) return null;
-
-  // Resolve target as the API will. We can't call assertWithin here
-  // because the API does it itself; we just need to know "is there a
-  // file at the destination?".
-  const resolved = path.resolve(process.cwd(), targetPath);
-
-  // File-arg branch: targetPath looks like `./foo.tsx`.
-  const {isFilePathArg} = await import('../../../foundation/fs/path-safety.mjs');
-  let dest;
-  if (isFilePathArg(targetPath)) {
-    dest = resolved;
-  } else {
-    const fileName = match.type === 'block'
-      ? path.basename(match.filePath)
-      : 'page.tsx';
-    dest = path.join(resolved, fileName);
-  }
-
-  return fs.existsSync(dest) ? dest : null;
-}

package/clients/cli/index.mjs

@@ -276,6 +276,12 @@ const commands = [
 ];
 
 const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
+/** An integration package's manifest: the package is not an app to set up. */
+const INTEGRATION_MANIFEST_FILES = [
+  'astryx.integration.ts',
+  'astryx.integration.mjs',
+  'astryx.integration.js',
+];
 
 /**
  * Build a fresh, fully-wired Astryx CLI program (root options, hooks, all
@@ -519,6 +525,8 @@ export async function createProgram() {
       if (SETUP_NUDGE_EXEMPT.has(actionCommand.name())) return;
       const cwd = process.cwd();
       if (!fs.existsSync(path.join(cwd, 'package.json'))) return; // not a project
+      // An integration package is not an app: `init` is not its next step.
+      if (INTEGRATION_MANIFEST_FILES.some(file => fs.existsSync(path.join(cwd, file)))) return;
       if (isAstryxInitialized(cwd)) return; // already set up — stay quiet
       // Same wording as the core/cli postinstall nudges. #4151's getCliInvocation()
       // renders the correct form for THIS project — scoped `npx @astryxdesign/cli`

package/clients/cli/lib/manifest.mjs

@@ -57,7 +57,13 @@ export const RESPONSE_TYPES = {
     'component.detail.showcase',
     'component.detail.blocks',
   ],
-  docs: ['docs.list', 'docs.index', 'docs.detail', 'docs.detail.section'],
+  docs: [
+    'docs.list',
+    'docs.index',
+    'docs.detail',
+    'docs.detail.section',
+    'docs.node',
+  ],
   blog: ['blog.list', 'blog.detail'],
   discover: [
     'discover.list',
@@ -110,8 +116,9 @@ const EXAMPLES = {
   docs: [
     'astryx docs',
     'astryx docs spacing --json',
-    'astryx docs theme --index',
+    'astryx docs theme',
     'astryx docs theme quick-start',
+    'astryx docs cli/integrations --full',
   ],
   discover: ['astryx discover --json'],
   search: [

package/foundation/agent-docs/agent-docs.d.mts

@@ -78,8 +78,9 @@ export function detectStylingSystem(targetDir: string): "stylex" | "tailwind" |
  * Generate the agent cheat sheet from live CLI metadata.
  *
  * Structured as: workflow (behavioral) → rules (error prevention) → CLI reference.
- * Templates are positioned first in the workflow to teach agents the
- * "look at reference code" reflex before writing any UI.
+ * Templates lead the workflow: every page starts from a scaffolded template,
+ * because the template already carries the frame and spacing that an agent
+ * composing from components would have to re-derive, and usually gets wrong.
  *
  * `stylingSystem` tailors the custom-styling guidance to what the project has
  * configured (see {@link detectStylingSystem}) so the agent never reaches for a

package/foundation/agent-docs/agent-docs.mjs

@@ -354,8 +354,9 @@ export function detectStylingSystem(targetDir) {
  * Generate the agent cheat sheet from live CLI metadata.
  *
  * Structured as: workflow (behavioral) → rules (error prevention) → CLI reference.
- * Templates are positioned first in the workflow to teach agents the
- * "look at reference code" reflex before writing any UI.
+ * Templates lead the workflow: every page starts from a scaffolded template,
+ * because the template already carries the frame and spacing that an agent
+ * composing from components would have to re-derive, and usually gets wrong.
  *
  * `stylingSystem` tailors the custom-styling guidance to what the project has
  * configured (see {@link detectStylingSystem}) so the agent never reaches for a
@@ -428,17 +429,19 @@ export function generateCompressedIndex(
   lines.push('  import "@astryxdesign/core/astryx.css";');
   lines.push('');
 
-  // Workflow — `build` is the front door; discover before writing UI.
-  lines.push("WORKFLOW — discover, don't guess. Before writing UI:");
-  lines.push('1. `astryx build "<idea>"` — START HERE: returns a kit (closest [page] + [block]s + [component]s). No args = full playbook.');
-  lines.push('2. `astryx template <name> [--skeleton]` — scaffold the [page]/[block]s it named, or study their layout. Templates are reference code.');
-  lines.push('3. `astryx component <Name>` — props + examples for every component you use.');
+  // Workflow — `build` is the front door, and every page starts from the
+  // template it names.
+  lines.push('WORKFLOW — start every page from a template. Never lay out a page from scratch:');
+  lines.push('1. `astryx build "<idea>"` — START HERE: names the [page] template to start from (always one: the closest match, or the app shell), two other templates, and the [block]s + [component]s for parts it lacks. No args = full playbook.');
+  lines.push('2. `astryx template <name> <path>` — scaffold that template into your project. Keep its frame, gap and padding; replace its data, copy and sections; delete sections you do not need.');
+  lines.push('3. `astryx template <Block>` for a part the template lacks; `astryx component <Name>` for props + examples before you use or change a component.');
+  lines.push('Changing a page you already have? Keep it: skip step 2 and add blocks and components inside its sections.');
   lines.push('');
 
   // Rules — the top error-preventers.
   lines.push('RULES:');
   lines.push('- No <div> — components do all layout/spacing, page frame included.');
-  lines.push('- Frame first: read `astryx docs layout` before writing any page or screen — page frame, region widths, breakpoint behavior.');
+  lines.push('- Frame first: the template you scaffold sets the page frame. Read `astryx docs layout` before you change it — region widths, breakpoint behavior.');
   lines.push('- Dense data = rows (Table, List/Item), never Card-wrapped list items; Card is for standalone widgets. Status = StatusDot/Token; Badge = counts only.');
   // Styling guidance tailored to the project's configured system — never
   // recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
@@ -463,7 +466,7 @@ export function generateCompressedIndex(
     css: 'replace any raw <div>/<span> layout, imported .css/@apply, or hardcoded value (#hex, 16px) with the component or a token (var(--color-*|--spacing-*|…))',
   };
   lines.push(
-    `- SELF-CHECK before you finish: re-read the file and ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}. If unsure a component/prop exists, run \`astryx component <Name>\` / \`astryx search "<thing>"\`; don't hand-roll CSS.`,
+    `- SELF-CHECK before you finish: re-read the file and ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}. Confirm the page kept its template's frame, gap and padding. If unsure a component/prop exists, run \`astryx component <Name>\` / \`astryx search "<thing>"\`; don't hand-roll CSS.`,
   );
   lines.push('');
 
@@ -486,6 +489,7 @@ export function generateCompressedIndex(
   if (resolvedTopics.length > 0) {
     lines.push(`  docs <topic>       ${resolvedTopics.join(', ')}`);
   }
+  lines.push('  docs cli           commands, API reference, integration authoring (one level at a time)');
   lines.push('  swizzle <Name>     eject component source for deep customization');
   lines.push('  upgrade --apply    run after any Astryx or integration dependency bump');
   const appendCount = agentDocs.reduce(