@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

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);
 }
 
@@ -185,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,
@@ -277,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',
@@ -308,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',
@@ -331,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'),
@@ -430,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({
@@ -526,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).
@@ -539,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 {
@@ -547,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.
     }
@@ -608,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;

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

@@ -97,15 +97,75 @@ export function isAstryxInitialized(targetDir = process.cwd()) {
 }
 
 /**
- * The one-line next-step both postinstall nudges print. Kept here so layer 1
- * (core) and layer 2 (cli) can never word it differently.
+ * Does an agent working in `startDir` already have the Astryx prompt in reach?
  *
- * Scoped package form (`@astryxdesign/cli`) — always resolves to us, even before
- * the CLI is installed. Bare `npx astryx` would fetch an unrelated look-alike
+ * 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 = process.cwd()) {
+  const start = path.resolve(startDir);
+  const repositoryRoot = findRepositoryRoot(start);
+  if (!repositoryRoot) return isAstryxInitialized(start);
+  for (let dir = start; ; dir = path.dirname(dir)) {
+    if (isAstryxInitialized(dir)) return true;
+    if (dir === repositoryRoot) return false;
+  }
+}
+
+/**
+ * The nearest folder at or above `start` that holds `.git` (a folder, or the
+ * file a worktree uses), or null outside a repository.
+ * @param {string} start
+ * @returns {string | null}
+ */
+function findRepositoryRoot(start) {
+  for (let dir = start; ; ) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * 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 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 = SETUP_INVOCATION,
+  {before = null} = {},
+) {
+  const run = before
+    ? `\`${before}\`, then \`${invocation} init\``
+    : `\`${invocation} init\``;
+  return `\nNext step: run ${run} to finish setup and install the Astryx agent prompt.\n\n`;
+}
+
+/** The nudge with the fallback invocation. */
+export const SETUP_NUDGE = setupNudge();
 
 /**
  * Pure decision: should a postinstall print the setup nudge? Shared by BOTH

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

@@ -97,11 +97,11 @@ export function detectStylingSystem(targetDir: string): "stylex" | "tailwind" |
  * among them. An agent cannot ask for a topic it was never told about, and
  * `getting-started` is the one it should reach for first.
  *
- * @param {string} version
+ * @param {string | null} version the Core version
  * @param {{coreDir?: string|null, invocation?: string, stylingSystem?: 'stylex'|'tailwind'|'css', zh?: boolean, lang?: string, topics?: string[], agentDocs?: Array<{package: string, append: readonly string[]}>}} [options]
  * @returns {string}
  */
-export function generateCompressedIndex(version: string, { coreDir, invocation, stylingSystem, topics, agentDocs, }?: {
+export function generateCompressedIndex(version: string | null, { coreDir, invocation, stylingSystem, topics, agentDocs, }?: {
     coreDir?: string | null;
     invocation?: string;
     stylingSystem?: "stylex" | "tailwind" | "css";
@@ -226,4 +226,5 @@ export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, on
 }): string[];
 import { discoverAgentDocs } from './agent-doc-state.mjs';
 import { isAstryxInitialized } from './agent-doc-state.mjs';
-export { discoverAgentDocs, isAstryxInitialized };
+import { isAstryxPromptInReach } from './agent-doc-state.mjs';
+export { discoverAgentDocs, isAstryxInitialized, isAstryxPromptInReach };

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

@@ -42,15 +42,17 @@ import {
   LEGACY_MARKER_END,
   discoverAgentDocs,
   isAstryxInitialized,
+  isAstryxPromptInReach,
 } from './agent-doc-state.mjs';
 
 // The agent-doc locations, markers, and the setup-state predicates
-// (discoverAgentDocs, isAstryxInitialized) are the ONE canonical contract. They
-// live in the dependency-free leaf ./agent-doc-state.mjs so the postinstall
-// nudge (enforcement layer 2) can load them safely at install time. Re-exported
-// here so existing importers (init/upgrade commands, the layer-3 nudge in
-// clients/cli/index.mjs, tests) keep their `from './agent-docs.mjs'` paths.
-export {discoverAgentDocs, isAstryxInitialized};
+// (discoverAgentDocs, isAstryxInitialized, isAstryxPromptInReach) are the ONE
+// canonical contract. They live in the dependency-free leaf
+// ./agent-doc-state.mjs so the postinstall nudge (enforcement layer 2) can load
+// them safely at install time. Re-exported here so existing importers
+// (init/upgrade commands, the layer-3 nudge in clients/cli/index.mjs, tests)
+// keep their `from './agent-docs.mjs'` paths.
+export {discoverAgentDocs, isAstryxInitialized, isAstryxPromptInReach};
 
 const MAX_PROJECT_AGENT_DOC_LINES = 32;
 const MANAGED_MARKER_TEXT = /(?:ASTRYX|XDS):(START|END)/u;
@@ -377,7 +379,7 @@ export function detectStylingSystem(targetDir) {
  * among them. An agent cannot ask for a topic it was never told about, and
  * `getting-started` is the one it should reach for first.
  *
- * @param {string} version
+ * @param {string | null} version the Core version
  * @param {{coreDir?: string|null, invocation?: string, stylingSystem?: 'stylex'|'tailwind'|'css', zh?: boolean, lang?: string, topics?: string[], agentDocs?: Array<{package: string, append: readonly string[]}>}} [options]
  * @returns {string}
  */
@@ -418,9 +420,9 @@ export function generateCompressedIndex(
       // Best-effort: component count is cosmetic; fall back to the default.
     }
   }
-
-  // Header — state the CLI prefix once; commands below are shown as `astryx <cmd>`.
   lines.push(`Astryx v${version} · ${componentCount} components`);
+
+  // State the CLI prefix once; commands below are shown as `astryx <cmd>`.
   lines.push(
     `CLI: run every command as \`${run} <cmd>\` (shown below as \`astryx ...\`).`,
   );