@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme add',
   displayName: 'astryx theme add',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Scaffold a theme into your project as editable source',
   description:
     "Copies a bundled or installed integration theme's source into your project so you own it. " +
@@ -49,7 +49,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown or ambiguous theme, a path escape, a missing catalog file, or an existing file without --overwrite',
+      when: 'unknown or ambiguous theme, a path escape, a missing descriptor or source, or an existing file without --overwrite',
     },
   ],
   related: ['theme list', 'theme build'],

package/clients/cli/commands/theme-build.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme build',
   displayName: 'astryx theme build',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Compile standalone themes or one keyed theme family',
   description:
     'Compiles defineTheme() sources through the same theme pipeline into scoped CSS, ' +

package/clients/cli/commands/theme-list.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme list',
   displayName: 'astryx theme list',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List themes available to add',
   description:
     'Lists themes bundled with this CLI and source themes contributed by installed integrations, ' +
@@ -37,7 +37,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'the bundled-theme manifest or an installed theme catalog cannot be read',
+      when: 'a bundled or installed theme descriptor cannot be read',
     },
   ],
   related: ['theme add', 'theme build'],

package/clients/cli/commands/theme-palette-generate.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'theme palette generate',
   displayName: 'astryx theme palette generate',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Generate an OKLCH palette candidate for human review',
   description:
     'Reads an explicit JSON request and runs the versioned astryx-oklch-v1 recipe. ' +
