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

package/assets/docs/tree/tokens-and-setup.doc.mjs

@@ -15,13 +15,7 @@ export const docs = {
   category: 'guide',
   description:
     'Using design tokens in custom styles and configuring a StyleX compiler for swizzled components.',
-  keywords: [
-    'StyleX setup',
-    'swizzle',
-    'webpack',
-    'Vite',
-    'Next.js',
-  ],
+  keywords: ['StyleX setup', 'swizzle', 'webpack', 'Vite', 'Next.js'],
 
   sections: [
     {
@@ -77,30 +71,40 @@ const styles = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'Astryx components ship pre-compiled: `astryx.css` and each package\'s own stylesheet hold all of their styles, so consuming the published packages needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one the component compiles but renders completely unstyled: no error, no warning. If a swizzled component looks unstyled, a missing StyleX compiler is almost always why. The same applies if you author your own StyleX with `stylex.create()`.',
+          text: "Astryx components ship pre-compiled: `astryx.css` and each package's own stylesheet hold all of their styles, so consuming the published packages needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one, importing the component throws an error that starts `Unexpected 'stylex.create' call at runtime`, and the page does not render. If a swizzled component throws that error, the app is missing a StyleX compiler. The same applies if you author your own StyleX with `stylex.create()`.",
         },
         {
           type: 'table',
           headers: ['Bundler', 'StyleX plugin'],
           rows: [
             ['Webpack', '@stylexjs/webpack-plugin'],
-            ['Vite / Rollup', '@stylexjs/rollup-plugin (or a community Vite plugin)'],
-            ['Babel (any bundler)', '@stylexjs/babel-plugin + @stylexjs/postcss-plugin'],
-            ['Next.js (App Router, SWC)', 'An SWC-based transform; see the Next.js note below'],
+            [
+              'Vite / Rollup',
+              '@stylexjs/rollup-plugin (or a community Vite plugin)',
+            ],
+            [
+              'Babel (any bundler)',
+              '@stylexjs/babel-plugin + @stylexjs/postcss-plugin',
+            ],
+            [
+              'Next.js (App Router, SWC)',
+              'An SWC-based transform; see the Next.js note below',
+            ],
           ],
         },
         {
           type: 'prose',
-          text: 'Next.js (App Router) is the sharp edge. StyleX\'s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, and with it SWC-dependent features like `next/font`.',
+          text: "Next.js (App Router) is the sharp edge. StyleX's canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, and with it SWC-dependent features like `next/font`.",
         },
         {
           type: 'prose',
-          text: 'The repo\'s `apps/example-nextjs-stylex` takes the Babel path (`next/babel`, `@stylexjs/babel-plugin`, `@stylexjs/postcss-plugin`). Babel turns off SWC, so that app does not use `next/font`. To keep `next/font`, use an SWC transform such as `@stylexswc/nextjs-plugin`.',
+          text: "The repo's `apps/example-nextjs-stylex` takes the Babel path (`next/babel`, `@stylexjs/babel-plugin`, `@stylexjs/postcss-plugin`). Babel turns off SWC, so that app does not use `next/font`. To keep `next/font`, use an SWC transform such as `@stylexswc/nextjs-plugin`.",
         },
         {
           type: 'code',
           lang: 'js',
-          label: 'next.config.mjs: SWC-based StyleX transform (keeps next/font working)',
+          label:
+            'next.config.mjs: SWC-based StyleX transform (keeps next/font working)',
           code: `import stylexPlugin from '@stylexswc/nextjs-plugin';
 
 export default stylexPlugin({
@@ -117,7 +121,7 @@ export default stylexPlugin({
           type: 'list',
           style: 'unordered',
           items: [
-            'Symptom of a missing compiler: swizzled component renders with no styles, but no build or runtime error.',
+            "Symptom of a missing compiler: importing a swizzled component throws an error that starts `Unexpected 'stylex.create' call at runtime`, and the page does not render.",
             'A Babel config turns off SWC in Next.js; skip it if you need `next/font`.',
             'Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler; only swizzled/authored StyleX source does.',
             'Keep loading `astryx.css` with a StyleX compiler in place. The compiler builds your own and swizzled source only; never add `node_modules/@astryxdesign` to its inputs.',

package/assets/docs/tree/tokens-data.doc.mjs

@@ -17,14 +17,14 @@ export const docs = {
     "order": 20
   },
   "category": "foundations",
-  "description": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Retaining any member emits the complete 56-variable group; an unused graph emits none.",
+  "description": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Source compilation emits the complete 56-variable group when any member is retained and none for an unused graph. Prebuilt CSS consumers load @astryxdesign/core/astryx.css, which defines the complete group for the already-compiled dataVars entry.",
   "sections": [
     {
       "title": "Data Visualization Tokens",
       "content": [
         {
           "type": "prose",
-          "text": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Retaining any member emits the complete 56-variable group; an unused graph emits none."
+          "text": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Source compilation emits the complete 56-variable group when any member is retained and none for an unused graph. Prebuilt CSS consumers load @astryxdesign/core/astryx.css, which defines the complete group for the already-compiled dataVars entry."
         },
         {
           "type": "table",

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/troubleshooting`: the messages the CLI
+ * @file `astryx docs authoring/help/troubleshooting`: the messages the CLI
  * prints while you build, verify, and install an integration, and the fix
  * for each.
  */
@@ -47,7 +47,7 @@ export const docs = {
             ],
             [
               'Note: `integration pack --check` is deprecated.',
-              'The old name still runs the same check. Switch to `npx astryx integration verify`; the old name will be removed in a later release.',
+              'The old name still runs the same check. Switch to `astryx integration verify`; the old name will be removed in a later release.',
             ],
           ],
         },
@@ -59,7 +59,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: '`npx astryx integration verify` prints each failure as a `[fail]` line. Add `--json` to see its issue code, such as `component_export_missing`.',
+          text: '`astryx integration verify` prints each failure as a `[fail]` line. Add `--json` to see its issue code, such as `component_export_missing`.',
         },
         {
           type: 'table',
@@ -67,7 +67,7 @@ export const docs = {
           rows: [
             [
               '`component_export_missing`: `Component "AcmeCarousel" advertises import "@acme/astryx-widgets/components/AcmeCarousel", but that packed module does not export "AcmeCarousel".`',
-              "package.json has no `exports` map, or the module does not export the name. Keep `export function AcmeCarousel`, and add the entry: `npm pkg set 'exports[./components/AcmeCarousel]=./components/AcmeCarousel.tsx'`.",
+              "package.json has no `exports` map, or the module does not export the name. Keep `export function AcmeCarousel`, and add the entry: `npm pkg set 'exports[./components/AcmeCarousel]=./components/AcmeCarousel.tsx'`. When the quoted name is a file name, such as `acme-carousel`, set the doc's `name` to the component the file exports. A type-only export does not count.",
             ],
             [
               '`template_export_missing`: `Template "acme-dashboard" public import "@acme/astryx-widgets/templates/acme-dashboard" does not have a default export.`',
@@ -78,7 +78,7 @@ export const docs = {
               "The `exports` map has no entry for it. Run `npm pkg set 'exports[./components/AcmeCarousel]=./components/AcmeCarousel.tsx'`, or `'exports[./templates/acme-dashboard]=./templates/acme-dashboard.tsx'` for a template.",
             ],
             [
-              '`component_import_unresolvable`: `…but a consumer cannot resolve it: Cannot find package \'@acme/old-name\'`',
+              "`component_import_unresolvable`: `…but a consumer cannot resolve it: Cannot find package '@acme/old-name'`",
               "You renamed the package after the add wrote each doc's `import`. Change `import` in every component doc to the new name.",
             ],
             [
@@ -95,19 +95,19 @@ export const docs = {
             ],
             [
               '`component_replaces_needs_cli` (a warning): The package has a component that sets `replaces` but declares no @astryxdesign/cli peer, or a peer range that admits an earlier CLI.',
-              "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.6.7'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json` to turn the replacement on. Until then the component keeps its own name and the Core component stays selected; a component named like its target stays ambiguous by that bare name.",
+              "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.6.7'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json` to turn the replacement on. Until then apps see no change ({@link generic:replace-a-core-component}).",
             ],
             [
               '`keywords_needs_cli`: The package has a template that sets `keywords` but declares no @astryxdesign/cli peer.',
-              "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.6.6'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`. A stable CLI before 0.6.6 rejects `keywords` and drops that template, and one before 0.6.4 also hides your doc topics.",
+              "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.6.6'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`. What an older CLI does with the field is in {@link generic:template-doc-overview}.",
             ],
             [
               '`themes_need_cli`: The package ships a theme but declares no @astryxdesign/cli peer.',
-              "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.6.4'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`. A stable CLI before 0.6.4 cannot read typed theme descriptors, so it drops your themes and can hide your doc topics.",
+              "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.6.4'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`. A CLI older than published 0.6.4 cannot read typed theme descriptors, so it drops your themes and can hide your doc topics.",
             ],
             [
               '`section_ids_need_cli`: The package has a doc section that sets `id` but declares no @astryxdesign/cli peer.',
-              'The same fix as `themes_need_cli`, or drop the section `id`s: a stable CLI before 0.6.4 rejects them and hides your doc topics.',
+              'The same fix as `themes_need_cli`, or drop the section `id`s: a CLI older than published 0.6.4 rejects them and hides your doc topics.',
             ],
           ],
         },
@@ -125,9 +125,17 @@ export const docs = {
           type: 'table',
           headers: ['Symptom', 'Fix'],
           rows: [
+            [
+              '`Error: No component named "AcmeCarousel"` for a component your package documents.',
+              "Its doc still names its file. Set `name` to the export, such as `name: 'AcmeCarousel'` in `acme-carousel.doc.mjs`. A family member is listed only when the module its family doc imports exports it ({@link generic:component-family}).",
+            ],
+            [
+              "`astryx component Dialog` opens Core's `Dialog`, not yours.",
+              "A name that Core, a legacy docs package, or another package's file already has stays theirs. Run `astryx component Dialog --package @acme/astryx-widgets`, or give your component a name of its own.",
+            ],
             [
               '`Error: Template "dashboard" is ambiguous — narrow it with --type and/or --package.`',
-              "Your template id matches a Core id. Rename it, such as `acme-dashboard`, or set `replaces: 'dashboard'` to take its place. `npx astryx doctor integration templates` warns about this before you publish.",
+              "Your template id matches a Core id. Rename it, such as `acme-dashboard`, or set `replaces: 'dashboard'` to take its place. `astryx doctor integration templates` warns about this before you publish.",
             ],
             [
               '`invalid_doc_graph`: `placement.parent "namespace:nope" names no namespace; @acme/astryx-widgets declares "acme".`',
@@ -135,15 +143,23 @@ export const docs = {
             ],
             [
               'Error: Unknown topic "acme". The docs of @acme/astryx-widgets did not load; run `astryx doctor integration docs` in that package to see why.',
-              'One invalid doc hides all of your docs. Run `npx astryx doctor integration docs` in the package and fix the `invalid_doc` it names.',
+              'One invalid doc hides all of your docs. Run `astryx doctor integration docs` in the package and fix the `invalid_doc` it names.',
+            ],
+            [
+              '`cli-command` warns: `Loaded integrations declare different CLI commands`',
+              "Two packages the app loads set different `cliCommand` values, so the CLI prints the package manager's command. Agree on one command, or remove the package that does not belong. See {@link generic:cli-command}.",
+            ],
+            [
+              '`invalid_cli_command`',
+              'Your `cliCommand` is not one line of plain text of at most 120 characters, so it is ignored. Fix the value; the rest of the manifest still loads.',
             ],
             [
-              '`npx astryx upgrade` runs none of your codemods',
+              '`astryx upgrade` runs none of your codemods',
               'The app must list your package in `integrations` in `astryx.config`, or pass `--integration @acme/astryx-widgets`. It runs a codemod folder only when its version is after `--from` and at most the installed `@astryxdesign/core`.',
             ],
             [
               'Your docs section, templates, or themes are missing only in some apps',
-              'Those apps run a CLI too old to read them: a stable CLI before 0.6.6 for a template that sets `keywords`, or before 0.6.4 for a template that sets `replaces`, a docs section, or a theme. Update `@astryxdesign/cli` there, and keep your optional `@astryxdesign/cli` peer so npm warns about an old CLI.',
+              "Those apps run a CLI too old to read them ({@link generic:checks} lists which field needs which CLI). Update `@astryxdesign/cli` there, and keep your optional `@astryxdesign/cli` peer so npm checks the app's CLI against it when the app installs your package.",
             ],
           ],
         },

package/assets/docs/tree/type-scale.doc.mjs

@@ -76,7 +76,7 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Heading for document structure',
-          code: `import {Heading} from '@astryxdesign/core';
+          code: `import {Heading} from '@astryxdesign/core/Heading';
 
 // Heading levels map to semantic tokens: level 1 → --text-heading-1-*
 <Heading level={1}>Page Title</Heading>
@@ -96,7 +96,7 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Text for body, label, and display text',
-          code: `import {Text} from '@astryxdesign/core';
+          code: `import {Text} from '@astryxdesign/core/Text';
 
 <Text type="body">Body text at the base scale.</Text>
 <Text type="large">Emphasized body text.</Text>
@@ -121,7 +121,7 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Customizing the type scale via defineTheme',
-          code: `import {defineTheme} from '@astryxdesign/core';
+          code: `import {defineTheme} from '@astryxdesign/core/theme';
 
 // Adjust the entire ramp holistically with base and ratio
 const editorialTheme = defineTheme({

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

@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/uninstall`: uninstall the global install with each package
+ * manager, remove the agent guide, and reset the cache and settings folders.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'uninstall',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 10,
+  },
+  title: 'Uninstall and reset',
+  category: 'guide',
+  keywords: [
+    'uninstall',
+    'remove',
+    'reset astryx',
+    'clear cache',
+    'delete cache',
+    'npm uninstall -g',
+    'remove agent guide',
+    'start over',
+  ],
+  description:
+    'Remove your global install, the agent guide it keeps, and the folders it uses, or reset them to start over.',
+  sections: [
+    {
+      id: 'agent-guide',
+      title: 'First, remove the agent guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'While the CLI is still installed, remove the agent guide from your home folder:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx init --user --remove-agents',
+        },
+        {
+          type: 'prose',
+          text: 'Or delete `~/.agents/skills/astryx` and the links to it listed in {@link generic:computer-agent-guide}.',
+        },
+      ],
+    },
+    {
+      id: 'uninstall',
+      title: 'Uninstall',
+      content: [
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm uninstall -g @astryxdesign/cli\n# or: pnpm remove -g @astryxdesign/cli · yarn global remove @astryxdesign/cli · bun remove -g @astryxdesign/cli · volta uninstall @astryxdesign/cli',
+        },
+        {
+          type: 'prose',
+          text: 'Projects are unaffected: each keeps the CLI it installs, if any.',
+        },
+      ],
+    },
+    {
+      id: 'reset',
+      title: 'Reset',
+      content: [
+        {
+          type: 'prose',
+          text: 'Delete either folder to reset it; Astryx recreates what it needs on the next run.',
+        },
+        {
+          type: 'table',
+          headers: ['Folder', 'Linux', 'macOS', 'Windows'],
+          rows: [
+            [
+              'Cache: versions for projects, saved discover answers',
+              '`~/.cache/astryx`',
+              '`~/Library/Caches/astryx`',
+              '`%LOCALAPPDATA%\\astryx\\Cache`',
+            ],
+            [
+              'Settings: update checks, the agent guide setting, and its links',
+              '`~/.config/astryx`',
+              '`~/Library/Application Support/astryx`',
+              '`%APPDATA%\\astryx`',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'On Linux, `XDG_CACHE_HOME` and `XDG_CONFIG_HOME` move them when set to absolute paths.',
+        },
+      ],
+    },
+    {
+      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/updates.doc.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/updates`: how the global install learns of newer
+ * versions, and the notice it prints (spec AST-081 FR6, FR10).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'updates',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 4,
+  },
+  title: 'Updates and notices',
+  category: 'guide',
+  keywords: [
+    'update',
+    'upgrade',
+    'upgrade astryx',
+    'update notice',
+    'new release',
+    'new version',
+    'NO_UPDATE_NOTIFIER',
+    'latest',
+  ],
+  description:
+    'Your global install checks for a newer version once a day and prints a two-line notice after a command succeeds. It never upgrades itself or a project.',
+  sections: [
+    {
+      id: 'notice',
+      title: 'The notice',
+      content: [
+        {
+          type: 'prose',
+          text: "Once a day, never in your first day, your global install checks the registry's `latest` version in the background, without slowing the command. When a newer one exists, a command that succeeds prints two lines on standard error, at most once a day:",
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'A new release of Astryx is available: 0.7.2 → 0.7.3\nTo upgrade, run: npm i -g @astryxdesign/cli@latest',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "The command is the one for the package manager that installed your global install: `npm i -g`, `pnpm add -g`, `yarn global add`, `bun add -g`, or `volta install`. A global folder moved with the package manager's own setting (`BUN_INSTALL`, Yarn's `global-folder`, `PNPM_HOME`, or npm's prefix) counts while that setting names it; an app's own copy never runs the update check.",
+            'When the newest version needs a newer Node than your computer runs, the second line says which Node to install first.',
+            "Inside a project, the notice is about the project's version, and names the project's install and `upgrade` commands. The install command always adds the CLI next to Core, so a project that installed only Core gets its own CLI too, as recommended.",
+          ],
+        },
+      ],
+    },
+    {
+      id: 'project-notice',
+      title: 'In a project',
+      content: [
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'A new release of Astryx is available: 0.7.1 → 0.7.3\nTo upgrade, run: pnpm add @astryxdesign/core@0.7.3 @astryxdesign/cli@0.7.3, then pnpm exec astryx upgrade --from 0.7.1 --apply',
+        },
+      ],
+    },
+    {
+      id: 'turn-off',
+      title: 'Turn it off',
+      content: [
+        {
+          type: 'prose',
+          text: 'No notice prints with `--json`, after a failed command, when the `CI` environment variable is set, or when `NO_UPDATE_NOTIFIER` is set; with either variable set, the CLI does not check the registry either. Unlike some CLIs, a notice prints even when standard error is not a terminal, because agents run the CLI without one.',
+        },
+        {
+          type: 'prose',
+          text: '`astryx doctor` shows the same thing at any time, in its `newest-release` check, along with why the last notice did not print, if one did not. When the last check ran, and when each notice printed, are kept in `state.json` in the settings folder ({@link generic:reference}).',
+        },
+      ],
+    },
+    {
+      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. Upgrading a project: {@link command:upgrade}.',
+        },
+      ],
+    },
+  ],
+};

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/upgrading`: update an integration
+ * @file `astryx docs authoring/ship/upgrading`: update an integration
  * package for each Astryx release, and the command apps run to upgrade with
  * it.
  */
@@ -28,14 +28,14 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: "# 1. Build and test against the new release\nnpm install -D @astryxdesign/cli@latest @astryxdesign/core@latest\n# 2. Rerun the checks\nnpx astryx doctor integration validate\nnpx astryx doctor integration docs\nnpx astryx integration verify\n# 3. Admit the new Core once the checks pass\nnpm pkg set 'peerDependencies.@astryxdesign/core=^0.6.0 || ^0.7.0'\n# 4. Migrate apps across a change that breaks them\nnpx astryx integration add codemod rename-delay --to 0.7.0",
+          code: "# 1. Build and test against the new release\nnpm install -D @astryxdesign/cli@latest @astryxdesign/core@latest\n# 2. Rerun the checks\nastryx doctor integration validate\nastryx doctor integration docs\nastryx integration verify\n# 3. Admit the new Core once the checks pass\nnpm pkg set 'peerDependencies.@astryxdesign/core=^0.6.0 || ^0.7.0'\n# 4. Migrate apps across a change that breaks them\nastryx integration add codemod rename-delay --to 0.7.0",
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
             'Run every check in {@link generic:checks}, not only the ones shown.',
-            'Name each codemod folder after the Core version whose upgrade should run it; see {@link generic:codemods}.',
+            'Codemod folders are named for Core versions: {@link generic:codemods}.',
             'Release the result as a new version of your package; see {@link generic:publishing}.',
           ],
         },
@@ -52,12 +52,12 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: '# Preview what would change; nothing is written\nnpx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets\n# Write the changes\nnpx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply',
+          code: '# Preview what would change; nothing is written\nastryx upgrade --from 0.6.3 --integration @acme/astryx-widgets\n# Write the changes\nastryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply',
         },
         {
           type: 'code',
           lang: 'text',
-          code: 'Integrations: @acme/astryx-widgets\n1 codemod to run\nApplying integration codemods...\n  Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)\n[ok]     [ok] src/Hero.tsx',
+          code: 'Integrations: @acme/astryx-widgets\n<n> codemods to run\nApplying integration codemods...\n  Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)\n[ok]     [ok] src/Hero.tsx',
         },
         {
           type: 'list',
@@ -65,7 +65,7 @@ export const docs = {
           items: [
             '`--from` is the `@astryxdesign/core` version the app had before, and the target is the installed Core.',
             '`--integration` names your package. Without it, or an `integrations` entry in `astryx.config`, the upgrade skips your codemods, even when the app has your package installed.',
-            "The count includes Core's codemods for the same versions, which run first.",
+            "`<n>` includes Core's codemods for the same versions, which run first.",
             'Put this command in your release notes.',
           ],
         },

package/assets/docs/tree/use-a-theme-in-an-app.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/themes/use-a-theme-in-an-app`:
+ * @file `astryx docs authoring/building-blocks/themes/use-a-theme-in-an-app`:
  * an app installs the integration and applies or extends the theme, like any theme.
  */
 
