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

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/checks`: what each package check
+ * @file `astryx docs cli/integrations/ship/checks`: what each package check
  * proves, what fails and what only warns, and one command to run them all.
  */
 
@@ -12,7 +12,7 @@ export const docs = {
   placement: {parent: 'namespace:ship', slot: 'guides', order: 20},
   title: 'Check an integration',
   category: 'guide',
-  keywords: ['check before publishing', 'validate an integration', 'ci'],
+  keywords: ['check before publishing', 'validate an integration'],
   description:
     'Pick the check for each problem, learn what fails and what only warns, and run every check in CI.',
   sections: [
@@ -22,7 +22,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Run these in the package folder. The four `doctor integration` checks read your source; `integration verify` checks the package npm would publish.',
+          text: 'Run these in the package folder. The four `doctor integration` checks read your source, and `integration check` runs all four; `integration verify` checks the package npm would publish.',
         },
         {
           type: 'table',
@@ -30,15 +30,15 @@ export const docs = {
           rows: [
             [
               '`npx astryx doctor integration validate`',
-              'The manifest loads, and each root holds contributions the CLI can read',
+              'The manifest loads, each root holds contributions the CLI can read, and each doc matches its authoring type',
               'A declared root is missing (`missing_root`), a contribution does not load (`invalid_doc`, `invalid_component`, `invalid_theme`), or two templates in the package replace one Core id (`ambiguous_template_replacement`)',
-              'The manifest has a key this CLI does not know (`unknown_manifest_key`). With no `astryx.integration.mjs` it prints a hint and exits 0',
+              "The manifest has a key this CLI does not know (`unknown_manifest_key`), or a doc field does not match the doc's authoring type: a field the type does not have, a missing required field, or a value outside the field's type. It checks docs with your installed `typescript`; without it, it prints `[skip] Docs not type-checked`. With no `astryx.integration.mjs` it prints a hint and exits 0",
             ],
             [
               '`npx astryx doctor integration components`',
-              'No component name clashes with a Core component, and each `replaces` names one Core component',
+              "No component name clashes with a Core component, each `replaces` names one Core component, and each component doc's props match the component's TypeScript props",
               'Core is not installed (`core_not_found`). In a package that declares the CLI range that turns replacement on, a `replaces` target is missing (`missing_component_replacement_target`) or invalid (`invalid_component_replacement`), or two components replace one Core component (`ambiguous_component_replacement`)',
-              'A name clashes with Core, or a component sets `replaces` in a package without that range (`inactive_component_replacement`, plus any missing, invalid, or duplicate `replaces` reported as a warning)',
+              'A name clashes with Core, a component sets `replaces` in a package without that range (`inactive_component_replacement`, plus any missing, invalid, or duplicate `replaces` reported as a warning), or a documented prop differs from the code: it is missing there (`not_in_code`), the doc omits a prop the package declares (`not_in_doc`), or its `required` (`required_mismatch`) or type (`type_mismatch`) disagrees. It reads props with your installed `typescript`; without it, it prints `[skip] Props not compared`',
             ],
             [
               '`npx astryx doctor integration templates`',
@@ -52,6 +52,12 @@ export const docs = {
               'A topic takes a Core topic name without `replaces` or `extends`, a doc is invalid (`invalid_doc`), or a namespace or placement fails, which hides the doc (`invalid_doc_graph`)',
               'A link names no doc (`invalid_doc_graph`)',
             ],
+            [
+              '`npx astryx integration check`',
+              'Everything the four `doctor integration` checks prove, in one command, for your build',
+              'Any of the four would exit 1 on its own. With `--strict`, also any warning, and any check that did not run, such as a package with no `astryx.integration.*`',
+              'Anything the four warn about, unless you pass `--strict`',
+            ],
             [
               '`npx astryx integration verify`',
               'The packed package holds every file, shows the same contributions, resolves every public import, and declares the CLI it needs',
@@ -62,29 +68,31 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Pass a package name, such as `npx astryx doctor integration validate @acme/astryx-widgets`, to check an installed copy from an app instead.',
+          text: 'Pass a package name, such as `npx astryx doctor integration validate @acme/astryx-widgets`, to check an installed copy from an app instead. To fix a props finding, see {@link generic:check-the-props}.',
         },
       ],
     },
     {
       id: 'run-every-check-in-ci',
-      title: 'Run every check in CI',
+      title: 'Run every check in every build (required)',
       content: [
         {
           type: 'prose',
-          text: 'Chain the five checks so the first failure stops the run. Install devDependencies first, because the components check needs Core.',
+          text: 'Every integration runs `integration check --strict` in its own build, so every build keeps your docs, types, and links in sync; this is required, not optional. Run `integration verify` before you publish. Install devDependencies first, because the components check needs Core, and `tsc --noEmit` needs `typescript` and a `tsconfig.json`. In package.json:',
         },
         {
           type: 'code',
-          lang: 'bash',
-          code: 'npx astryx doctor integration validate && npx astryx doctor integration components && npx astryx doctor integration templates && npx astryx doctor integration docs && npx astryx integration verify',
+          lang: 'json',
+          code: '"typecheck": "tsc --noEmit && astryx integration check --strict"',
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
-            '`integration verify` runs `validate` but none of the other three: a Core name clash, a `replaces` that names no Core template, a topic that takes a Core name, or a hidden guide still passes it.',
-            'Warnings keep exit code 0, so read them before you publish.',
+            '`integration check` runs `validate`, `components`, `templates`, and `docs` in that order, prints each result, then a summary, and exits 1 when any of them would.',
+            '`--strict` also exits 1 on any warning and on any check that did not run. Without it, warnings keep exit code 0: use that while you fix the warnings a package already has.',
+            'Its exit codes and JSON are a contract for your build: a new check, or a new failure code, joins only in a minor release that names it in the release notes. A patch can still ship a Core component, template, or CLI topic whose name conflicts with one of yours.',
+            '`integration verify` runs `validate` but none of the other three: a Core name clash, a `replaces` that names no Core template, a topic that takes a Core name, or a hidden guide still passes it. Run both before you publish: `npx astryx integration check --strict && npx astryx integration verify`.',
             'Bare `npx astryx doctor` in the package also warns about a doc section over 32 KB, which no check above measures.',
           ],
         },
@@ -105,14 +113,14 @@ export const docs = {
             'It runs `npm pack` the way `npm publish` would, including your `prepack` script.',
             'It checks that every contribution file is in the `.tgz` file. A root missing from `files` fails with `Add "templates" to "files" in package.json.`',
             'It lists the components, templates, themes, docs, and codemods the temporary app sees, and compares them with your source.',
-            "It resolves each component's `import`, and each template's public import, the way Node does, and checks that the module exports the component, or a default export for a template.",
+            "It resolves each component's `import`, and each template's public import, the way Node does, and checks that the module exports the component under the name its doc documents, or a default export for a template. A type-only export does not count.",
             'For each theme, it rebuilds the source, compares the built module and production CSS with the authored outputs, and proves the module, CSS, and optional font CSS exports resolve from the packed package.',
             'It fails a package that needs an `@astryxdesign/cli` peer and lacks it: `>=0.6.6` for a template that sets `keywords`, and `>=0.6.4` for a template that sets `replaces`, a docs section, a placed guide, a doc section with an `id`, or a theme.',
           ],
         },
         {
           type: 'prose',
-          text: '`integration pack --check`, the name this check had in 0.6, still runs it and prints a note; it will be removed in a later release. The options and exit codes are in {@link command:integration verify}.',
+          text: '`integration pack --check`, the name this check had before published 0.6.5, still runs it and prints a note; it will be removed in a later release. The options and exit codes are in {@link command:integration verify}.',
         },
       ],
     },

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/codemods`: add codemods to an
+ * @file `astryx docs cli/integrations/building-blocks/codemods`: add codemods to an
  * integration package, and know which of them `astryx upgrade` runs in an app.
  */
 
