@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/document-the-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template`:
  * document page and block templates for discovery and correct reuse.
  */
 

package/assets/docs/tree/document-the-theme.doc.mjs

@@ -13,7 +13,7 @@ export const docs = {
   title: 'Document the theme',
   category: 'guide',
   description:
-    'Document a theme by extending the core theme topic, so an app reads it in `astryx docs theme`.',
+    'Document a theme by extending the core theme topic, so an app reads it in {@link generic:theme}.',
   sections: [
     {
       id: 'extend-the-theme-topic',
@@ -21,7 +21,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Give your theme a doc topic that extends the core `theme` topic, so an app that lists your package sees your theme at the end of `astryx docs theme`. Add it with `extends: 'theme'` ({@link generic:extend-or-replace}).",
+          text: "Give your theme a doc topic that extends the core `theme` topic, so an app that lists your package sees your theme at the end of {@link generic:theme}. Add it with `extends: 'theme'` ({@link generic:extend-or-replace}).",
         },
         {
           type: 'code',
@@ -50,7 +50,7 @@ export default {
         },
         {
           type: 'prose',
-          text: 'Keep the section short: how to install the package, run `theme add`, apply the generated module ({@link generic:use-a-theme-in-an-app}), and customize with `extends`. When the theme uses a custom font, name the families and the optional exported font stylesheet that `theme add` imports ({@link generic:fonts-and-assets}). Extend `theme` rather than a topic another package replaces, or an app that lists that package first drops your section.',
+          text: 'Keep the section short: how to install the package, run `theme add`, apply the generated module ({@link generic:use-a-theme-in-an-app}), and customize with `extends`. When the theme uses a custom font, name the families and the optional exported font stylesheet that `theme add` imports ({@link generic:fonts-and-assets}). Extend `theme` rather than a topic another package replaces, or an app that loads that package after yours drops your section.',
         },
       ],
     },

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/export-template-assets`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/export-template-assets`:
  * expose and include everything a copied template imports, and declare the
  * packages it needs.
  */

package/assets/docs/tree/extend-or-replace.doc.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/extend-or-replace`: take over an
- * existing topic with `replaces`, merge sections into one with `extends`, and
- * check overlaps with Core topics.
+ * @file `astryx docs cli/integrations/building-blocks/docs/extend-or-replace`:
+ * take over an existing topic with `replaces`, merge sections into one with
+ * `extends`, and check overlaps with Core topics.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -26,7 +26,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration add doc acme-getting-started --replaces getting-started\n# The old name now opens your topic\nnpx astryx docs getting-started',
+          code: 'astryx integration add doc acme-getting-started --replaces getting-started\n# The old name now opens your topic\nastryx docs getting-started',
         },
         {
           type: 'code',
@@ -46,12 +46,12 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Set `extends` to merge sections into an existing topic instead of owning it. A section with the same key replaces the base section, and a new section is added at the end.',
+          text: 'Set `extends` to merge sections into an existing topic instead of owning it. A section replaces the base section it matches, and a section that matches none is added at the end.',
         },
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration add doc acme-theming --extends theme\nnpx astryx docs theme --index',
+          code: 'astryx integration add doc acme-theming --extends theme\nastryx docs theme --index',
         },
         {
           type: 'code',
@@ -63,7 +63,7 @@ export const docs = {
           type: 'list',
           style: 'unordered',
           items: [
-            "A section's key is its `id`, or a key made from its title. Read the base topic's keys with `--index`.",
+            "Read the base topic's keys with `--index`, and give a section that replaces one that key as its `id`. A section without an `id` matches only a base section with exactly its title, or one whose `id` is the key its title makes, so `Integration Themes` is added beside a base `Integration themes` that has no `id`.",
             "The topic keeps the base's title and description, and readers open it by the base's name.",
             'Replace the `Overview` placeholder that `integration add` writes, or it is added to the base topic.',
             "Extend a topic to correct or add to it. A copy made with `replaces` stops getting the owner's fixes.",
@@ -82,12 +82,12 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx doctor integration docs',
+          code: 'astryx doctor integration docs',
         },
         {
           type: 'code',
           lang: 'text',
-          code: 'severity:     [info]\ntopic:        acme-getting-started\nrelationship: replaces\ncoreTopic:    getting-started\nmessage:      Intentional override: "acme-getting-started" replaces the Core topic "getting-started".\n\nseverity:     [fail]\ntopic:        tokens\nrelationship: accidental\ncoreTopic:    tokens\nmessage:      Accidental conflict: "tokens" is already a Core topic. Rename it, declare replaces: \'tokens\' to take it over, or declare extends: \'tokens\' to merge sections.',
+          code: 'severity:     [info]\ntopic:        acme-getting-started\nrelationship: replaces\ncoreTopic:    getting-started\nmessage:      Intentional override: "acme-getting-started" replaces the Core topic "getting-started".\n\nseverity:     [fail]\ntopic:        color\nrelationship: accidental\ncoreTopic:    color\nmessage:      Accidental conflict: "color" is already a Core topic. Rename it, declare replaces: \'color\' to take it over, or declare extends: \'color\' to merge sections.',
         },
         {
           type: 'list',
@@ -99,5 +99,15 @@ export const docs = {
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'In global mode: a doc that extends or replaces a topic from a package installed for the computer applies in folders outside any project; inside a project, only those from packages the project installs apply. See {@link namespace:global} and {@link generic:global-integrations}.',
+        },
+      ],
+    },
   ],
 };

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

