@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/assets/docs/{authoring.doc.mjs → tree/field-reference.doc.mjs}

@@ -1,14 +1,15 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs authoring`: every authoring schema, one section each.
+ * @file `astryx docs authoring/field-reference`: every authoring schema, one
+ * section each. `astryx docs authoring <name>` reads one of them.
  *
  * Built from the self-docs colocated under packages/cli/authoring, so it cannot
  * drift from the schemas it describes. `astryx doctor` names a self-doc this
- * topic cannot reach.
+ * guide cannot reach.
  */
 
-import {buildAuthoringTopic} from '../../foundation/discovery/authoring-self-docs.mjs';
+import {buildAuthoringTopic} from '../../../foundation/discovery/authoring-self-docs.mjs';
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
 export const docs = await buildAuthoringTopic();

package/assets/docs/tree/fonts-and-assets.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/themes/fonts-and-assets`:
+ * @file `astryx docs authoring/building-blocks/themes/fonts-and-assets`:
  * ship a theme's optional font loader beside its built module and CSS.
  */
 
@@ -61,7 +61,7 @@ export const oceanTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'The stylesheet can contain self-hosted `@font-face` rules or import a hosted stylesheet. A hosted `@import` is simple, but it delays loading compared with a preconnected `<link>`; choose that trade-off deliberately. If the app loads the same family outside the generated module, Doctor warns because it cannot prove the loader, but the warning does not fail the app.',
+          text: 'The stylesheet can contain self-hosted `@font-face` rules or import a hosted stylesheet. A hosted `@import` is simple, but it delays loading compared with a preconnected `<link>`; choose that trade-off deliberately. Doctor warns when it cannot prove the loader — a hosted `@import`, or no font stylesheet while the app loads the family itself — but the warning does not fail the app.',
         },
         {
           type: 'code',
@@ -83,7 +83,7 @@ export const oceanTheme = defineTheme({
             'Load every weight and style the theme uses. Do not let the browser synthesize bold or italic.',
             'Include self-hosted font files and their licenses in the packed package.',
             'Keep CSS and font assets side-effectful so a bundler does not remove the loader.',
-            'Run `integration verify`; it fails when an exported font stylesheet or one of its packed files cannot resolve.',
+            'Run `integration verify`; it fails when an exported font stylesheet cannot resolve, but it does not check the font files the stylesheet names.',
           ],
         },
       ],

package/assets/docs/tree/generate-a-palette.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/themes/generate-a-palette`:
+ * @file `astryx docs authoring/building-blocks/themes/generate-a-palette`:
  * turn a few seed colors into a full light and dark color palette.
  */
 
@@ -21,7 +21,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'A theme needs dozens of related colors — shades of each brand color for backgrounds, borders, text, and states, in both light and dark mode. A palette is that full set of shades. Rather than hand-pick every one, you name a few seed colors and generate the rest, so the shades stay consistent and keep enough contrast to read.',
+          text: 'A theme needs dozens of related colors — shades of each brand color for backgrounds, borders, text, and states, in both light and dark mode. A palette is that full set of shades. Rather than hand-pick every one, you name a few seed colors and generate the rest, so the shades stay consistent.',
         },
         {
           type: 'prose',
@@ -40,9 +40,9 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           code: `# Print the palette without writing files
-npx astryx theme palette generate themes/ocean/palette.config.json
+astryx theme palette generate themes/ocean/palette.config.json
 # Write the palette and its receipt
-npx astryx theme palette generate themes/ocean/palette.config.json \\
+astryx theme palette generate themes/ocean/palette.config.json \\
   --out themes/ocean/tokens/ocean.palette.ts`,
         },
         {
@@ -50,7 +50,9 @@ npx astryx theme palette generate themes/ocean/palette.config.json \\
           lang: 'text',
           code: `[ok] Wrote themes/ocean/tokens/ocean.palette.ts
 