@@ -82,7 +82,7 @@ export default {
         },
         {
           type: 'prose',
-          text: "`type: 'code'` rewrites the app's source files that match `fileExtensions`. `type: 'config'` rewrites the app's `astryx.config` file instead, and runs before code codemods. `title` shows in the upgrade output, and `api.jscodeshift` is a jscodeshift instance for the file. Every field is in {@link generic:authoring}.",
+          text: "`type: 'code'` rewrites the app's source files that match `fileExtensions`. `type: 'config'` rewrites the app's `astryx.config` file instead, and runs before code codemods. `title` shows in the upgrade output, and `api.jscodeshift` is a jscodeshift instance for the file. Every field is in {@link schema:codemod}.",
         },
       ],
     },
@@ -124,14 +124,14 @@ npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply`,
           type: 'code',
           lang: 'text',
           code: `Integrations: @acme/astryx-widgets
-1 codemod to run (dry run)
+<n> codemods to run (dry run)
 Applying integration codemods...
   Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)
 !     ~ src/Hero.tsx (would change)`,
         },
         {
           type: 'prose',
-          text: "The count includes Core's codemods for the same versions, which run first and print above `Integrations:`. To run only yours, as when you test it, add `--codemod rename-delay`.",
+          text: "`<n>` counts Core's codemods for the same versions too: they run first and print above `Integrations:`. To run only yours, as when you test it, add `--codemod rename-delay`.",
         },
         {
           type: 'prose',

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/describe-the-component/component-family`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/component-family`:
  * author one ComponentDoc for several public exports in a component family.
  */
 
@@ -38,10 +38,8 @@ export const docs = {
           ],
         },
         {
-          type: 'reference',
-          target: 'schema:component-doc',
-          projection: {fields: ['components']},
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:component-doc}.',
         },
       ],
     },
@@ -95,7 +93,11 @@ export default {
         },
         {
           type: 'prose',
-          text: 'The public module named by `import` must export every component or hook named by a full entry.',
+          text: "The public module named by `import` must export every component or hook named by a full entry. Apps then list, search and open each component in the family by its own name. A full entry the module does not export is not listed, and `integration verify` does not report it: check the family with `astryx component --list`. When `import` names output your pack lifecycle builds (such as `dist`), the members are listed once that output exists, and `integration verify` compares them as they are listed after the pack builds it.",
+        },
+        {
+          type: 'prose',
+          text: "A member's source is the `.tsx` file in the family doc's folder, or below it, that declares it: the one the family's own file or the module `import` names reaches, else the one in that folder that declares the name, as when `import` names built output. A member that only a bundle or a file outside that folder declares is still listed, with no source for `--source` or `swizzle`. A member is not listed when a doc's file or a Core name your package replaces already has its name. A member that shares a name with Core opens with `--package`.",
         },
       ],
     },

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/component-imports`: make an
+ * @file `astryx docs cli/integrations/building-blocks/components/component-imports`: make an
  * integration component's documented import resolve from the packed package.
  */
 