@@ -21,8 +21,8 @@ export const doc = {
     'JSON is also supported. Existing author-owned files are left untouched unless --overwrite is explicit. ' +
     'When used in a theme integration, keep the palette request under the theme slug, ' +
     'write the candidate and receipt under that same slug, import the candidate from the theme source, ' +
-    "and list all three paths in the theme catalog entry's `files` array " +
-    'so `astryx theme add` copies them into the consumer project.',
+    'and keep all three inside the theme directory: `astryx theme add` copies that whole ' +
+    'directory into the consumer project, so nothing else has to list them.',
   fn: 'themePaletteGenerate',
   args: [{name: 'config', param: 'configPath', required: true}],
   options: [

package/clients/cli/commands/theme-palette.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'theme palette',
   displayName: 'astryx theme palette',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Create and work with theme-owned color palettes',
   description:
     'Palette authoring tools. The initial generate command creates reviewable candidates. ' +

package/clients/cli/commands/theme-targets.behavior.test.mjs

@@ -17,8 +17,9 @@ describe('astryx theme targets', () => {
     const {status, stdout} = await runCli(['theme', 'targets', 'Switch']);
 
     expect(status).toBe(0);
-    expect(stdout).toMatch(/^switch\s+Switch\s+size\s+checked, disabled$/m);
-    expect(stdout).toMatch(/^switch-thumb\s+Switch\s+size\s+checked$/m);
+    // Inline layout: key  component - props - states - className
+    expect(stdout).toMatch(/^switch\s+Switch - size - checked, disabled - astryx-switch$/m);
+    expect(stdout).toMatch(/^switch-thumb\s+Switch - size - checked - astryx-switch-thumb$/m);
     expect(stdout).toMatch(/4 across 1 component/);
   });
 
@@ -28,7 +29,7 @@ describe('astryx theme targets', () => {
     expect(status).toBe(0);
     expect(stdout).toMatch(/^popover\s{2,}Popover/m);
     expect(stdout).toMatch(
-      /^popover-surface \[deprecated; use popover\]\s{2,}Popover/m,
+      /^popover-surface\s{2,}Popover - astryx-popover-surface - deprecated; use popover$/m,
     );
   });
 

package/clients/cli/commands/theme-targets.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme targets',
   displayName: 'astryx theme targets',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List the component theming targets a theme can override',
   description:
     'Prints every `defineTheme` components key across the system: the stable class it paints, ' +

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'theme template',
   displayName: 'astryx theme template',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Write the annotated theme template into your project',
   description:
     'Writes theme.template.ts: the annotated reference for the whole theme surface, covering every ' +

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'theme',
   displayName: 'astryx theme',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Theme tools: build, export, and manage themes',
   description:
     'The theme command group. Running astryx theme with no subcommand prints the ' +

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'upgrade',
   displayName: 'astryx upgrade',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Migrate versions and update ShadCN-copied compositions',
   description:
     'Migrates project source from a previous Astryx version to the installed one by ' +
@@ -101,13 +101,14 @@ export const doc = {
     {label: 'Apply a migration', cli: 'astryx upgrade --from 0.1.0 --apply'},
   ],
   exitCodes: [
-    {code: 0, when: 'success (including dry-run previews)'},
+    {code: 0, when: 'success, including complete dry-run previews'},
     {
       code: 1,
       when:
         'missing or invalid --from, --registry with --list or a migration flag, a --path escape, ' +
         'no installed @astryxdesign/core (or legacy @xds/core), jscodeshift missing and not installed by --install-deps, ' +
         'an astryx.config that fails validation and that no pending config codemod repairs, ' +
+        'an unreadable or invalid protection declaration, a protected file that still requires a codemod change, ' +
         'an unknown codemod, a codemod or post-codemod hook failure, or unresolved registry items',
     },
   ],

package/clients/cli/commands/upgrade.file-protection.test.mjs

@@ -0,0 +1,228 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file End-to-end protection and regeneration behavior for `astryx upgrade`.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const CLI = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'bin',
+  'astryx.mjs',
+);
+let root;
+
+function write(relative, contents) {
+  const file = path.join(root, relative);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, contents);
+  return file;
+}
+
+function run(args) {
+  const result = spawnSync(
+    process.execPath,
+    [CLI, '--json', 'upgrade', ...args],
+    {
+      cwd: root,
+      encoding: 'utf8',
+      timeout: 60_000,
+      env: {...process.env, FORCE_COLOR: '0', CI: ''},
+    },
+  );
+  return {...result, envelope: JSON.parse(result.stdout)};
+}
+
+function seed({hook = false} = {}) {
+  write('package.json', JSON.stringify({name: 'consumer', private: true}));
+  write(
+    'node_modules/@astryxdesign/core/package.json',
+    JSON.stringify({name: '@astryxdesign/core', version: '0.6.0'}),
+  );
+  write('.gitattributes', 'generated/** linguist-generated=true\n');
+  const source =
+    "import {useResizable} from '@astryxdesign/core';\n" +
+    'export const usePanel = () => useResizable({minSizePx: 200});\n';
+  write('src/owned.tsx', source);
+  write('generated/panel.tsx', `// @generated\n${source}`);
+  write(
+    'astryx.config.mjs',
+    hook
+      ? `export default {hooks: {postCodemod: [{name: 'regenerate', buildCommand: () => ({command: process.execPath, args: ['-e', ${JSON.stringify("const fs=require('node:fs');const p='generated/panel.tsx';const s=fs.readFileSync(p,'utf8');fs.writeFileSync(p,s.replaceAll('minSizePx','minSize')); ")} ]})}]}};\n`
+      : 'export default {};\n',
+  );
+}
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-protected-upgrade-'));
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+const ARGS = [
+  '--from',
+  '0.5.0',
+  '--codemod',
+  'rename-resizable-pixel-bounds',
+  '--path',
+  '.',
+];
+
+describe('upgrade protected-file contract', () => {
+  it('reports the same protected candidate in dry-run and apply while retaining owned edits', () => {
+    seed();
+
+    const dry = run(ARGS);
+    expect(dry.status).toBe(1);
+    expect(dry.envelope).toMatchObject({
+      type: 'upgrade.run',
+      data: {
+        complete: false,
+        errorCode: 'ERR_CODEMOD_PROTECTED',
+        modifiedFiles: ['src/owned.tsx'],
+        protectedFiles: [
+          {
+            file: 'generated/panel.tsx',
+            reasons: ['generated'],
+            declarations: expect.arrayContaining([
+              'linguist-generated in .gitattributes:1',
+              '@generated in the leading comment block',
+            ]),
+          },
+        ],
+      },
+    });
+    expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(
+      'minSizePx',
+    );
+
+    const applied = run([...ARGS, '--apply']);
+    expect(applied.status).toBe(1);
+    expect(applied.envelope.data.protectedFiles).toEqual(
+      dry.envelope.data.protectedFiles,
+    );
+    expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(
+      'minSize: 200',
+    );
+    expect(
+      fs.readFileSync(path.join(root, 'generated/panel.tsx'), 'utf8'),
+    ).toContain('minSizePx');
+  });
+
+  it('preserves a protected config migration when strict config loading fails', () => {
+    write('package.json', JSON.stringify({name: 'consumer', private: true}));
+    write(
+      'node_modules/@astryxdesign/core/package.json',
+      JSON.stringify({name: '@astryxdesign/core', version: '0.1.3'}),
+    );
+    write(
+      'astryx.config.mjs',
+      `// @generated\nexport default {layout: {components: {KpiCard: '@/KpiCard'}}};\n`,
+    );
+    write('src/index.ts', 'export {};\n');
+
+    const result = run([
+      '--from',
+      '0.1.2',
+      '--codemod',
+      'migrate-layout-components-to-experimental',
+      '--path',
+      'src',
+      '--apply',
+    ]);
+
+    expect(result.status).toBe(1);
+    expect(result.envelope).toMatchObject({
+      type: 'upgrade.run',
+      data: {
+        complete: false,
+        errorCode: 'ERR_CODEMOD_PROTECTED',
+        protectedFiles: [expect.objectContaining({file: 'astryx.config.mjs'})],
+      },
+    });
+    expect(
+      fs.readFileSync(path.join(root, 'astryx.config.mjs'), 'utf8'),
+    ).toContain('layout');
+  });
+
+  it('fails before writes when a protection declaration cannot be parsed', () => {
+    seed();
+    write('.hgignore', 'syntax: regexp\n[bad\n');
+
+    const result = run([...ARGS, '--apply']);
+
+    expect(result.status).toBe(1);
+    expect(result.envelope).toMatchObject({
+      code: 'ERR_CODEMOD_PROTECTION_SOURCE',
+    });
+    expect(result.envelope.error).toContain('.hgignore');
+    expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(
+      'minSizePx',
+    );
+  });
+
+  it('preserves protected-file facts when regeneration fails', () => {
+    seed();
+    write(
+      'astryx.config.mjs',
+      `export default {hooks: {postCodemod: [{name: 'regenerate', buildCommand: () => ({command: process.execPath, args: ['-e', 'process.exit(7)']})}]}};\n`,
+    );
+
+    const applied = run([...ARGS, '--apply']);
+
+    expect(applied.status).toBe(1);
+    expect(applied.envelope).toMatchObject({
+      type: 'upgrade.run',
+      data: {
+        complete: false,
+        errorCode: 'ERR_CODEMOD_PROTECTED',
+        protectedFiles: [
+          expect.objectContaining({file: 'generated/panel.tsx'}),
+        ],
+        errors: [
+          expect.objectContaining({
+            codemod: 'post-codemod-hook',
+            error: expect.stringContaining('Post-codemod hook failed'),
+          }),
+        ],
+      },
+    });
+  });
+
+  it('runs declared regeneration and clears a generated-file block after reevaluation', () => {
+    seed({hook: true});
+
+    const applied = run([...ARGS, '--apply']);
+
+    expect(applied.status, applied.stderr).toBe(0);
+    expect(applied.envelope).toMatchObject({
+      type: 'upgrade.run',
+      data: {
+        complete: true,
+        modifiedFiles: ['src/owned.tsx', 'generated/panel.tsx'],
+        protectedFiles: [],
+        declinedCandidates: [],
+      },
+    });
+    expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(
+      'minSize: 200',
+    );
+    expect(
+      fs.readFileSync(path.join(root, 'generated/panel.tsx'), 'utf8'),
+    ).toContain('minSize: 200');
+
+    const second = run([...ARGS, '--apply']);
+    expect(second.status, second.stderr).toBe(0);
+    expect(second.envelope.data.complete).toBe(true);
+    expect(second.envelope.data.filesChanged).toBe(0);
+  });
+});

