@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/clients/cli/commands/upgrade.older-cli.test.mjs

@@ -0,0 +1,160 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx upgrade` with a CLI older than the installed Core: the human
+ * output never says the code is up to date, warns once with the same upgrade
+ * pinned to the CLI release that matches the Core, and keeps the exit status;
+ * `--json` carries the same facts in `cliBehindCore`. Pasted anywhere, the
+ * printed command runs that upgrade in the same project.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
+import {
+  commandInFolder,
+  getDlxPrefix,
+  quoteCommandArgument,
+} from '../../../foundation/env/package-manager.mjs';
+
+const CLI_VERSION = JSON.parse(
+  fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf8'),
+).version;
+const [MAJOR, MINOR] = CLI_VERSION.split('.').map(Number);
+const NEWER_CORE = `${MAJOR}.${MINOR + 1}.0`;
+const NON_ASCII = /[\u0080-\uFFFF]/;
+
+let tmpDir;
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+  const file = path.join(tmpDir, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, body);
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-older-cli-'));
+  write('package.json', JSON.stringify({name: 'consumer', private: true}));
+  write(
+    'node_modules/@astryxdesign/core/package.json',
+    JSON.stringify({name: '@astryxdesign/core', version: NEWER_CORE}),
+  );
+  write('src/index.ts', 'export const x = 1;\n');
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * The pinned command the CLI prints for this project. It names the folder the
+ * CLI ran in and the source directory as the CLI resolved them.
+ * @param {...string} rest the arguments after `--path <dir>`
+ */
+function pinned(...rest) {
+  const project = fs.realpathSync(tmpDir);
+  return commandInFolder(
+    project,
+    [
+      getDlxPrefix(tmpDir),
+      `@astryxdesign/cli@${NEWER_CORE}`,
+      'upgrade',
+      '--from',
+      CLI_VERSION,
+      '--path',
+      quoteCommandArgument(path.join(project, 'src')),
+      ...rest,
+    ].join(' '),
+  );
+}
+
+/**
+ * Stand-ins for the package runners: each drops its own words and the pinned
+ * package, then runs this CLI with the rest of the command.
+ */
+const RUNS_THIS_CLI = [
+  ['npx', 1],
+  ['bunx', 1],
+  ['pnpm', 2],
+  ['yarn', 2],
+]
+  .map(
+    ([name, words]) =>
+      `${name}() { shift ${words}; "$0" ${quoteCommandArgument(path.join(CLI_ROOT, 'clients', 'cli', 'bin', 'astryx.mjs'))} "$@"; }`,
+  )
+  .join('; ');
+
+describe('astryx upgrade with a CLI older than the installed Core', () => {
+  it('says it cannot finish and prints the upgrade pinned to the matching CLI', async () => {
+    const r = await runCli(['upgrade', '--from', CLI_VERSION, '--apply'], {
+      cwd: tmpDir,
+    });
+    const output = `${r.stdout}\n${r.stderr}`;
+
+    expect(r.status).toBe(0);
+    expect(output).not.toMatch(/up to date/i);
+    expect(output).not.toContain('No codemods available');
+    expect(r.stderr).toContain(
+      `This CLI (${CLI_VERSION}) is older than the installed @astryxdesign/core (${NEWER_CORE})`,
+    );
+    // The command has a line of its own, so it copies exactly.
+    expect(r.stderr).toContain(
+      `the CLI that matches your Core:\n  ${pinned('--apply')}\n`,
+    );
+    expect(r.stdout.trim().split('\n').at(-1)).toBe('Upgrade incomplete');
+    expect(output.split('\n').filter(line => NON_ASCII.test(line))).toEqual([]);
+  });
+
+  it('carries cliBehindCore in --json with the same exit status', async () => {
+    const r = await runCli(['--json', 'upgrade', '--from', CLI_VERSION], {
+      cwd: tmpDir,
+    });
+    const parsed = JSON.parse(r.stdout);
+
+    expect(r.status).toBe(0);
+    expect(parsed.type).toBe('upgrade.status');
+    expect(parsed.data.status).toBe('no_codemods');
+    expect(parsed.data.cliBehindCore).toEqual({
+      cliVersion: CLI_VERSION,
+      command: pinned(),
+    });
+  });
+
+  // Where an upgrade runs decides what it finds: the installed Core is read
+  // from that folder, and --path must stay inside it. Printed without its
+  // folder, the command exited 1 when pasted in a subfolder
+  // (ERR_PATH_TRAVERSAL) or in the folder above (ERR_VERSION_DETECT).
+  it.skipIf(process.platform === 'win32')(
+    'prints a command that upgrades the same project wherever it is pasted',
+    async () => {
+      write('src/deep/index.ts', 'export const y = 2;\n');
+      const r = await runCli(['--json', 'upgrade', '--from', CLI_VERSION], {
+        cwd: tmpDir,
+      });
+      const {command} = JSON.parse(r.stdout).data.cliBehindCore;
+
+      for (const pastedIn of [
+        path.join(tmpDir, 'src', 'deep'),
+        path.dirname(tmpDir),
+      ]) {
+        const ran = spawnSync(
+          '/bin/sh',
+          ['-c', `${RUNS_THIS_CLI}; ${command}`, process.execPath],
+          {cwd: pastedIn, encoding: 'utf8'},
+        );
+
+        expect(ran.status, ran.stderr).toBe(0);
+        expect(ran.stdout).toContain(`Installed target: ${NEWER_CORE}`);
+        expect(ran.stdout).toContain(
+          `Scanning ${path.join(fs.realpathSync(tmpDir), 'src')} `,
+        );
+      }
+    },
+    30_000,
+  );
+});

package/clients/cli/index.mjs

@@ -16,8 +16,14 @@ 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} 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 {buildManifest} from './lib/manifest.mjs';
 import {cliError} from './lib/cli-error.mjs';
 import {emit, section, text, records} from './formatters/index.mjs';
@@ -26,7 +32,9 @@ 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 {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 +71,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 +106,7 @@ export const JSON_SUPPORTED = new Set([
   'theme targets',
   'theme palette generate',
   'integration add',
+  'integration check',
   'integration verify',
   'integration pack',
   'upgrade',
@@ -184,6 +193,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,
@@ -276,6 +310,26 @@ const commands = [
 ];
 
 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 +361,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 +385,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 +488,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 +585,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 +617,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 +627,30 @@ 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
+      // 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).
+      const choice = runChoice(cwd);
+      if (choice.copy === 'starting' && choice.coreVersion && choice.coreVersion !== choice.version) {
+        const root = projectRootOf(readReleaseFacts(cwd)) ?? cwd;
+        console.error(
+          setupNudge(getCliInvocation(root, {installed: true}), {before: addCliCommand(root, choice.coreVersion)}).trimEnd(),
+        );
+        return;
+      }
+      console.error(setupNudge(getCliInvocation(cwd)).trimEnd());
     } catch {
       // Never let the nudge break a command.
     }
@@ -607,7 +703,7 @@ export async function createProgram() {
       );
       if (program.opts().json) {
         process.__xdsJsonHandled = true;
-        console.log(JSON.stringify({apiVersion: API_VERSION, type: 'manifest', data: manifest}, null, 2));
+        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).

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.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

@@ -180,8 +180,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/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

@@ -307,3 +307,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);
+  });
+});

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

@@ -20,6 +20,34 @@ export function discoverAgentDocs(targetDir: string): string[];
  * @returns {boolean}
  */
 export function isAstryxInitialized(targetDir?: string): boolean;
+/**
+ * Does an agent working in `startDir` already have the Astryx prompt in reach?
+ *
+ * Coding agents read the agent docs between the repository root and the folder
+ * they work in. So inside a git repository, init's block in any folder from
+ * `startDir` up to the repository root counts: a workspace package of a
+ * monorepo initialized at its root is set up. Outside a repository only
+ * `startDir` itself is checked, as {@link isAstryxInitialized} does. Both the
+ * per-command nudge and the postinstall nudges ask this.
+ *
+ * @param {string} [startDir=process.cwd()]
+ * @returns {boolean}
+ */
+export function isAstryxPromptInReach(startDir?: string): boolean;
+/**
+ * The one-line next-step every setup layer prints. Kept here so layer 1
+ * (core), layer 2 (cli postinstall) and layer 3 (each command) can never word
+ * it differently. Each layer passes the stem from the CLI's picker when it can
+ * load it.
+ *
+ * @param {string} [invocation] the CLI invocation stem, e.g. `pnpm exec astryx`
+ * @param {{before?: string | null}} [options] `before`: a command to run
+ *   first, such as the one that adds the CLI to a project that has none
+ * @returns {string}
+ */
+export function setupNudge(invocation?: string, { before }?: {
+    before?: string | null;
+}): string;
 /**
  * Pure decision: should a postinstall print the setup nudge? Shared by BOTH
  * postinstall layers, so the matrix cannot drift between them, and unit-testable
@@ -61,11 +89,12 @@ export const AGENT_DOC_PATHS: string[];
  */
 export const INIT_MARKERS: string[];
 /**
- * The one-line next-step both postinstall nudges print. Kept here so layer 1
- * (core) and layer 2 (cli) can never word it differently.
- *
- * Scoped package form (`@astryxdesign/cli`) — always resolves to us, even before
- * the CLI is installed. Bare `npx astryx` would fetch an unrelated look-alike
+ * The invocation the setup nudge falls back to when the CLI's picker
+ * (`getCliInvocation`) cannot be loaded. Scoped package form
+ * (`@astryxdesign/cli`) — always resolves to us, even before the CLI is
+ * installed. npx with the unscoped name would fetch an unrelated look-alike
  * package (see PR #4151).
  */
-export const SETUP_NUDGE: "\nNext step: run `npx @astryxdesign/cli init` to finish setup and install the Astryx agent prompt.\n\n";
+export const SETUP_INVOCATION: "npx @astryxdesign/cli";
+/** The nudge with the fallback invocation. */
+export const SETUP_NUDGE: string;