@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/clients/cli/lib/json-shim.mjs

@@ -29,11 +29,16 @@
  *   4. Routing unknown-subcommand attempts through the same error
  *      envelope path (so `astryx bogus-cmd --json` gets exit 1 + envelope
  *      instead of exit 0 + help envelope).
+ *   5. Emitting an error envelope, not the help envelope, when Commander
+ *      shows help because the invocation failed (`help <unknown>`, or a
+ *      command group with no subcommand), which exits 1.
  *
- * Non-JSON behavior is preserved exactly: every code path that printed
- * to stderr before still prints to stderr. Commander writes its
- * "error: ..." line via configureOutput.writeErr, which we pass
- * through verbatim outside of --json mode.
+ * Commander writes its own "error: ..." line via configureOutput.writeErr.
+ * The shim drops that line in both modes. Under --json the error envelope
+ * replaces it; in text mode `handleCommanderError` writes the Astryx line
+ * instead (`Error: <message>`, the same message the envelope carries), so
+ * a parse failure reads like every other CLI error. Other stderr output,
+ * such as help printed as the failure report, still passes through.
  */
 
 import {API_VERSION, isJsonMode, toErrorEnvelope} from '../../../foundation/response/json.mjs';
@@ -117,6 +122,35 @@ export function buildHelpEnvelope(cmd) {
   };
 }
 
+/**
+ * The error envelope for help Commander shows because the invocation failed
+ * (it then exits 1): `help <name>` for an unknown name on the root, or a
+ * command group run without a subcommand.
+ *
+ * @param {import('commander').Command} cmd the command whose help was shown
+ * @returns {ReturnType<typeof toErrorEnvelope>}
+ */
+export function buildHelpErrorEnvelope(cmd) {
+  const available = cmd.commands
+    .filter(s => !(/** @type {any} */ (s))._hidden && s.name() !== 'help')
+    .map(s => s.name());
+  if (!cmd.parent) {
+    // Commander dispatches `help <name>` with ['help', <name>, ...] in args.
+    const requested = cmd.args[1];
+    return toErrorEnvelope(
+      requested ? `unknown command '${requested}'` : 'unknown command',
+      available.map(name => ({name, reason: 'available command'})),
+      ERROR_CODES.ERR_UNKNOWN_COMMAND,
+    );
+  }
+  const group = fullNameOf(cmd);
+  return toErrorEnvelope(
+    `'${group}' needs a subcommand`,
+    available.map(name => ({name: `${group} ${name}`, reason: 'available subcommand'})),
+    ERROR_CODES.ERR_MISSING_ARGUMENT,
+  );
+}
+
 /**
  * Emit a JSON error envelope to stdout (the JSON contract uses stdout
  * for both success and error).
@@ -217,11 +251,20 @@ function applyShimRecursively(cmd) {
   });
   cmd.configureOutput({
     writeOut: (str) => process.stdout.write(str),
+    // Commander's own "error: ..." line never reaches the user. Under --json a
+    // consumer parsing both streams must not see it alongside the envelope;
+    // in text mode it is Commander's format, not Astryx's, so an invalid
+    // global option (`--lang zh-Hans`) printed `error: option '--lang
+    // <locale>' argument 'zh-Hans' is invalid…` where every other CLI error
+    // prints `Error: …`. handleCommanderError writes the Astryx line below,
+    // for both modes, from the same message.
+    //
+    // ONLY that line. Commander also writes HELP through this channel when it
+    // shows help because the invocation failed (a command group with no
+    // subcommand), and that output is still wanted in text mode.
     writeErr: (str) => {
-      // Suppress Commander's "error: ..." stderr line when --json is
-      // active, so a JSON consumer parsing both streams doesn't see
-      // it alongside the envelope. Non-JSON callers are unaffected.
       if (jsonActive()) return;
+      if (/^error:\s/i.test(str)) return;
       process.stderr.write(str);
     },
   });
@@ -310,7 +353,9 @@ function patchOutputHelp(cmd) {
     if (jsonActive()) {
       if (!process.__xdsJsonHandled) {
         process.__xdsJsonHandled = true;
-        const env = buildHelpEnvelope(cmd);
+        const env = contextOptions?.error
+          ? buildHelpErrorEnvelope(cmd)
+          : buildHelpEnvelope(cmd);
         process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
       }
       return;
@@ -334,7 +379,9 @@ function patchPrototype(CommandCtor) {
     if (jsonActive()) {
       if (!process.__xdsJsonHandled) {
         process.__xdsJsonHandled = true;
-        const env = buildHelpEnvelope(this);
+        const env = contextOptions?.error
+          ? buildHelpErrorEnvelope(this)
+          : buildHelpEnvelope(this);
         process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
       }
       return;
@@ -396,16 +443,15 @@ export function handleCommanderError(err) {
     code: commanderCodeToErrorCode(code, message),
   });
 
-  // Real error paths.
+  // Real error paths. Strip Commander's "error: " prefix once: in the envelope
+  // the key is already `error`, and in text mode the Astryx prefix replaces it.
+  const cleaned = message.replace(/^error:\s*/i, '');
   if (jsonActive()) {
-    // Strip Commander's "error: " prefix — the envelope key is `error`
-    // already, doubled "error" is noise.
-    const cleaned = message.replace(/^error:\s*/i, '');
     emitJsonError(cleaned, undefined, commanderCodeToErrorCode(code, cleaned));
   } else {
-    // Non-JSON mode: Commander already wrote the "error: ..." line
-    // to stderr via configureOutput.writeErr before throwing the
-    // CommanderError. Nothing to do — exit with the original code.
+    // Commander's own line was suppressed above, so a parse failure reads the
+    // same as every other CLI error — the `Error: …` line cliError prints.
+    process.stderr.write(`Error: ${cleaned}\n`);
   }
   process.exit(exitCode || 1);
 }