-[ok] Wrote themes/ocean/tokens/ocean.palette.receipt.json`,
+[ok] Wrote themes/ocean/tokens/ocean.palette.receipt.json
+
+Review and edit the candidate before adopting it as theme-owned palette data.`,
         },
         {
           type: 'prose',
@@ -58,7 +60,7 @@ npx astryx theme palette generate themes/ocean/palette.config.json \\
         },
         {
           type: 'prose',
-          text: 'Add `--preview <file>.html` to also get a web page showing every shade, so you can eyeball the palette in a browser. Write it outside `themes/` so it does not ship in your package. The full list of config fields and options is in {@link command:theme palette generate}.',
+          text: 'Add `--preview <file>.html` to also get a web page showing every shade, so you can eyeball the palette in a browser. Write it outside `themes/` so it does not ship in your package. Every option is in {@link command:theme palette generate}, and the config it reads is described in {@link function:generateTonalPalette}.',
         },
       ],
     },

package/assets/docs/tree/global-integrations.doc.mjs

@@ -0,0 +1,124 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs authoring/global-integrations`: make an
+ * integration work when people install it next to their global Astryx
+ * install; a checklist and the commands to try it (spec AST-081 FR12).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'global-integrations',
+  placement: {
+    parent: 'namespace:authoring',
+    slot: 'guides',
+    order: 25,
+  },
+  title: 'Make your integration work globally',
+  category: 'guide',
+  keywords: [
+    'global integration',
+    'global mode',
+    'npm i -g',
+    'installed for this computer',
+    'outside a project',
+    'peer range',
+    'peerDependencies',
+    'cliCommand conflict',
+    'try it globally',
+  ],
+  description:
+    "People can install your integration next to their global Astryx install, where it works in every folder outside a project; inside a project, only the project's own integrations work. A checklist, with the exact commands to try it.",
+  sections: [
+    {
+      id: 'peer-range',
+      title: "First: your peer ranges must include the global CLI's version",
+      content: [
+        {
+          type: 'prose',
+          text: 'Your `@astryxdesign/core` (and, if you use it, `@astryxdesign/cli`) `peerDependencies` ranges must include the version of the CLI installed globally. If they do not, Astryx skips your package outside projects, and `astryx doctor` warns and names the range.',
+        },
+        {
+          type: 'prose',
+          text: "Inside a project that does not install your package, `astryx discover` offers it, with the command that adds it to that project, once your peer range admits the project's release.",
+        },
+      ],
+    },
+    {
+      id: 'where-it-works',
+      title: 'Where your integration works',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "Installed in an app: it works in that app, as always, whichever `astryx` the person runs, because the app's version of Astryx answers there.",
+            'Installed next to the global install (`npm i -g @astryxdesign/cli your-package`), or in the same folder as the CLI by a tool that installs them together: it works in every folder outside a project. People and agents there see its components, templates, docs, themes, codemods, and discover source.',
+            "Installed only globally, inside an app that does not install it: it adds nothing there. When it supports the app's version and loads, `astryx discover` lists it as one the app could add, with the app's install command.",
+            "Installed both ways: the app's copy is the one used in that app. In your own package folder, your working copy is used.",
+          ],
+        },
+        {
+          type: 'prose',
+          text: "Astryx loads a global integration with the same loader and checks as an app's, so nothing extra goes in your manifest.",
+        },
+      ],
+    },
+    {
+      id: 'checklist',
+      title: 'Checklist',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Declare the `@astryxdesign/core` (and, if you use it, `@astryxdesign/cli`) `peerDependencies` range your package really supports. Outside a project, Astryx skips your package when that range leaves out the global version, and `astryx doctor` says why: too narrow, and global users lose it after an upgrade; too wide, and it loads against a Core it may not build with.',
+            'Keep imports in your docs and templates to packages an app installs with yours, since outside a project there is no app to check them against.',
+            "If you set `cliCommand`, know that outside a project it starts every command Astryx prints, and that two global integrations naming different commands cancel out, falling back to `astryx` ({@link generic:cli-command}). Inside an app, only the app's integrations count.",
+            'Try it globally before you publish, with the steps below.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'try-it',
+      title: 'Try it globally',
+      content: [
+        {
+          type: 'prose',
+          text: 'Pack your package, install it next to a global CLI, and look at it from an empty folder:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm pack\nnpm i -g @astryxdesign/cli ./your-package-1.0.0.tgz\nmkdir -p /tmp/try-global && cd /tmp/try-global\nastryx discover\nastryx docs\nastryx doctor',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`astryx discover` lists your package as installed, with what it adds.',
+            '`astryx docs` lists your topics, and `astryx search <one of your component names>` finds them.',
+            "`astryx doctor`'s `computer-integrations` check lists your package as used, with no warning.",
+            "In an app that does not install it, `astryx discover` lists it as one the app could add, with the app's install command, and none of its components or docs show up.",
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Remove it again with `npm uninstall -g your-package`.',
+        },
+      ],
+    },
+    {
+      id: 'more',
+      title: 'More on global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'How global mode works for the people who install your package: {@link namespace:global}. Their side of global integrations: {@link generic:computer-integrations}.',
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,131 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global`: global mode. What it is, how to install it, what you get,
+ * and which version runs where; the parent of every global-mode page
+ * (spec AST-081).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'global',
+  title: 'Global mode',
+  summary:
+    'Install Astryx once on your computer and use it in any folder. Each project still runs its own version of Astryx, so a global install never changes what a project gets.',
+  keywords: [
+    'global',
+    'global mode',
+    'globally',
+    'global install',
+    'npm i -g',
+    'install globally',
+    'install once',
+    'any folder',
+    'outside a project',
+    'which version',
+    'computer',
+  ],
+  slots: {
+    guides: {
+      title: 'Global mode, question by question',
+      accepts: {
+        kinds: ['generic'],
+      },
+    },
+  },
+  blocks: [
+    {
+      type: 'prose',
+      text: "Global mode means installing the Astryx CLI once for your computer, so the astryx command works everywhere: in your projects, in an empty folder, and for every coding agent. Inside a project, the project's own version of Astryx answers, so your global install never changes what a project gets.",
+    },
+    {
+      type: 'code',
+      lang: 'bash',
+      code: 'npm i -g @astryxdesign/cli',
+    },
+    {
+      type: 'heading',
+      level: 3,
+      text: 'What you get',
+    },
+    {
+      type: 'list',
+      style: 'unordered',
+      items: [
+        'Docs, components, templates, and search in any folder, before you have a project.',
+        'Every coding agent on your computer knows Astryx, through a short guide the CLI keeps where agent tools look.',
+        "Each project keeps its own version: in a project, the project's version answers, whichever astryx command you run.",
+      ],
+    },
+    {
+      type: 'heading',
+      level: 3,
+      text: 'Which version runs',
+    },
+    {
+      type: 'table',
+      headers: ['Where you run it', 'Which version answers'],
+      rows: [
+        [
+          'Inside a project',
+          "The project's own CLI. In a project that installs only `@astryxdesign/core`, the astryx command you started, with a hint once a day to add the CLI.",
+        ],
+        ['Outside any project', 'Your global version.'],
+        [
+          'Commands for your computer, such as `astryx init --user`',
+          'Your global version, in any folder.',
+        ],
+      ],
+    },
+    {
+      type: 'prose',
+      text: 'Not sure whether you want a project install, a global one, or both: {@link generic:project-global-or-both}. The details: {@link generic:who-answers}.',
+    },
+    {
+      type: 'heading',
+      level: 3,
+      text: 'Updates',
+    },
+    {
+      type: 'prose',
+      text: 'Your global install never upgrades itself or a project. When a newer version is out, a command that succeeds ends with a two-line notice, at most once a day: {@link generic:updates}.',
+    },
+    {
+      type: 'heading',
+      level: 3,
+      text: 'Agents',
+    },
+    {
+      type: 'prose',
+      text: 'The CLI keeps a short Astryx guide where agent tools look in your home folder, so an agent working anywhere knows Astryx is there: {@link generic:computer-agent-guide}.',
+    },
+    {
+      type: 'heading',
+      level: 3,
+      text: 'Integrations',
+    },
+    {
+      type: 'prose',
+      text: "Integrations you install next to your global install work outside projects. Inside a project, only the project's own integrations do: {@link generic:computer-integrations}. Building one: {@link generic:global-integrations}.",
+    },
+    {
+      type: 'heading',
+      level: 3,
+      text: 'More',
+    },
+    {
+      type: 'list',
+      style: 'unordered',
+      items: [
+        'Install, and work offline: {@link generic:install-once}.',
+        'Monorepos and nested folders: {@link generic:monorepos}.',
+        'CI and containers: {@link generic:ci-and-containers}.',
+        'Something looks wrong: {@link generic:problems}.',
+        'Uninstall and reset: {@link generic:uninstall}.',
+        'Every path, setting, JSON field, and error code: {@link generic:reference}.',
+        'What each command does outside a project: {@link namespace:commands}.',
+      ],
+    },
+  ],
+};

