@astryxdesign/cli 0.7.2-canary.f16dc9f → 0.7.2-canary.f2b60a0

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

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

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

@@ -50,7 +50,7 @@ export default {
         },
         {
           type: 'prose',
-          text: 'Keep the section short: how to install the package, run `theme add`, apply the generated module ({@link generic:use-a-theme-in-an-app}), and customize with `extends`. When the theme uses a custom font, name the families and the optional exported font stylesheet that `theme add` imports ({@link generic:fonts-and-assets}). Extend `theme` rather than a topic another package replaces, or an app that lists that package first drops your section.',
+          text: 'Keep the section short: how to install the package, run `theme add`, apply the generated module ({@link generic:use-a-theme-in-an-app}), and customize with `extends`. When the theme uses a custom font, name the families and the optional exported font stylesheet that `theme add` imports ({@link generic:fonts-and-assets}). Extend `theme` rather than a topic another package replaces, or an app that loads that package after yours drops your section.',
         },
       ],
     },

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

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

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

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/extend-or-replace`: take over an
- * existing topic with `replaces`, merge sections into one with `extends`, and
- * check overlaps with Core topics.
+ * @file `astryx docs cli/integrations/building-blocks/docs/extend-or-replace`:
+ * take over an existing topic with `replaces`, merge sections into one with
+ * `extends`, and check overlaps with Core topics.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -46,7 +46,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Set `extends` to merge sections into an existing topic instead of owning it. A section with the same key replaces the base section, and a new section is added at the end.',
+          text: 'Set `extends` to merge sections into an existing topic instead of owning it. A section replaces the base section it matches, and a section that matches none is added at the end.',
         },
         {
           type: 'code',
@@ -63,7 +63,7 @@ export const docs = {
           type: 'list',
           style: 'unordered',
           items: [
-            "A section's key is its `id`, or a key made from its title. Read the base topic's keys with `--index`.",
+            "Read the base topic's keys with `--index`, and give a section that replaces one that key as its `id`. A section without an `id` matches only a base section with exactly its title, or one whose `id` is the key its title makes, so `Integration Themes` is added beside a base `Integration themes` that has no `id`.",
             "The topic keeps the base's title and description, and readers open it by the base's name.",
             'Replace the `Overview` placeholder that `integration add` writes, or it is added to the base topic.',
             "Extend a topic to correct or add to it. A copy made with `replaces` stops getting the owner's fixes.",
@@ -87,7 +87,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'text',
-          code: 'severity:     [info]\ntopic:        acme-getting-started\nrelationship: replaces\ncoreTopic:    getting-started\nmessage:      Intentional override: "acme-getting-started" replaces the Core topic "getting-started".\n\nseverity:     [fail]\ntopic:        tokens\nrelationship: accidental\ncoreTopic:    tokens\nmessage:      Accidental conflict: "tokens" is already a Core topic. Rename it, declare replaces: \'tokens\' to take it over, or declare extends: \'tokens\' to merge sections.',
+          code: 'severity:     [info]\ntopic:        acme-getting-started\nrelationship: replaces\ncoreTopic:    getting-started\nmessage:      Intentional override: "acme-getting-started" replaces the Core topic "getting-started".\n\nseverity:     [fail]\ntopic:        color\nrelationship: accidental\ncoreTopic:    color\nmessage:      Accidental conflict: "color" is already a Core topic. Rename it, declare replaces: \'color\' to take it over, or declare extends: \'color\' to merge sections.',
         },
         {
           type: 'list',

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

@@ -61,7 +61,7 @@ export const oceanTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'The stylesheet can contain self-hosted `@font-face` rules or import a hosted stylesheet. A hosted `@import` is simple, but it delays loading compared with a preconnected `<link>`; choose that trade-off deliberately. If the app loads the same family outside the generated module, Doctor warns because it cannot prove the loader, but the warning does not fail the app.',
+          text: 'The stylesheet can contain self-hosted `@font-face` rules or import a hosted stylesheet. A hosted `@import` is simple, but it delays loading compared with a preconnected `<link>`; choose that trade-off deliberately. Doctor warns when it cannot prove the loader — a hosted `@import`, or no font stylesheet while the app loads the family itself — but the warning does not fail the app.',
         },
         {
           type: 'code',
@@ -83,7 +83,7 @@ export const oceanTheme = defineTheme({
             'Load every weight and style the theme uses. Do not let the browser synthesize bold or italic.',
             'Include self-hosted font files and their licenses in the packed package.',
             'Keep CSS and font assets side-effectful so a bundler does not remove the loader.',
-            'Run `integration verify`; it fails when an exported font stylesheet or one of its packed files cannot resolve.',
+            'Run `integration verify`; it fails when an exported font stylesheet cannot resolve, but it does not check the font files the stylesheet names.',
           ],
         },
       ],

package/assets/docs/tree/generate-a-palette.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'A theme needs dozens of related colors — shades of each brand color for backgrounds, borders, text, and states, in both light and dark mode. A palette is that full set of shades. Rather than hand-pick every one, you name a few seed colors and generate the rest, so the shades stay consistent and keep enough contrast to read.',
+          text: 'A theme needs dozens of related colors — shades of each brand color for backgrounds, borders, text, and states, in both light and dark mode. A palette is that full set of shades. Rather than hand-pick every one, you name a few seed colors and generate the rest, so the shades stay consistent.',
         },
         {
           type: 'prose',
@@ -50,7 +50,9 @@ npx astryx theme palette generate themes/ocean/palette.config.json \\
           lang: 'text',
           code: `[ok] Wrote themes/ocean/tokens/ocean.palette.ts
 