@@ -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

@@ -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 cli/integrations/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:integrations',
+    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 cli/integrations/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 cli/integrations/building-blocks/templates/write-good-templates --full\`.
+2. Read \`astryx docs cli/integrations/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 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.
 
 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/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/integrations.doc.mjs

@@ -24,17 +24,29 @@ export const docs = {
     },
   },
   blocks: [
+    {
+      type: 'prose',
+      text: 'In global mode: users can install your integration for their computer, beside the global CLI. It then applies in folders outside any project, and inside a project only if the project installs it. See {@link namespace:global} and {@link generic:global-integrations}.',
+    },
     {
       type: 'prose',
       text: 'An integration is a way to share things with Astryx users: a package you own and maintain, built on a framework Astryx gives you. Publish one, many, or any mix, and people install it in one step. It works with the Astryx CLI alongside Core. See each kind under {@link namespace:building-blocks}.',
     },
     {
       type: 'prose',
-      text: 'For example, ship a carousel as an integration. Any app that installs it can find it with `npx astryx search carousel`, and the CLI uses it like any Astryx Core component.',
+      text: 'For example, ship a carousel as an integration. Any app that installs it can find it with `astryx search carousel`, and the CLI uses it like any Astryx Core component.',
     },
     {
       type: 'prose',
       text: 'An integration can also replace a built-in template or doc. To start, install `@astryxdesign/cli` and open {@link generic:quick-start}.',
     },
+    {
+      type: 'prose',
+      text: 'Every field of every file you write for an integration is in {@link generic:authoring}.',
+    },
+    {
+      type: 'prose',
+      text: "Every integration runs `astryx integration check --strict` in its own build: it is required, not optional, so a doc, prop, or link that stops matching the code fails your build instead of your users' apps. See {@link generic:checks}.",
+    },
   ],
 };

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',

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

@@ -32,21 +32,21 @@ export const docs = {
   blocks: [
     {
       type: 'prose',
-      text: "Build a layout outside-in. Settle the shell and its region budgets before any content exists, then work inward. Content-first layouts drift into a padded column of cards, because every section ends up inventing its own container.",
+      text: 'Build a layout outside-in. Settle the shell and its region budgets before any content exists, then work inward. Content-first layouts drift into a padded column of cards, because every section ends up inventing its own container.',
     },
     {
       type: 'list',
       style: 'ordered',
       items: [
-        "Scaffold: pick the shell, budget each region, and choose navigation",
-        "Structure: rank the content in each region, then pick the weakest container that groups it",
-        "Spacing: hold one content line per region, then tune gaps and density",
-        "Breakpoints: decide what each region does as width changes",
+        'Scaffold: pick the shell, budget each region, and choose navigation',
+        "Structure: rank each region's content and choose its container",
+        'Spacing: align each region to one content line, then set gaps and density',
+        'Breakpoints: decide what each region does as width changes',
       ],
     },
     {
       type: 'prose',
-      text: "This guide decides layout, not component APIs. Run `npx astryx build \"<idea>\"` to start from the closest template for your app type, and `npx astryx component <Name>` for a component's props.",
+      text: 'This guide decides layout, not component APIs. Run `astryx build "<idea>"` to start from the closest template for your app type, and `astryx component <Name>` for a component\'s props.',
     },
   ],
   slots: {