package/clients/cli/commands/upgrade.mjs

@@ -13,6 +13,7 @@
  */
 
 import {jsonOut, jsonError} from '../../../foundation/response/json.mjs';
+import {emit, section, records} from '../formatters/index.mjs';
 import {logger} from '../../../api/logger.mjs';
 import {AstryxError} from '../../../api/error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
@@ -33,27 +34,45 @@ export function registerUpgrade(program) {
        */
       async options => {
         const json = program.opts().json || false;
-        logger.setSilent(json);
+        const isList = Boolean(options.list);
+        // Silence the logger for --list so the handler renders from the
+        // result (parity with --json), and for --json as before.
+        // Re-enable on error so handled failures still print.
+        logger.setSilent(json || isList);
 
         /** @type {import('../../../api/upgrade/upgrade.type.mjs').UpgradeListResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRegistryResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeStatusResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRunResponse} */
         let result;
         try {
           result = await upgradeApi(options, {cwd: process.cwd()});
         } catch (e) {
-          // Handled failures throw AstryxError: --json emits the structured
-          // envelope (byte-identical to the old inline jsonError) + exits 1;
-          // human mode already saw the error line + outro via the logger, so we
-          // just set the exit code. Anything else is unexpected — let the
-          // top-level boundary in bin/astryx.mjs format it as before.
+          // Re-enable the logger so the error is visible in text mode.
+          // For --list the logger was silent; for other modes the API
+          // already printed the error before throwing.
+          logger.setSilent(json);
           if (e instanceof AstryxError) {
             if (json) jsonError(e.message, undefined, e.code);
-            else process.exitCode = 1;
+            else {
+              // The logger was silent only for --list; replay the error there.
+              // Non-list failures were already printed by the API.
+              if (isList) logger.error(e.message);
+              process.exitCode = 1;
+            }
             return NO_RESULT_SET;
           }
           throw e;
         }
 
         if (json) jsonOut(result);
+        else if (result.type === 'upgrade.list') {
+          // Render the list from the result, not the API logger, so the text
+          // carries the same fields the JSON does (name, title, version, optional).
+          emit(
+            section('Available codemods'),
+            records(result.data, {
+              fields: ['name', 'title', 'version', 'optional'],
+            }),
+          );
+        }
 
         const registrySummary =
           result.type === 'upgrade.registry'
@@ -65,6 +84,9 @@ export function registerUpgrade(program) {
                 ? result.data.registryCompositions
                 : undefined;
         if (registrySummary && !registrySummary.ok) process.exitCode = 1;
+        if (result.type === 'upgrade.run' && result.data.complete === false) {
+          process.exitCode = 1;
+        }
 
         // `--list` is the one lookup here: which migrations exist for the
         // range. Everything else migrates the project — an effect, reported by

package/clients/cli/formatters/index.mjs

@@ -152,6 +152,8 @@ function toAscii(s) {
     .replace(/[\u2018\u2019]/g, "'")
     .replace(/[\u201C\u201D]/g, '"')
     .replace(/\u2026/g, '...')
+    .replace(/\u2192/g, '->')
+    .replace(/\u2190/g, '<-')
     .replace(/\u00a0/g, ' ');
 }
 

package/clients/cli/formatters/index.test.mjs

@@ -117,6 +117,12 @@ describe('ASCII normalization', () => {
     expect(list(['Avatar \u2014 Group']).toString()).toBe('- Avatar - Group');
   });
 
+  it('converts Unicode arrows to ASCII arrows', () => {
+    expect(text('Rename items \u2192 options').toString()).toBe('Rename items -> options');
+    expect(text('options \u2190 items').toString()).toBe('options <- items');
+    expect(record({title: 'a \u2192 b'}).toString()).toBe('title: a -> b');
+  });
+
   it('leaves code verbatim (no normalization)', () => {
     expect(code('a \u2014 b').toString()).toBe('a \u2014 b');
   });

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/hook-format.mjs

@@ -9,7 +9,10 @@
  * - Brief: signature line with import hint, description, key params
  */
 
-import {discoverHooks, findHookDoc} from '../../../foundation/discovery/hook-discovery.mjs';
+import {
+  discoverHooks,
+  findHookDoc,
+} from '../../../foundation/discovery/hook-discovery.mjs';
 import {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
 import {formatAccessibility, mdCell} from './component-format.mjs';
 
@@ -23,7 +26,9 @@ function buildSignature(docs) {
   const name = docs.name;
 
   // Build params string — only top-level params (skip options.foo nested params)
-  const topParams = (docs.params || []).filter((/** @type {any} */ p) => !p.name.includes('.'));
+  const topParams = (docs.params || []).filter(
+    (/** @type {any} */ p) => !p.name.includes('.'),
+  );
   const paramStr = topParams
     .map((/** @type {any} */ p) => {
       const opt = p.required ? '' : '?';
@@ -150,7 +155,9 @@ export function formatHookCompact(docs, importPath) {
   const imp = importPath || docs.importPath;
   if (imp) {
     sections.push('## Import\n');
-    sections.push(`\`\`\`tsx\nimport { ${docs.name} } from '${imp}';\n\`\`\`\n`);
+    sections.push(
+      `\`\`\`tsx\nimport { ${docs.name} } from '${imp}';\n\`\`\`\n`,
+    );
   }
 
   // Best Practices (matches component compact)
@@ -228,7 +235,9 @@ export function formatHookBrief(docs) {
   // Key params (matches component brief 'prop, prop' line)
   const paramNames = (docs.params || [])
     .filter((/** @type {any} */ p) => !p.name.includes('.'))
-    .map((/** @type {any} */ p) => p.required ? `${p.name}: ${p.type.split('|')[0].trim()}` : p.name);
+    .map((/** @type {any} */ p) =>
+      p.required ? `${p.name}: ${p.type.split('|')[0].trim()}` : p.name,
+    );
   if (paramNames.length > 0) {
     output.push(`  ${paramNames.join(', ')}`);
   }
@@ -253,7 +262,7 @@ export async function formatHookBriefAll(coreDir) {
       const docPath = findHookDoc(coreDir, hookName);
       if (docPath) {
         try {
-          const docs = await loadDocs(docPath);
+          const docs = await loadDocs(docPath, {root: 'hooks'});
           output.push(formatHookBrief(docs));
         } catch {
           output.push(`${hookName}\n  (no docs)\n`);

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(