-[ok] Wrote themes/ocean/tokens/ocean.palette.receipt.json`,
+[ok] Wrote themes/ocean/tokens/ocean.palette.receipt.json
+
+Review and edit the candidate before adopting it as theme-owned palette data.`,
         },
         {
           type: 'prose',
@@ -58,7 +60,7 @@ npx astryx theme palette generate themes/ocean/palette.config.json \\
         },
         {
           type: 'prose',
-          text: 'Add `--preview <file>.html` to also get a web page showing every shade, so you can eyeball the palette in a browser. Write it outside `themes/` so it does not ship in your package. The full list of config fields and options is in {@link command:theme palette generate}.',
+          text: 'Add `--preview <file>.html` to also get a web page showing every shade, so you can eyeball the palette in a browser. Write it outside `themes/` so it does not ship in your package. Every option is in {@link command:theme palette generate}, and the config it reads is described in {@link function:generateTonalPalette}.',
         },
       ],
     },

package/assets/docs/tree/grade-template-with-agent.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/templates/grade-template-with-agent`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/write-good-templates/grade-template-with-agent`:
  * give an agent the canonical rubric and require a reproducible template grade.
  */
 

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

@@ -36,5 +36,13 @@ export const docs = {
       type: 'prose',
       text: 'An integration can also replace a built-in template or doc. To start, install `@astryxdesign/cli` and open {@link generic:quick-start}.',
     },
+    {
+      type: 'prose',
+      text: 'Every field of every file you write for an integration is in {@link generic:authoring}.',
+    },
+    {
+      type: 'prose',
+      text: "Every integration runs `astryx integration check --strict` in its own build: it is required, not optional, so a doc, prop, or link that stops matching the code fails your build instead of your users' apps. See {@link generic:checks}.",
+    },
   ],
 };

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

@@ -1,8 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs/links`: link one doc to another by
- * identity, link the CLI's docs, and fix a link that names no doc.
+ * @file `astryx docs cli/integrations/building-blocks/docs/links`: link one doc
+ * to another by identity, link the CLI's docs, and fix a link that names no
+ * doc.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -36,8 +37,8 @@ export const docs = {
           type: 'list',
           style: 'unordered',
           items: [
-            'The kind is `generic` for a topic or guide, `namespace` for a docs section, and `command` or `function` for a CLI command or API function.',
-            'A link to a component or a template does not resolve. Write its name in backticks instead, such as `AcmeCarousel`.',
+            'The kind is `generic` for a topic or guide, `namespace` for a docs section, `command` or `function` for a CLI command or API function, `schema` or `enum` for a schema or a fixed set of values, `component` for a component, and `page` or `block` for a template.',
+            'Name a component by its export name and a template by its id. Its link reads as the command that opens it, such as `astryx component AcmeCarousel --package @acme/widgets`.',
             'Inside backticks or a code block, link syntax prints as written.',
           ],
         },
@@ -89,7 +90,7 @@ export const docs = {
           style: 'unordered',
           items: [
             'The warning keeps exit code 0, so read the report before you ship; see {@link generic:check-your-docs}.',
-            'A stable CLI before 0.7.0 does not read links: it prints each one as written. See {@link generic:versioning}.',
+            'Published 0.6.4 and later read links. An older CLI, such as published 0.6.3, prints each one as written; see {@link generic:versioning}.',
           ],
         },
       ],

package/assets/docs/tree/migration-setup.doc.mjs

@@ -21,6 +21,7 @@ export const docs = {
     'reset',
     'smoke test',
     'layer audit',
+    'cascade layers',
     'Tailwind coexistence',
   ],
 

package/assets/docs/tree/migration-verification.doc.mjs

@@ -19,7 +19,6 @@ export const docs = {
     'verification',
     'checklist',
     'AI prompt',
-    'keyboard navigation',
   ],
 
   sections: [

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

@@ -19,7 +19,6 @@ export const docs = {
     'Tailwind',
     'shadcn',
     'Radix',
-    'cascade layers',
     'coexistence',
   ],
   slots: {

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/package-and-test`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test`:
  * expose a template from its package and prove the copied result in an app.
  */
 

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/document-the-template/page-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/page-template`:
  * the page-only fields that help people find a page.
  */
 
