@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/authoring/doctypes/template/parse.d.mts

@@ -18,7 +18,9 @@ export type BlockTemplateDoc = import("./type.js").BlockTemplateDoc;
  * Templates as they load. Integration templates already published omit
  * `displayName` and `aspectRatio` and group themselves under their own
  * `category`, so the loader accepts those (template discovery falls back to an
- * aspect ratio of 1). The published types keep asking authors for all three.
+ * aspect ratio of 1). The published `TemplateDoc` keeps asking authors for all
+ * three; `IntegrationTemplateDoc`, for an integration package's templates,
+ * takes the package's own `category`.
  */
 export type LoadedPageTemplateDoc = Omit<PageTemplateDoc, "displayName" | "category"> & {
     displayName?: string;
@@ -28,7 +30,9 @@ export type LoadedPageTemplateDoc = Omit<PageTemplateDoc, "displayName" | "categ
  * Templates as they load. Integration templates already published omit
  * `displayName` and `aspectRatio` and group themselves under their own
  * `category`, so the loader accepts those (template discovery falls back to an
- * aspect ratio of 1). The published types keep asking authors for all three.
+ * aspect ratio of 1). The published `TemplateDoc` keeps asking authors for all
+ * three; `IntegrationTemplateDoc`, for an integration package's templates,
+ * takes the package's own `category`.
  */
 export type LoadedBlockTemplateDoc = Omit<BlockTemplateDoc, "displayName" | "aspectRatio" | "category"> & {
     displayName?: string;

package/authoring/doctypes/template/parse.mjs

@@ -78,7 +78,9 @@ const blockTemplateSchema = z
  * Templates as they load. Integration templates already published omit
  * `displayName` and `aspectRatio` and group themselves under their own
  * `category`, so the loader accepts those (template discovery falls back to an
- * aspect ratio of 1). The published types keep asking authors for all three.
+ * aspect ratio of 1). The published `TemplateDoc` keeps asking authors for all
+ * three; `IntegrationTemplateDoc`, for an integration package's templates,
+ * takes the package's own `category`.
  *
  * @typedef {Omit<PageTemplateDoc, 'displayName' | 'category'>
  *   & {displayName?: string, category?: string}} LoadedPageTemplateDoc

package/authoring/doctypes/template/template.doc.mjs

