@astryxdesign/cli 0.7.2 → 0.7.3-canary.02f5fe4

package/clients/cli/commands/postinstall.mjs

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file postinstall command — the hidden `astryx postinstall` hook.
+ *
+ * Prints the welcome box (lib/welcome-box.mjs). Hidden from help and the
+ * manifest; it looks nothing up and does not support --json.
+ *
+ * The command surface comes from the colocated CommandDoc via `defineCommand`.
+ */
+
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {emit, code} from '../formatters/index.mjs';
+import {defineCommand} from '../lib/define-command.mjs';
+import {welcomeBox} from '../lib/welcome-box.mjs';
+import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
+import {doc as postinstallCommand} from './postinstall.doc.mjs';
+
+/**
+ * @param {import('commander').Command} program
+ */
+export function registerPostinstall(program) {
+  defineCommand(program, postinstallCommand, {
+    hidden: true,
+    action: () => {
+      emit(code(welcomeBox(getCliInvocation())));
+      // Prints the welcome box. Nothing is looked up.
+      return NO_RESULT_SET;
+    },
+  });
+}

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

@@ -121,6 +121,25 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     expect(r.stderr).toMatch(NUDGE);
   });
 
+  it.each([
+    ['in the home folder', ''],
+    ['at the top of a settings folder in it', '.dotfiles'],
+  ])('stays quiet %s, where init writes no agent docs', async (_label, rel) => {
+    const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+    process.env.HOME = tmp;
+    process.env.USERPROFILE = tmp;
+    try {
+      write(path.join(rel, 'package.json'), '{"name":"t"}');
+      const r = await runCli(['docs', 'tokens'], path.join(tmp, rel));
+      expect(r.stderr).not.toMatch(NUDGE);
+    } finally {
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  });
+
   it("in a project with only Core of another release, names adding the CLI at Core's version first, as the daily hint does", async () => {
     write(
       'package.json',
@@ -167,6 +186,65 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
   });
 
+  it('is quiet in a nested package once init has written the docs at the project root', async () => {
+    // init run in functions/ writes at the root that declares Astryx.
+    write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('AGENTS.md', MARKER);
+    write('functions/package.json', '{"name":"functions"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));
+    expect(r.stderr).not.toMatch(NUDGE);
+  });
+
+  it('nudges in a nested package while the project root has no docs', async () => {
+    write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('functions/package.json', '{"name":"functions"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));
+    expect(r.stderr).toMatch(NUDGE);
+  });
+
+  // A nested package.json that is not the project's (spec AST-040 FR9): the
+  // reminder sends the person to the project's folder, never adds the CLI to
+  // the nested package.json (spec AST-081 FR2).
+  it("in a nested package whose package.json is not the project's, says to run from the project's folder", async () => {
+    write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('package-lock.json', '{}');
+    write('functions/package.json', '{"name":"functions"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));
+    // Only `cd` comes first, so the app has no CLI of its own yet: the
+    // command is the scoped package at the answering release, never the bare
+    // `astryx` name a package runner would fetch from the registry.
+    const {version} = JSON.parse(fs.readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
+    expect(r.stderr.trim()).toBe(
+      `Next step: run \`cd ${tmp}\`, then \`npx @astryxdesign/cli@${version} init\` to finish setup and install the Astryx agent prompt.`,
+    );
+  });
+
+  // Inside a git repository the project-root check above adds nothing to the
+  // walk up to the repository root: the same outcomes as without it.
+  it('inside a repository, is quiet in a nested package once init has written the docs at the project root', async () => {
+    fs.mkdirSync(path.join(tmp, '.git'));
+    write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('AGENTS.md', MARKER);
+    write('functions/package.json', '{"name":"functions"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));
+    expect(r.stderr).not.toMatch(NUDGE);
+  });
+
+  it('inside a repository, still nudges when the only docs lie above the repository root', async () => {
+    write('package.json', JSON.stringify({name: 'outer', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('AGENTS.md', MARKER);
+    fs.mkdirSync(path.join(tmp, 'repo', '.git'), {recursive: true});
+    write('repo/package.json', '{"name":"repo"}');
+    // It declares Astryx: a folder that declares nothing is outside a
+    // project, where no reminder prints (spec AST-081 FR3).
+    write(
+      'repo/functions/package.json',
+      JSON.stringify({name: 'functions', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'repo', 'functions'));
+    expect(r.stderr).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/{build-theme.mjs → theme.mjs}

@@ -96,7 +96,7 @@ import {doc as themePaletteGenerateFn} from '../../../api/theme/themePaletteGene
 
 /**
  * Path to this CLI's real entry (clients/cli/bin/astryx.mjs), resolved from
- * this module's location (clients/cli/commands/build-theme.mjs → ../bin/
+ * this module's location (clients/cli/commands/theme.mjs → ../bin/
  * astryx.mjs). Used to re-invoke `theme build` as a child process in watch mode.
  */
 function resolveCliBin() {

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

@@ -21,6 +21,7 @@ export const doc = {
     'agent-docs block when Core or configured integration guidance changes. ' +
     'Dry-run by default. --apply writes codemod and receipt changes, runs hooks, then refreshes agent docs. ' +
     'Anything a post-codemod hook prints goes to stderr, so stdout carries only the result. ' +
+    'Run from a folder inside a project, it upgrades that project and names files in the result relative to the folder you ran it in. ' +
     'ShadCN-copied compositions are checked automatically during a normal upgrade, or alone with --registry. ' +
     'Outside a project, --list lists the codemods this release ships and --registry finds no copied compositions to update; ' +
     'a migration writes nothing and fails with ERR_VERSION_DETECT, because no installed Core names its target.',
@@ -69,8 +70,9 @@ export const doc = {
     {
       flag: '--path <dir>',
       param: 'options.path',
-      description: 'Source directory to scan',
-      default: './src',
+      description:
+        "Source directory to scan, relative to where you run the command, however you spell it. Without --path, the project's src folder, from any folder in the project",
+      default: './src at the project root',
     },
     {
       flag: '--install-deps',

package/clients/cli/commands/upgrade.mjs

@@ -31,8 +31,9 @@ export function registerUpgrade(program) {
     action:
       /**
        * @param {import('../../../api/upgrade/upgrade.mjs').UpgradeOptions} options
+       * @param {import('commander').Command} command
        */
-      async options => {
+      async (options, command) => {
         const json = program.opts().json || false;
         const isList = Boolean(options.list);
         // Silence the logger for --list so the handler renders from the
@@ -42,8 +43,14 @@ export function registerUpgrade(program) {
 
         /** @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;
+        // `--path` shows its default in help, but a path nobody typed is the
+        // project's src, not one read from this folder: leave it unset.
+        const apiOptions =
+          command.getOptionValueSource('path') === 'default'
+            ? {...options, path: undefined}
+            : options;
         try {
-          result = await upgradeApi(options, {cwd: process.cwd()});
+          result = await upgradeApi(apiOptions, {cwd: process.cwd()});
         } catch (e) {
           // Re-enable the logger so the error is visible in text mode.
           // For --list the logger was silent; for other modes the API

package/clients/cli/commands/upgrade.subfolder-path.test.mjs

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx upgrade` from a folder inside a project: a `--path` you type
+ * is read from that folder, however you spell it, and without `--path` the
+ * upgrade scans the project's own src. The option's default must not read as
+ * a typed `./src`. The `--json` result names files relative to the folder the
+ * command ran in.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+/** Core 0.7.0 renamed this prop; its codemod renames it on Typeahead. */
+const OLD_PROP_SOURCE =
+  "import {Typeahead} from '@astryxdesign/core';\n" +
+  'export const App = () => <Typeahead label="Fruit" emptySearchResultsText="None" />;\n';
+
+let root;
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+  const file = path.join(root, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, body);
+}
+
+/** @param {string} rel */
+const renamed = rel =>
+  fs
+    .readFileSync(path.join(root, rel), 'utf-8')
+    .includes('emptySearchText="None"');
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-subfolder-'));
+  write(
+    'package.json',
+    JSON.stringify({
+      name: 'app',
+      private: true,
+      dependencies: {'@astryxdesign/core': '0.7.0'},
+    }),
+  );
+  write(
+    'node_modules/@astryxdesign/core/package.json',
+    JSON.stringify({name: '@astryxdesign/core', version: '0.7.0'}),
+  );
+  write('src/App.tsx', OLD_PROP_SOURCE);
+  // A folder inside the project with source of its own and no package.json.
+  write('frontend/src/App.tsx', OLD_PROP_SOURCE);
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+/** @param {string[]} args @param {string} [folder] */
+async function upgradeFrom(args, folder = 'frontend') {
+  const r = await runCli(
+    ['upgrade', '--from', '0.6.8', ...args, '--apply', '--json'],
+    {
+      cwd: path.join(root, folder),
+    },
+  );
+  expect(r.status).toBe(0);
+  return JSON.parse(r.stdout);
+}
+
+describe('upgrade --path from a folder inside the project', () => {
+  it.each([['./src'], ['src'], ['src/'], ['./src/']])(
+    'reads --path %s from the folder you ran in',
+    async spelling => {
+      const result = await upgradeFrom(['--path', spelling]);
+
+      expect(result.data.modifiedFiles).toEqual(['src/App.tsx']);
+      expect(renamed('frontend/src/App.tsx')).toBe(true);
+      expect(renamed('src/App.tsx')).toBe(false);
+    },
+  );
+
+  it("scans the project's src without --path", async () => {
+    const result = await upgradeFrom([]);
+
+    expect(result.data.modifiedFiles).toEqual(['../src/App.tsx']);
+    expect(renamed('src/App.tsx')).toBe(true);
+    expect(renamed('frontend/src/App.tsx')).toBe(false);
+  });
+
+  it('names files from the project root when run there', async () => {
+    const result = await upgradeFrom([], '.');
+
+    expect(result.data.modifiedFiles).toEqual(['src/App.tsx']);
+  });
+});

package/clients/cli/index.mjs

@@ -16,23 +16,25 @@ import {Command, Option} from 'commander';
 import {fileURLToPath} from 'node:url';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {formatCliCommand, getCliInvocation} from '../../foundation/env/package-manager.mjs';
+import {formatCliCommand, getCliInvocation, quoteCommandArgument} from '../../foundation/env/package-manager.mjs';
 import {hasRecordedProject} from '../../foundation/env/cli-command.mjs';
 import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
 import {API_VERSION, setJsonMode} from '../../foundation/response/json.mjs';
 import {answeredBy, runChoice} from '../../foundation/release/run-context.mjs';
-import {addCliCommand} from '../../foundation/release/notices.mjs';
-import {projectRootOf} from '../../foundation/release/choose.mjs';
-import {readReleaseFacts} from '../../foundation/release/project.mjs';
+import {cliInstallAdvice, installFolder} from '../../foundation/release/notices.mjs';
 import {buildManifest} from './lib/manifest.mjs';
 import {cliError} from './lib/cli-error.mjs';
-import {emit, section, text, records} from './formatters/index.mjs';
+import {section, text, records} from './formatters/index.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {installJsonShim} from './lib/json-shim.mjs';
-import {addDocHelp, markReportsResult} from './lib/define-command.mjs';
-import {doc as manifestDoc} from './commands/manifest.doc.mjs';
-import {isAstryxInitialized, isAstryxPromptInReach} from '../../foundation/agent-docs/agent-docs.mjs';
+import {markReportsResult} from './lib/define-command.mjs';
+import {
+  agentDocsTargetDir,
+  assertAgentDocsTarget,
+  isAstryxInitialized,
+  isAstryxPromptInReach,
+} from '../../foundation/agent-docs/agent-docs.mjs';
 import {CLI_ROOT} from '../../foundation/fs/paths.mjs';
 import {setupNudge} from '../../foundation/agent-docs/agent-doc-state.mjs';
 import * as debug from '../../foundation/debug/index.mjs';
@@ -292,7 +294,7 @@ function captureInvocation(actionCommand, root) {
  */
 const commands = [
   {name: 'init', path: './commands/init.mjs', register: 'registerInit'},
-  {name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},
+  {name: 'component', path: './commands/component.mjs', register: 'registerComponent'},
   {name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},
   {name: 'blog', path: './commands/blog.mjs', register: 'registerBlog'},
   {name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},
@@ -300,13 +302,17 @@ const commands = [
   // agent-docs folded into init — functions still importable from agent-docs.mjs
   {name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},
   {name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},
-  {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},
+  {name: 'theme', path: './commands/theme.mjs', register: 'registerTheme'},
   {name: 'integration', path: './commands/integration.mjs', register: 'registerIntegration'},
-  {name: 'hook', path: './commands/hook/index.mjs', register: 'registerHook'},
+  {name: 'hook', path: './commands/hook.mjs', register: 'registerHook'},
   {name: 'discover', path: './commands/discover.mjs', register: 'registerDiscover'},
   {name: 'search', path: './commands/search.mjs', register: 'registerSearch'},
   {name: 'build', path: './commands/build.mjs', register: 'registerBuild'},
   {name: 'doctor', path: './commands/doctor.mjs', register: 'registerDoctor'},
+  // Registered after every other command: the manifest lists the commands in
+  // registration order.
+  {name: 'manifest', path: './commands/manifest.mjs', register: 'registerManifest'},
+  {name: 'postinstall', path: './commands/postinstall.mjs', register: 'registerPostinstall'},
 ];
 
 const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
@@ -635,6 +641,19 @@ export async function createProgram() {
       if (INTEGRATION_MANIFEST_FILES.some(file => fs.existsSync(path.join(cwd, file)))) return;
       if (inOwnSourceCheckout(cwd)) return; // developing Astryx itself, not an app
       if (isAstryxPromptInReach(cwd)) return; // already set up — stay quiet
+      // Where init writes the docs, by init's own rule: the project root, which
+      // can sit above a nested package such as functions/. Inside a git
+      // repository the walk above already reaches it (the root never lies
+      // above the repository root), so this changes nothing there; outside a
+      // repository the walk checks only cwd, and this finds the root.
+      if (isAstryxInitialized(agentDocsTargetDir(cwd))) return;
+      // In the home folder, or at the top of a settings folder in it, init
+      // writes no agent docs, so naming it would repeat on every command.
+      try {
+        assertAgentDocsTarget(agentDocsTargetDir(cwd));
+      } catch {
+        return;
+      }
       // Same wording as the core/cli postinstall nudges. getCliInvocation()
       // renders the correct form for THIS project — an integration's cliCommand,
       // scoped `npx @astryxdesign/cli` one-off, or `<pm> astryx` when installed —
@@ -642,14 +661,33 @@ export async function createProgram() {
       // A project with no CLI of its own, answered by another release than its
       // Core's: add the CLI at Core's version first, as the daily hint says,
       // then run that CLI's init (spec AST-081 FR2).
-      const choice = runChoice(cwd);
-      if (choice.copy === 'starting' && choice.coreVersion && choice.coreVersion !== choice.version) {
-        const root = projectRootOf(readReleaseFacts(cwd)) ?? cwd;
+      // A folder that belongs to no project spec:AST-040 FR9 defines gets no
+      // reminder, as outside a project.
+      const target = installFolder(cwd);
+      if (target == null) return;
+      // From a folder inside the project whose package.json is not the
+      // project's, init runs from the project's folder. Only `cd` comes
+      // before it, so the command is the picker's for that folder, never the
+      // bare `astryx` name a package runner would fetch from the registry
+      // (spec AST-081 FR5).
+      if (target.moved) {
         console.error(
-          setupNudge(getCliInvocation(root, {installed: true}), {before: addCliCommand(root, choice.coreVersion)}).trimEnd(),
+          setupNudge(getCliInvocation(target.dir), {before: `cd ${quoteCommandArgument(target.dir)}`}).trimEnd(),
         );
         return;
       }
+      const choice = runChoice(cwd);
+      if (choice.copy === 'starting' && choice.coreVersion && choice.coreVersion !== choice.version) {
+        // The daily hint's comparison and command: add the CLI at Core's
+        // version, then run that CLI's init.
+        const add = cliInstallAdvice({cwd, core: choice.coreVersion});
+        if (add?.command) {
+          console.error(
+            setupNudge(getCliInvocation(add.root, {installed: true}), {before: add.command}).trimEnd(),
+          );
+          return;
+        }
+      }
       console.error(setupNudge(getCliInvocation(cwd)).trimEnd());
     } catch {
       // Never let the nudge break a command.
@@ -659,7 +697,7 @@ export async function createProgram() {
   for (const cmd of commands) {
     try {
       const mod = await import(cmd.path);
-      mod[cmd.register](program);
+      mod[cmd.register](program, {jsonSupported: JSON_SUPPORTED, version: pkg.version});
     } catch (e) {
       // Command fails to load but CLI still works
       const reason = /** @type {any} */ (e).message;
@@ -679,84 +717,6 @@ export async function createProgram() {
     }
   }
 
-  // Capability manifest — a single, self-describing view of the whole CLI so
-  // agents can discover every command, argument, flag, and response type without
-  // scraping `--help`. `astryx manifest --json` is the dedicated surface; the bare
-  // `xds --json` embeds the same payload under data.manifest for convenience.
-  // Intentionally CLI-special — no `api/manifest`. It introspects the live
-  // Commander `program`, so extracting it to `api/` would create the `api → cli`
-  // cycle from #4302. `buildManifest(program)` lives in lib/; see its header.
-  const manifestCommand = program
-    .command('manifest')
-    .description('Print the full CLI capability manifest (use with --json)')
-    .action(() => {
-      const manifest = buildManifest(program, {
-        jsonSupported: JSON_SUPPORTED,
-        version: pkg.version,
-      });
-      // The manifest IS a result set: one entry per command the CLI ships.
-      debug.recordCommandResult(
-        debug.resultSet({
-          count: manifest.commands.length,
-          resultKind: 'command',
-        }),
-      );
-      if (program.opts().json) {
-        process.__xdsJsonHandled = true;
-        console.log(JSON.stringify({apiVersion: API_VERSION, type: 'manifest', data: manifest, meta: {answeredBy: answeredBy()}}, null, 2));
-        return;
-      }
-      // Human-readable summary as greppable records (agents should use --json).
-      // One record per command: name, whether it supports --json, and the
-      // description. Field names are the manifest entry's own keys.
-      emit(
-        section(`${manifest.name} v${manifest.version} (${manifest.commands.length} commands)`),
-        records(
-          manifest.commands.map(c => ({
-            name: c.name,
-            json: c.json ? 'yes' : '',
-            description: c.description || '',
-          })),
-          {fields: ['name', 'json', 'description']},
-        ),
-        text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
-      );
-    });
-  addDocHelp(manifestCommand, manifestDoc);
-  markReportsResult(manifestCommand);
-
-  // Hidden command used by package.json postinstall scripts
-  const postinstallCommand = program
-    .command('postinstall', {hidden: true})
-    .action(() => {
-      // Prints the welcome box. Nothing is looked up.
-      debug.recordCommandResult(debug.NO_RESULT_SET);
-      const r = getCliInvocation();
-      const pad = (/** @type {string} */ s, /** @type {number} */ len) => s + ' '.repeat(Math.max(0, len - s.length));
-      const W = 49; // inner width of the box
-      const line = (/** @type {string} */ s) => `  │ ${pad(s, W)}│`;
-      console.log(`
-  ╭${'─'.repeat(W + 2)}╮
-${line('')}
-${line('  Design system installed!')}
-${line('')}
-${line('  Get started:')}
-${line(`    ${r} init          Setup + AI agent docs`)}
-${line(`    ${r} --help        See all commands`)}
-${line('')}
-${line('  Or run directly:')}
-${line(`    ${r} init           Setup + AI agent docs`)}
-${line(`    ${r} component     Browse component docs`)}
-${line(`    ${r} hook          Browse hook docs`)}
-${line(`    ${r} docs          Design system reference`)}
-${line(`    ${r} swizzle       Customize a component`)}
-${line(`    ${r} template      Add a page template`)}
-${line('')}
-  ╰${'─'.repeat(W + 2)}╯
-`);
-    });
-  markReportsResult(postinstallCommand);
-
   // Install the JSON shim AFTER all commands are registered so we can
   // patch outputHelp on every command (root + subcommands). The shim
   // extends the --json contract to cover Commander's parse-time short

package/clients/cli/lib/component-format.mjs

@@ -21,7 +21,7 @@ import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
  * (→ `.astryx-table-cell`), and `astryx-button` → key `button`.
  *
  * Keep the `astryx-` literal in sync with packages/core/src/naming.ts
- * (NAMESPACE / classPrefix), the same way build-theme.mjs mirrors it.
+ * (NAMESPACE / classPrefix), the same way commands/theme.mjs mirrors it.
  * <!-- SYNC: packages/core/src/naming.ts (namespace prefix source of truth) -->
  * @param {import('@astryxdesign/cli/authoring').ComponentThemingTarget} target
  * @returns {string}

package/clients/cli/lib/define-command.mjs

@@ -63,10 +63,10 @@ export function reportsResultVia(cmd) {
 /**
  * Mark a hand-registered command as reporting its result.
  *
- * For the handful of commands that cannot come from a CommandDoc — the root
- * program, `manifest` (it introspects the live program, so it cannot be
- * declared by one), `postinstall`, and the stub left behind when a command
- * module fails to load. They call {@link recordCommandResult} themselves; this
+ * For what does not come from a CommandDoc: the root program, and the stub
+ * left behind when a command module fails to load. Every command, `manifest`
+ * and the hidden `postinstall` hook included, registers through
+ * {@link defineCommand}. These call {@link recordCommandResult} themselves; this
  * says so, and the coverage test pins the set of commands allowed to, so the
  * mark cannot become a quiet way around the contract.
  *
@@ -105,10 +105,12 @@ export function commandDocsOf(cmd) {
  *   fn?: import('@astryxdesign/cli/authoring').FunctionDoc,
  *   action?: (...args: any[]) => import('../../../foundation/debug/command-result.mjs').CommandResult
  *     | Promise<import('../../../foundation/debug/command-result.mjs').CommandResult>,
- * }} [impl]
+ *   hidden?: boolean,
+ * }} [impl] `hidden` keeps the command out of help and the manifest (a
+ *   package-script hook, not a command for people or agents).
  * @returns {import('commander').Command} the created command.
  */
-export function defineCommand(parent, doc, {fn, action} = {}) {
+export function defineCommand(parent, doc, {fn, action, hidden} = {}) {
   // The command token is the last path segment ("theme build" -> "build"),
   // since subcommands are added to their group command, not the program.
   const token = doc.name.split(' ').pop() ?? doc.name;
@@ -119,7 +121,10 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
     })
     .join(' ');
 
-  const cmd = parent.command(argSpec ? `${token} ${argSpec}` : token);
+  const cmd = parent.command(
+    argSpec ? `${token} ${argSpec}` : token,
+    hidden ? {hidden: true} : {},
+  );
   Object.defineProperty(cmd, COMMAND_DOCS, {value: {doc, fn}, configurable: true});
   if (doc.summary) cmd.description(doc.summary);
   if (doc.deprecated) {

package/clients/cli/lib/exit-codes.test.mjs

@@ -24,6 +24,10 @@ for (const file of fs.readdirSync(COMMANDS).sort()) {
 }
 
 const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
+/** Hidden commands (a package-script hook): documented, never in the manifest. */
+const HIDDEN = new Set(
+  program.commands.filter((c) => /** @type {any} */ (c)._hidden).map((c) => c.name()),
+);
 /** @type {Map<string, any>} */
 const entries = new Map();
 const walk = (/** @type {any} */ c) => {
@@ -98,6 +102,7 @@ describe('command exit codes', () => {
 
   it('the manifest carries every command exit code', () => {
     for (const doc of commandDocs) {
+      if (HIDDEN.has(doc.name)) continue;
       expect(entries.get(doc.name)?.exitCodes, doc.name).toEqual(
         doc.exitCodes.map(({code, when}) => ({code, when})),
       );

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

@@ -55,6 +55,10 @@ const CLI_LAYER_TYPES = {
 };
 
 const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
+/** Hidden commands (a package-script hook): documented, never in the manifest. */
+const HIDDEN = new Set(
+  program.commands.filter((c) => /** @type {any} */ (c)._hidden).map((c) => c.name()),
+);
 
 /** Flatten the manifest command tree into fully-qualified names. */
 function flatten(cmds, out = []) {
@@ -116,12 +120,19 @@ describe('manifest: drift guards', () => {
 
   it('takes every command example from its CommandDoc', () => {
     for (const [name, doc] of commandDocs) {
+      if (HIDDEN.has(name)) continue;
       const entry = allEntries.find((c) => c.name === name);
       expect(entry, `CommandDoc "${name}" has no manifest entry`).toBeDefined();
       expect(entry.examples ?? [], name).toEqual((doc.examples ?? []).map((e) => e.cli));
     }
   });
 
+  it('documents the hidden postinstall hook and keeps it out of the manifest', () => {
+    expect([...HIDDEN]).toEqual(['postinstall']);
+    expect(commandDocs.has('postinstall')).toBe(true);
+    expect(allNames.has('postinstall')).toBe(false);
+  });
+
   it('lists every response type the wrapped API function returns', () => {
     for (const [name, doc] of commandDocs) {
       if (!doc.fn) continue;
@@ -152,6 +163,7 @@ describe('manifest: drift guards', () => {
 
   it('takes response types from the wrapped FunctionDoc, plus CLI-layer envelopes', () => {
     for (const [name, doc] of commandDocs) {
+      if (HIDDEN.has(name)) continue;
       const entry = allEntries.find((c) => c.name === name);
       const returns = doc.fn ? functionDocs.get(doc.fn).returns.map((r) => r.type) : [];
       const expected = [...returns, ...(CLI_LAYER_TYPES[name] ?? [])];

package/clients/cli/lib/welcome-box.mjs

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The welcome box `astryx postinstall` prints after the package installs.
+ *
+ * A fixed banner, not tabular output, so it is drawn here rather than with the
+ * formatter kit; the command prints it verbatim through `emit(code(...))`.
+ * @input The CLI invocation for this project (e.g. `pnpm exec astryx`).
+ * @output {@link welcomeBox}
+ * @position clients/cli/lib — presentation helper for commands/postinstall.mjs
+ */
+
+/** Inner width of the box. */
+const W = 49;
+
+/**
+ * @param {string} s
+ * @param {number} len
+ */
+const pad = (s, len) => s + ' '.repeat(Math.max(0, len - s.length));
+
+/** @param {string} s */
+const line = s => `  │ ${pad(s, W)}│`;
+
+/**
+ * The welcome box, with a blank line before and after it.
+ * @param {string} r the CLI invocation, e.g. `pnpm exec astryx`
+ * @returns {string}
+ */
+export function welcomeBox(r) {
+  return `
+  ╭${'─'.repeat(W + 2)}╮
+${line('')}
+${line('  Design system installed!')}
+${line('')}
+${line('  Get started:')}
+${line(`    ${r} init          Setup + AI agent docs`)}
+${line(`    ${r} --help        See all commands`)}
+${line('')}
+${line('  Or run directly:')}
+${line(`    ${r} init           Setup + AI agent docs`)}
+${line(`    ${r} component     Browse component docs`)}
+${line(`    ${r} hook          Browse hook docs`)}
+${line(`    ${r} docs          Design system reference`)}
+${line(`    ${r} swizzle       Customize a component`)}
+${line(`    ${r} template      Add a page template`)}
+${line('')}
+  ╰${'─'.repeat(W + 2)}╯
+`;
+}