@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/assets/docs/tree/single-component.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/describe-the-component/single-component`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/single-component`:
  * write and maintain the default ComponentDoc for one public component.
  */
 
@@ -56,14 +56,13 @@ export default {
           style: 'unordered',
           items: [
             'Keep `props` on the top-level doc. Private implementation helpers do not need entries.',
-            'Keep the doc beside the source and change both in the same pull request.',
+            'Name the doc after the source file beside it, such as `AcmeCarousel.doc.mjs` beside `AcmeCarousel.tsx`, and change both in the same pull request.',
             'If the module later exposes several related public exports, adapt this doc with {@link generic:component-family}.',
           ],
         },
         {
-          type: 'reference',
-          target: 'schema:component-doc',
-          presentation: 'summary',
+          type: 'prose',
+          text: 'Every field is in {@link schema:component-doc}.',
         },
       ],
     },
@@ -87,6 +86,15 @@ export default {
   ],
 },`,
         },
+        {
+          type: 'prose',
+          text: "Set `keywords` to the words people search for: synonyms and the task the component does, such as `keywords: ['slider', 'slideshow', 'rotating cards']`. `astryx search` ranks a match on a component's name or keywords above one in its description, so without keywords a search for the component's task can list Core components first. Check with the words a person would type:",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx search "rotating cards" --type component',
+        },
       ],
     },
     {
@@ -122,6 +130,7 @@ export default {
             'Set `required: true` only when every caller must pass the prop.',
             'Write `default` exactly as the value should appear in documentation.',
             'Skip styling escape hatches such as `xstyle`, `className`, and `style`.',
+            '`astryx doctor integration components` lists a documented prop the code lacks, a public prop the doc misses, and a wrong `required`. See {@link generic:check-the-props}.',
           ],
         },
       ],
@@ -157,7 +166,7 @@ export default {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx component AcmeCarousel\nnpx astryx integration verify',
+          code: 'astryx component AcmeCarousel\nastryx doctor integration components\nastryx integration verify',
         },
       ],
     },

package/assets/docs/tree/start-a-template.doc.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/start-a-template`: what a
- * template is, why an integration shares one, whether it is a page or a
- * block, and how to add one.
+ * @file `astryx docs cli/integrations/building-blocks/templates/start-a-template`:
+ * what a template is, why an integration shares one, whether it is a page or
+ * a block, and how to add one.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -38,8 +38,8 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           code: `# How an app finds a template and copies it
-npx astryx template --list
-npx astryx template acme-dashboard src/app/dashboard`,
+astryx template --list
+astryx template acme-dashboard src/app/dashboard`,
         },
       ],
     },
@@ -97,7 +97,7 @@ npx astryx template acme-dashboard src/app/dashboard`,
         {
           type: 'code',
           lang: 'bash',
-          code: '# See the Core ids\nnpx astryx --json template --list --package @astryxdesign/core',
+          code: '# See the Core ids\nastryx --json template --list --package @astryxdesign/core',
         },
       ],
     },
@@ -112,8 +112,8 @@ npx astryx template acme-dashboard src/app/dashboard`,
         {
           type: 'code',
           lang: 'bash',
-          code: `npx astryx integration add template acme-dashboard
-npx astryx integration add template acme-stat-card --type block`,
+          code: `astryx integration add template acme-dashboard
+astryx integration add template acme-stat-card --type block`,
         },
         {
           type: 'code',
@@ -139,5 +139,15 @@ Declare template root ./templates in astryx.integration.mjs.
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'In global mode: when users install your package for their computer, beside the global CLI, your templates show up in folders outside any project; inside a project, only if the project installs your package. See {@link namespace:global} and {@link generic:global-integrations}.',
+        },
+      ],
+    },
   ],
 };

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/describe-the-component/subcomponent`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/subcomponent`:
  * give one member of a component family its own ComponentDoc.
  */
 
@@ -51,6 +51,7 @@ export default {
   type: 'component',
   name: 'AcmeDialog',
   displayName: 'Acme Dialog',
+  import: '@acme/astryx-widgets/components/AcmeDialog',
   usage: {description: 'Presents a focused task above the current page.'},
   components: [
     {
@@ -82,6 +83,7 @@ export default {
   type: 'component',
   name: 'AcmeDialogHeader',
   displayName: 'Acme Dialog Header',
+  import: '@acme/astryx-widgets/components/AcmeDialogHeader',
   subComponentOf: 'AcmeDialog',
   description: 'Labels an Acme Dialog and holds its close action.',
   props: [
@@ -95,10 +97,8 @@ export default {
 };`,
         },
         {
-          type: 'reference',
-          target: 'schema:component-doc',
-          projection: {fields: ['subComponentOf', 'description', 'props']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:component-doc}.',
         },
         {
           type: 'list',
@@ -106,7 +106,7 @@ export default {
           items: [
             '`subComponentOf` must exactly match the parent doc\'s `name`.',
             '`description` explains this member\'s role in the family. `usage` is optional; add it when the member needs guidance beyond that sentence.',
-            'The child inherits family fields such as `group`, `category`, `keywords`, `theming`, and `playground` unless it overrides them.',
+            'The CLI does not copy family fields such as `group`, `category`, or `keywords` from the parent to the child. Set any the child needs in its own doc.',
           ],
         },
       ],

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

