@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/assets/docs/tree/agent-guidance.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/agent-guidance`: add short lines of
+ * @file `astryx docs cli/integrations/building-blocks/configuration/agent-guidance`: add short lines of
  * guidance that apps put in front of their AI agents, within the limits.
  */
 
@@ -27,7 +27,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: "npx astryx integration add agent-doc 'Use AcmeCarousel for rotating content.'",
+          code: "astryx integration add agent-doc 'Use AcmeCarousel for rotating content.'",
         },
         {
           type: 'prose',
@@ -80,6 +80,10 @@ export default {
           type: 'prose',
           text: 'A line is one line of plain text. Line breaks, control characters, spaces at either end, and managed-block markers such as `<!-- ASTRYX:START -->` are rejected.',
         },
+        {
+          type: 'prose',
+          text: 'Start a command in a line with the word astryx alone, with no runner in front, as in: Run astryx doctor before finishing. The block names the command the app runs once, at its top, for every command below it, so your line works in every app. See {@link generic:cli-command}.',
+        },
       ],
     },
     {
@@ -93,7 +97,7 @@ export default {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx init --features agents',
+          code: 'astryx init --features agents',
         },
         {
           type: 'code',
@@ -119,9 +123,9 @@ export default {
         {
           type: 'code',
           lang: 'bash',
-          code: `npx astryx init --features agents
+          code: `astryx init --features agents
 # Or: --from takes the Core version the app had before
-npx astryx upgrade --from 0.7.0 --apply`,
+astryx upgrade --from <version> --apply`,
         },
         {
           type: 'code',
@@ -134,5 +138,15 @@ npx astryx upgrade --from 0.7.0 --apply`,
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: "In global mode: the agent guide the CLI keeps for the computer carries no integration's guidance, because it serves every folder; your guidance reaches agents through the agent docs `init` writes in an app that installs your package. See {@link namespace:global} and {@link generic:computer-agent-guide}.",
+        },
+      ],
+    },
   ],
 };

package/assets/docs/tree/block-template.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/document-the-template/block-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/block-template`:
  * the block-only fields: component relationships and the preview shape.
  */
 
@@ -54,18 +54,8 @@ export default {
       title: 'Choose the component relationship',
       content: [
         {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {
-            fields: [
-              'exampleFor',
-              'alsoExampleFor',
-              'alsoShowcaseFor',
-              'componentsUsed',
-              'isShowcase',
-            ],
-          },
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:template-doc}.',
         },
         {
           type: 'prose',
@@ -101,14 +91,12 @@ export default {
       title: 'Choose a useful preview',
       content: [
         {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {fields: ['aspectRatio']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:template-doc}.',
         },
         {
           type: 'prose',
-          text: 'Start from the value for the closest shape below, render the block at that ratio, and adjust it until it neither clips nor leaves large empty space. These are starting points, not contract defaults.',
+          text: 'Set `aspectRatio` from the value for the closest shape below, render the block at that ratio, and adjust it until it neither clips nor leaves large empty space. These are starting points, not contract defaults.',
         },
         {
           type: 'table',

package/assets/docs/tree/build-the-template.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template`:
  * author portable template source and every asset that source needs.
  */
 

package/assets/docs/tree/building-blocks.doc.mjs

@@ -23,6 +23,10 @@ export const docs = {
     },
   },
   blocks: [
+    {
+      type: 'prose',
+      text: 'In global mode: every kind your package adds also applies outside projects when users install it for their computer, beside the global CLI; inside a project, only if the project installs it. See {@link namespace:global} and {@link generic:global-integrations}.',
+    },
     {
       type: 'prose',
       text: 'These are everything you can add to an integration. Mix them however you like. You are not limited to any one thing.',

package/assets/docs/tree/check-the-props.doc.mjs

@@ -37,7 +37,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx doctor integration components',
+          code: 'astryx doctor integration components',
         },
         {
           type: 'code',
@@ -58,8 +58,8 @@ docType:   boolean
           style: 'unordered',
           items: [
             "A doc's own `props` describe the export its `name` names. In a family doc, each entry describes its own export. A hook entry documents parameters and returns, so it is not compared.",
-            "It reads props with the `typescript` your package installs, and reads your package's `tsconfig.json` the way `tsc -p` does. Without TypeScript it prints `[skip] Props not compared` and the reason.",
-            'Every finding is a warning, so the exit code stays 0. Read them before you publish. With `--json`, they are in `data.propDrift.findings`.',
+            "It reads props with the `typescript` your package installs, and reads your package's `tsconfig.json` the way `tsc -p` does. It finds TypeScript the way the docs check does, TypeScript 7 included ({@link generic:check-your-docs}). Without a usable one it prints `[skip] Props not compared` and the reason.",
+            'Findings are warnings and leave the exit code at 0. Read them before you publish. With `--json`, they are in `data.propDrift.findings`.',
           ],
         },
       ],