package/assets/docs/tree/grade-template-with-agent.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/templates/grade-template-with-agent`:
+ * @file `astryx docs authoring/building-blocks/templates/write-good-templates/grade-template-with-agent`:
  * give an agent the canonical rubric and require a reproducible template grade.
  */
 
@@ -36,11 +36,11 @@ export const docs = {
           code: `Grade integration template <id> from <package> at <revision>.
 
 Before scoring:
-1. Read \`npx astryx docs cli/integrations/building-blocks/templates/write-good-templates --full\`.
-2. Read \`npx astryx docs cli/integrations/building-blocks/templates/write-good-templates/template-grading-rubric --full\` and every guide it links.
+1. Read \`astryx docs authoring/building-blocks/templates/write-good-templates --full\`.
+2. Read \`astryx docs authoring/building-blocks/templates/write-good-templates/template-grading-rubric --full\` and every guide it links.
 3. Inspect the template source, its matching .doc.mjs file, package.json exports and files, and astryx.integration.mjs.
-4. Run \`npx astryx integration verify\` in the package.
-5. Follow \`npx astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app --full\`: install the packed package in the clean app, copy the template, build the app, and render the behavior matrix.
+4. Run \`astryx integration verify\` in the package.
+5. Follow \`astryx docs authoring/building-blocks/templates/build-the-template/package-and-test/test-template-in-app --full\`: install the packed package in the clean app, copy the template, build the app, and render the behavior matrix.
 
 Score all seven rubric categories. Cite file and line evidence for every deduction. Do not award points for a state you did not inspect. If browser or build evidence is unavailable, say so and mark the template not publishable.
 

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

@@ -1,12 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @file astryx docs cli/integrations/help — find a CLI message and its fix. */
+/** @file astryx docs authoring/help — find a CLI message and its fix. */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
 export const docs = {
   type: 'namespace',
   name: 'help',
-  placement: {parent: 'namespace:integrations', slot: 'guides', order: 40},
+  placement: {parent: 'namespace:authoring', slot: 'guides', order: 40},
   title: 'Help',
   summary: 'Find a CLI message and how to fix it.',
   keywords: ['help', 'troubleshooting', 'error'],

package/assets/docs/tree/host-entry.doc.mjs

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/host-entry`: run the CLI from a tool that carries it,
+ * through `@astryxdesign/cli/host` (spec AST-081 FR1,
+ * architecture:cli-surface INV30).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'host-entry',
+  placement: {parent: 'namespace:cli', slot: 'guides', order: 15},
+  title: 'Host entry',
+  category: 'guide',
+  keywords: [
+    'host entry',
+    'runHostedCli',
+    '@astryxdesign/cli/host',
+    'carry the cli',
+    'embed the cli',
+    'programmatic run',
+    'package sets',
+    'cliCommand',
+  ],
+  description:
+    'Run the Astryx CLI from your own command-line tool: the inputs `runHostedCli` takes, what it returns, and when the process ends instead.',
+  sections: [
+    {
+      id: 'start',
+      title: 'Start a run',
+      content: [
+        {
+          type: 'prose',
+          text: "A tool that carries the CLI for its own users starts one run per process with `runHostedCli` from `@astryxdesign/cli/host`. The run behaves as the CLI's own command does with the same arguments in the same folder, and the commands it prints start with your tool's command.",
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "import {runHostedCli} from '@astryxdesign/cli/host';\n\nconst {status} = await runHostedCli({\n  argv: process.argv.slice(2),\n  cwd: process.cwd(),\n  cliCommand: 'acme astryx',\n});\nprocess.exitCode = status;",
+        },
+      ],
+    },
+    {
+      id: 'options',
+      title: 'Options',
+      content: [
+        {
+          type: 'table',
+          headers: ['Option', 'Default', 'Meaning'],
+          rows: [
+            [
+              '`argv`',
+              'none',
+              'The command-line arguments, without the command name.',
+            ],
+            [
+              '`cwd`',
+              "the process's working folder",
+              'The folder the run works in. It must exist.',
+            ],
+            [
+              '`cliCommand`',
+              "the package manager's name",
+              'The command your users type, such as `acme astryx`: a non-blank single line of at most 120 characters, with no surrounding spaces.',
+            ],
+            [
+              '`declinedProjectCli`',
+              'none',
+              "Why you did not run the project's own CLI, such as `untrusted`: a non-blank single line of at most 120 characters. That CLI then never runs.",
+            ],
+            [
+              '`roots`',
+              'none',
+              'Your package sets, in order of preference: folders whose `node_modules` each hold a CLI, the Core of the same release, and integrations. A run never installs a release; it takes the release a project needs from the first set that holds it.',
+            ],
+            [
+              '`integrations`',
+              'none',
+              'Integrations you approve for use outside a project, by package name.',
+            ],
+            [
+              '`discoverSources`',
+              'none',
+              "Your own discover sources. `astryx discover` reports each as the host's.",
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      id: 'result',
+      title: 'Result and errors',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "It resolves with `{status, packages}`: the exit status the CLI's own command would exit with, and each package the run used, with its version and whether it came from the project or a package set.",
+            'When another release answers from one of your package sets through its own host entry, that entry runs in the same process with the same inputs, and the call resolves with its result.',
+            'It rejects with a `TypeError`, before anything runs, for an unknown option or an invalid value, and with an `Error` when a run already started in the process. Start each run in a new process.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'process-ends',
+      title: 'When the process ends instead',
+      content: [
+        {
+          type: 'prose',
+          text: "Like the CLI's own command, a run ends the process with its exit status, and the call never resolves, when it:",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'prints help or the version (`--help`, `-h`, `help`, `--version`, `-V`, `--version --json`);',
+            'rejects the command line, such as an unknown command or option;',
+            'reports an error it stops on, including every error in `--json` mode;',
+            'meets an unexpected error;',
+            "hands the run to another CLI's own command: the project's CLI when you pass no `declinedProjectCli`, or a package set whose CLI has no host entry.",
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/install-once.doc.mjs

@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/install-once`: install the CLI for the computer with each
+ * package manager; the cache of versions projects need; offline (spec AST-081).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'install-once',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 2,
+  },
+  title: 'Install Astryx globally',
+  category: 'guide',
+  keywords: [
+    'pnpm add -g',
+    'yarn global add',
+    'bun add -g',
+    'volta install',
+    'npx',
+    'offline',
+    'cache',
+    'per-user cache',
+    'EACCES',
+    'permission denied',
+    'sudo',
+    'npm prefix',
+  ],
+  description:
+    'Install the Astryx CLI once for your computer with npm, pnpm, Yarn, Bun, or Volta, and what happens when you are offline.',
+  sections: [
+    {
+      id: 'install',
+      title: 'Install it',
+      content: [
+        {
+          type: 'prose',
+          text: 'Install the CLI package with your package manager. One astryx command then works in every folder.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm i -g @astryxdesign/cli\n# or: pnpm add -g @astryxdesign/cli · yarn global add @astryxdesign/cli · bun add -g @astryxdesign/cli · volta install @astryxdesign/cli',
+        },
+        {
+          type: 'prose',
+          text: "Keep the CLI installed in each project too: that pins its version for teammates and CI ({@link generic:project-global-or-both}). Inside a project, whichever astryx command you type, the project's version answers. Outside a project, your global install answers with its own version, and a version you name, such as `npx @astryxdesign/cli@0.7.0`, answers as exactly that version.",
+        },
+      ],
+    },
+    {
+      id: 'eacces',
+      title: 'Permission denied (EACCES)',
+      content: [
+        {
+          type: 'prose',
+          text: 'If `npm i -g` fails with `EACCES`, do not use `sudo`. Give npm a global folder you own, then add its `bin` folder to your PATH, or use a Node version manager such as nvm, fnm, or Volta:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm config set prefix ~/.npm-global\nexport PATH="$HOME/.npm-global/bin:$PATH"\nnpm i -g @astryxdesign/cli',
+        },
+        {
+          type: 'prose',
+          text: "Astryx's update notice then names that folder in its upgrade command.",
+        },
+      ],
+    },
+    {
+      id: 'versions-for-projects',
+      title: 'Versions for your projects',
+      content: [
+        {
+          type: 'prose',
+          text: "When a project's own CLI is installed but cannot start, Astryx runs the CLI version equal to the project's Core instead, installing it once into a cache in your home folder and reusing it. It uses npm for that, so your npm registry, proxy, and offline settings apply. Deleting the cache is safe: versions come back when a project needs them. Where it lives: {@link generic:reference}.",
+        },
+      ],
+    },
+    {
+      id: 'offline',
+      title: 'Offline',
+      content: [
+        {
+          type: 'prose',
+          text: "Your global install answers offline in a project with only Core, and so does any project that installs its own CLI. Outside a project, commands that read components, such as `astryx component Button`, need your global version's Core: after any command you run online, your global install downloads it once into the cache in the background, so they work offline from then on (not in CI, where nothing downloads by itself: {@link generic:ci-and-containers}; and not on Windows, where the first component command downloads it). Only a project whose own CLI cannot start needs a version installed or cached; when it is neither and cannot be fetched, your global install answers with a one-line warning, and Astryx waits 2 minutes before trying to download it again (10 minutes after a second failure in a row). {@link generic:problems} has the exact message.",
+        },
+      ],
+    },
+    {
+      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. Next: {@link generic:who-answers}.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/layout-spacing.doc.mjs

@@ -13,8 +13,7 @@ export const docs = {
   title: 'Layout spacing',
   placement: {parent: 'namespace:layout', slot: 'guides', order: 40},
   category: 'guide',
-  description:
-    'Hold one content line per region, then tune gaps and density.',
+  description: 'Hold one content line per region, then tune gaps and density.',
   keywords: [
     'alignment',
     'content line',
@@ -35,7 +34,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Hold one content line per region, then tune gaps and density. Alignment, Rhythm, and Density and size cover each step; these rules hold for all of them.',
+          text: 'Hold one content line per region, then tune gaps and density. Alignment, Rhythm, and Density and size each build on these rules.',
         },
         {
           type: 'list',