@@ -31,14 +31,14 @@ export const doc = {
       name: 'name',
       type: 'string',
       description:
-        'Stable identifier for block templates; change `displayName`, not `name`, to edit their visible label. For page templates it is a human-readable label, while the existing template-directory/CLI slug owns the default registry path.',
+        "Stable identifier for block templates; change `displayName`, not `name`, to edit their visible label in the gallery. For page templates it is a human-readable label, while the existing template-directory/CLI slug owns the default registry path. `astryx template --list` and `astryx search` print `name` as the label of both, and `astryx template <id>` finds a template by its id, never by `name`: an integration template's id is its path under the templates folder without the `.doc.*` suffix.",
       required: true,
     },
     {
       name: 'displayName',
       type: 'string',
       description:
-        "Human-readable label for the gallery/CLI. Spaces out block names that mirror a PascalCase component ('ChatMessageMetadata' → 'Chat Message Metadata').",
+        "Human-readable label for the gallery. The CLI prints `name` instead; `astryx template --list --json` also returns an integration template's `displayName`. Spaces out block names that mirror a PascalCase component ('ChatMessageMetadata' → 'Chat Message Metadata').",
       required: true,
     },
     {
@@ -162,7 +162,7 @@ export default {
   notes: [
     {
       type: 'prose',
-      text: 'When it loads, a template may leave out `displayName` and `aspectRatio` and use its own `category`, as integration templates already published do; a block with no `aspectRatio` previews at 1. Write to the type anyway; it is the contract.',
+      text: 'When it loads, a template may leave out `displayName` and `aspectRatio` and use its own `category`, as integration templates already published do; a block with no `aspectRatio` previews at 1. Write to the type anyway; it is the contract, and `astryx doctor integration validate` warns about an integration template that leaves out `displayName` or `aspectRatio`.',
     },
     {
       type: 'prose',

package/authoring/doctypes/template/type.ts

@@ -201,3 +201,25 @@ export type TemplateCategory =
   | 'Shell - Blank';
 
 export type TemplateDoc = PageTemplateDoc | BlockTemplateDoc;
+
+/** A page template an integration package ships, with its own `category`. */
+export interface IntegrationPageTemplateDoc extends Omit<
+  PageTemplateDoc,
+  'category'
+> {
+  category?: string;
+}
+
+/** A block template an integration package ships, with its own `category`. */
+export interface IntegrationBlockTemplateDoc extends Omit<
+  BlockTemplateDoc,
+  'category'
+> {
+  category?: string;
+}
+
+/** The doc-type for an integration package's template metadata: TemplateDoc,
+ *  with `category` the package's own string (bare `astryx template` groups
+ *  the package's templates by it) instead of a TemplateCategory value. */
+export type IntegrationTemplateDoc =
+  IntegrationPageTemplateDoc | IntegrationBlockTemplateDoc;

package/authoring/doctypes/theme/theme.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   displayName: 'ThemeDoc',
   namespace: 'authoring',
   description:
-    'The strongly typed descriptor for one integration or CLI-bundled source theme.',
+    "The strongly typed descriptor for one source theme: bundled with the CLI, shipped by an integration, or kept in the project's src/themes, where `theme eject` writes one.",
   appliesTo: '<theme-source-stem>.doc.mjs',
   fields: [
     {
@@ -65,7 +65,7 @@ export default {
   notes: [
     {
       type: 'prose',
-      text: 'ThemeDoc is static metadata. Default-export one object with literal string and boolean fields; discovery validates it without executing the descriptor or theme source.',
+      text: "ThemeDoc is static metadata. The descriptor holds one default-exported object of literal string and boolean fields, directly under a `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */` comment, and nothing else: without that comment, or with any other statement, it fails to load. Discovery validates it without executing the descriptor or theme source.",
     },
     {
       type: 'prose',

package/authoring/gap-report/gap-report.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'GapReportHandler',
   namespace: 'authoring',
   description:
-    'A handler for `astryx gap-report`: a plain object with an `audience` and a `handle` function. Set it as `gapReport` in astryx.config, or export it as `gapReport` from an integration manifest. Every handler runs: the project handler first, then each integration handler in config order.',
+    "A handler for `astryx gap-report`: a plain object with an `audience` and a `handle` function. Set it as `gapReport` in astryx.config, or export it as `gapReport` from an integration manifest. Handlers add up rather than replace each other: the project handler first, then each loaded integration's in load order (the `integrations` list, then autolinked ones), whichever package the report is about.",
   appliesTo:
     '`gapReport` in astryx.config.*, or the `gapReport` named export of astryx.integration.*',
   fields: [
@@ -104,7 +104,7 @@ export const doc = {
                   name: 'report.target.version',
                   type: 'string',
                   description:
-                    'The installed version. Null when it is not known.',
+                    "The integration's version from its package.json. Null for Core, and when the package.json has none.",
                   required: true,
                 },
                 {

package/authoring/identity/identity.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   displayName: 'Provider and artifact identity',
   namespace: 'authoring',
   description:
-    'Separates stable provider/artifact identity from package instances and runtime lifecycle state. Provider identity names integration manifests and settles provider conflicts. Docs-tree nodes are identified by doc identity; the tree covers the CLI\'s own docs. Artifact, instance, and compiler-input identities are defined for every provider-owned artifact; no command reads them.',
+    "Separates stable provider/artifact identity from package instances and runtime lifecycle state. Provider identity names integration manifests and settles provider conflicts. Docs-tree nodes are identified by doc identity; the tree covers the CLI's docs and each integration's. Artifact IDs for kinds outside the docs tree, provider instances, and compiler-input entries are defined for every provider-owned artifact; no command builds them.",
   appliesTo:
     'Integration manifests, provider conflicts, and docs-tree node ids.',
   fields: [
@@ -41,14 +41,14 @@ export const doc = {
       name: 'ProviderInstance',
       type: '{ id; providerId; packageName; packageVersion; sourceDigest }',
       description:
-        'One immutable package version and source/content digest. Installed, configured, loaded, selected, and healthy state is a separate runtime overlay.',
+        'One immutable package version and source/content digest. It carries no installed, configured, loaded, selected, or healthy state.',
       required: true,
     },
     {
       name: 'AuthoredDocEntry',
       type: '{ id; provider; kind; stableName; source; authored }',
       description:
-        'Normalized compiler input. Discovery supplies stableName independently from the authored display name, source paths remain package-relative, and provider provenance plus the authored snapshot are immutable.',
+        'Normalized compiler input. `stableName`, the key in its doc ID, is given separately from the authored display name; source paths remain package-relative, and provider provenance plus the authored snapshot are immutable.',
       required: true,
     },
   ],

package/authoring/index.d.ts

@@ -28,6 +28,7 @@ export type {HookDoc} from './doctypes/types.js'; //         useToast.doc.mjs
 export type {FunctionDoc} from './doctypes/types.js'; //     search.doc.mjs (hook | api)
 export type {ReferenceDoc} from './doctypes/types.js'; //    theming.doc.mjs
 export type {TemplateDoc} from './doctypes/types.js'; //     Foo.doc.mjs
+export type {IntegrationTemplateDoc} from './doctypes/types.js'; // an integration's Foo.doc.mjs
 export type {SchemaDoc} from './doctypes/types.js'; //       config.doc.mjs (object shape)
 export type {CommandDoc} from './doctypes/types.js'; //      search.doc.mjs (CLI command)
 export type {EnumDoc} from './doctypes/types.js'; //         error-codes.doc.mjs (vocabulary)
@@ -162,6 +163,7 @@ export type {
   CommandArgDoc,
   CommandOptionDoc,
   CommandExampleDoc,
+  CommandOutsideProject,
   // enum
   EnumMemberDoc,
 } from './doctypes/types.js';

package/authoring/integration/integration.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
     'The astryx.integration.* manifest that sits beside an integration ' +
     "package's package.json. It can preserve a stable provider identity across a package rename, " +
     "and points the CLI at the package's components, templates, codemods, doc topics, " +
-    'source themes, managed agent guidance, and issue tracker. Every field is optional.',
+    'source themes, managed agent guidance, issue tracker, and the command its users run the CLI with. Every field is optional.',
   appliesTo: 'astryx.integration.{ts,mjs,js}',
   fields: [
     {
@@ -51,7 +51,7 @@ export const doc = {
       name: 'docs',
       type: 'string',
       description:
-        'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} in it shows up in `astryx docs` next to the built-in topics; a topic can also set `replaces` or `extends` to take over a built-in topic or add to it.',
+        'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} under it shows up in `astryx docs`: a flat topic next to the built-in topics, where it can set `replaces` or `extends` to take over a built-in topic or add to it, and a guide with `placement` at its own route in the docs tree, under a namespace doc of the same package.',
       example: "'./docs'",
     },
     {
@@ -71,9 +71,24 @@ export const doc = {
     {
       name: 'issuesUrl',
       type: 'string',
-      description: 'Where to file issues/feedback for this integration.',
+      description:
+        "Where people file issues for this package: an absolute URL, such as its GitHub issues page. A value that is not a URL fails the whole manifest; the scheme is not checked. Nothing warns when it is missing, but without it `astryx gap-report` about this package fails unless the project or a loaded integration has a gapReport handler, and `astryx swizzle` prints no feedback link for this package's components. When no handler is loaded, a github.com issues URL is filed with the GitHub CLI once the reporter passes `--confirm-public`; any other URL is returned for the reporter to open.",
       example: "'https://github.com/acme/widgets/issues'",
     },
+    {
+      name: 'docsiteUrl',
+      type: 'string',
+      description:
+        "Link to this integration's docs site, such as its home page. Catalogs that list the package may show it.",
+      example: "'https://widgets.acme.dev'",
+    },
+    {
+      name: 'cliCommand',
+      type: 'string',
+      description:
+        'The command your users run the Astryx CLI with, when it is not their package manager, such as a wrapper your company ships. Every command the CLI prints in an app that loads your package starts with it, in place of `pnpm exec astryx` or `yarn astryx`: hints, errors, Doctor fixes, and doc text. One line, without a subcommand. If two loaded packages set different commands, neither is used and `astryx doctor` warns. An invalid value is ignored with an `invalid_cli_command` warning, and the rest of the manifest still loads. JSON output keeps commands bare.',
+      example: "'acme astryx'",
+    },
   ],
   examples: [
     {
@@ -92,6 +107,10 @@ export const doc = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: "In global mode: a manifest loads the same way when users install your package for their computer, beside the global CLI, and then applies in folders outside any project; inside a project, only if the project installs it. Peer ranges for `@astryxdesign/core` and `@astryxdesign/cli` are checked against the global CLI's release. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
     {
       type: 'prose',
       text:
@@ -107,18 +126,23 @@ export const doc = {
         'trimmed, non-blank string of at most 240 Unicode code points with no ' +
         'line separators, control characters, NUL, or Astryx/XDS managed-marker ' +
         'text. The configured project may contain at most 32 integration lines ' +
-        'total.',
+        'total. Write each command in a line as a bare `astryx` command; the ' +
+        'managed block says once, before your lines, how the app starts the CLI.',
+    },
+    {
+      type: 'prose',
+      text: "Set `cliCommand` only when your users run the CLI with a command other than their package manager's, such as `acme astryx`. The CLI picks the command it prints in this order: the `cliCommand` of the loaded integrations when they name one command, then the command a host tool names, then the package manager's. Two different `cliCommand` values cancel out, and `astryx doctor` warns in its `cli-command` check. See `astryx docs cli/integrations/building-blocks/configuration/cli-command`.",
     },
     {
       type: 'prose',
-      text: 'A themes root is forward-compatible but version-gated: a CLI released before this field ignores it with a warning and continues loading every contribution kind it understands. That older CLI cannot list or add the contributed themes.',
+      text: 'A themes root is version-gated: an older CLI lists and adds none of its themes. Depending on its age, that CLI ignores `themes` with an `unknown_manifest_key` warning and loads every other contribution kind, reports the root as invalid because it expects the earlier `manifest.json` theme catalog, or, if it is old enough to treat an unknown field as an error, rejects the whole manifest, so the package contributes nothing there.',
     },
     {
       type: 'prose',
       text:
         'Validate the manifest with `astryx doctor integration validate`. At the ' +
         'load boundary, a known field of the wrong type is an error, issuesUrl ' +
-        'must be a valid URL, and unknown fields become warnings so an older CLI ' +
+        'and docsiteUrl must be valid URLs, and unknown fields become warnings so an older CLI ' +
         'can still load the fields it understands. Before publishing, also run ' +
         '`templates`, `components`, and `docs` under the same `doctor integration` ' +
         'group. Those leaves compare authored identities with Core and explain ' +

package/authoring/integration/parse.test.mjs

@@ -87,6 +87,27 @@ describe('parseIntegration (load boundary)', () => {
     expect(reason({issuesUrl: 'nope'})).toContain('issuesUrl');
   });
 
+  it('accepts a docsiteUrl as a known key', () => {
+    const manifest = {docsiteUrl: 'https://widgets.example.com'};
+    expect(parseIntegration(manifest)).toEqual(manifest);
+    expect(unknownIntegrationKeys(manifest)).toEqual([]);
+  });
+
+  it('rejects a non-URL docsiteUrl', () => {
+    expect(reason({docsiteUrl: 'nope'})).toContain('docsiteUrl');
+  });
+
+  it('accepts a cliCommand and rejects one that is not a single clean line', () => {
+    expect(parseIntegration({cliCommand: 'acme astryx'})).toEqual({
+      cliCommand: 'acme astryx',
+    });
+    expect(reason({cliCommand: ''})).toContain('cliCommand');
+    expect(reason({cliCommand: ' acme astryx'})).toContain('cliCommand');
+    expect(reason({cliCommand: 'acme\nastryx'})).toContain('cliCommand');
+    expect(reason({cliCommand: 'a'.repeat(121)})).toContain('120');
+    expect(reason({cliCommand: 42})).toContain('cliCommand');
+  });
+
   it('rejects a noncanonical providerId', () => {
     expect(reason({providerId: 'Acme Widgets'})).toContain('providerId');
   });

package/authoring/integration/schema.d.mts

@@ -3,12 +3,12 @@
 
 /**
  * Parse every default-manifest field except the independently isolated
- * `agentDocs` contribution.
+ * `agentDocs` and `cliCommand` fields.
  * @param {unknown} input
  * @param {string} label
- * @returns {Omit<AstryxIntegration, 'agentDocs'>}
+ * @returns {Omit<AstryxIntegration, 'agentDocs' | 'cliCommand'>}
  */
-export function parseIntegrationBase(input: unknown, label: string): Omit<AstryxIntegration, "agentDocs">;
+export function parseIntegrationBase(input: unknown, label: string): Omit<AstryxIntegration, "agentDocs" | "cliCommand">;
 /**
  * Parse only the optional agent-doc contribution.
  * @param {unknown} input
@@ -16,6 +16,15 @@ export function parseIntegrationBase(input: unknown, label: string): Omit<Astryx
  * @returns {NonNullable<AstryxIntegration['agentDocs']>}
  */
 export function parseAgentDocsField(input: unknown, label: string): NonNullable<AstryxIntegration["agentDocs"]>;
+/**
+ * Parse only the optional `cliCommand` field. Isolated like `agentDocs`: an
+ * invalid command is ignored with a warning, and the rest of the manifest
+ * still contributes.
+ * @param {unknown} input
+ * @param {string} label
+ * @returns {string}
+ */
+export function parseCliCommandField(input: unknown, label: string): string;
 /**
  * The manifest keys this CLI does not know, in the order they were authored.
  *
@@ -28,6 +37,7 @@ export function parseAgentDocsField(input: unknown, label: string): NonNullable<
  * @returns {string[]}
  */
 export function unknownIntegrationKeys(input: unknown): string[];
+export const cliCommandSchema: z.ZodString;
 export const agentDocsSchema: z.ZodObject<{
     append: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>;
@@ -39,6 +49,7 @@ export const integrationBaseSchema: z.ZodObject<{
     docs: z.ZodOptional<z.ZodString>;
     themes: z.ZodOptional<z.ZodString>;
     issuesUrl: z.ZodOptional<z.ZodString>;
+    docsiteUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export const integrationSchema: z.ZodObject<{
     providerId: z.ZodOptional<z.ZodString>;
@@ -48,9 +59,11 @@ export const integrationSchema: z.ZodObject<{
     docs: z.ZodOptional<z.ZodString>;
     themes: z.ZodOptional<z.ZodString>;
     issuesUrl: z.ZodOptional<z.ZodString>;
+    docsiteUrl: z.ZodOptional<z.ZodString>;
     agentDocs: z.ZodOptional<z.ZodObject<{
         append: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>>;
+    cliCommand: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.

package/authoring/integration/schema.mjs

@@ -19,6 +19,7 @@ import {formatZodError} from '../_shared/errors.mjs';
 /** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 
 const MAX_AGENT_DOC_LINES = 8;
+const MAX_CLI_COMMAND_CODE_POINTS = 120;
 const MAX_AGENT_DOC_LINE_CODE_POINTS = 240;
 const MANAGED_MARKER_TEXT = /(?:ASTRYX|XDS):(START|END)/u;
 const PROVIDER_ID_RE =
@@ -51,6 +52,21 @@ function invalidAgentDocLine(value) {
   return null;
 }
 
+export const cliCommandSchema = z.string().superRefine((value, ctx) => {
+  const message = invalidAgentDocLine(value);
+  if (message) {
+    ctx.addIssue({code: 'custom', message});
+    return;
+  }
+  const codePoints = [...value].length;
+  if (codePoints > MAX_CLI_COMMAND_CODE_POINTS) {
+    ctx.addIssue({
+      code: 'custom',
+      message: `must contain at most ${MAX_CLI_COMMAND_CODE_POINTS} Unicode code points (received ${codePoints})`,
+    });
+  }
+});
+
 const agentDocLineSchema = z.string().superRefine((value, ctx) => {
   const message = invalidAgentDocLine(value);
   if (message) ctx.addIssue({code: 'custom', message});
@@ -78,6 +94,7 @@ export const integrationBaseSchema = z.object({
   docs: z.string().optional(),
   themes: z.string().optional(),
   issuesUrl: z.string().url().optional(),
+  docsiteUrl: z.string().url().optional(),
 });
 
 // Unknown top-level keys are stripped rather than rejected. `.strict()` made a key from a
@@ -91,14 +108,15 @@ export const integrationBaseSchema = z.object({
 // IS an authoring mistake and still fails here.
 export const integrationSchema = integrationBaseSchema.extend({
   agentDocs: agentDocsSchema.optional(),
+  cliCommand: cliCommandSchema.optional(),
 });
 
 /**
  * Parse every default-manifest field except the independently isolated
- * `agentDocs` contribution.
+ * `agentDocs` and `cliCommand` fields.
  * @param {unknown} input
  * @param {string} label
- * @returns {Omit<AstryxIntegration, 'agentDocs'>}
+ * @returns {Omit<AstryxIntegration, 'agentDocs' | 'cliCommand'>}
  */
 export function parseIntegrationBase(input, label) {
   const result = integrationBaseSchema.safeParse(input);
@@ -118,6 +136,20 @@ export function parseAgentDocsField(input, label) {
   return result.data;
 }
 
+/**
+ * Parse only the optional `cliCommand` field. Isolated like `agentDocs`: an
+ * invalid command is ignored with a warning, and the rest of the manifest
+ * still contributes.
+ * @param {unknown} input
+ * @param {string} label
+ * @returns {string}
+ */
+export function parseCliCommandField(input, label) {
+  const result = cliCommandSchema.safeParse(input);
+  if (!result.success) throw new Error(formatZodError(label, result.error));
+  return result.data;
+}
+
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  *

package/authoring/integration/type.ts

@@ -44,6 +44,18 @@ export interface AstryxIntegration {
   };
   /** Where to file issues/feedback for this integration. */
   issuesUrl?: string;
+  /** Link to this integration's docs site, such as its home page. The CLI
+   *  accepts it as a known field; catalogs that list the package may show
+   *  it. */
+  docsiteUrl?: string;
+  /** The command that runs the Astryx CLI for this package's users, such as
+   *  `acme astryx`. Every command the CLI prints in a project that loads
+   *  this package starts with it, in place of the package-manager prefix
+   *  (`pnpm exec astryx`, `yarn astryx`). One line, no subcommand. When two
+   *  loaded integrations set different commands, neither is used and
+   *  `astryx doctor` warns. An invalid value is ignored with a warning; the
+   *  rest of the manifest still loads. JSON output keeps commands bare. */
+  cliCommand?: string;
 }
 
 /**

package/clients/cli/bin/astryx.mjs

@@ -14,7 +14,7 @@
 // unsupported runtimes this guard protects against.
 //
 // Sibling package modules (e.g. `cli/`, `lib/`) are resolved by this bin's REAL
-// path. When the CLI is installed as a package, `npx astryx` runs this file
+// path. When the CLI is installed as a package, the package manager runs this file
 // through the `node_modules/.bin/astryx` symlink, and some Node versions resolve
 // relative specifiers from the symlink's directory rather than the real package
 // — breaking bare `../…` imports with a cryptic ERR_MODULE_NOT_FOUND.
@@ -53,10 +53,24 @@ if (!isNodeVersionSupported(process.versions.node)) {
   process.exit(1);
 }
 
+// Global mode: choose the release that answers this folder and, when it is
+// not this copy, hand the run to it before anything the project provides (its
+// astryx.config, integrations, or Core) is loaded. Returns only when this copy
+// answers. See foundation/release/handoff.mjs and spec AST-081 FR2 and FR9.
+const {startRun} = await importSrc('../../foundation/release/handoff.mjs');
+await startRun({
+  cliRoot: join(binDir, '..', '..', '..'),
+  argv: process.argv.slice(2),
+});
+
 // Imports that transitively load `styleText` must happen AFTER the gate above,
 // so they are dynamically imported here rather than at the top of the module.
-const {program, loadProjectDebugHandler, handleVersionJsonPreflight} =
-  await importSrc('index.mjs');
+const {
+  program,
+  loadProjectDebugHandler,
+  loadProjectForHelp,
+  handleVersionJsonPreflight,
+} = await importSrc('index.mjs');
 const {isJsonMode, toErrorEnvelope} = await importSrc('../../foundation/response/json.mjs');
 const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
 const {setOutcome} = await importSrc('../../foundation/debug/index.mjs');
@@ -107,6 +121,9 @@ process.on('uncaughtException', handleFatal);
 // Pick up the project's `debug` function before parsing, so parse errors and
 // `--help` — which short-circuit before any hook runs — are reported too.
 await loadProjectDebugHandler();
+// Help prints its commands while Commander parses, so a help run reads the
+// project's declared `cliCommand` here.
+await loadProjectForHelp();
 
 // `--version --json` answers and exits without Commander, so it runs here —
 // after the handler exists, or the run would go unrecorded.

package/clients/cli/cli-command.test.mjs

@@ -0,0 +1,166 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Every printed command starts with the project's CLI command: the door a host
+ * sets, or the `cliCommand` a loaded integration declares. JSON keeps commands
+ * bare.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} 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 {
+  hasRecordedProject,
+  runWithCliDoor,
+} from '../../foundation/env/cli-command.mjs';
+import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
+import {loadProjectForHelp} from './index.mjs';
+
+const BIN = path.resolve(import.meta.dirname, 'bin', 'astryx.mjs');
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  // Repo-local, so Vite permits importing the integration manifest.
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-cli-command-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * An app that installs one integration declaring `cliCommand`, with no
+ * astryx.config: the integration is autolinked.
+ * @param {string} cliCommand
+ */
+function appWithIntegration(cliCommand) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'app', dependencies: {'@acme/x': '1.0.0'}}),
+  );
+  fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '<!-- ASTRYX:START -->\n');
+  const pkg = path.join(tmpDir, 'node_modules', '@acme', 'x');
+  fs.mkdirSync(pkg, {recursive: true});
+  fs.writeFileSync(
+    path.join(pkg, 'package.json'),
+    JSON.stringify({name: '@acme/x', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkg, 'astryx.integration.mjs'),
+    `export default ${JSON.stringify({cliCommand})};\n`,
+  );
+}
+
+describe("an integration's cliCommand", () => {
+  it('starts the hints of a command that never loads the project itself', async () => {
+    appWithIntegration('acme astryx');
+    const {status, stderr} = await runCli(['theme', 'remove', 'nope'], tmpDir);
+    expect(status).toBe(1);
+    expect(stderr).toContain('`acme astryx theme add nope`');
+  });
+});
+
+describe('the setup nudge in a project with no CLI of its own', () => {
+  it('names the declared cliCommand for the step after installing the CLI (spec AST-081 FR5)', async () => {
+    // Outside this repository: the nudge stays quiet in the CLI's own checkout.
+    const app = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'astryx-cli-command-nudge-'),
+    );
+    try {
+      // Only Core, of another release than the CLI that answers, an
+      // integration declaring cliCommand, and no agent docs yet.
+      fs.writeFileSync(
+        path.join(app, 'package.json'),
+        JSON.stringify({
+          name: 'app',
+          dependencies: {'@acme/x': '1.0.0', '@astryxdesign/core': '0.0.1'},
+        }),
+      );
+      fs.writeFileSync(path.join(app, 'package-lock.json'), '{}');
+      for (const [name, version, extra] of [
+        ['@acme/x', '1.0.0', 'acme astryx'],
+        ['@astryxdesign/core', '0.0.1', null],
+      ]) {
+        const dir = path.join(app, 'node_modules', ...name.split('/'));
+        fs.mkdirSync(dir, {recursive: true});
+        fs.writeFileSync(
+          path.join(dir, 'package.json'),
+          JSON.stringify({name, version}),
+        );
+        if (extra) {
+          fs.writeFileSync(
+            path.join(dir, 'astryx.integration.mjs'),
+            `export default ${JSON.stringify({cliCommand: extra})};\n`,
+          );
+        }
+      }
+
+      const {stderr} = await runCli(['docs', 'tokens'], app);
+      expect(stderr).toContain(
+        'Next step: run `npm install @astryxdesign/cli@0.0.1`, then `acme astryx init`',
+      );
+    } finally {
+      fs.rmSync(app, {recursive: true, force: true});
+    }
+  });
+});
+
+describe('help', () => {
+  it('loads the project for a help run, and only for one', async () => {
+    appWithIntegration('acme astryx');
+    const cwd = process.cwd();
+    process.chdir(tmpDir);
+    try {
+      await loadProjectForHelp(['docs', 'theme']);
+      expect(hasRecordedProject(tmpDir)).toBe(false);
+      await loadProjectForHelp(['component', '--help']);
+      expect(getCliInvocation(tmpDir)).toBe('acme astryx');
+    } finally {
+      process.chdir(cwd);
+    }
+  });
+
+  it("prints the integration's command in `--help`", () => {
+    appWithIntegration('acme astryx');
+    const result = spawnSync(process.execPath, [BIN, '--help'], {
+      cwd: tmpDir,
+      encoding: 'utf-8',
+    });
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('acme astryx search button');
+  });
+});
+
+describe("a host's door", () => {
+  it('prefixes doc commands in text and leaves them bare in JSON', async () => {
+    const text = await runWithCliDoor('acme astryx', () =>
+      runCli(['docs', 'getting-started', '--full']),
+    );
+    expect(text.stdout).toContain('acme astryx init');
+
+    const json = await runWithCliDoor('acme astryx', () =>
+      runCli(['docs', 'getting-started', '--json']),
+    );
+    expect(json.stdout).toContain('astryx init');
+    expect(json.stdout).not.toContain('acme astryx');
+  });
+
+  it('prefixes suggested commands in text and leaves them bare in JSON', async () => {
+    const text = await runWithCliDoor('acme astryx', () =>
+      runCli(['search', '']),
+    );
+    expect(text.stderr).toContain('acme astryx search button');
+
+    const json = await runWithCliDoor('acme astryx', () =>
+      runCli(['search', '', '--json']),
+    );
+    expect(JSON.parse(json.stdout).suggestions[0].name).toBe(
+      'astryx search button',
+    );
+  });
+});