package/clients/cli/lib/json-shim.test.mjs

@@ -20,7 +20,12 @@
  */
 
 import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {Command} from 'commander';
 import {runCli} from '../../../test-utils/run-cli.mjs';
+import {installJsonShim} from './json-shim.mjs';
+import {setJsonMode} from '../../../foundation/response/json.mjs';
 
 function parseJson(stdout) {
   return JSON.parse(stdout);
@@ -207,3 +212,67 @@ describe('--json shim: stdout discipline under --json', () => {
     }
   });
 });
+
+describe('--json shim: help shown for a failed invocation is an error envelope', () => {
+  it('astryx help bogus --json emits ERR_UNKNOWN_COMMAND, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['help', 'bogus', '--json']);
+    expect(status).toBe(1);
+    expect(stderr).toBe('');
+    const parsed = parseJson(stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
+    expect(parsed.error).toMatch(/bogus/);
+  });
+
+  it('the real binary emits the same envelope for help bogus --json', () => {
+    // One program per process, so the root's own outputHelp patch is used here.
+    const bin = fileURLToPath(new URL('../bin/astryx.mjs', import.meta.url));
+    const res = spawnSync(process.execPath, [bin, 'help', 'bogus', '--json'], {
+      encoding: 'utf-8',
+      timeout: 20_000,
+    });
+    expect(res.status).toBe(1);
+    expect(res.stderr).toBe('');
+    const parsed = parseJson(res.stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
+  });
+
+  it('a group added after install gets the same error envelope', () => {
+    // This is the only coverage of the no-subcommand path: every group the CLI
+    // ships has an action of its own (see command-result-coverage.test.mjs), so
+    // a group without one has to be built here.
+    const program = new Command('astryx');
+    installJsonShim(program);
+    // Added later, so only the prototype-level patch covers its outputHelp.
+    const late = new Command('late');
+    late.command('child');
+    program.addCommand(late);
+    /** @type {string[]} */
+    const writes = [];
+    const origWrite = process.stdout.write;
+    // @ts-expect-error - test-only capture
+    process.stdout.write = (chunk) => writes.push(String(chunk)) > 0;
+    setJsonMode(true);
+    delete process.__xdsJsonHandled;
+    try {
+      late.outputHelp({error: true});
+    } finally {
+      process.stdout.write = origWrite;
+      setJsonMode(false);
+      delete process.__xdsJsonHandled;
+    }
+    const parsed = parseJson(writes.join(''));
+    expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
+    expect(parsed.suggestions).toEqual([{name: 'late child', reason: 'available subcommand'}]);
+  });
+
+  it('astryx help theme --json still emits the help envelope, exit 0', async () => {
+    const {status, stdout} = await runCli(['help', 'theme', '--json']);
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('help');
+    expect(parsed.data.command).toBe('astryx theme');
+  });
+});

package/clients/cli/lib/manifest.d.ts

@@ -48,6 +48,8 @@ export interface ManifestCommand {
   responseTypes?: string[];
   /** Example invocations. */
   examples?: string[];
+  /** Documented exit codes: the process exit status and when it occurs. */
+  exitCodes?: {code: number; when: string}[];
   /** Nested subcommands (e.g. `theme build` under `theme`). */
   subcommands?: ManifestCommand[];
 }

package/clients/cli/lib/manifest.mjs

@@ -35,6 +35,8 @@
  */
 
 import {API_VERSION} from '../../../foundation/response/json.mjs';
+import {commandDocsOf} from './define-command.mjs';
+import {doc as manifestDoc} from '../commands/manifest.doc.mjs';
 
 /**
  * Response `type` discriminators each fully-qualified command can emit in
@@ -49,18 +51,26 @@ export const RESPONSE_TYPES = {
   init: ['init.run', 'init.remove'],
   component: [
     'component.list',
+    'component.batch',
     'component.detail',
     'component.detail.props',
     'component.detail.source',
     'component.detail.showcase',
     'component.detail.blocks',
   ],
-  docs: ['docs.list', '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',
     'discover.detail',
     'discover.detail.doc',
+    'discover.item',
     'discover.search',
   ],
   search: ['search'],
@@ -90,9 +100,6 @@ export const RESPONSE_TYPES = {
   'doctor integration templates': ['integration.template-conflicts'],
   'doctor integration components': ['integration.component-conflicts'],
   'doctor integration docs': ['integration.doc-conflicts'],
-  'layout expand': ['layout.expand'],
-  'layout check': ['layout.check'],
-  'layout grammar': ['layout.grammar'],
 };
 
 /**
@@ -103,9 +110,16 @@ const EXAMPLES = {
   component: [
     'astryx component',
     'astryx component XDSButton',
+    'astryx component Button Badge Text',
     'astryx component XDSButton --props --json',
   ],
-  docs: ['astryx docs', 'astryx docs spacing --json'],
+  docs: [
+    'astryx docs',
+    'astryx docs spacing --json',
+    'astryx docs theme',
+    'astryx docs theme quick-start',
+    'astryx docs cli/integrations --full',
+  ],
   discover: ['astryx discover --json'],
   search: [
     'astryx search modal --json',
@@ -166,11 +180,6 @@ const EXAMPLES = {
     'astryx doctor integration docs @acme/widgets --json',
   ],
   init: ['astryx init', 'astryx init --all --json'],
-  'layout expand': [
-    `astryx layout expand 'V[g6] > C{card-callout}*4' ./src/Page.tsx`,
-  ],
-  'layout check': [`astryx layout check 'A[cp6] > L > LC > S[p6]' --json`],
-  'layout grammar': ['astryx layout grammar'],
 };
 
 /**
@@ -232,6 +241,18 @@ function fullName(cmd, root) {
   return parts.join(' ');
 }
 
+/**
+ * The docs a command was built from. `manifest` is registered by hand in
+ * index.mjs, so its CommandDoc is read here.
+ * @param {import('commander').Command} cmd
+ * @param {string} name
+ */
+function docsOf(cmd, name) {
+  return (
+    commandDocsOf(cmd) ?? (name === 'manifest' ? {doc: manifestDoc} : undefined)
+  );
+}
+
 /**
  * Recursively describe a Commander command and its subcommands.
  *
@@ -247,6 +268,8 @@ function describeCommand(cmd, root, jsonSupported) {
   // `_hidden` is a Commander internal not present on its public types.
   if (!name || /** @type {any} */ (cmd)._hidden || name === 'help') return null;
 