@@ -1,8 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/template-assets`: make every
- * style, font, icon, and media dependency survive a template copy.
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets`:
+ * make every style, font, icon, and media dependency survive a template copy.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/document-the-template/template-doc-overview`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/template-doc-overview`:
  * the source and doc file pair, the fields every template doc shares, and how
  * to check what Astryx lists.
  */
@@ -54,22 +54,11 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'These fields apply to every page and block. The page, block, and replacement guides add the fields unique to each.',
+          text: 'The fields below apply to every page and block. The page, block, and replacement guides add the fields unique to each.',
         },
         {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {
-            fields: [
-              'type',
-              'name',
-              'displayName',
-              'description',
-              'keywords',
-              'isReady',
-            ],
-          },
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:template-doc}.',
         },
         {
           type: 'list',
@@ -78,7 +67,7 @@ export const docs = {
             'Set `type` to the kind you chose in {@link generic:start-a-template}. It decides which other fields the doc accepts.',
             'The file name sets the template id ({@link generic:start-a-template}). Labels live in the doc: the terminal list prints `name`, and JSON listings print `displayName`. Changing either never changes the id.',
             'Write the description for someone choosing between templates. The Doc metadata category in {@link generic:template-grading-rubric} defines what a complete description covers.',
-            "Name the ideas the template serves in `keywords`: the domains, tasks, and other names a builder might use for it, in lowercase, such as `['monitoring', 'uptime', 'on-call']` for a service-health dashboard. `astryx search` matches them as it matches the description, and `astryx build` ranks page templates on them, so the description can stay about the layout.",
+            "Name the ideas the template serves in `keywords`: the domains, tasks, and other names a builder might use for it, in lowercase, such as `['monitoring', 'uptime', 'on-call']` for a service-health dashboard. How search and build use them is in {@link generic:authoring}, so the description can stay about the layout.",
             'Add `isReady: false` as soon as you generate the doc, because a doc without `isReady` is listed as ready. Keep it until the template passes {@link generic:test-template-in-app} and the quality review.',
           ],
         },
@@ -99,7 +88,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx --json template --list --package @acme/astryx-templates',
+          code: 'astryx --json template --list --package @acme/astryx-templates',
         },
         {
           type: 'code',

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-fonts`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-fonts`:
  * use the app typeface by default, and ship every font file a template needs
  * when it must bring its own.
  */

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-icons`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-icons`:
  * render template icons through Astryx and ship custom product icons from the
  * package.
  */

package/assets/docs/tree/template-images-media.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-images-media`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-images-media`:
  * keep template images and video working after the copy, or make them clear
  * placeholders.
  */

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-styles`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-styles`:
  * style a template with Astryx first, keep editable styles in the file, and
  * ship shared CSS from the package.
  */
@@ -85,7 +85,7 @@ const styles = stylex.create({
         },
         {
           type: 'prose',
-          text: 'Then export that path and include the file in the package ({@link generic:export-template-assets}). In a TypeScript app, this import type-checks only when the app declares `*.css` modules.',
+          text: 'Then export that path and include the file in the package ({@link generic:export-template-assets}). TypeScript 6 and later check side-effect imports by default, so this import type-checks only when the app or its framework declares `*.css` modules.',
         },
       ],
     },

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates`: guides for adding,
+ * @file `astryx docs cli/integrations/building-blocks/templates`: guides for adding,
  * documenting, packaging, and testing templates in an integration package.
  */
 
@@ -31,4 +31,10 @@ export const docs = {
       accepts: {kinds: ['namespace']},
     },
   },
+  blocks: [
+    {
+      type: 'prose',
+      text: 'In global mode: templates from an integration installed for the computer show up outside projects; inside a project, only templates from integrations the project installs. See {@link namespace:global} and {@link generic:global-integrations}.',
+    },
+  ],
 };

package/assets/docs/tree/test-in-an-app.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/test-in-an-app`: install the packed
+ * @file `astryx docs cli/integrations/ship/test-in-an-app`: install the packed
  * package in an app and run the commands its users run.
  */
 
