@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/authoring/doctypes/function/function.doc.mjs

@@ -18,7 +18,7 @@ export const doc = {
     'functions. A hook (HookDoc) is the hook-flavored view of this same kind; FunctionDoc ' +
     'adds the fields an API function needs (a {type, data} return envelope, thrown error ' +
     'codes, the wrapping CLI command). The CLI binding itself lives in a separate CommandDoc.',
-  appliesTo: 'api/<name>/<name>.doc.mjs',
+  appliesTo: 'api/<dir>/<name>.doc.mjs',
   fields: [
     {
       name: 'type',
@@ -41,7 +41,7 @@ export const doc = {
       name: 'kind',
       type: "'hook' | 'api'",
       description:
-        'Which flavor; drives docsite sectioning; inferred from importPath if omitted.',
+        "Which flavor. Nothing reads it today: no reader sections docs by it or infers it from `importPath`. The CLI's API function docs set 'api'.",
     },
     {
       name: 'summary',
@@ -57,12 +57,13 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's API functions use 'cli/api', which the docs tree adopts by kind: each is the leaf `cli/api/functions/<name>`. Every function doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
+        "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's API functions use 'cli/api', which the docs tree adopts by kind: each is the leaf `cli/api/functions/<name>`, the name in kebab case (`themeUse` is `theme-use`). Every function doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',
       type: 'string[]',
-      description: 'Alternate slugs that also resolve to this doc.',
+      description:
+        'Reserved: other names for this doc. Nothing reads it today, so they do not resolve to it.',
     },
     {
       name: 'keywords',
@@ -231,11 +232,11 @@ export const doc = {
   displayName: 'search()',
   namespace: 'cli/api',
   importPath: '@astryxdesign/cli/api',
-  summary: 'Find components, hooks, docs, and templates by term.',
+  summary: 'Find components, hooks, docs, templates, and themes by term.',
   signature: 'search(query, options?): Promise<SearchResponse>',
   params: [
     {name: 'query', type: 'string', description: 'The search term.', required: true},
-    {name: 'options.type', type: "'component' | 'hook' | 'doc' | 'template'", description: 'Restrict results to one domain.'},
+    {name: 'options.type', type: "'component' | 'hook' | 'doc' | 'template' | 'theme'", description: 'Restrict results to one domain.'},
   ],
   returns: [
     {type: 'search', description: 'Envelope with the query and ranked results[].'},
@@ -253,11 +254,11 @@ export const doc = {
   notes: [
     {
       type: 'prose',
-      text: 'When it loads, a stamped function doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+      text: '`parseDoc` accepts a stamped function doc without `displayName` and does not check its `usage`, and the CLI reads its own function docs without checking them. Write to the type anyway; it is the contract.',
     },
     {
       type: 'prose',
-      text: "The `type` discriminant is 'function' for both flavors. Set `kind: 'hook'` or `kind: 'api'` to drive docsite sectioning; it is inferred from `importPath` when omitted.",
+      text: "The `type` discriminant is 'function' for both flavors. `kind: 'hook'` or `kind: 'api'` names the flavor; nothing reads it today.",
     },
     {
       type: 'prose',

package/authoring/doctypes/hook/hook.doc.mjs

@@ -16,7 +16,8 @@ export const doc = {
     'The doc-type for a standalone React hook (e.g. useMediaQuery, useFocusTrap, ' +
     'useOverflow) that gets its own `.doc.mjs`. Hooks that are part of a component API ' +
     "(e.g. useImperativeDialog) belong in that component's MultiComponentDoc `components` " +
-    "array instead. `HookDoc` is the hook-flavored view of the shared `type: 'function'` kind.",
+    "array instead. `HookDoc` is the hook-flavored view of the shared `type: 'function'` kind. " +
+    "`astryx hook` reads Core's hook docs only; an integration lists its hooks in a component doc's `components` array.",
   appliesTo: '{useX}.doc.mjs',
   fields: [
     {
@@ -195,14 +196,14 @@ export const docs = {
     description:
       'Subscribes to a CSS media query and re-renders when it changes. Use for responsive behavior that CSS alone cannot express, such as swapping components by breakpoint.',
   },
-  relatedHooks: ['useIsMobile'],
+  relatedHooks: ['useImageMode'],
 };`,
     },
   ],
   notes: [
     {
       type: 'prose',
-      text: 'When it loads, a hook doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+      text: '`parseDoc` accepts a stamped hook doc without `displayName` and does not check its `usage`, and `astryx hook` prints a hook doc without checking it at all. Write to the type anyway; it is the contract.',
     },
     {
       type: 'prose',
@@ -210,7 +211,7 @@ export const docs = {
     },
     {
       type: 'prose',
-      text: "Only standalone hooks get their own file. A hook that is part of a component API is documented as an entry in that component's MultiComponentDoc `components` array (with `params`/`returns`), so it renders under the component.",
+      text: "A hook that is part of a component API is listed in that component's MultiComponentDoc `components` array: inline with `params`/`returns`, or by name with its own SubComponentDoc file, as Core's useTableSelection is.",
     },
   ],
 };

package/authoring/doctypes/hook/type.ts

@@ -68,6 +68,10 @@ export interface HookDoc extends AuthoredDocGraphFields {
  * Translation overlay for hook documentation.
  */
 export interface HookTranslationDoc {
+  /** Optional exact name from the base doc. Ignored at render time. */
+  name?: string;
+  /** Optional translated displayName. Ignored at render time. */
+  displayName?: string;
   /** Compressed/translated description. */
   description?: string;
   /** Param descriptions keyed by param name. */

package/authoring/doctypes/namespace/namespace.doc.mjs

@@ -55,7 +55,8 @@ export const doc = {
     {
       name: 'audience',
       type: "'public' | 'internal'",
-      description: "Bundle audience. Defaults to 'public'.",
+      description:
+        "Reserved: bundle audience. Nothing reads it yet: a namespace that sets 'internal' still shows in `astryx docs`.",
       default: "'public'",
     },
     {
@@ -67,7 +68,7 @@ export const doc = {
       name: 'slots',
       type: 'Record<string, NamespaceSlot>',
       description:
-        'Named placement and collection targets. Each slot declares a title and accepted doc kinds; configured providers require an explicit extension slot.',
+        "Named placement and collection targets. Each slot declares a title and the doc kinds it accepts. `accepts.providers` is not read yet: only docs of the namespace's own package can be placed in a slot.",
       required: true,
     },
     {
@@ -80,7 +81,7 @@ export const doc = {
       name: 'blocks',
       type: '(ReferenceContentBlock | GraphContentBlock)[]',
       description:
-        'Ordered layout content for the namespace page. Graph-only workflow, collection, and reference blocks are available here without widening the stable ReferenceContentBlock union used by existing topic renderers. Not rendered yet: `astryx docs <route>` lists every slot and its children in order.',
+        'Ordered layout content for the namespace page. Graph-only workflow, collection, and reference blocks are available here without widening the stable ReferenceContentBlock union used by existing topic renderers. `astryx docs <route>` prints the prose, heading, code, table, and list blocks above the slots, and `--json` returns every block with its links resolved. A collection block is not rendered yet, and `astryx doctor` warns on one.',
     },
   ],
   examples: [
@@ -100,7 +101,7 @@ export const docs = {
     },
   },
   adopts: [{
-    source: {group: 'cli-commands', kinds: ['command']},
+    source: {group: 'cli/commands', kinds: ['command']},
     into: 'reference',
   }],
 };`,
@@ -109,11 +110,11 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: "The docs tree reads namespace docs from the CLI and from every configured integration. An integration's namespace doc is a top-level level of the tree, and its guides name it with `placement`; a doc can be placed only in a namespace of its own package. When two packages claim one route, the CLI's own docs win, then integrations in configured order, and `astryx doctor` names the loser.",
+      text: "The docs tree reads namespace docs from the CLI and from every configured integration. An integration's namespace doc without a `placement` is a top-level level of the tree, and its guides name it with `placement`; a doc can be placed only in a namespace of its own package. When two packages claim one route, the CLI's own docs win, then integrations in configured order, and `astryx doctor` names the loser.",
     },
     {
       type: 'prose',
-      text: 'Child docs request one canonical home with placement. Collections store and render stable references to those docs; they never create a second identity or parent.',
+      text: 'Child docs request one canonical home with placement. A collection block refers to those docs by stable reference and never creates a second identity or parent. It is not rendered yet: `astryx doctor` warns on one.',
     },
     {
       type: 'list',

package/authoring/doctypes/reference/reference.doc.mjs

@@ -18,7 +18,8 @@ export const doc = {
     'accessibility, migration guides. Unlike ComponentDoc it is not tied to a component: ' +
     'drop a `.doc.mjs` in the docs directory and it shows up in `astryx docs`. Content is ' +
     'built from ordered sections of mixed content blocks.',
-  appliesTo: 'assets/docs/<topic>.doc.mjs',
+  appliesTo:
+    "<topic>.doc.{ts,mjs,js} in the folder the integration manifest's `docs` names",
   fields: [
     {
       name: 'type',
@@ -69,7 +70,7 @@ export const doc = {
       name: 'extends',
       type: 'string',
       description:
-        "Name of an existing topic this doc merges onto, section by section: a section whose title matches one in the base replaces it, a section the base does not have is appended. The topic keeps the base's title and description. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.",
+        "Name of an existing topic this doc merges onto, section by section. A section replaces the base section with the same `id`, or else the one with exactly its title when either of the two has no `id`. A key derived from a title counts only against an `id`: a section without an `id` also matches a base section whose `id` is the key its title derives, and a section with an `id` also matches a base section without one whose title derives that `id`. Two different `id`s never match, two sections without an `id` whose titles differ only in case or punctuation stay separate, and a section that matches none is appended. The topic keeps the base's title and description. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.",
       example: "'theme'",
     },
     {
@@ -83,7 +84,7 @@ export const doc = {
           name: 'sections[].id',
           type: 'string',
           description:
-            'Stable section anchor. New docs should set this instead of relying on a mutable title.',
+            'Stable section anchor. New docs should set this instead of relying on a mutable title. Published @astryxdesign/cli 0.6.3 and earlier reject the field and hide every doc topic the package ships, so `astryx integration verify` fails an integration that sets one until it declares an `@astryxdesign/cli` peer of `>=0.6.4`.',
         },
         {
           name: 'sections[].title',
@@ -109,7 +110,7 @@ export const doc = {
           name: 'sections[].previewType',
           type: 'ReferenceTokenPreviewType',
           description:
-            "Preview type for token tables in this section. When set, the docsite renders a visual preview column from the token's computed value. Omit for non-token sections.",
+            'Preview type for token tables in this section. The CLI rejects a value not in the list below and returns the value in `astryx docs --json`, but draws no preview from it. Omit for non-token sections.',
         },
       ],
     },
@@ -117,17 +118,17 @@ export const doc = {
       name: 'tokenCategory',
       type: 'string',
       description:
-        "Token category for foundational docs that map to a token section (e.g. 'color'). Lets the tokens overview link to this doc for detailed guidance.",
+        "Token category for foundational docs that map to a token section (e.g. 'color'). `astryx docs --json` returns it as authored; no tokens page links to the doc through it.",
     },
   ],
   examples: [
     {
       label: 'A reference doc with one section',
       code: `/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
+export default {
   type: 'generic',
-  name: 'spacing',
-  title: 'Spacing',
+  name: 'acme-spacing',
+  title: 'Acme Spacing',
   description: 'Spacing tokens for gap, margin, and padding.',
   category: 'foundations',
   tokenCategory: 'spacing',
@@ -151,7 +152,7 @@ export const docs = {
     },
     {
       type: 'prose',
-      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, the stable discriminated union of prose, heading, code, table, list, and token-ref, plus the reference block (ReferenceDocBlock). A read inlines a reference block the way it inlines a token-ref, so `astryx docs`, in text and in `--json`, returns only the stable block kinds. Docs-graph-only workflow and collection blocks are exported separately as GraphContentBlock and accepted by NamespaceDoc. choice, callout, and checklist remain invalid. ReferenceContentBlock is also reused by the `notes` field on SchemaDoc and CommandDoc. Inside text, `{@link <target>}` links another doc by identity (`[<provider>:]<kind>:<name>`): the CLI prints the command that opens it, and `astryx doctor` warns on one that names no doc.',
+      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, the stable discriminated union of prose, heading, code, table, list, and token-ref, plus the reference block (ReferenceDocBlock). A read inlines a reference block the way it inlines a token-ref, so `astryx docs`, in text and in `--json`, returns only the stable block kinds. Docs-graph-only workflow and collection blocks are exported separately as GraphContentBlock and accepted by NamespaceDoc. choice, callout, and checklist remain invalid. ReferenceContentBlock is also reused by the `notes` field on SchemaDoc and CommandDoc. Inside text, `{@link <target>}` links another doc by identity (`[<provider>:]<kind>:<name>`): the CLI prints the command that opens it, and `astryx doctor` warns on one that names no doc. Write a CLI command in text, shell code, or a table cell as a bare `astryx` command: a text read adds the runner the reader uses in front of it, and `--json` returns it as written.',
     },
     {
       type: 'prose',
@@ -194,7 +195,7 @@ type ReferenceDocBlock = {
 
 type GraphContentBlock =
   | { type: 'workflow'; title?: string; steps: WorkflowStep[] }
-  | { type: 'collection'; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
+  | { type: 'collection'; title?: string; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
   | ReferenceDocBlock;`,
     },
     {
@@ -203,7 +204,7 @@ type GraphContentBlock =
     },
     {
       type: 'prose',
-      text: "A section may set `previewType` to render a visual preview column for token tables: one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.",
+      text: "A section may set `previewType`, a hint for previewing its token table, to one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'; the CLI rejects any other value.",
     },
   ],
 };

package/authoring/doctypes/schema/schema.doc.mjs

@@ -55,7 +55,7 @@ export const doc = {
       name: 'aliases',
       type: 'string[]',
       description:
-        'Alternate slugs that also resolve to this doc (back-compat).',
+        'Reserved: alternate slugs for this doc. Nothing reads it yet: `astryx docs` finds a schema doc by its `name` only.',
     },
     {
       name: 'appliesTo',
@@ -141,7 +141,7 @@ export const doc = {
       name: 'notes',
       type: 'ReferenceContentBlock[]',
       description:
-        'Freeform prose/notes rendered after the field table. Same block union as ReferenceDoc (prose, heading, code, table, list, token-ref).',
+        'Freeform prose/notes rendered after the field table and examples. The stable ReferenceContentBlock union (prose, heading, code, table, list, token-ref), without the reference block a ReferenceDoc section also takes; a token-ref note is accepted but not rendered.',
     },
   ],
   examples: [
@@ -152,17 +152,17 @@ export const doc = {
   type: 'schema',
   name: 'integration',
   displayName: 'Astryx Integration',
-  namespace: 'cli',
-  description: 'The astryx.integration.* manifest that registers the components a package provides.',
+  namespace: 'authoring',
+  description: 'The astryx.integration.* manifest that points the CLI at what a package contributes.',
   appliesTo: 'astryx.integration.{ts,mjs,js}',
   fields: [
-    {name: 'name', type: 'string', description: 'Package name.', required: true},
+    {name: 'docs', type: 'string', description: 'The folder that holds your doc topics, relative to package.json.'},
     {
-      name: 'components',
-      type: '{ dir: string }',
-      description: 'Where component sources live.',
+      name: 'agentDocs',
+      type: '{ append?: readonly string[] }',
+      description: 'Guidance your package adds to the agent instructions the CLI manages.',
       fields: [
-        {name: 'components.dir', type: 'string', description: 'Glob root for Acme*.tsx files.', required: true},
+        {name: 'agentDocs.append', type: 'readonly string[]', description: 'Lines added at the end, at most eight.'},
       ],
     },
   ],

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,
     },
     {

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

@@ -163,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,7 +71,8 @@ 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'",
     },
     {
@@ -81,6 +82,13 @@ export const doc = {
         "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: [
     {
@@ -99,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:
@@ -114,11 +126,16 @@ 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',

package/authoring/integration/parse.test.mjs

@@ -97,6 +97,17 @@ describe('parseIntegration (load boundary)', () => {
     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>;
@@ -53,6 +63,7 @@ export const integrationSchema: z.ZodObject<{
     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});
@@ -92,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);
@@ -119,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

@@ -48,6 +48,14 @@ export interface AstryxIntegration {
    *  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;
 }
 
 /**