+  const docs = docsOf(cmd, name);
+
   const subcommands = /** @type {object[]} */ (
     (cmd.commands || [])
       .map(sub => describeCommand(sub, root, jsonSupported))
@@ -279,6 +302,12 @@ function describeCommand(cmd, root, jsonSupported) {
 
   if (EXAMPLES[name]) entry.examples = [...EXAMPLES[name]];
 
+  const exitCodes = (docs?.doc.exitCodes ?? []).map(({code, when}) => ({
+    code,
+    when,
+  }));
+  if (exitCodes.length > 0) entry.exitCodes = exitCodes;
+
   // Sort subcommands by name for a stable, agent-facing contract — the same
   // guarantee the top-level command list makes. Otherwise Commander
   // registration order leaks into the manifest and a pure reorder of

package/clients/cli/lib/manifest.test.mjs

@@ -156,7 +156,10 @@ describe('manifest: shape', () => {
 
   it('derives arguments from Commander metadata', () => {
     const component = allEntries.find((c) => c.name === 'component');
-    expect(component.arguments.map((a) => a.name)).toContain('name');
+    const names = component.arguments.find((a) => a.name === 'names');
+    expect(names.required).toBe(false);
+    expect(names.variadic).toBe(true);
+    expect(names.description).toContain('Two or more return one ordered batch');
     const themeBuild = allEntries.find((c) => c.name === 'theme build');
     expect(themeBuild.arguments.map((a) => a.name)).toContain('files');
     const files = themeBuild.arguments.find((a) => a.name === 'files');
@@ -193,6 +196,23 @@ describe('manifest: e2e', () => {
     // Enriched: the full structured manifest is embedded.
     expect(parsed.data.manifest).toBeDefined();
     expect(parsed.data.manifest.commands.find((c) => c.name === 'component').responseTypes)
-      .toContain('component.list');
+      .toEqual(expect.arrayContaining(['component.list', 'component.batch']));
+  });
+});
+
+describe('manifest: text projection', () => {
+  it('astryx manifest (text) uses the JSON entry keys as its field names', async () => {
+    const text = await runCli(['manifest']);
+    expect(text.status).toBe(0);
+    const json = JSON.parse((await runCli(['manifest', '--json'])).stdout);
+    const jsonKeys = new Set(json.data.commands.flatMap((c) => Object.keys(c)));
+    const textKeys = new Set(
+      text.stdout
+        .split('\n')
+        .map((line) => /^([A-Za-z]+):\s/.exec(line)?.[1])
+        .filter(Boolean),
+    );
+    expect(textKeys).toContain('name');
+    for (const key of textKeys) expect(jsonKeys).toContain(key);
   });
 });

package/clients/cli/lib/parse-error-format.test.mjs

@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A parse failure reads like every other Astryx error in text mode.
+ *
+ * `astryx theme list --lang zh-Hans` printed Commander's own line —
+ * `error: option '--lang <locale>' argument 'zh-Hans' is invalid…` — while
+ * every other CLI error prints `Error: …`. `--json` was already correct
+ * (ERR_INVALID_LANG), so text and JSON disagreed on everything except the exit
+ * code. Commander writes that line before any Astryx code runs, so the shim is
+ * the only place that can speak for it.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {Command} from 'commander';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {installJsonShim} from './json-shim.mjs';
+
+describe('a parse error prints the Astryx error format', () => {
+  it.each([
+    ['invalid --lang value', ['theme', 'list', '--lang', 'zh-Hans'], 'ERR_INVALID_LANG'],
+    ['invalid --detail value', ['theme', 'list', '--detail', 'nope'], 'ERR_INVALID_DETAIL'],
+    ['unknown option', ['component', '--bogus-flag'], 'ERR_INVALID_OPTION'],
+    ['missing argument', ['theme', 'build'], 'ERR_MISSING_ARGUMENT'],
+  ])('%s', async (_label, args, code) => {
+    const human = await runCli(args);
+
+    expect(human.status).toBe(1);
+    expect(human.stderr).toContain('Error: ');
+    // Commander's own lowercase line must not reach the user.
+    expect(human.stderr).not.toMatch(/(^|\n)error: /);
+
+    // --json is unchanged, and the two modes agree on the exit code.
+    const json = await runCli(['--json', ...args]);
+    expect(json.status).toBe(human.status);
+    expect(JSON.parse(json.stdout).code).toBe(code);
+    expect(json.stderr).toBe('');
+  });
+
+  it('carries Commander\'s explanation, not just a generic line', async () => {
+    const {stderr} = await runCli(['theme', 'list', '--lang', 'zh-Hans']);
+    expect(stderr).toContain("'zh-Hans' is invalid");
+    expect(stderr).toContain('en, zh, dense');
+  });
+
+  it('leaves --help and --version at exit 0 with nothing on stderr', async () => {
+    for (const args of [['--help'], ['theme', '--help']]) {
+      const r = await runCli(args);
+      expect(r.status).toBe(0);
+      expect(r.stderr).toBe('');
+    }
+  });
+
+  // Commander writes help through the same stderr channel when it shows help
+  // BECAUSE the invocation failed, so suppressing that channel wholesale would
+  // have taken the help with it. Driven on a throwaway program rather than a
+  // real command, so the guard outlives whichever command happens to have a
+  // subcommand group today.
+  it('still lets help reach stderr when help IS the failure report', () => {
+    const program = new Command('probe');
+    const group = program.command('group');
+    group.command('leaf').action(() => {});
+    installJsonShim(program);
+
+    /** @type {string[]} */
+    const written = [];
+    const original = process.stderr.write;
+    // @ts-expect-error test double for the write signature
+    process.stderr.write = str => {
+      written.push(String(str));
+      return true;
+    };
+    try {
+      group.outputHelp({error: true});
+    } finally {
+      process.stderr.write = original;
+    }
+
+    expect(written.join('')).toMatch(/Usage: probe group/);
+  });
+});

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
@@ -182,6 +183,8 @@ export function removeXdsBlock(filePath: string, { deleteIfEmpty }?: {
 /**
  * Remove Astryx section from all known agent doc files.
  * @param {string} targetDir
+ * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
+ *   resolves outside `targetDir`; nothing is changed.
  */
 export function removeAgentDocs(targetDir: string): void;
 /**
@@ -208,6 +211,8 @@ export function removeAgentDocs(targetDir: string): void;
  * @param {string} [options.renderedBlock] - Fully rendered expected block. Init
  *   and upgrade pass one shared block to every target.
  * @returns {string[]} List of files written
+ * @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
+ *   write resolves outside `targetDir`; nothing is written.
  */
 export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, onlyReplace, topics, renderedBlock, }?: {
     zh?: boolean | undefined;

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

@@ -22,11 +22,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {findCoreDir, CLI_ROOT} from '../fs/paths.mjs';
-import {assertWithin} from '../fs/path-safety.mjs';
+import {assertWithin, PathSafetyError} from '../fs/path-safety.mjs';
 import {getCliInvocation} from '../env/package-manager.mjs';
 import {discoverComponents} from '../discovery/component-discovery.mjs';
 import {Project} from '../config/project.mjs';
 import {humanLog} from '../response/json.mjs';
+import {ERROR_CODES} from '../response/error-codes.mjs';
 import {
   AGENTS_MD,
   CLAUDE_MD,
@@ -353,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
@@ -427,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;
@@ -462,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('');
 
@@ -485,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(
@@ -705,12 +710,65 @@ export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {
   return true;
 }
 
+/**
+ * Whether an agent-doc file already carries a managed-block marker.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function hasManagedMarker(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return content.includes(MARKER_START) || content.includes(LEGACY_MARKER_START);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether `removeXdsBlock` would change `filePath`: it holds one well-formed
+ * managed block.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function hasRemovableBlock(filePath) {
+  try {
+    return findManagedBlock(fs.readFileSync(filePath, 'utf-8')) != null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every file a run writes must resolve inside `targetDir`, symlinks
+ * included. Checked for the whole write set before the first write, so an
+ * escape writes nothing.
+ * @param {string} targetDir
+ * @param {Iterable<string>} relPaths
+ */
+function assertTargetsWithin(targetDir, relPaths) {
+  for (const p of relPaths) {
+    assertWithin(p, targetDir, {label: 'agent docs path'});
+  }
+}
+
 /**
  * Remove Astryx section from all known agent doc files.
  * @param {string} targetDir
+ * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
+ *   resolves outside `targetDir`; nothing is changed.
  */
 export function removeAgentDocs(targetDir) {
   const allPaths = discoverAgentDocs(targetDir);
+  try {
+    assertTargetsWithin(
+      targetDir,
+      allPaths.filter(p => hasRemovableBlock(path.join(targetDir, p))),
+    );
+  } catch (err) {
+    // The code reaches the error envelope as is, so it must be registered.
+    if (!(err instanceof PathSafetyError)) throw err;
+    throw new PathSafetyError(err.message, ERROR_CODES.ERR_PATH_TRAVERSAL);
+  }
 
   for (const p of allPaths) {
     const filePath = path.join(targetDir, p);
@@ -718,9 +776,9 @@ export function removeAgentDocs(targetDir) {
     const deleteIfEmpty = p === AGENTS_MD || p === CLAUDE_DIR_MD;
     if (removeXdsBlock(filePath, {deleteIfEmpty})) {
       if (!fs.existsSync(filePath)) {
-        humanLog(`✓ Removed empty ${p}`);
+        humanLog(`[ok] Removed empty ${p}`);
       } else {
-        humanLog(`✓ Removed design system section from ${p}`);
+        humanLog(`[ok] Removed design system section from ${p}`);
       }
     }
   }
@@ -750,6 +808,8 @@ export function removeAgentDocs(targetDir) {
  * @param {string} [options.renderedBlock] - Fully rendered expected block. Init
  *   and upgrade pass one shared block to every target.
  * @returns {string[]} List of files written
+ * @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
+ *   write resolves outside `targetDir`; nothing is written.
  */
 export function installAgentDocs(
   targetDir,
@@ -806,6 +866,7 @@ export function installAgentDocs(
   // Agent preset
   if (agent) {
     const {inject, create} = resolveAgentPaths(targetDir, agent);
+    assertTargetsWithin(targetDir, [...inject, ...create]);
     for (const p of inject) {
       injectXdsBlock(path.join(targetDir, p), compressedIndex);
       written.push(p);
@@ -833,6 +894,14 @@ export function installAgentDocs(
   if (existing.length > 0) {
     const wrappers = discoverAgentDocWrappers(targetDir, existing);
     const targets = existing.filter(p => !wrappers.has(p));
+    // A refresh skips unmarked files and a wrapper is only written when it
+    // carries a block, so only the files this run writes are checked.
+    /** @param {string} p */
+    const marked = p => hasManagedMarker(path.join(targetDir, p));
+    assertTargetsWithin(targetDir, [
+      ...targets.filter(p => !onlyReplace || marked(p)),
+      ...[...wrappers].filter(marked),
+    ]);
 
     for (const p of targets) {
       const didWrite = injectXdsBlock(path.join(targetDir, p), compressedIndex, {onlyReplace});
@@ -860,6 +929,7 @@ export function installAgentDocs(
   if (onlyReplace) return written;
 
   const defaultPath = AGENTS_MD;
+  assertTargetsWithin(targetDir, [defaultPath]);
   injectXdsBlock(path.join(targetDir, defaultPath), compressedIndex, {
     createIfMissing: true,
     header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,