@@ -37,7 +37,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'A file does not have to be named after its component. When `Slides.tsx` exports `AcmeCarousel` and nothing named `Slides`, keep the doc beside it as `Slides.doc.mjs` and set its `name` to `AcmeCarousel`: apps list, search and open the component by that name, and `integration verify` checks that its import exports `AcmeCarousel`. A file that exports its own name keeps that name.',
+          text: 'A file does not have to be named after its component. When `Slides.tsx` exports `AcmeCarousel` and nothing named `Slides`, keep the doc beside it as `Slides.doc.mjs` and set its `name` to `AcmeCarousel`: apps list, search and open the component by that name, and `integration verify` checks that its import exports `AcmeCarousel`. A file that exports its own name keeps that name. A package that names its files in kebab case works the same way: `acme-gallery.doc.mjs` beside `acme-gallery.tsx` sets `name: \'AcmeGallery\'`.',
         },
         {
           type: 'prose',
@@ -51,7 +51,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: '`integration verify` installs the packed package in a temporary app, resolves each documented import, and checks that the module exports the documented component name.',
+          text: '`integration verify` unpacks the packed package into a temporary app, resolves each documented import, and checks that the module exports the documented component name. Its `--json` output names each failure by code.',
         },
         {
           type: 'code',

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components`: guides for adding and
+ * @file `astryx docs cli/integrations/building-blocks/components`: guides for adding and
  * documenting components in an integration package.
  */
 

package/assets/docs/tree/debug-and-gap-reports.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/debug-and-gap-reports`: receive a record
+ * @file `astryx docs cli/integrations/building-blocks/configuration/debug-and-gap-reports`: receive a record
  * of each CLI run with `debug`, and handle `astryx gap-report` with
  * `gapReport`, both named exports of the integration manifest.
  */
@@ -44,7 +44,7 @@ export default {
         },
         {
           type: 'prose',
-          text: 'The event is a `DebugEvent` with `command`, `outcome`, `exitCode`, `durationMs`, `error`, and more, its values scrubbed (`redacted: true`). Every field is in {@link generic:authoring}.',
+          text: 'The event is a `DebugEvent` with `command`, `outcome`, `exitCode`, `durationMs`, `error`, and more, its values scrubbed (`redacted: true`). Every field is in {@link schema:debug-event}.',
         },
         {
           type: 'prose',
@@ -104,22 +104,11 @@ export const gapReport = {
         },
         {
           type: 'prose',
-          text: 'Every handler in the app gets every report, so check `report.target.package` and skip reports about other packages. The receipt `status` is one of:',
-        },
-        {
-          type: 'table',
-          headers: ['`status`', 'Meaning'],
-          rows: [
-            [
-              '`filed`',
-              'You created or queued the report. Return `url` or `message`.',
-            ],
-            [
-              '`routed_only`',
-              'You point the caller to where to file it. `url` is required.',
-            ],
-            ['`skipped`', 'You chose not to act, for example on a duplicate.'],
-          ],
+          text: 'Every handler in the app gets every report, so check `report.target.package` and skip reports about other packages.',
+        },
+        {
+          type: 'prose',
+          text: 'Every field is in {@link schema:gap-report-handler}.',
         },
         {
           type: 'prose',

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

@@ -45,7 +45,7 @@ export const oceanTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'Local imports must stay inside the theme folder. One that leaves it, such as `../../shared/colors`, fails with `invalid_theme`, and the theme disappears from `theme list`. `npx astryx theme template` writes a file that explains every `defineTheme` field. For the full token set, scope selectors, and component theming, read {@link generic:author-a-theme}.',
+          text: 'Local imports must stay inside the theme folder. One that leaves it, such as `../../shared/colors`, fails with `invalid_theme`, and every theme in the package disappears from `theme list`. `npx astryx theme template` writes a file that explains every `defineTheme` field. For the full token set and component theming, read {@link generic:author-a-theme}.',
         },
       ],
     },