@@ -96,6 +96,11 @@ docType:   boolean
               "The documented `type` differs from the code's, where both read exactly",
               'Copy the type from the source, or fix the code. The next section says which types are judged',
             ],
+            [
+              '`default_mismatch`',
+              "The documented `default` differs from the literal default the component writes in its props destructuring, such as `size = 'md'`",
+              'Copy the default from the source, quoted as code: `default: "\'md\'"`. Quotes and spacing are ignored, and a default that is not a literal on either side (a constant, a call, prose) is not compared',
+            ],
           ],
         },
       ],

package/assets/docs/tree/check-your-docs.doc.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/check-your-docs`: what each check
- * proves about an integration's docs: the docs check, each doc's fields, the
- * read size, and the CLI peer.
+ * @file `astryx docs cli/integrations/building-blocks/docs/check-your-docs`:
+ * what each check proves about an integration's docs: the docs check, each
+ * doc's fields, the read size, and the CLI peer.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -22,17 +22,29 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Run `doctor integration docs` in your package to check the docs tree, every link, and overlaps with Core topics. Pass a package name to check an installed package.',
+          text: 'Run `doctor integration docs` in your package to check the docs tree, every link, and overlaps with Core topics, and to list any passage two topics repeat. Pass a package name to check an installed package.',
         },
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx doctor integration docs\n# In an app, check an installed package\nnpx astryx doctor integration docs @acme/astryx-widgets',
+          code: 'astryx doctor integration docs\n# In an app, check an installed package\nastryx doctor integration docs @acme/astryx-widgets',
         },
         {
           type: 'code',
           lang: 'text',
-          code: 'Checking integration docs: @acme/astryx-widgets@1.0.0\n\n[ok] The docs tree and every link in these docs check out.\n\n[ok] No doc topics overlap with Core.',
+          code: 'Checking integration docs: @acme/astryx-widgets@1.0.0\n\n[ok] The docs tree and every link in these docs check out.\n\n[ok] No doc topics overlap with Core.\n[ok] No topic copies a passage from another.\n[ok] No filler phrases or low-density topics.',
+        },
+        {
+          type: 'prose',
+          text: 'Write each fact in one topic. When two of your topics, or one of yours and a Core topic, repeat 10 or more words of prose word for word, the check lists the pair as a `copied_passage` warning. It names the topic that keeps the text (a Core topic, or of your two the one the passage fits) and the line in the other where to put the link instead ({@link generic:links}). Code and examples are not compared, and a topic may carry the text of the Core topic it replaces. A run with fewer than 4 distinct content words (words other than function words such as \"the\", \"in\" or \"it\"), or one that three or more topics share (a series lead-in), is not listed. Each listed pair is also a warning (`copied_passage`): `doctor integration docs` still exits 0, and `integration check --strict` fails until you fix it.',
+        },
+        {
+          type: 'prose',
+          text: "Keep docs dense. The check lists, as a `doc_fluff` warning, each padding phrase in your prose, with its file line and what to write instead, and each topic of 80 or more prose words in which fewer than half the words carry content (words other than function words such as the, and, in), with its measured share and the floor of 0.5. `doctor integration docs` still exits 0, and `integration check --strict` fails until you cut it. Code, examples, and quoted text are not read. The phrases: `it\'s important to note`, `it is important to note`, `important to note that`, `it\'s worth noting`, `it is worth noting`, `worth noting that`, `it should be noted`, `please note`, `note that` (opening a sentence), `as mentioned above`, `as mentioned earlier`, `as mentioned before`, `as noted above`, `as you can see`, `needless to say`, `in order to`, `due to the fact that`, `for the purpose of`, `at this point in time`, `in other words`, `basically`, `essentially`, `obviously`.",
+        },
+        {
+          type: 'prose',
+          text: "Point at another doc with a link, never by writing `astryx docs <name>` in prose: `{@link generic:<name>}` for one of your package's topics, or `{@link @astryxdesign/cli:generic:<name>}` for a Core doc (`namespace:` for a Core namespace). The CLI prints the link as the command that opens the doc, and doctor checks that the doc exists. The check lists each written pointer to a doc that exists as a `stray_doc_pointer` warning, with the link to write instead. A command with more words, or one in a code block, is a walkthrough and is not listed.",
         },
         {
           type: 'prose',
@@ -46,7 +58,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'A doc that does not load, an accidental Core overlap, or a failed namespace or placement fails the check with exit code 1. A link that names no doc only warns, and the exit code stays 0.',
+          text: 'A doc that does not load, an accidental Core overlap, a `reference` block that names no doc, or a failed namespace or placement fails the check with exit code 1. A link that names no doc only warns, and the exit code stays 0.',
         },
         {
           type: 'table',
@@ -67,6 +79,11 @@ export const docs = {
               '`[fail]` `invalid_doc_graph`',
               '1',
             ],
+            [
+              'A `reference` block whose target names no doc',
+              '`[fail]` `invalid_doc_reference`',
+              '1',
+            ],
             ['A link that names no doc', '`[warn]` `invalid_doc_graph`', '0'],
             [
               'A topic that sets `replaces` or `extends`',
@@ -92,7 +109,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx doctor integration validate',
+          code: 'astryx doctor integration validate',
         },
         {
           type: 'code',
@@ -115,8 +132,8 @@ fix:      Remove \`summary\`: SingleComponentDoc has no field \`summary\`.`,
           items: [
             "The folder decides the type: `ComponentDoc` in your components root, `IntegrationTemplateDoc` in your templates root, `ThemeDoc` in your themes root, and in your docs root the type the doc's `type` names. Keep the `@type` comment above each doc's export too, so your editor shows the same problems as you type.",
             'Every finding is a warning, so the exit code stays 0. With `--json`, they are in `data.docTypes.findings`.',
-            'It uses the `typescript` your package installs. Without it, it prints `[skip] Docs not type-checked` and the reason.',
-            'Every field of every doc type is in `astryx docs authoring`.',
+            'It uses the `typescript` your package installs. Where `typescript` is missing or has no JavaScript compiler API, as TypeScript 7 does, it uses `@typescript/typescript6`, the TypeScript 6 API package, if your package installs it. Without either, it prints `[skip] Docs not type-checked` and the reason.',
+            'Every field of every doc type is in {@link generic:authoring}.',
           ],
         },
       ],
