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

package/clients/cli/index.mjs

@@ -16,17 +16,27 @@ import {Command, Option} from 'commander';
 import {fileURLToPath} from 'node:url';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {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 {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} 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';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -63,7 +73,7 @@ export function handleVersionJsonPreflight(argv = process.argv.slice(2)) {
   // reports the same shape Commander's own `--version` path does.
   debug.recordCommandResult(debug.NO_RESULT_SET);
   debug.setOutcome('ok', {exitCode: 0});
-  console.log(JSON.stringify({apiVersion: API_VERSION, type: 'version', data: {version: pkg.version}}, null, 2));
+  console.log(JSON.stringify({apiVersion: API_VERSION, type: 'version', data: {version: pkg.version}, meta: {answeredBy: answeredBy()}}, null, 2));
   process.exit(0);
 }
 
@@ -98,6 +108,7 @@ export const JSON_SUPPORTED = new Set([
   'theme targets',
   'theme palette generate',
   'integration add',
+  'integration check',
   'integration verify',
   'integration pack',
   'upgrade',
@@ -184,6 +195,31 @@ export async function loadProjectDebugHandler() {
   }
 }
 
+/**
+ * Load the project's integrations before a help run, so help prints commands
+ * with the `cliCommand` they declare (spec:AST-081 FR5). Help is printed while
+ * Commander parses, before any hook, so the preAction load cannot reach it.
+ * `Project.load` reads astryx.config and each integration's manifest; it does
+ * no discovery. Skipped when the debug preload already loaded the project, and
+ * outside a package. Called from the bin before Commander parses.
+ *
+ * @param {string[]} [argv] arguments after the binary.
+ * @returns {Promise<void>}
+ */
+export async function loadProjectForHelp(argv = process.argv.slice(2)) {
+  const help =
+    argv.includes('--help') || argv.includes('-h') || argv[0] === 'help';
+  if (!help) return;
+  try {
+    const cwd = process.cwd();
+    if (hasRecordedProject(cwd)) return;
+    const {Project} = await import('../../foundation/config/project.mjs');
+    await Project.load(cwd);
+  } catch {
+    // Help prints with the package-manager guess.
+  }
+}
+
 /**
  * Hand the whole invocation to the debug recorder: which command ran, its
  * positional arguments by name, its options and where each value came from,
@@ -258,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'},
@@ -266,16 +302,40 @@ 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']);
+
+/**
+ * Is `cwd` inside the CLI's own source checkout while the CLI runs from it?
+ * An installed CLI always lives under `node_modules`; a CLI running from source
+ * does not, and its checkout is the pnpm workspace that holds it. Developing
+ * Astryx is not an app to set up, so the setup nudge stays quiet there.
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function inOwnSourceCheckout(cwd) {
+  if (CLI_ROOT.split(path.sep).includes('node_modules')) return false;
+  let checkout = CLI_ROOT;
+  while (!fs.existsSync(path.join(checkout, 'pnpm-workspace.yaml'))) {
+    const parent = path.dirname(checkout);
+    if (parent === checkout) return false;
+    checkout = parent;
+  }
+  const rel = path.relative(checkout, path.resolve(cwd));
+  return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
 /** An integration package's manifest: the package is not an app to set up. */
 const INTEGRATION_MANIFEST_FILES = [
   'astryx.integration.ts',
@@ -307,7 +367,8 @@ export async function createProgram() {
   // kit in clients/cli/formatters.
   program.addHelpText(
     'after',
-    '\n' +
+    // A function, so the example names the invocation when help is printed.
+    () => '\n' +
       [
         section(
           'Output format',
@@ -330,9 +391,13 @@ export async function createProgram() {
           {fields: ['block', 'shape']},
         ),
         text(
-          'Grep a field across records, e.g.  astryx search button | grep "^command:". ' +
+          `Grep a field across records, e.g.  ${formatCliCommand('search button')} | grep "^command:". ` +
             'Errors/warnings go to stderr; use --json for structured parsing.',
         ),
+        text(
+          "Global mode: in a project, the project's own CLI answers (this copy hands the run to it); a copy installed for the computer checks for updates once a day and keeps an agent skill in your home folder. " +
+            `See ${formatCliCommand('docs global')}.`,
+        ),
       ]
         .map(block => block.toString())
         .join('\n\n'),
@@ -429,6 +494,7 @@ export async function createProgram() {
             // Enriched, self-describing surface (the full manifest payload).
             manifest,
           },
+          meta: {answeredBy: answeredBy()},
         }, null, 2));
         debug.recordCommandResult(
           debug.resultSet({
@@ -525,10 +591,29 @@ export async function createProgram() {
     process.exit(1);
   });
 
+  /**
+   * Load the project's integrations before any command runs, so every command
+   * it prints starts with the `cliCommand` they declare (the picker reads them
+   * synchronously; see foundation/env/cli-command.mjs). Skipped when this
+   * process already loaded the project, such as the bin's debug preload. A
+   * project that cannot load is the command's to report, never this hook's.
+   */
+  program.hook('preAction', async () => {
+    try {
+      const cwd = process.cwd();
+      if (hasRecordedProject(cwd)) return;
+      const {Project} = await import('../../foundation/config/project.mjs');
+      await Project.load(cwd);
+    } catch {
+      // Best-effort: the picker falls back to its package-manager guess.
+    }
+  });
+
   /**
    * Enforcement layer 3 — setup nudge. If this project hasn't run `astryx init`
-   * yet (no Astryx marker in any agent-doc file — see isAstryxInitialized), remind
-   * the user/agent that setup is missing.
+   * yet (no Astryx marker in any agent-doc file between the project and its
+   * repository root — see isAstryxPromptInReach), remind the user/agent that
+   * setup is missing.
    *
    * Uses `preAction` (not postAction) so it fires for EVERY valid command — even
    * ones whose action errors or calls process.exit (postAction is skipped then).
@@ -538,7 +623,9 @@ export async function createProgram() {
    * consumers parse stdout, not stderr — a stderr nudge would not reach them anyway.
    * The core/cli postinstall layers already nudge at install time regardless of
    * --json; a machine-readable nudge could later be an envelope field. Also skipped
-   * for the installer commands themselves and outside a project (no package.json).
+   * for the installer commands themselves, outside a project (no package.json,
+   * or one that neither installs nor declares Astryx), and inside the CLI's own
+   * source checkout when it runs from there.
    */
   program.hook('preAction', (thisCommand, actionCommand) => {
     try {
@@ -546,15 +633,62 @@ 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
+      // A package.json that neither installs nor declares Astryx is outside a
+      // project: `init` would set up a project the folder does not have
+      // (spec AST-081 FR3).
+      if (isOutsideProject(cwd)) return;
       // 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`
-      // one-off, or `<pm> astryx` when installed — never the bare `npx astryx` footgun.
-      console.error(
-        `\nNext step: run \`${getCliInvocation(cwd)} init\` to finish setup and install the Astryx agent prompt.`,
-      );
+      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 —
+      // never npx with the unscoped name, which fetches an unrelated package.
+      // 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).
+      // 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(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.
     }
@@ -563,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;
@@ -583,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}, 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/cli-error.mjs

@@ -53,6 +53,7 @@
 import {isJsonMode, jsonError as _jsonError, humanWarn} from '../../../foundation/response/json.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {setOutcome} from '../../../foundation/debug/index.mjs';
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
 
 /**
  * Suggestion object — matches the shape used by API errors and the JSON
@@ -122,7 +123,9 @@ export function cliError(message, options = {}) {
   if (suggestions?.length) {
     console.error('');
     for (const s of suggestions) {
-      const tag = s.reason ? `  ${s.name}  (${s.reason})` : `  ${s.name}`;
+      // A suggested command stays bare in JSON and is prefixed here.
+      const name = /^astryx(\s|$)/.test(s.name) ? formatCliCommand(s.name) : s.name;
+      const tag = s.reason ? `  ${name}  (${s.reason})` : `  ${name}`;
       console.error(tag);
     }
   }

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

@@ -67,7 +67,7 @@ describe('formatFull sub-component rendering', () => {
     expect(out).not.toContain('undefined');
     // Points the reader at the sub-component's own docs instead of a blank.
     expect(out).toMatch(
-      /(?:astryx|@astryxdesign\/cli) component XDSRadioListItem/,
+      /(?:astryx|@astryxdesign\/cli(?:@\S+)?) component XDSRadioListItem/,
     );
   });
 

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) {
@@ -180,8 +185,8 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
  */
 export function addDocHelp(cmd, doc) {
   addExitCodesHelp(cmd, doc.exitCodes);
-  // Rendered when help is shown, so the run prefix (npx astryx, pnpm astryx,
-  // ...) is looked up then, not on every start.
+  // Rendered when help is shown, so the run prefix (pnpm exec astryx, yarn
+  // astryx, ...) is looked up then, not on every start.
   cmd.addHelpText('after', () => {
     const examples = (doc.examples ?? []).flatMap(({label, cli}) => [
       ...(label ? [`  # ${label}`] : []),

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/json-shim.mjs

@@ -42,6 +42,7 @@
  */
 
 import {API_VERSION, isJsonMode, toErrorEnvelope} from '../../../foundation/response/json.mjs';
+import {answeredBy} from '../../../foundation/release/run-context.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {setCommand, setOutcome, recordHelp} from '../../../foundation/debug/index.mjs';
 
@@ -84,7 +85,7 @@ function jsonActive() {
  * subcommand (e.g. `astryx component --help --json`).
  *
  * @param {import('commander').Command} cmd
- * @returns {{apiVersion: number, type: 'help', data: object}}
+ * @returns {{apiVersion: number, type: 'help', data: object, meta: {answeredBy: {cli: string, core: string | null, copy: 'project' | 'starting' | 'matched' | 'carried' | 'fallback'}}}}
  */
 export function buildHelpEnvelope(cmd) {
   // Reconstruct the fully-qualified command name (e.g. "astryx theme build").
@@ -119,6 +120,7 @@ export function buildHelpEnvelope(cmd) {
       options,
       subcommands,
     },
+    meta: {answeredBy: answeredBy()},
   };
 }
 

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

@@ -50,6 +50,13 @@ export interface ManifestCommand {
   examples?: string[];
   /** Documented exit codes: the process exit status and when it occurs. */
   exitCodes?: {code: number; when: string}[];
+  /**
+   * What the command does in a folder outside any project: `same` gives the
+   * answer it gives in a new project; `refuse` writes nothing and fails, naming
+   * the app project or integration package it needs; `own` does something
+   * else, which its docs state. Absent on a group that only holds subcommands.
+   */
+  outsideProject?: 'same' | 'refuse' | 'own';
   /** Nested subcommands (e.g. `theme build` under `theme`). */
   subcommands?: ManifestCommand[];
 }
@@ -64,6 +71,8 @@ export interface CLIManifest {
   commands: ManifestCommand[];
   /** Sorted list of fully-qualified command names that support `--json`. */
   jsonSupported: string[];
+  /** What a run may do beyond its command (the hand-off, the daily update check, the agent skill), and the docs topic that explains it. */
+  globalMode: {docs: string; summary: string};
   /** Flat index of response `type` discriminators keyed by command name. */
   responseTypes: Record<string, string[]>;
 }

package/clients/cli/lib/manifest.mjs

@@ -9,7 +9,8 @@
  *
  * Its per-command facts come from the command's own definitions: names,
  * arguments and options from Commander metadata (program.commands, cmd.options,
- * cmd.registeredArguments, cmd.description()); examples from its CommandDoc;
+ * cmd.registeredArguments, cmd.description()); examples, exit codes, and what
+ * it does outside a project from its CommandDoc;
  * response `type` discriminators from the returns of the FunctionDoc it wraps
  * (both attached by `defineCommand`); `--json` support from the JSON_SUPPORTED
  * allowlist in index.mjs. The hand-kept lists are CLI_LAYER_RESPONSE_TYPES,
@@ -39,6 +40,16 @@ import {API_VERSION} from '../../../foundation/response/json.mjs';
 import {commandDocsOf} from './define-command.mjs';
 import {doc as manifestDoc} from '../commands/manifest.doc.mjs';
 
+/**
+ * What a run may do beyond the command it was asked for (spec AST-081;
+ * `spec:AST-017` FR14), and where it is explained.
+ */
+export const GLOBAL_MODE = Object.freeze({
+  docs: 'astryx docs global',
+  summary:
+    "In a folder that belongs to a project, the project's own CLI answers: this copy hands the run to it. In a project with no CLI of its own, and outside any project, this copy answers. A copy installed for the computer checks the registry for a newer release once a day in the background, and keeps one agent skill file in the home folder.",
+});
+
 /**
  * Envelopes the CLI layer builds itself, so the wrapped FunctionDoc cannot
  * declare them: `manifest` wraps no API function, `theme build` batches several
@@ -194,6 +205,10 @@ function describeCommand(cmd, root, jsonSupported) {
   }));
   if (exitCodes.length > 0) entry.exitCodes = exitCodes;
 
+  // What the command does outside a project (spec AST-081 FR4). Every command
+  // declares it in its CommandDoc; a group that only holds subcommands does not.
+  if (docs?.doc.outsideProject) entry.outsideProject = docs.doc.outsideProject;
+
   // 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
@@ -265,6 +280,7 @@ export function buildManifest(program, opts = {}) {
     globalOptions: describeGlobalOptions(program),
     commands,
     jsonSupported: [...jsonSupported].sort(),
+    globalMode: GLOBAL_MODE,
     // Flat index of every response `type` discriminator the CLI can emit,
     // keyed by command — lets an agent know what to expect back per call.
     responseTypes: Object.fromEntries(

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] ?? [])];
@@ -307,3 +319,28 @@ describe('manifest: text projection', () => {
     for (const key of textKeys) expect(jsonKeys).toContain(key);
   });
 });
+
+describe('global mode is discoverable (spec:AST-017 FR14)', () => {
+  it('the manifest names what a run may do beyond its command, and the docs topic that explains it', () => {
+    expect(manifest.globalMode.docs).toBe('astryx docs global');
+    for (const word of ['hands the run', 'once a day', 'agent skill']) {
+      expect(manifest.globalMode.summary).toContain(word);
+    }
+  });
+
+  it('--help carries one line pointing to the global mode docs', () => {
+    const help = program.helpInformation() + '';
+    let after = '';
+    program.emit('afterHelp', {
+      error: false,
+      write: (/** @type {string} */ s) => {
+        after += s;
+      },
+    });
+    const lines = `${help}${after}`
+      .split('\n')
+      .filter(line => line.startsWith('Global mode:'));
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toMatch(/docs global\.$/u);
+  });
+});