@astryxdesign/cli 0.7.2-canary.e26723d → 0.7.2-canary.e4bdd70

package/assets/docs/tree/sections-and-placement.doc.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/sections-and-placement`: give an
- * integration package its own section in the docs tree, place guides in it,
- * and fix a placement that fails.
+ * @file `astryx docs cli/integrations/building-blocks/docs/sections-and-placement`:
+ * give an integration package its own section in the docs tree, place guides
+ * in it, and fix a placement that fails.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -62,9 +62,7 @@ export const docs = {
           type: 'list',
           style: 'unordered',
           items: [
-            "`parent` is `namespace:<name>`, a namespace that your own package ships. You cannot place a doc in the CLI's sections or in another package's.",
-            "`slot` is a slot that the namespace declares for the doc's kind. You can leave it out when the namespace has only one slot.",
-            '`order` is an integer that sorts the guides in the slot and sets their Previous and Next moves. Guides without one come last, by name.',
+            'Every field is in {@link schema:authored-doc-graph-fields}.',
             'A placed guide opens only by its route, `acme/deploying`. Its bare name no longer opens it.',
           ],
         },

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/see-it-in-an-app`: inspect an
+ * @file `astryx docs cli/integrations/building-blocks/components/see-it-in-an-app`: inspect an
  * integration component from an app that installs the package.
  */
 
@@ -33,7 +33,9 @@ npx astryx search carousel`,
         {
           type: 'code',
           lang: 'text',
-          code: `# AcmeCarousel
+          code: `package: @acme/astryx-widgets
+
+# AcmeCarousel
 
 Cycles through slides one at a time. Use it for a small set of related cards.
 

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 cli/integrations/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} */
@@ -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.',
           ],
         },

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.
  */
 
@@ -61,9 +61,8 @@ export default {
           ],
         },
         {
-          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: 'npx astryx search "rotating cards" --type component',
+        },
       ],
     },
     {

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} */

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

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.
  */
 

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.
  */
 
@@ -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`'],
             [

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.
  */

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.
  */
@@ -103,11 +103,11 @@ export const docs = {
             ],
             [
               '`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.',
             ],
           ],
         },
@@ -151,7 +151,7 @@ export const docs = {
             ],
             [
               '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: 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 checks the app's CLI against it when the app installs your package.",
             ],
           ],
         },

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 cli/integrations/ship/upgrading`: update an integration
  * package for each Astryx release, and the command apps run to upgrade with
  * it.
  */
@@ -57,7 +57,7 @@ export const docs = {
         {
           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

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

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 cli/integrations/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.
  */

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 cli/integrations/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.
  */
@@ -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`',
             ],
           ],
         },
@@ -136,10 +136,10 @@ 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.',
           ],
         },

package/assets/docs/tree/write-the-template-file.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/write-the-template-file`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/write-the-template-file`:
  * what gets copied, where the copied file lands, and the imports and
  * export a copied template needs.
  */
@@ -145,7 +145,7 @@ export default function AcmeAccountSummary() {
           type: 'list',
           style: 'unordered',
           items: [
-            'Add `use client` as the first statement only when hooks, event handlers, or browser APIs need a client boundary.',
+            'Add `use client` as the first statement only when hooks, event handlers, browser APIs, or a component passed as a prop, such as `icon={BellIcon}`, need a client boundary.',
             'Keep a static template server-compatible when it needs no client behavior.',
           ],
         },

package/authoring/codemod/codemod.doc.mjs

@@ -17,7 +17,8 @@ export const doc = {
     'A codemod module the CLI runs during `astryx upgrade`. Default-export a ' +
     "plain object with a `type` discriminant: 'code' rewrites source files, " +
     "'config' rewrites the astryx.config.* file. There is no factory to call.",
-  appliesTo: 'the codemods/ dir of an integration',
+  appliesTo:
+    '`<codemods>/<version>/<id>.{ts,mjs,js}` in an integration package: `<codemods>` is the codemods root of astryx.integration.*, and `<version>` is the exact @astryxdesign/core version (such as 0.7.0) whose upgrade runs the codemod. A file directly in the root never runs.',
   fields: [
     {
       name: 'title',
@@ -44,6 +45,7 @@ export const doc = {
       description:
         'File extensions this codemod applies to. Code codemods only; a ' +
         'config codemod always targets astryx.config.*.',
+      default: "['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs']",
       example: "['.tsx', '.ts']",
     },
     {
@@ -58,6 +60,7 @@ export const doc = {
           name: 'file',
           type: 'AstryxCodemodFile',
           description: 'The source file presented to the transform.',
+          required: true,
           fields: [
             {
               name: 'file.path',
@@ -77,6 +80,7 @@ export const doc = {
           name: 'api',
           type: 'AstryxCodemodApi',
           description: 'Helpers and context passed as the second argument.',
+          required: true,
           fields: [
             {
               name: 'api.jscodeshift',
@@ -89,14 +93,14 @@ export const doc = {
               name: 'api.stats',
               type: '(...args: unknown[]) => void',
               description:
-                'Report a statistic (no-op-friendly; provided for jscodeshift parity).',
+                'Accepted for jscodeshift parity. A call does nothing, and upgrade shows nothing for it.',
               required: true,
             },
             {
               name: 'api.report',
               type: '(...args: unknown[]) => void',
               description:
-                'Report progress (no-op-friendly; provided for jscodeshift parity).',
+                'Accepted for jscodeshift parity. A call does nothing, and upgrade shows nothing for it.',
               required: true,
             },
           ],