@@ -127,12 +144,12 @@ fix:      Remove \`summary\`: SingleComponentDoc has no field \`summary\`.`,
       content: [
         {
           type: 'prose',
-          text: '`npx astryx doctor` also measures every read and warns on one over 32 KB. Run it in your package or in an app that installs it; `doctor integration docs` does not check size.',
+          text: '`astryx doctor` also measures every read and warns on one over 32 KB. Run it in your package or in an app that installs it; `doctor integration docs` does not check size.',
         },
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx doctor',
+          code: 'astryx doctor',
         },
         {
           type: 'code',
@@ -156,7 +173,7 @@ fix:      Remove \`summary\`: SingleComponentDoc has no field \`summary\`.`,
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration verify',
+          code: 'astryx integration verify',
         },
         {
           type: 'code',

package/assets/docs/tree/checks.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/checks`: what each package check
+ * @file `astryx docs cli/integrations/ship/checks`: what each package check
  * proves, what fails and what only warns, and one command to run them all.
  */
 
@@ -29,37 +29,37 @@ export const docs = {
           headers: ['Command', 'Proves', 'Exits 1 when', 'Only warns when'],
           rows: [
             [
-              '`npx astryx doctor integration validate`',
+              '`astryx doctor integration validate`',
               'The manifest loads, each root holds contributions the CLI can read, and each doc matches its authoring type',
               'A declared root is missing (`missing_root`), a contribution does not load (`invalid_doc`, `invalid_component`, `invalid_theme`), or two templates in the package replace one Core id (`ambiguous_template_replacement`)',
-              "The manifest has a key this CLI does not know (`unknown_manifest_key`), or a doc field does not match the doc's authoring type: a field the type does not have, a missing required field, or a value outside the field's type. It checks docs with your installed `typescript`; without it, it prints `[skip] Docs not type-checked`. With no `astryx.integration.mjs` it prints a hint and exits 0",
+              "The manifest has a key this CLI does not know (`unknown_manifest_key`), or a doc field does not match the doc's authoring type: a field the type does not have, a missing required field, or a value outside the field's type. It also warns on what no reader can serve: a prop listed twice (`duplicate_prop`), a `propDescriptions` key that names no documented prop (`unknown_translated_prop`), a section with no content (`empty_section`), two sections of a topic with one key (`duplicate_section_key`), or a `.doc.zh.mjs` or `.doc.dense.mjs` overlay beside no topic file (`orphan_doc_overlay`). It checks docs with your installed `typescript`, or, where that is missing or has no JavaScript compiler API (TypeScript 7), with an installed `@typescript/typescript6`; without either, it prints `[skip] Docs not type-checked`. With no `astryx.integration.mjs` it prints a hint and exits 0",
             ],
             [
-              '`npx astryx doctor integration components`',
+              '`astryx doctor integration components`',
               "No component name clashes with a Core component, each `replaces` names one Core component, and each component doc's props match the component's TypeScript props",
               'Core is not installed (`core_not_found`). In a package that declares the CLI range that turns replacement on, a `replaces` target is missing (`missing_component_replacement_target`) or invalid (`invalid_component_replacement`), or two components replace one Core component (`ambiguous_component_replacement`)',
-              'A name clashes with Core, a component sets `replaces` in a package without that range (`inactive_component_replacement`, plus any missing, invalid, or duplicate `replaces` reported as a warning), or a documented prop differs from the code: it is missing there (`not_in_code`), the doc omits a prop the package declares (`not_in_doc`), or its `required` (`required_mismatch`) or type (`type_mismatch`) disagrees. It reads props with your installed `typescript`; without it, it prints `[skip] Props not compared`',
+              'A name clashes with Core, a component sets `replaces` in a package without that range (`inactive_component_replacement`, plus any missing, invalid, or duplicate `replaces` reported as a warning), or a documented prop differs from the code: it is missing there (`not_in_code`), the doc omits a prop the package declares (`not_in_doc`), or its `required` (`required_mismatch`), type (`type_mismatch`), or literal `default` (`default_mismatch`) disagrees, or a `{@link}` in a component doc names no doc (`invalid_doc_graph`). It reads props with your installed `typescript`; without it, it prints `[skip] Props not compared`',
             ],
             [
-              '`npx astryx doctor integration templates`',
+              '`astryx doctor integration templates`',
               'Each `replaces` names a Core template of the same type',
               'A `replaces` target is missing (`missing_template_replacement_target`) or of the other type (`invalid_template_replacement`), or two templates replace one id (`ambiguous_template_replacement`)',
               'A template id matches a Core id without `replaces`',
             ],
             [
-              '`npx astryx doctor integration docs`',
-              'Your docs tree, every link, and topic names against Core',
+              '`astryx doctor integration docs`',
+              'Your docs tree, every link, topic names against Core, passages two topics repeat word for word, padding phrases and low-density topics, and written pointers to docs',
               'A topic takes a Core topic name without `replaces` or `extends`, a doc is invalid (`invalid_doc`), or a namespace or placement fails, which hides the doc (`invalid_doc_graph`)',
-              'A link names no doc (`invalid_doc_graph`)',
+              'A link names no doc (`invalid_doc_graph`), two topics repeat a passage word for word (`copied_passage`), prose pads with a listed phrase or falls under the density floor (`doc_fluff`), or prose, a description or summary, or the text of a component doc writes `astryx docs <name>` where a link would be checked (`stray_doc_pointer`)',
             ],
             [
-              '`npx astryx integration check`',
+              '`astryx integration check`',
               'Everything the four `doctor integration` checks prove, in one command, for your build',
               'Any of the four would exit 1 on its own. With `--strict`, also any warning, and any check that did not run, such as a package with no `astryx.integration.*`',
               'Anything the four warn about, unless you pass `--strict`',
             ],
             [
-              '`npx astryx integration verify`',
+              '`astryx integration verify`',
               'The packed package holds every file, shows the same contributions, resolves every public import, and declares the CLI it needs',
               'Anything `validate` fails on, no manifest, a file left out of the `.tgz` file, an import that does not resolve, or a missing CLI peer',
               'Anything `validate` warns about, or a component sets `replaces` and the package does not declare the CLI range that turns it on (`component_replaces_needs_cli`)',
@@ -68,17 +68,17 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Pass a package name, such as `npx astryx doctor integration validate @acme/astryx-widgets`, to check an installed copy from an app instead. To fix a props finding, see {@link generic:check-the-props}.',
+          text: 'Pass a package name, such as `astryx doctor integration validate @acme/astryx-widgets`, to check an installed copy from an app instead. To fix a props finding, see {@link generic:check-the-props}.',
         },
       ],
     },
     {
       id: 'run-every-check-in-ci',
-      title: 'Run every check in CI',
+      title: 'Run every check in every build (required)',
       content: [
         {
           type: 'prose',
-          text: "Run `integration check --strict` in your package's own build, so every build keeps your docs, types, and links in sync, and run `integration verify` before you publish. Install devDependencies first, because the components check needs Core, and `tsc --noEmit` needs `typescript` and a `tsconfig.json`. In package.json:",
+          text: 'Every integration runs `integration check --strict` in its own build, so every build keeps your docs, types, and links in sync; this is required, not optional. The strict check fails on every copied passage the docs check lists ({@link generic:check-your-docs}). Run `integration verify` before you publish. Install devDependencies first, because the components check needs Core, and `tsc --noEmit` needs `typescript` and a `tsconfig.json`. In package.json:',
         },
         {
           type: 'code',
@@ -92,8 +92,8 @@ export const docs = {
             '`integration check` runs `validate`, `components`, `templates`, and `docs` in that order, prints each result, then a summary, and exits 1 when any of them would.',
             '`--strict` also exits 1 on any warning and on any check that did not run. Without it, warnings keep exit code 0: use that while you fix the warnings a package already has.',
             'Its exit codes and JSON are a contract for your build: a new check, or a new failure code, joins only in a minor release that names it in the release notes. A patch can still ship a Core component, template, or CLI topic whose name conflicts with one of yours.',
-            '`integration verify` runs `validate` but none of the other three: a Core name clash, a `replaces` that names no Core template, a topic that takes a Core name, or a hidden guide still passes it. Run both before you publish: `npx astryx integration check --strict && npx astryx integration verify`.',
-            'Bare `npx astryx doctor` in the package also warns about a doc section over 32 KB, which no check above measures.',
+            '`integration verify` runs `validate` but none of the other three: a Core name clash, a `replaces` that names no Core template, a topic that takes a Core name, or a hidden guide still passes it. Run both before you publish: `astryx integration check --strict && astryx integration verify`.',
+            'Bare `astryx doctor` in the package also warns about a doc section over 32 KB, which no check above measures.',
           ],
         },
       ],
@@ -120,7 +120,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: '`integration pack --check`, the name this check had in 0.6, still runs it and prints a note; it will be removed in a later release. The options and exit codes are in {@link command:integration verify}.',
+          text: '`integration pack --check`, the name this check had before published 0.6.5, still runs it and prints a note; it will be removed in a later release. The options and exit codes are in {@link command:integration verify}.',
         },
       ],
     },

package/assets/docs/tree/ci-and-containers.doc.mjs

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/ci-and-containers`: Astryx in CI and containers: no
+ * update checks, caching versions, read-only home folders (spec AST-081 FR6,
+ * FR7, FR10).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'ci-and-containers',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 8,
+  },
+  title: 'CI and containers',
+  category: 'guide',
+  keywords: [
+    'ci',
+    'github actions',
+    'container',
+    'docker',
+    'read-only home',
+    'cache the release cache',
+  ],
+  description:
+    "What Astryx does in CI and containers: no update checks or notices, the project's version as always, and how to cache versions or work with a read-only home folder.",
+  sections: [
+    {
+      id: 'in-ci',
+      title: 'In CI',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Most CI services set `CI=true`. When `CI` is set to anything but empty, `0`, or `false`, Astryx never checks for updates and never prints a notice; `CI=false`, `CI=0`, and an empty `CI` do not count. `NO_UPDATE_NOTIFIER`, set to anything, does the same anywhere.',
+            "Add `@astryxdesign/cli` to the project as a devDependency at the same version as `@astryxdesign/core`; then CI runs the version pinned in the repo, and nothing is fetched. A global install in a CI image also works: in a project, it runs the project's version.",
+            'Use `--json` for output a script reads; it never carries the answered-by line or a notice.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'cache',
+      title: 'Cache project versions',
+      content: [
+        {
+          type: 'prose',
+          text: "When the project installs its own CLI and you install the project's dependencies first, there is nothing to cache. Astryx downloads into its cache only the CLI version a project whose own CLI cannot start needs, and, outside a project, the Core of a global install for commands that read components. In CI it downloads nothing in the background, so a global install in a CI image fetches that Core on its first component command. To skip those downloads on every run, cache this folder between runs:",
+        },
+        {
+          type: 'table',
+          headers: ['Linux', 'macOS', 'Windows'],
+          rows: [
+            [
+              '`~/.cache/astryx` (or `$XDG_CACHE_HOME/astryx`)',
+              '`~/Library/Caches/astryx`',
+              '`%LOCALAPPDATA%\\astryx\\Cache`',
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      id: 'read-only',
+      title: 'Read-only home folders',
+      content: [
+        {
+          type: 'prose',
+          text: "When the cache cannot be written, a project whose own CLI cannot start is answered by the global install, with a warning naming the folder. Point `XDG_CACHE_HOME` at a writable absolute path, or reinstall the project's dependencies. The global install's daily check and agent guide are skipped quietly when they cannot be written.",
+        },
+      ],
+    },
+    {
+      id: 'more',
+      title: 'More on global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'This page is part of {@link namespace:global}, which explains what global mode is and how each part works.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/cli-command.doc.mjs

@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/configuration/cli-command`:
+ * name the command an integration's users run the CLI with, so every command
+ * the CLI prints in their apps starts with it.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'cli-command',
+  placement: {parent: 'namespace:configuration', slot: 'guides', order: 15},
+  title: 'CLI command',
+  category: 'guide',
+  keywords: [
+    'cliCommand',
+    'command name',
+    'wrapper',
+    'printed commands',
+    'pnpm exec astryx',
+  ],
+  description:
+    'Name the command your users run the CLI with, so every command the CLI prints in their apps starts with it.',
+  sections: [
+    {
+      id: 'when-to-set-it',
+      title: 'When to set it',
+      content: [
+        {
+          type: 'prose',
+          text: "The CLI ends most answers with the next command to run: a hint, an error fix, a Doctor fix, or a doc example. By default each one starts with a command that reaches the release that answered: what the app's package manager runs, such as `pnpm exec astryx` or `yarn astryx`, when the app's own CLI answered, and otherwise the CLI package pinned to that release, such as `npx @astryxdesign/cli@0.7.2`.",
+        },
+        {
+          type: 'prose',
+          text: 'Set `cliCommand` only when your users run the CLI some other way, such as a wrapper your company ships that runs it with your package loaded. Otherwise the commands the CLI prints send them, and their agents, to a CLI that answers without your package. Most packages leave it out.',
+        },
+      ],
+    },
+    {
+      id: 'set-it',
+      title: 'Set it',
+      content: [
+        {
+          type: 'prose',
+          text: 'Add `cliCommand` to `astryx.integration.mjs`: the command, without a subcommand.',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          code: `// astryx.integration.mjs
+export default {
+  components: './components',
+  cliCommand: 'acme astryx',
+};`,
+        },
+        {
+          type: 'prose',
+          text: 'In an app that installs your package, the CLI then prints every command with it:',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'Error: Theme "ocean" is not added. Run `acme astryx theme add ocean` first.',
+        },
+        {
+          type: 'prose',
+          text: 'That covers hints, errors, suggestions, Doctor fixes, `--help`, the setup reminder, the agent block `init` writes, and doc text. `--json` output keeps every command without a runner, as in `"command": "astryx theme add ocean"`, so a script reads the same fields in every app.',
+        },
+      ],
+    },
+    {
+      id: 'how-the-cli-picks',
+      title: 'How the CLI picks the command',
+      content: [
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'The `cliCommand` of the packages the app loads, when they name one command.',
+            'The command a host tool names when it runs the CLI for the app. Nothing in a plain project names one.',
+            "A command that reaches the release that answered: what the app's package manager runs when the app's own CLI answered, such as `pnpm exec astryx` or `yarn astryx`; `astryx` outside a project when the CLI installed for the computer answered; otherwise the CLI package pinned to that release, such as `npx @astryxdesign/cli@0.7.2` (see {@link generic:who-answers}).",
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Two packages that set the same command agree, and the CLI uses it.',
+        },
+      ],
+    },
+    {
+      id: 'when-two-packages-disagree',
+      title: 'When two packages disagree',
+      content: [
+        {
+          type: 'prose',
+          text: "If two packages an app loads set different commands, the CLI uses neither: it prints commands with what the app's package manager runs, even when a host tool named a command. `astryx doctor` warns in its `cli-command` check and names both packages:",
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `status:  [warn]
+label:   CLI command
+message: Loaded integrations declare different CLI commands: @acme/astryx-widgets (\`acme astryx\`), @other/kit (\`other astryx\`). Neither is used, so printed commands start with \`pnpm exec astryx\`.`,
+        },
+        {
+          type: 'prose',
+          text: 'The app fixes it by removing the package that does not belong, or the packages agree on one command.',
+        },
+      ],
+    },
+    {
+      id: 'check-it',
+      title: 'Check it',
+      content: [
+        {
+          type: 'prose',
+          text: 'An invalid value is ignored, and the rest of your manifest still loads. `astryx doctor integration validate` reports it as `invalid_cli_command`. A valid `cliCommand` is one line of plain text without spaces at either end, at most 120 characters.',
+        },
+        {
+          type: 'prose',
+          text: "In an app that installs your package, `astryx doctor` passes its `cli-command` check and names your package as the one that set the command. A CLI released before this field reports `cliCommand` as an unknown key and prints the package manager's command.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx doctor integration validate\n# In an app that installs the package\nastryx doctor',
+        },
+      ],
+    },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: "In global mode: outside a project, the `cliCommand` of integrations installed for the computer applies; when none is declared, commands start with the plain command of the CLI installed for the computer. Inside a project, only the project's integrations count, so a `cliCommand` from a package installed for the computer never changes the project's printed commands. See {@link namespace:global} and {@link generic:global-integrations}.",
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/cli.doc.mjs

@@ -20,4 +20,10 @@ export const docs = {
     guides: {title: 'Guides', accepts: {kinds: ['generic', 'namespace']}},
     reference: {title: 'Reference', accepts: {kinds: ['namespace']}},
   },
+  blocks: [
+    {
+      type: 'prose',
+      text: 'Use the CLI in any folder: install it once for your computer, and every project still gets the release that matches its Core. See {@link namespace:global}.',
+    },
+  ],
 };