@@ -33,7 +33,7 @@ export const docs = {
           type: 'list',
           style: 'unordered',
           items: [
-            "Install the CLI in the app too: `npx astryx` runs the CLI from the app's `node_modules`.",
+            "Install the CLI in the app too: `astryx` runs the CLI from the app's `node_modules`.",
             'The app holds a copy, not a link. After each change, pack again and run the same `npm install`.',
             'Reading your work inside the package shows your source. The app shows what npm would publish.',
           ],
@@ -51,7 +51,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx component AcmeCarousel\nnpx astryx template --list --package @acme/astryx-widgets\nnpx astryx theme list --package @acme/astryx-widgets\nnpx astryx docs acme\nnpx astryx search deploying --type doc',
+          code: 'astryx component AcmeCarousel\nastryx template --list --package @acme/astryx-widgets\nastryx theme list --package @acme/astryx-widgets\nastryx docs acme\nastryx search deploying --type doc',
         },
         {
           type: 'table',
@@ -63,11 +63,11 @@ export const docs = {
             ],
             [
               '`template --list --package`',
-              'An `acme-dashboard` entry with `package: @acme/astryx-widgets`',
+              'An `acme-dashboard` entry whose `package` is `@acme/astryx-widgets`',
             ],
             [
               '`theme list --package`',
-              '`- ocean (maintained, @acme/astryx-widgets)`',
+              'An `ocean` entry whose `package` is `@acme/astryx-widgets`',
             ],
             ['`docs acme`', 'Your section, with guides such as `deploying`'],
             [
@@ -88,12 +88,12 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: '`npx astryx doctor` checks the whole app, including every package it loaded. `doctor integration validate` checks your package as the app installed it.',
+          text: '`astryx doctor` checks the whole app, including every package it loaded. `doctor integration validate` checks your package as the app installed it.',
         },
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx doctor\nnpx astryx doctor integration validate @acme/astryx-widgets',
+          code: 'astryx doctor\nastryx doctor integration validate @acme/astryx-widgets',
         },
         {
           type: 'code',

package/assets/docs/tree/test-template-in-app.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/test-template-in-app`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app`:
  * copy the packed template into a clean app, build it, and render it the way
  * apps will.
  */
@@ -38,14 +38,14 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           code: `# Confirm discovery and metadata
-npx astryx --json template --list --package @acme/astryx-widgets
+astryx --json template --list --package @acme/astryx-widgets
 
 # Inspect source without writing
-npx astryx template acme-dashboard --package @acme/astryx-widgets
+astryx template acme-dashboard --package @acme/astryx-widgets
 
 # Copy a page and a block to their real app locations
-npx astryx template acme-dashboard --package @acme/astryx-widgets src/app/acme-dashboard
-npx astryx template acme-stat-card --package @acme/astryx-widgets src/components`,
+astryx template acme-dashboard --package @acme/astryx-widgets src/app/acme-dashboard
+astryx template acme-stat-card --package @acme/astryx-widgets src/components`,
         },
         {
           type: 'list',

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

@@ -21,6 +21,10 @@ export const docs = {
     'extend a theme',
   ],
   blocks: [
+    {
+      type: 'prose',
+      text: 'In global mode: outside projects, the theme list includes themes from integrations installed for the computer, and `theme add` there only shows them; inside a project, it lists only themes from integrations the project installs. See {@link namespace:global} and {@link generic:global-integrations}.',
+    },
     {
       type: 'prose',
       text: 'A theme contribution has editable `defineTheme` source plus a built module and production CSS. `integration add theme` scaffolds the source and declares the package exports; `theme build` writes the built outputs. An app installs the package, runs `theme add`, applies the theme from its generated app module, and customizes it with `extends` instead of copying source.',

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/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 cli/integrations/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({