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

package/assets/docs/tree/short-and-findable.doc.mjs

@@ -1,8 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/short-and-findable`: keep each read
- * short, lead each section with its summary, and write docs that search finds.
+ * @file `astryx docs authoring/building-blocks/docs/short-and-findable`:
+ * keep each read short, lead each section with its summary, and write docs
+ * that search finds.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -20,7 +21,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Readers open one section at a time, so give each section one idea and keep it to about 30 lines. `npx astryx doctor` warns on any read over 32 KB.',
+          text: 'Readers open one section at a time, so give each section one idea and keep it to about 30 lines. `astryx doctor` warns on any read over 32 KB.',
         },
         {
           type: 'list',
@@ -34,7 +35,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: '# The section list\nnpx astryx docs acme/deploying\n# One section\nnpx astryx docs acme/deploying check-before-you-ship\n# Everything\nnpx astryx docs acme/deploying --full',
+          code: '# The section list\nastryx docs acme/deploying\n# One section\nastryx docs acme/deploying check-before-you-ship\n# Everything\nastryx docs acme/deploying --full',
         },
       ],
     },
@@ -58,7 +59,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'text',
-          code: 'build-before-you-ship  Build before you ship - Build the app, then upload the `dist` folder to your host.',
+          code: 'build-before-you-ship  Build before you ship - Build the app, then upload the `dist` folder.',
         },
       ],
     },
@@ -68,14 +69,14 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Search ranks a query that matches a whole title, or an identifier in backticks, above words in body text. Title each section with the task a reader searches for.',
+          text: 'In a topic with more than one section, search ranks a section whose title matches the query, or that names it in backticks, above words in body text. Title each section with the task a reader searches for.',
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
             'Name the task in the words a reader types, such as "Deploy to production". Avoid titles such as "Overview" or "Details".',
-            'Write field names, file names, and error codes in backticks, such as `deployTarget`: search treats each one as a keyword.',
+            'Write field names, file names, and error codes in backticks, such as `deployTarget`: in a topic with more than one section, search treats each one as a keyword.',
             'Other words in the summary and body match too, but rank below titles and identifiers. The summary shows under each hit, so make it answer the query.',
           ],
         },
@@ -92,7 +93,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx search "place a doc" --type doc',
+          code: 'astryx search "place a doc" --type doc',
         },
         {
           type: 'list',

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 authoring/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 authoring/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 authoring/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 authoring/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 authoring/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:field-reference}, 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 authoring/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-grading-rubric.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/template-grading-rubric`:
+ * @file `astryx docs authoring/templates/template-grading-rubric`:
  * complete scoring rules for page and block template quality.
  */
 