@@ -26,7 +26,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npm install @acme/astryx-widgets\nnpx astryx theme add ocean --package @acme/astryx-widgets',
+          code: 'npm install @acme/astryx-widgets\nastryx theme add ocean --package @acme/astryx-widgets',
         },
         {
           type: 'code',
@@ -34,7 +34,9 @@ export const docs = {
           code: `import {Theme} from '@astryxdesign/core/theme';
 import {themes, defaultThemeSlug} from './astryx-themes';
 
-<Theme theme={themes[defaultThemeSlug]}>{/* app */}</Theme>`,
+<Theme theme={themes[defaultThemeSlug]}>
+  <App />
+</Theme>`,
         },
         {
           type: 'prose',
@@ -64,5 +66,15 @@ export const productTheme = defineTheme({
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'In global mode: install the theme package in each app that uses the theme; inside a project, the CLI ignores packages installed for the computer. See {@link namespace:global} and {@link generic:global-integrations}.',
+        },
+      ],
+    },
   ],
 };

package/assets/docs/tree/verify-packed-template.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/verify-packed-template`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/package-and-test/verify-packed-template`:
  * what `integration verify` checks for templates, and what it leaves to the
  * app test.
  */
@@ -27,7 +27,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration verify',
+          code: 'astryx integration verify',
         },
         {
           type: 'prose',
@@ -67,7 +67,7 @@ export const docs = {
             'Whether the copied file type-checks in every supported app toolchain.',
             'Whether package-owned CSS, fonts, icons, images, or media load in a browser.',
             'Whether layout, color modes, keyboard and pointer input, and real content work.',
-            'Whether a template id collides with Core, or whether a `replaces` target exists. Run `npx astryx doctor integration templates` for those.',
+            'Whether a template id collides with Core, or whether a `replaces` target exists. Run `astryx doctor integration templates` for those.',
             'How the template scores on quality.',
           ],
         },

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/versioning`: version an integration
+ * @file `astryx docs authoring/ship/versioning`: version an integration
  * package, know which changes break apps, declare peer ranges, keep apps on
  * older CLIs working, and match codemod folders to versions.
  */
@@ -54,13 +54,13 @@ export const docs = {
           rows: [
             [
               'A component name, such as `AcmeCarousel`',
-              'Imports, and `npx astryx component AcmeCarousel`',
+              'Imports, and `astryx component AcmeCarousel`',
             ],
             [
               'A template id, such as `acme-dashboard`',
-              '`npx astryx template acme-dashboard`',
+              '`astryx template acme-dashboard`',
             ],
-            ['A theme slug, such as `ocean`', '`npx astryx theme add ocean`'],
+            ['A theme slug, such as `ocean`', '`astryx theme add ocean`'],
             [
               'A topic name or route, such as `acme/deploying`',
               'Reads of the old name, and links to it from other docs',
@@ -106,8 +106,8 @@ export const docs = {
             ],
             [
               '`@astryxdesign/cli`',
-              'You ship a docs section, a placed guide, a template that sets `replaces` or `keywords`, a doc section with an `id`, or a theme',
-              '`>=0.6.6` when you ship a template that sets `keywords`, otherwise `>=0.6.4`. Optional in `peerDependenciesMeta`',
+              'You ship a docs section, a placed guide, a template that sets `replaces` or `keywords`, a component that sets `replaces`, a doc section with an `id`, or a theme',
+              '`>=0.6.6` when you ship a template that sets `keywords`, `>=0.6.7` when a component sets `replaces`, otherwise `>=0.6.4`. Optional in `peerDependenciesMeta`',
             ],
           ],
         },
@@ -120,6 +120,10 @@ export const docs = {
           type: 'prose',
           text: '`integration verify` fails a package that needs the CLI peer and lacks it, or whose range admits a stable CLI too old for what it ships. `integration add doc --parent` and `integration add theme` write the peer for you.',
         },
+        {
+          type: 'prose',
+          text: "When the CLI is outside that range, `doctor integration validate` and `integration check` list a `cli_peer_version` note naming your package. A note fails nothing, `--strict` included, and `integration verify` does not report it. Below the range the note gives the commands that install a newer Core and CLI together, as dev dependencies in your own package folder, and then run `upgrade --apply`. Above it, in an app the note asks for a release of your package that supports that CLI, and in your own package folder it asks you to test your package with that CLI and widen the range.",
+        },
       ],
     },
     {
@@ -136,10 +140,11 @@ export const docs = {
           items: [
             'An unknown field in `astryx.integration.mjs` is ignored with an `unknown_manifest_key` warning, and the rest of the manifest still loads.',
             'A named export that the CLI does not know is ignored with no warning, so `debug` and `gapReport` are safe to add.',
-            'A stable CLI before 0.7.0 prints each `{@link ...}` as written.',
+            'Published 0.6.3 and earlier print each `{@link ...}` as written.',
             'Published 0.6.3 and earlier reject a template that sets `replaces` or `keywords`, drop that template, and hide every doc topic your package ships. Published 0.6.4 and 0.6.5 still drop a template that sets `keywords`.',
-            'A stable CLI before 0.6.4 cannot read a docs section, a section `id`, or a theme folder that `integration add theme` writes. It can then hide every doc topic your package ships.',
-            'Stable 0.6.3 still loads your components, but 0.6.0 cannot read the component docs that `integration add component` writes: `component AcmeCarousel` fails there.',
+            'Published 0.6.3 and earlier cannot read a docs section, a section `id`, or a theme folder that `integration add theme` writes. They can then hide every doc topic your package ships.',
+            'Published 0.6.2 and 0.6.3 still load your components, but published 0.6.0 and 0.6.1 cannot read the component docs that `integration add component` writes: `component AcmeCarousel` fails there.',
+            'An app on an older CLI lists a component whose doc names another export of its file under the file name, and lists no family members, so `component AcmeCarousel` fails there.',
           ],
         },
         {