@@ -31,7 +31,7 @@ export const docs = {
           type: 'code',
           lang: 'javascript',
           label: 'templates/acme-dashboard.doc.mjs',
-          code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+          code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
 export default {
   type: 'page',
   name: 'acme-dashboard',
@@ -49,12 +49,8 @@ export default {
       title: 'Help people find the page',
       content: [
         {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {
-            fields: ['category', 'scaffold'],
-          },
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:template-doc}.',
         },
         {
           type: 'list',

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/publishing`: publish an integration to
+ * @file `astryx docs cli/integrations/ship/publishing`: publish an integration to
  * npm, use release tags, and check the package before and after.
  */
 

package/assets/docs/tree/quick-start.doc.mjs

@@ -34,20 +34,22 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, then install the Astryx CLI and Core for development.',
+          text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, make it an ES module, then install the Astryx CLI, Core, and TypeScript for development.',
         },
         {
           type: 'code',
           lang: 'bash',
-          code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core",
+          code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets type=module\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core typescript@6",
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
+            'Set `"type": "module"`: the `.js` files the CLI generates, such as a built theme, are ES modules, and Node fails to load them in a package marked `"type": "commonjs"`, which `npm init -y` writes on npm 11.',
             'Start with `"exports": {}`: each component and template you add then writes the public import that `integration verify` resolves.',
             'Run the CLI as `npx astryx`, which runs the `@astryxdesign/cli` you installed as a devDependency.',
             'Component commands read Core, so they need `@astryxdesign/core` installed.',
+            "The checks compare your docs with your code through TypeScript's JavaScript compiler API, so they need `typescript` 5.0 through 6 installed. TypeScript 7 does not ship that API, and with it the checks skip those comparisons.",
           ],
         },
         {
@@ -86,6 +88,33 @@ export const docs = {
           type: 'prose',
           text: 'You now have an integration package with one exported component.',
         },
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Check it in every build (required)',
+        },
+        {
+          type: 'prose',
+          text: 'Every integration runs `integration check --strict` in its own build, so a doc, prop, template, or link that stops matching the code fails your build instead of reaching the apps that install your package. Set it up now, as the `typecheck` script, and run it.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm pkg set scripts.typecheck="astryx integration check --strict"\nnpm run typecheck',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: '[ok] 0 errors, 0 warnings, 0 skipped. Every check passed.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Run `typecheck` in CI and before every publish. When you add a `tsconfig.json`, put `tsc --noEmit && ` in front of the check so the same script checks your types.',
+            'What each check covers, and what `--strict` adds: {@link generic:checks}.',
+          ],
+        },
         {
           type: 'heading',
           level: 3,
@@ -172,19 +201,19 @@ export const docs = {
             ],
             [
               '`peerDependencies`',
-              '`@astryxdesign/cli`; add `@astryxdesign/core` when your code imports it',
+              '`@astryxdesign/core` when your code imports it; `@astryxdesign/cli`, optional, when you ship a feature that needs a newer CLI ({@link generic:versioning})',
               'The app supplies these packages for your integration.',
             ],
             [
               '`devDependencies`',
-              '`@astryxdesign/cli` and `@astryxdesign/core`',
-              'Lets you run the CLI and build components while working on the integration.',
+              '`@astryxdesign/cli`, `@astryxdesign/core`, and `typescript`',
+              'Lets you run the CLI, build components, and run the checks while working on the integration.',
             ],
           ],
         },
         {
           type: 'prose',
-          text: 'Peer ranges and releases are covered in {@link generic:versioning}; `files` and publishing in {@link generic:publishing}.',
+          text: 'Peer ranges and releases are covered in {@link generic:versioning}; `files` and publishing in {@link generic:publishing}. Add `"typecheck": "tsc --noEmit && astryx integration check --strict"` to `scripts` so each run checks your types and that your docs, props, and links still match the code. It needs `typescript` and a `tsconfig.json`; see {@link generic:checks}.',
         },
       ],
     },
@@ -226,21 +255,8 @@ export const docs = {
           text: 'The file tells the CLI where this package keeps its integration items. Edit it only when you want a custom root or another optional setting. Paths are relative to package.json, and later adds keep a custom path you already set.',
         },
         {
-          type: 'reference',
-          target: 'schema:integration',
-          projection: {
-            fields: [
-              'providerId',
-              'components',
-              'templates',
-              'codemods',
-              'docs',
-              'themes',
-              'agentDocs',
-              'issuesUrl',
-            ],
-          },
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:integration}.',
         },
         {
           type: 'heading',

package/assets/docs/tree/replace-a-core-component.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/replace-a-core-component`:
+ * @file `astryx docs cli/integrations/building-blocks/components/replace-a-core-component`:
  * intentionally make an integration component the default for a Core identity.
  */
 
@@ -65,10 +65,8 @@ export default {
 };`,
         },
         {
-          type: 'reference',
-          target: 'schema:component-doc',
-          projection: {fields: ['replaces']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:component-doc}.',
         },
         {
           type: 'prose',
@@ -87,7 +85,7 @@ export default {
           type: 'list',
           style: 'unordered',
           items: [
-            'Any `@astryxdesign/cli` range that starts at that release or later turns it on, including the `>=0.7.0` that earlier `integration add theme` and `integration add doc --parent` wrote.',
+            'Any `@astryxdesign/cli` range that starts at that release or later turns it on, including the `>=0.7.0` that `integration add doc --parent` wrote in published 0.6.4 and 0.6.5, and `integration add theme` in published 0.6.5.',
             'Without such a range, the component keeps its own name, the Core component stays selected (a component named like its target stays ambiguous by that bare name, as before), and `doctor integration components` warns with the range to add. Apps that load such a package see no change.',
             '`replaces` names the Core `ComponentDoc` identity, not its display label, import path, or a standalone hook.',
             'Your component may keep a distinct name or use the same name as the target. A distinct name remains directly addressable on older CLIs that ignore `replaces`.',

package/assets/docs/tree/replace-a-core-template.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/document-the-template/replace-a-core-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/replace-a-core-template`:
  * deliberately replace one Core template through template metadata.
  */
 
@@ -54,7 +54,7 @@ export const docs = {
           type: 'code',
           lang: 'javascript',
           label: 'templates/acme-app-shell.doc.mjs',
-          code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+          code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
 export default {
   type: 'page',
   name: 'acme-app-shell',
@@ -67,10 +67,8 @@ export default {
 };`,
         },
         {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {fields: ['replaces']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:template-doc}.',
         },
         {
           type: 'prose',
@@ -84,7 +82,7 @@ export default {
       content: [
         {
           type: 'prose',
-          text: 'Declare the CLI floor from the field above as an optional peer ({@link generic:versioning}).',
+          text: 'Declare the CLI floor that `integration verify` names as an optional peer ({@link generic:versioning}).',
         },
         {
           type: 'code',
@@ -103,7 +101,7 @@ export default {
         },
         {
           type: 'prose',
-          text: '`integration verify` reports `replaces_needs_cli` when that peer is missing or too old. Without it, an older CLI drops that template and hides your doc topics.',
+          text: '`integration verify` reports `replaces_needs_cli` when that peer is missing or too old. Without it, published 0.6.3 and earlier drop that template and hide your doc topics.',
         },
       ],
     },

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.
  */
 
@@ -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: 'npx 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`.',
+            '`npx 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: 'npx astryx component AcmeCarousel\nnpx astryx doctor integration components\nnpx astryx 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} */