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

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/building-blocks/templates/document-the-template`:
+ * @file `astryx docs authoring/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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/themes/document-the-theme`:
+ * @file `astryx docs authoring/building-blocks/themes/document-the-theme`:
  * document a theme by extending the core theme topic, not in agent guidance.
  */
 

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/building-blocks/templates/build-the-template/package-and-test/export-template-assets`:
+ * @file `astryx docs authoring/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,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/docs/extend-or-replace`:
+ * @file `astryx docs authoring/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.
  */

package/assets/docs/{authoring.doc.mjs → tree/field-reference.doc.mjs}

@@ -1,14 +1,15 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs authoring`: every authoring schema, one section each.
+ * @file `astryx docs authoring/field-reference`: every authoring schema, one
+ * section each. `astryx docs authoring <name>` reads one of them.
  *
  * Built from the self-docs colocated under packages/cli/authoring, so it cannot
  * drift from the schemas it describes. `astryx doctor` names a self-doc this
- * topic cannot reach.
+ * guide cannot reach.
  */
 
-import {buildAuthoringTopic} from '../../foundation/discovery/authoring-self-docs.mjs';
+import {buildAuthoringTopic} from '../../../foundation/discovery/authoring-self-docs.mjs';
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
 export const docs = await buildAuthoringTopic();

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/themes/fonts-and-assets`:
+ * @file `astryx docs authoring/building-blocks/themes/fonts-and-assets`:
  * ship a theme's optional font loader beside its built module and CSS.
  */
 

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/themes/generate-a-palette`:
+ * @file `astryx docs authoring/building-blocks/themes/generate-a-palette`:
  * turn a few seed colors into a full light and dark color palette.
  */
 

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/global-integrations`: make an
+ * @file `astryx docs authoring/global-integrations`: make an
  * integration work when people install it next to their global Astryx
  * install; a checklist and the commands to try it (spec AST-081 FR12).
  */
@@ -11,7 +11,7 @@ export const docs = {
   type: 'generic',
   name: 'global-integrations',
   placement: {
-    parent: 'namespace:integrations',
+    parent: 'namespace:authoring',
     slot: 'guides',
     order: 25,
   },

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/write-good-templates/grade-template-with-agent`:
+ * @file `astryx docs authoring/building-blocks/templates/write-good-templates/grade-template-with-agent`:
  * give an agent the canonical rubric and require a reproducible template grade.
  */
 