@@ -55,13 +55,14 @@ export const oceanTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'To base a theme on an existing one, `extends` it: import the base theme and override only the tokens you change. The derived theme keeps a live link to the base and inherits its later changes — unlike `--from`, which forks a copy ({@link generic:add-a-theme}).',
+          text: 'To base a theme on an existing one, `extends` it: import the base theme and override only the tokens you change. Add the derived theme with `integration add theme ocean-contrast`, and import the base from its built package export, since local imports cannot leave the theme folder. The derived theme keeps a live link to the base and picks up its later changes when you rebuild it — unlike `--from`, which forks a copy ({@link generic:add-a-theme}).',
         },
         {
           type: 'code',
           lang: 'ts',
-          code: `import {defineTheme} from '@astryxdesign/core/theme';
-import {oceanTheme} from './oceanTheme';
+          code: `// themes/ocean-contrast/oceanContrastTheme.ts
+import {defineTheme} from '@astryxdesign/core/theme';
+import {oceanTheme} from '@acme/astryx-widgets/themes/ocean';
 
 export const oceanContrastTheme = defineTheme({
   name: 'ocean-contrast',
@@ -79,7 +80,7 @@ export const oceanContrastTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'Each `[light, dark]` pair compiles to a `light-dark()` value, which switches only colors. Give it colors. For a value that is not a plain color — a gradient — put `light-dark()` on each color stop, not around the whole value: a browser without `light-dark()` drops the declaration, and the stop form is the one that degrades safely.',
+          text: 'Each `[light, dark]` pair compiles to a `light-dark()` value, which switches only colors. Give it colors. For a value that is not a plain color — a gradient — put `light-dark()` on each color stop, not around the whole value: `light-dark()` takes two colors, so wrapping whole gradients makes the value invalid where the token is used, and `theme build` does not warn.',
         },
       ],
     },

package/assets/docs/tree/describe-the-component.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/components/describe-the-component`:
+ * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component`:
  * choose and maintain the ComponentDoc shape that matches a component's public
  * source.
  */
@@ -37,7 +37,7 @@ export const docs = {
       items: [
         'Change the source and its `.doc.mjs` together.',
         'Update the doc whenever the public name, import, behavior, props, defaults, examples, or accessibility requirements change.',
-        '`integration verify` checks the doc shape and packed import, but it cannot prove the prose still matches the component.',
+        '`integration verify` checks the doc shape and packed import, and `doctor integration components` compares each props table with the component\'s TypeScript props ({@link generic:check-the-props}). Neither can prove the prose still matches the component.',
       ],
     },
     {

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

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/docs`: the guides to writing docs for an
- * integration package, which join the same docs tree as the CLI's own
- * (spec:AST-046, spec:AST-047).
+ * @file `astryx docs cli/integrations/building-blocks/docs`: the guides to
+ * writing docs for an integration package, which join the same docs tree as
+ * the CLI's own (spec:AST-046, spec:AST-047).
  */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */

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