@@ -102,7 +102,11 @@ const gradeRows = TEMPLATE_RUBRIC.grades.map(({grade, min, max, meaning}) => [
 export const docs = {
   type: 'generic',
   name: 'template-grading-rubric',
-  placement: {parent: 'namespace:write-good-templates', slot: 'guides', order: 10},
+  placement: {
+    parent: 'namespace:write-good-templates',
+    slot: 'guides',
+    order: 10,
+  },
   title: 'Full grading rubric',
   category: 'guide',
   description:
@@ -112,6 +116,10 @@ export const docs = {
       id: 'understand-the-score',
       title: 'Understand the score',
       content: [
+        {
+          type: 'prose',
+          text: 'Start with {@link generic:is-my-code-good}: it owns the shared Astryx quality criteria. This rubric adds template weights, counting rules, and template-only checks, and each category that scores a shared criterion names it.',
+        },
         {
           type: 'prose',
           text: `Template rubric ${TEMPLATE_RUBRIC.version} scores seven categories for 100 points. Aim for 100; ${TEMPLATE_RUBRIC.minimumGrade} (${TEMPLATE_RUBRIC.minimumScore}) is the publication floor, not the target. Each category below lists its weight. Never award points for anything you did not inspect.`,
@@ -137,11 +145,11 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Count every JSX opening tag in the copied `.tsx` source. An Astryx element is a component imported from `@astryxdesign/core` or from a public component export of the integration package. A raw HTML element is any lowercase intrinsic JSX tag. Count occurrences, not only unique tag names.',
+          text: 'This category scores the Astryx components criterion in {@link generic:is-my-code-good}. Count every JSX opening tag in the copied `.tsx` source. An Astryx element is a component imported from `@astryxdesign/core` or from a public component export of the integration package. A raw HTML element is any lowercase intrinsic JSX tag. Count occurrences, not only unique tag names.',
         },
         {
           type: 'prose',
-          text: 'Do not count fragments or a PascalCase helper defined in the same file. Inspect that helper and count the raw HTML inside it. For each raw element, decide whether it is necessary because Astryx has no equivalent, or unnecessary because an Astryx component can replace it.',
+          text: 'Do not count fragments or a PascalCase helper defined in the same file. Inspect that helper and count the raw HTML inside it. For each raw element, decide with that guide whether it is necessary because Astryx has no equivalent, or unnecessary because an Astryx component can replace it.',
         },
         {
           type: 'table',
@@ -156,35 +164,6 @@ export const docs = {
             ['21 or more', '0'],
           ],
         },
-        {
-          type: 'table',
-          headers: ['Raw HTML use', 'Astryx replacement'],
-          rows: [
-            [
-              '`div` for layout',
-              '`VStack`, `HStack`, `Card`, `Section`, or `Center`',
-            ],
-            ['`div` for a grid', '`Grid`'],
-            ['`span` or `p` for text', '`Text`'],
-            ['`h1` through `h6`', '`Heading level={N}`'],
-            ['`button`', '`Button` or `IconButton`'],
-            ['`a`', '`Link`'],
-            ['In-page `nav` or `aside`', '`LayoutPanel` in the start slot'],
-            [
-              '`header` or `main`',
-              '`LayoutHeader` or `LayoutContent` in `Layout`',
-            ],
-            ['`ul`, `ol`, or `li`', '`List` and `ListItem`'],
-            [
-              '`input`, `textarea`, or `select`',
-              'The matching Astryx form control',
-            ],
-            ['`table`, `tr`, or `td`', '`Table`'],
-            ['`hr`', '`Divider`'],
-            ['`dialog`', '`Dialog`'],
-            ['`details` or `summary`', '`Collapsible`'],
-          ],
-        },
         {
           type: 'list',
           style: 'unordered',
@@ -202,7 +181,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Count raw icon markup in the copied file. {@link generic:template-icons} shows how to render icons through Astryx instead.',
+          text: 'This category scores the Icons criterion in {@link generic:is-my-code-good}. Count raw icon markup in the copied file. {@link generic:template-icons} shows how to render icons through Astryx instead.',
         },
         {
           type: 'list',
@@ -231,7 +210,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Prefer Astryx component props and design tokens. Count individual CSS properties inside `stylex.create` and inline `style` objects. Count each `className` and `stylex.props` use once. Do not count Astryx props such as `gap`, `padding`, `variant`, `size`, `color`, `level`, `columns`, `contentPadding`, or `height`.',
+          text: 'This category scores the Styling criterion in {@link generic:is-my-code-good}. Count individual CSS properties inside `stylex.create` and inline `style` objects. Count each `className` and `stylex.props` use once. Do not count Astryx props such as `gap`, `padding`, `variant`, `size`, `color`, `level`, `columns`, `contentPadding`, or `height`.',
         },
         {
           type: 'table',
@@ -260,7 +239,7 @@ export const docs = {
           type: 'list',
           style: 'ordered',
           items: [
-            'Use `Layout` or `Center` as the page root. A template whose category starts with `Shell -` uses `AppShell` because global chrome is its purpose.',
+            'Choose the page root with the Layout criterion in {@link generic:is-my-code-good}. In a template, only a category that starts with `Shell -` owns global chrome, so it uses `AppShell`; every other page template uses `Layout` or `Center`.',
             'Outside a `Shell -` template, leave global navigation to the host app. Put in-page navigation in a `LayoutPanel` and page headings in `LayoutHeader`.',
             'Use `Grid` with `columns={{minWidth: 280}}` for responsive collections. Do not fix the column count or rebuild the grid in raw CSS.',
             'Use `Center` for centered content instead of custom flexbox workarounds.',
@@ -385,7 +364,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Inspect every image reference in the copied file against {@link generic:template-images-media}.',
+          text: 'This category scores the Images and assets criterion in {@link generic:is-my-code-good}. Inspect every image reference in the copied file against {@link generic:template-images-media}.',
         },
         {
           type: 'table',
@@ -413,7 +392,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Award 2 points for each condition. Grade the copied file, not only the package source.',
+          text: 'This category scores the Code health criterion in {@link generic:is-my-code-good}, plus conditions only a template has. Award 2 points for each condition. Grade the copied file, not only the package source.',
         },
         {
           type: 'table',

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 authoring/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 authoring/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 authoring/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 authoring/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 authoring/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 authoring/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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/themes`: author a theme
+ * @file `astryx docs authoring/building-blocks/themes`: author a theme
  * in an integration; apps install, apply, and extend it like any theme.
  */
 
@@ -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.',