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

package/assets/docs/is-my-code-good.doc.mjs

@@ -0,0 +1,287 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs is-my-code-good`: one evidence-first guide for checking
+ * whether a product surface uses Astryx well and improving it with an agent.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'is-my-code-good',
+  title: 'Is my Astryx code good?',
+  category: 'guide',
+  keywords: [
+    'is my code good',
+    'review my code',
+    'code review',
+    'check my code',
+    'evaluate my code',
+    'review astryx code',
+    'rubric',
+    'astryx quality rubric',
+    'custom code audit',
+  ],
+  description:
+    'Check whether a product surface fits its app and uses Astryx well, require evidence for every claim, and improve it with a repeatable agent review.',
+  sections: [
+    {
+      id: 'understand-the-app',
+      title: 'Understand the app',
+      content: [
+        {
+          type: 'prose',
+          text: 'Do not judge a file or surface in isolation. First learn the app context that makes a pattern correct, inconsistent, or incomplete.',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Name what the app is for, who uses it, and the task this surface helps them complete.',
+            'Trace where the surface sits: its route, entry point, navigation path, parent shell, and the page or block pattern it is meant to use.',
+            'Inspect sibling surfaces that do the same or adjacent jobs. Record their shared headers, actions, layout primitives, spacing, density, states, and narrow-screen behavior.',
+            'Read project guidance, including the root and relevant nested `AGENTS.md` files. Record app-owned wrapper components and intentional app conventions.',
+            'Record the installed `@astryxdesign/core`, `@astryxdesign/cli`, and integration-package versions from the project manifest and lockfile. Run the installed invocation of `astryx component --list` to see core and integration components, then inspect app-owned wrappers that do not appear in that catalog.',
+            'List the real data states, roles and permissions, supported locales and RTL behavior, and mobile or narrow-width needs that affect the task.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Keep this context with the review. Mark anything you could not learn as `not inspected`. Do not flag a documented, intentional app convention merely because it differs from a generic pattern; cite the convention and verify that the user task and accessibility requirements still work.',
+        },
+      ],
+    },
+    {
+      id: 'choose-the-review',
+      title: 'Choose the review',
+      content: [
+        {
+          type: 'prose',
+          text: 'Review one exact revision and one named product surface, route, or component in its app context. Pick the smallest review that can answer your question.',
+        },
+        {
+          type: 'table',
+          headers: ['Review', 'Use it for', 'What it can prove'],
+          rows: [
+            [
+              'Source check',
+              'A fast check for raw elements, direct icons, custom styles, and unsupported imports',
+              'Source findings plus app context visible in the project. It cannot call the rendered product good.',
+            ],
+            [
+              'Full product review',
+              'Calling a surface done',
+              'App fit and task completion plus source quality, rendered layout, states, assets, project checks, and accessibility evidence.',
+            ],
+            [
+              'Template publication grade',
+              'An integration template that people copy',
+              'The shared criteria plus versioned scoring, metadata, packaging, copy, and clean-app checks in {@link generic:grade-template-with-agent}.',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'If all you have is one source file, run the source check anyway and use any project context that is available. Report clear source blockers; list missing app purpose, route, sibling patterns, shell, theme and density, installed components and versions, real states and roles, locale and mobile needs, revision, runnable app, rendered states, and project checks; and do not call the full product good.',
+        },
+        {
+          type: 'prose',
+          text: "`astryx` in this guide means the project's installed CLI invocation, such as its local binary or existing package script. If the project has no installed invocation, report that evidence gap instead of downloading a different CLI version for the review.",
+        },
+        {
+          type: 'prose',
+          text: 'A screenshot can prove a visible result, but it cannot prove which imports, components, or styles produced it. Source alone cannot prove responsive behavior, interaction, color modes, or whether an asset loads. Mark anything outside the supplied evidence as `not inspected`.',
+        },
+      ],
+    },
+    {
+      id: 'apply-the-rubric',
+      title: 'Apply the shared rubric',
+      content: [
+        {
+          type: 'prose',
+          text: 'Mark each category `good`, `needs work`, or `not inspected`. Cite the route, sibling surface, project guidance, theme, component catalog, or user requirement behind every context-dependent result; cite a file and line for every source result; and name the rendered state for every visual result. Never turn missing evidence into a pass. A blocker is a finding that prevents the surface from building, rendering, operating, letting the target user complete the task, or meeting an accessibility requirement. Other departures from the rubric are `needs work`.',
+        },
+        {
+          type: 'table',
+          headers: ['Category', 'What good means'],
+          rows: [
+            [
+              'App fit and task completion',
+              "The surface uses the app's established shell, page pattern, theme, density, wrappers, integrations, and interaction conventions unless a deviation is intentional and evidenced. The target user can complete the surface's job across the real states and permissions in scope.",
+            ],
+            [
+              'Astryx components',
+              'Astryx owns each visible or interactive pattern for which it has a suitable component. Raw elements remain only when their native semantics are necessary or Astryx has no equivalent.',
+            ],
+            [
+              'Icons',
+              'Icons render through `Icon`, `IconButton`, or the receiving component icon prop, not as raw SVG or a library component used directly.',
+            ],
+            [
+              'Styling',
+              'Component props and design tokens do the work before custom StyleX declarations, inline styles, or classes. Each custom rule has a reason because no supported Astryx surface fits.',
+            ],
+            [
+              'Layout',
+              'Astryx layout primitives express the visible structure, hierarchy, spacing, and responsive behavior without rebuilding the same patterns in raw containers or CSS.',
+            ],
+            [
+              'Images and assets',
+              'Every image, font, and other asset is intentional, accessible, stable, and working from the product build path.',
+            ],
+            [
+              'Code health',
+              'Public imports resolve, client boundaries are necessary, reachable states are handled, and no dead code or wrapper hides a finding.',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: "Before calling a pattern custom or wrong, compare sibling surfaces and the installed component catalog. Reuse an app-owned wrapper or integration component when it already owns the job. A documented app convention is not a finding merely because it differs from a generic pattern; cite the convention and verify the user's task and accessibility requirements.",
+        },
+        {type: 'heading', level: 3, text: 'Common component replacements'},
+        {
+          type: 'table',
+          headers: ['Raw pattern', 'Common Astryx owner'],
+          rows: [
+            [
+              'Layout `div`',
+              '`VStack`, `HStack`, `Grid`, `Card`, `Section`, or `Center`',
+            ],
+            ['`span`, `p`, or `h1` through `h6`', '`Text` or `Heading`'],
+            ['`button` or linked action', '`Button`, `IconButton`, or `Link`'],
+            ['In-page `nav` or `aside`', '`LayoutPanel`'],
+            [
+              '`header` or `main`',
+              '`LayoutHeader` or `LayoutContent` inside `Layout`',
+            ],
+            ['`ul`, `ol`, or `li`', '`List` and `ListItem`'],
+            [
+              '`input`, `textarea`, or `select`',
+              'The matching Astryx form control',
+            ],
+            ['`table`, `tr`, or `td`', '`Table`'],
+            [
+              '`hr`, `dialog`, `details`, or `summary`',
+              '`Divider`, `Dialog`, or `Collapsible`',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Keep a native element when its semantics are necessary and Astryx has no equivalent. Common examples are a `form` that provides native submission, `input type="hidden"` for native form state, and an `img` when no general Astryx image component fits.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "Compare the route with sibling surfaces that do the same job. Identify the app's shared header, actions, shell, page pattern, spacing, and density before judging the target.",
+            'Inspect every JSX opening tag. Moving raw HTML behind a PascalCase helper does not make the underlying pattern an Astryx component.',
+            'Count every raw SVG element used as an icon, including `svg`, `path`, `circle`, `rect`, `line`, `polyline`, `polygon`, `ellipse`, and `g`. For an inline SVG helper, count its raw SVG elements once in the helper definition, not again at each render. Count each icon-library component rendered directly outside an Astryx icon surface.',
+            'Look up a possible replacement with `astryx component <Name> --dense`. Do not invent a component or prop that the installed version does not provide.',
+            'Run the installed `astryx component --list` and inspect app-owned wrappers before rebuilding a pattern. Prefer the component the app or one of its installed integrations already uses for the job.',
+            'Inspect every `stylex.create` declaration, inline style, `className`, and `stylex.props` use. Look for a component prop or token first.',
+            "When replacing a literal spacing value, read `astryx docs spacing --full` for the matching step or token and the target component doc for the prop's accepted scale. Do not guess a pixel-to-step mapping.",
+            'Choose the root that matches the surface. Use `Layout` for a page, `Center` for centered content, and `AppShell` only when the surface owns global application chrome.',
+            'Render realistic empty, loading, error, long-content, and interactive states. Check narrow and wide widths plus each supported color mode.',
+            'Verify the target roles and permissions, supported locales and RTL behavior, and mobile needs. Follow the real task from entry to completion instead of judging only the static page.',
+            'Run the product build, type check, tests, and accessibility checks. Keep a missing or failed check visible instead of calling the result good.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'This shared rubric has no numeric score. It answers whether ordinary product code uses Astryx well without pretending that an inapplicable template field or missing browser state earned points. Integration templates add a versioned score in {@link generic:template-grading-rubric}.',
+        },
+      ],
+    },
+    {
+      id: 'collect-the-evidence',
+      title: 'Collect the evidence',
+      content: [
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Record the exact revision, named surface, route, and source files in scope. If the files are outside version control, record a content hash for each file and say that no project revision was available.',
+            "Write down the app's purpose, target users, surface task, entry point, navigation path, parent shell, expected page pattern, and sibling surfaces used for comparison.",
+            'Record project guidance, theme, density, installed Astryx and integration versions, the relevant output of `astryx component --list`, and app-owned wrappers or conventions.',
+            'List the states and context that matter, including real data shapes, roles and permissions, empty, loading, error, long content, interaction, narrow width, wide width, supported color modes, locales, and RTL behavior when they apply.',
+            'Run the product and capture each named rendered state. Use screenshots or a live browser result for visible claims, and follow the target user task from entry to completion.',
+            'Run the build, type check, tests, and accessibility checks. Keep their commands and results with the review.',
+            'For each Astryx component whose replacement, prop, or composition is in question, read `astryx component <Name> --dense`.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'ask-an-agent',
+      title: 'Ask an agent',
+      content: [
+        {
+          type: 'prose',
+          text: 'Start with a read-only pass so the original findings stay visible. Replace every angle-bracket value in this prompt.',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          label: 'Agent evaluation prompt',
+          code: `Evaluate how well <surface> at <revision> fits <app> and uses Astryx. Do not edit files during this first pass.
+
+\`astryx\` below means the project's installed CLI invocation, such as its local binary or existing package script. If none is installed, report that evidence gap instead of downloading a different version.
+
+Before evaluating:
+1. Read \`astryx docs is-my-code-good --full\`.
+2. Read the root and relevant nested \`AGENTS.md\` files plus other project guidance. State what the app is for, who uses it, and the task this surface supports.
+3. Trace the surface's route, entry point, navigation path, parent shell, and expected page or block pattern.
+4. Inspect at least two sibling surfaces that do the same or adjacent jobs. Record their shared headers, actions, layout, spacing, density, states, and narrow-screen behavior.
+5. Record the app's theme, density, app-owned wrappers, and documented intentional conventions.
+6. Read the project manifest and lockfile for the installed Astryx, CLI, and integration versions. Run \`astryx component --list\`, then identify relevant integration components and app-owned wrappers.
+7. List the real data states, roles and permissions, supported locales and RTL behavior, and mobile or narrow-width needs.
+8. Inspect every source file in scope and its public imports.
+9. Run \`astryx component <Name> --dense\` for each Astryx component whose replacement, prop, or composition you question.
+10. Read \`astryx docs spacing --full\` and the target component's docs before mapping a literal spacing value to a prop or token.
+11. Render every supplied state at narrow and wide widths and in each supported color mode.
+12. Read the build, type-check, test, and accessibility-check results.
+
+If only source is supplied, continue with a source check. Report blockers visible in the source, list every missing app-context and product-evidence item, and do not call the full product good. Do not leave the blocker list empty only because no checks were supplied.
+
+Judge the code against the app as well as Astryx. Ask whether it matches sibling surfaces, uses the right shell and page pattern, reuses app or integration components instead of rebuilding them, preserves intentional app conventions, and lets the target user complete the task.
+
+For each rubric category, return \`good\`, \`needs work\`, or \`not inspected\`. Every context-dependent finding must cite the route, sibling file, project guidance, theme, component catalog, wrapper, or user requirement it relies on. Cite file and line evidence for source findings and name the rendered state for visual findings. Mark context you could not learn as \`not inspected\`. Do not flag a documented intentional app convention merely because it differs from a generic pattern. Never turn missing evidence into a pass. Do not hide raw HTML or custom styles behind a helper. Do not calculate a template score for ordinary product code.
+
+Return:
+- app purpose, target users, surface job, route, and entry path
+- app context inspected and app context missing
+- product evidence inspected and product evidence missing
+- one row per rubric category with result, evidence, and fix
+- task-completion, functional, or accessibility blockers visible in the source or found by the supplied checks
+- the top three fixes in order
+- every claim that still needs a person to verify`,
+        },
+      ],
+    },
+    {
+      id: 'verify-and-repeat',
+      title: 'Verify, improve, and repeat',
+      content: [
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Reject a `good` result without app-context, source, and rendered evidence. Open every cited route, sibling file, guidance file, and source location, and reproduce every named visible state.',
+            'Check that documented intentional app conventions were not flagged merely for differing from a generic pattern, and that context the reviewer could not learn stayed `not inspected`.',
+            'Fix task-completion, build, functional, and accessibility blockers first.',
+            'Reuse the app shell, page pattern, wrappers, and installed integration components before replacing unnecessary raw elements, direct icons, and custom styles.',
+            'Follow the target user task again, render the full state set, and rerun the project checks.',
+            'Repeat the read-only review on the new revision. Keep the first report so the improvement and every remaining tradeoff stay visible.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'For an integration template, finish with the scored package and copy workflow in {@link generic:grade-template-with-agent}. Ordinary product code stops with the evidence-backed category report and does not receive a template publication grade.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/add-a-component.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/components/add-a-component`: choose a
+ * @file `astryx docs authoring/building-blocks/components/add-a-component`: choose a
  * component name and generate its first source and doc files.
  */
 

package/assets/docs/tree/add-a-theme.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/themes/add-a-theme`:
+ * @file `astryx docs authoring/building-blocks/themes/add-a-theme`:
  * scaffold a theme in a package — blank, or forked from an existing theme.
  */
 

package/assets/docs/tree/add-a-topic.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/docs/add-a-topic`: add a
+ * @file `astryx docs authoring/building-blocks/docs/add-a-topic`: add a
  * doc topic to an integration package, write its sections, and pick the doc
  * kind for each thing the package ships.
  */
@@ -79,7 +79,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Start every CLI command in a doc with the word astryx alone, with no runner such as npx or pnpm exec in front. The CLI prefixes each one when it prints the doc, with the command the reader runs: `pnpm exec astryx` or `yarn astryx` from their package manager, or the `cliCommand` an integration sets. See {@link generic:cli-command}.',
+          text: 'Start every CLI command in a doc with the word astryx alone, with no runner such as npx or pnpm exec in front. The CLI prefixes each one when it prints the doc, with the command the reader runs: `pnpm exec astryx` or `yarn astryx` from their package manager, or the `cliCommand` an integration sets. See {@link generic:cli-command}. `doctor integration validate` (and so `integration check`) lists each command written with a runner as a `runner_command` note, with its file, line and the bare command to write. A note fails nothing. An install step, which runs before the CLI is installed, is the one exception: write the scoped package name, `@astryxdesign/cli`, after the download runner. The unscoped name after a download runner is always listed, because it fetches an unrelated package.',
         },
         {
           type: 'code',

package/assets/docs/tree/agent-guidance.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/configuration/agent-guidance`: add short lines of
+ * @file `astryx docs authoring/building-blocks/configuration/agent-guidance`: add short lines of
  * guidance that apps put in front of their AI agents, within the limits.
  */
 

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

@@ -20,6 +20,12 @@ export const docs = {
   slots: {
     kinds: {title: 'Reference', accepts: {kinds: ['namespace']}},
   },
+  blocks: [
+    {
+      type: 'prose',
+      text: 'To run the whole CLI from your own command-line tool, with its arguments, folder, and command name, use the host entry: {@link generic:host-entry}.',
+    },
+  ],
   adopts: [
     {
       source: {group: 'cli/api', kinds: ['function', 'schema', 'enum']},

package/assets/docs/tree/{integrations.doc.mjs → authoring.doc.mjs}

@@ -1,27 +1,36 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @file astryx docs cli/integrations — build an integration package. */
+/**
+ * @file `astryx docs authoring`: everything for integration authors. The
+ * guides build, ship, and fix an integration package; the field reference
+ * covers every file it holds.
+ */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
 export const docs = {
   type: 'namespace',
-  name: 'integrations',
-  placement: {parent: 'namespace:cli', slot: 'guides', order: 10},
-  title: 'Build an integration',
+  name: 'authoring',
+  title: 'Authoring',
   summary:
-    'Build an npm package that adds components, templates, themes, docs, and codemods to Astryx apps.',
+    'Build an npm package that adds components, templates, themes, docs, and codemods to Astryx apps, and look up every field of every file it holds.',
   keywords: [
+    'authoring',
     'integration',
     'integration package',
     'make an integration',
     'publish an integration',
     'integration authoring',
+    'authoring reference',
   ],
   slots: {
     guides: {
       title: 'Build an integration',
       accepts: {kinds: ['generic', 'namespace']},
     },
+    reference: {
+      title: 'Reference',
+      accepts: {kinds: ['generic']},
+    },
   },
   blocks: [
     {
@@ -42,7 +51,7 @@ export const docs = {
     },
     {
       type: 'prose',
-      text: 'Every field of every file you write for an integration is in {@link generic:authoring}.',
+      text: 'Every field of every file you write for an integration is in {@link generic:field-reference}.',
     },
     {
       type: 'prose',

package/assets/docs/tree/block-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/block-template`:
+ * @file `astryx docs authoring/building-blocks/templates/document-the-template/block-template`:
  * the block-only fields: component relationships and the preview shape.
  */
 

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template`:
  * author portable template source and every asset that source needs.
  */
 

package/assets/docs/tree/building-blocks.doc.mjs

@@ -1,12 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @file astryx docs cli/integrations/building-blocks — the kinds you can add. */
+/** @file astryx docs authoring/building-blocks — the kinds you can add. */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
 export const docs = {
   type: 'namespace',
   name: 'building-blocks',
-  placement: {parent: 'namespace:integrations', slot: 'guides', order: 20},
+  placement: {parent: 'namespace:authoring', slot: 'guides', order: 20},
   title: 'Building Blocks',
   summary:
     'Add components, templates, themes, docs, and codemods, and configure how it behaves.',

package/assets/docs/tree/check-the-props.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/check-the-props`:
+ * @file `astryx docs authoring/building-blocks/components/describe-the-component/check-the-props`:
  * compare each component doc's props table with the component's TypeScript
  * props, read each finding, and fix the doc or the code.
  */

package/assets/docs/tree/check-your-docs.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/docs/check-your-docs`:
+ * @file `astryx docs authoring/building-blocks/docs/check-your-docs`:
  * what each check proves about an integration's docs: the docs check, each
  * doc's fields, the read size, and the CLI peer.
  */
@@ -133,7 +133,7 @@ fix:      Remove \`summary\`: SingleComponentDoc has no field \`summary\`.`,
             "The folder decides the type: `ComponentDoc` in your components root, `IntegrationTemplateDoc` in your templates root, `ThemeDoc` in your themes root, and in your docs root the type the doc's `type` names. Keep the `@type` comment above each doc's export too, so your editor shows the same problems as you type.",
             'Every finding is a warning, so the exit code stays 0. With `--json`, they are in `data.docTypes.findings`.',
             'It uses the `typescript` your package installs. Where `typescript` is missing or has no JavaScript compiler API, as TypeScript 7 does, it uses `@typescript/typescript6`, the TypeScript 6 API package, if your package installs it. Without either, it prints `[skip] Docs not type-checked` and the reason.',
-            'Every field of every doc type is in {@link generic:authoring}.',
+            'Every field of every doc type is in {@link generic:field-reference}.',
           ],
         },
       ],

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/ship/checks`: what each package check
+ * @file `astryx docs authoring/ship/checks`: what each package check
  * proves, what fails and what only warns, and one command to run them all.
  */
 
@@ -30,9 +30,9 @@ export const docs = {
           rows: [
             [
               '`astryx doctor integration validate`',
-              'The manifest loads, each root holds contributions the CLI can read, and each doc matches its authoring type',
+              'The manifest loads, each root holds contributions the CLI can read, and each doc matches its authoring type. Notes, which fail nothing, list a malformed `cliCommand` and each command a topic writes with a package runner (`runner_command`)',
               '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`), 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 also warns on what no reader can serve: a prop listed twice (`duplicate_prop`), a `propDescriptions` key that names no documented prop (`unknown_translated_prop`), a section with no content (`empty_section`), two sections of a topic with one key (`duplicate_section_key`), or a `.doc.zh.mjs` or `.doc.dense.mjs` overlay beside no topic file (`orphan_doc_overlay`). It checks docs with your installed `typescript`, or, where that is missing or has no JavaScript compiler API (TypeScript 7), with an installed `@typescript/typescript6`; without either, it prints `[skip] Docs not type-checked`. 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 also warns on what no reader can serve: a prop listed twice (`duplicate_prop`), a `propDescriptions` key that names no documented prop (`unknown_translated_prop`), a section with no content (`empty_section`), two sections of a topic with one key (`duplicate_section_key`), or a `.doc.zh.mjs` or `.doc.dense.mjs` overlay beside no topic file (`orphan_doc_overlay`). Since 0.7.3 it also lists, from source and without failing, what the package tells apps to import that they cannot: a component's import (the doc's `import`, or the one the CLI derives) or a template's public import whose subpath package.json `exports` does not declare (`component_import_not_exported`, `template_import_not_exported`) or that names another package (`component_import_other_package`); an example that imports an undeclared subpath (`example_import_not_exported`); a template that imports a path outside the templates root (`template_import_outside_root`) or a path its package or Core does not export (`template_private_import`). It lists the same way a component's import whose module does not export the component (`component_import_missing_name`), an example or a template that imports a name its package does not export (`example_import_missing_name`, `template_import_missing_name`), and a template source with no default export (`template_no_default_export`). Each is a note, printed with its fix, that fails `--strict` from the next minor; an import it cannot judge, such as an `exports` target not built yet or a deep path into a `dist/` not built yet, is listed under `publicImports` as not checked. It checks docs with your installed `typescript`, or, where that is missing or has no JavaScript compiler API (TypeScript 7), with an installed `@typescript/typescript6`; without either, it prints `[skip] Docs not type-checked`. With no `astryx.integration.mjs` it prints a hint and exits 0",
             ],
             [
               '`astryx doctor integration components`',

package/assets/docs/tree/ci-and-containers.doc.mjs

@@ -24,6 +24,9 @@ export const docs = {
     'docker',
     'read-only home',
     'cache the release cache',
+    'agent machine',
+    'restart',
+    'ephemeral machine',
   ],
   description:
     "What Astryx does in CI and containers: no update checks or notices, the project's version as always, and how to cache versions or work with a read-only home folder.",
@@ -74,6 +77,16 @@ export const docs = {
         },
       ],
     },
+    {
+      id: 'short-lived',
+      title: 'Machines that keep only the home folder',
+      content: [
+        {
+          type: 'prose',
+          text: 'Some agent machines keep the home folder across restarts but not system folders. A global install there disappears on restart while the agent guide in the home folder stays, so agents are told to run a global astryx command that is gone; the guide says to run the command that installed the CLI, such as `npm i -g @astryxdesign/cli`, when that command is not found, and `astryx doctor` names the same step. To keep the CLI across restarts, install it into a folder in your home and put its `bin` folder on your PATH, as for a permission error ({@link generic:install-once}), or run that command when the machine starts.',
+        },
+      ],
+    },
     {
       id: 'more',
       title: 'More on global mode',

package/assets/docs/tree/cli-command.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/configuration/cli-command`:
+ * @file `astryx docs authoring/building-blocks/configuration/cli-command`:
  * name the command an integration's users run the CLI with, so every command
  * the CLI prints in their apps starts with it.
  */

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

@@ -14,7 +14,7 @@ export const docs = {
   name: 'cli',
   title: 'Astryx CLI',
   summary:
-    'Commands, programmatic APIs, integration authoring, and output contracts.',
+    'Commands, programmatic APIs, and output contracts. Building an integration is under {@link namespace:authoring}.',
   keywords: ['cli', 'commands', 'api', 'reference'],
   slots: {
     guides: {title: 'Guides', accepts: {kinds: ['generic', 'namespace']}},

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/codemods`: add codemods to an
+ * @file `astryx docs authoring/building-blocks/codemods`: add codemods to an
  * integration package, and know which of them `astryx upgrade` runs in an app.
  */
 

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/component-family`:
+ * @file `astryx docs authoring/building-blocks/components/describe-the-component/component-family`:
  * author one ComponentDoc for several public exports in a component family.
  */
 

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/components/component-imports`: make an
+ * @file `astryx docs authoring/building-blocks/components/component-imports`: make an
  * integration component's documented import resolve from the packed package.
  */
 

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

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

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

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @file astryx docs cli/integrations/building-blocks/configuration — set how your integration behaves. */
+/** @file astryx docs authoring/building-blocks/configuration — set how your integration behaves. */
 
 /** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
 export const docs = {

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/building-blocks/configuration/debug-and-gap-reports`: receive a record
+ * @file `astryx docs authoring/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.
  */

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/themes/define-the-theme`:
+ * @file `astryx docs authoring/building-blocks/themes/define-the-theme`:
  * map the palette to tokens, keep light-dark() to colors, and avoid Core internals.
  */
 

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/building-blocks/components/describe-the-component`:
+ * @file `astryx docs authoring/building-blocks/components/describe-the-component`:
  * choose and maintain the ComponentDoc shape that matches a component's public
  * source.
  */

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

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