@@ -36,11 +36,11 @@ export const docs = {
           code: `Grade integration template <id> from <package> at <revision>.
 
 Before scoring:
-1. Read \`astryx docs cli/integrations/building-blocks/templates/write-good-templates --full\`.
-2. Read \`astryx docs cli/integrations/building-blocks/templates/write-good-templates/template-grading-rubric --full\` and every guide it links.
+1. Read \`astryx docs authoring/building-blocks/templates/write-good-templates --full\`.
+2. Read \`astryx docs authoring/building-blocks/templates/write-good-templates/template-grading-rubric --full\` and every guide it links.
 3. Inspect the template source, its matching .doc.mjs file, package.json exports and files, and astryx.integration.mjs.
 4. Run \`astryx integration verify\` in the package.
-5. Follow \`astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app --full\`: install the packed package in the clean app, copy the template, build the app, and render the behavior matrix.
+5. Follow \`astryx docs authoring/building-blocks/templates/build-the-template/package-and-test/test-template-in-app --full\`: install the packed package in the clean app, copy the template, build the app, and render the behavior matrix.
 
 Score all seven rubric categories. Cite file and line evidence for every deduction. Do not award points for a state you did not inspect. If browser or build evidence is unavailable, say so and mark the template not publishable.
 

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

@@ -1,12 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @file astryx docs cli/integrations/help — find a CLI message and its fix. */
+/** @file astryx docs authoring/help — find a CLI message and its fix. */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
 export const docs = {
   type: 'namespace',
   name: 'help',
-  placement: {parent: 'namespace:integrations', slot: 'guides', order: 40},
+  placement: {parent: 'namespace:authoring', slot: 'guides', order: 40},
   title: 'Help',
   summary: 'Find a CLI message and how to fix it.',
   keywords: ['help', 'troubleshooting', 'error'],

package/assets/docs/tree/host-entry.doc.mjs

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/host-entry`: run the CLI from a tool that carries it,
+ * through `@astryxdesign/cli/host` (spec AST-081 FR1,
+ * architecture:cli-surface INV30).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'host-entry',
+  placement: {parent: 'namespace:cli', slot: 'guides', order: 15},
+  title: 'Host entry',
+  category: 'guide',
+  keywords: [
+    'host entry',
+    'runHostedCli',
+    '@astryxdesign/cli/host',
+    'carry the cli',
+    'embed the cli',
+    'programmatic run',
+    'package sets',
+    'cliCommand',
+  ],
+  description:
+    'Run the Astryx CLI from your own command-line tool: the inputs `runHostedCli` takes, what it returns, and when the process ends instead.',
+  sections: [
+    {
+      id: 'start',
+      title: 'Start a run',
+      content: [
+        {
+          type: 'prose',
+          text: "A tool that carries the CLI for its own users starts one run per process with `runHostedCli` from `@astryxdesign/cli/host`. The run behaves as the CLI's own command does with the same arguments in the same folder, and the commands it prints start with your tool's command.",
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "import {runHostedCli} from '@astryxdesign/cli/host';\n\nconst {status} = await runHostedCli({\n  argv: process.argv.slice(2),\n  cwd: process.cwd(),\n  cliCommand: 'acme astryx',\n});\nprocess.exitCode = status;",
+        },
+      ],
+    },
+    {
+      id: 'options',
+      title: 'Options',
+      content: [
+        {
+          type: 'table',
+          headers: ['Option', 'Default', 'Meaning'],
+          rows: [
+            [
+              '`argv`',
+              'none',
+              'The command-line arguments, without the command name.',
+            ],
+            [
+              '`cwd`',
+              "the process's working folder",
+              'The folder the run works in. It must exist.',
+            ],
+            [
+              '`cliCommand`',
+              "the package manager's name",
+              'The command your users type, such as `acme astryx`: a non-blank single line of at most 120 characters, with no surrounding spaces.',
+            ],
+            [
+              '`declinedProjectCli`',
+              'none',
+              "Why you did not run the project's own CLI, such as `untrusted`: a non-blank single line of at most 120 characters. That CLI then never runs.",
+            ],
+            [
+              '`roots`',
+              'none',
+              'Your package sets, in order of preference: folders whose `node_modules` each hold a CLI, the Core of the same release, and integrations. A run never installs a release; it takes the release a project needs from the first set that holds it.',
+            ],
+            [
+              '`integrations`',
+              'none',
+              'Integrations you approve for use outside a project, by package name.',
+            ],
+            [
+              '`discoverSources`',
+              'none',
+              "Your own discover sources. `astryx discover` reports each as the host's.",
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      id: 'result',
+      title: 'Result and errors',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "It resolves with `{status, packages}`: the exit status the CLI's own command would exit with, and each package the run used, with its version and whether it came from the project or a package set.",
+            'When another release answers from one of your package sets through its own host entry, that entry runs in the same process with the same inputs, and the call resolves with its result.',
+            'It rejects with a `TypeError`, before anything runs, for an unknown option or an invalid value, and with an `Error` when a run already started in the process. Start each run in a new process.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'process-ends',
+      title: 'When the process ends instead',
+      content: [
+        {
+          type: 'prose',
+          text: "Like the CLI's own command, a run ends the process with its exit status, and the call never resolves, when it:",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'prints help or the version (`--help`, `-h`, `help`, `--version`, `-V`, `--version --json`);',
+            'rejects the command line, such as an unknown command or option;',
+            'reports an error it stops on, including every error in `--json` mode;',
+            'meets an unexpected error;',
+            "hands the run to another CLI's own command: the project's CLI when you pass no `declinedProjectCli`, or a package set whose CLI has no host entry.",
+          ],
+        },
+      ],
+    },
+  ],
+};

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/docs/links`: link one doc
+ * @file `astryx docs authoring/building-blocks/docs/links`: link one doc
  * to another by identity, link the CLI's docs, and fix a link that names no
  * doc.
  */

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/building-blocks/templates/build-the-template/package-and-test`:
+ * @file `astryx docs authoring/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/building-blocks/templates/document-the-template/page-template`:
+ * @file `astryx docs authoring/building-blocks/templates/document-the-template/page-template`:
  * the page-only fields that help people find a page.
  */
 

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/ship/publishing`: publish an integration to
+ * @file `astryx docs authoring/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

@@ -5,7 +5,7 @@ export const docs = {
   type: 'generic',
   name: 'quick-start',
   placement: {
-    parent: 'namespace:integrations',
+    parent: 'namespace:authoring',
     slot: 'guides',
     order: 10,
   },

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/building-blocks/components/replace-a-core-component`:
+ * @file `astryx docs authoring/building-blocks/components/replace-a-core-component`:
  * intentionally make an integration component the default for a Core identity.
  */
 

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/building-blocks/templates/document-the-template/replace-a-core-template`:
+ * @file `astryx docs authoring/building-blocks/templates/document-the-template/replace-a-core-template`:
  * deliberately replace one Core template through template metadata.
  */
 

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/docs/sections-and-placement`:
+ * @file `astryx docs authoring/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.
  */

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/building-blocks/components/see-it-in-an-app`: inspect an
+ * @file `astryx docs authoring/building-blocks/components/see-it-in-an-app`: inspect an
  * integration component from an app that installs the package.
  */
 

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

@@ -1,12 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @file astryx docs cli/integrations/ship — test, publish, and upgrade. */
+/** @file astryx docs authoring/ship — test, publish, and upgrade. */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
 export const docs = {
   type: 'namespace',
   name: 'ship',
-  placement: {parent: 'namespace:integrations', slot: 'guides', order: 30},
+  placement: {parent: 'namespace:authoring', slot: 'guides', order: 30},
   title: 'Ship',
   summary: 'Test, publish, and upgrade your package.',
   keywords: ['ship', 'publish', 'release', 'upgrade'],

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/docs/short-and-findable`:
+ * @file `astryx docs authoring/building-blocks/docs/short-and-findable`:
  * keep each read short, lead each section with its summary, and write docs
  * that search finds.
  */

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/single-component`:
+ * @file `astryx docs authoring/building-blocks/components/describe-the-component/single-component`:
  * write and maintain the default ComponentDoc for one public component.
  */
 

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/templates/start-a-template`:
+ * @file `astryx docs authoring/building-blocks/templates/start-a-template`:
  * what a template is, why an integration shares one, whether it is a page or
  * a block, and how to add one.
  */

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/subcomponent`:
+ * @file `astryx docs authoring/building-blocks/components/describe-the-component/subcomponent`:
  * give one member of a component family its own ComponentDoc.
  */
 

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

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

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/building-blocks/templates/document-the-template/template-doc-overview`:
+ * @file `astryx docs authoring/building-blocks/templates/document-the-template/template-doc-overview`:
  * the source and doc file pair, the fields every template doc shares, and how
  * to check what Astryx lists.
  */
@@ -67,7 +67,7 @@ export const docs = {
             'Set `type` to the kind you chose in {@link generic:start-a-template}. It decides which other fields the doc accepts.',
             'The file name sets the template id ({@link generic:start-a-template}). Labels live in the doc: the terminal list prints `name`, and JSON listings print `displayName`. Changing either never changes the id.',
             'Write the description for someone choosing between templates. The Doc metadata category in {@link generic:template-grading-rubric} defines what a complete description covers.',
-            "Name the ideas the template serves in `keywords`: the domains, tasks, and other names a builder might use for it, in lowercase, such as `['monitoring', 'uptime', 'on-call']` for a service-health dashboard. How search and build use them is in {@link generic:authoring}, so the description can stay about the layout.",
+            "Name the ideas the template serves in `keywords`: the domains, tasks, and other names a builder might use for it, in lowercase, such as `['monitoring', 'uptime', 'on-call']` for a service-health dashboard. How search and build use them is in {@link generic:field-reference}, so the description can stay about the layout.",
             'Add `isReady: false` as soon as you generate the doc, because a doc without `isReady` is listed as ready. Keep it until the template passes {@link generic:test-template-in-app} and the quality review.',
           ],
         },

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

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

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

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

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

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

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

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

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-styles`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/template-assets/template-styles`:
  * style a template with Astryx first, keep editable styles in the file, and
  * ship shared CSS from the package.
  */

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/templates`: guides for adding,
+ * @file `astryx docs authoring/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/ship/test-in-an-app`: install the packed
+ * @file `astryx docs authoring/ship/test-in-an-app`: install the packed
  * package in an app and run the commands its users run.
  */