@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

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,38 +22,44 @@ 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',
           headers: ['Command', 'Proves', 'Exits 1 when', 'Only warns when'],
           rows: [
             [
-              '`npx astryx doctor integration validate`',
-              'The manifest loads, and each root holds contributions the CLI can read',
+              '`astryx doctor integration validate`',
+              '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 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",
             ],
             [
-              '`npx astryx doctor integration components`',
-              'No component name clashes with a Core component, and each `replaces` names one Core component',
+              '`astryx doctor integration components`',
+              "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`), type (`type_mismatch`), or literal `default` (`default_mismatch`) disagrees, or a `{@link}` in a component doc names no doc (`invalid_doc_graph`). It reads props with your installed `typescript`; without it, it prints `[skip] Props not compared`',
             ],
             [
-              '`npx astryx doctor integration templates`',
+              '`astryx doctor integration templates`',
               'Each `replaces` names a Core template of the same type',
               'A `replaces` target is missing (`missing_template_replacement_target`) or of the other type (`invalid_template_replacement`), or two templates replace one id (`ambiguous_template_replacement`)',
               'A template id matches a Core id without `replaces`',
             ],
             [
-              '`npx astryx doctor integration docs`',
-              'Your docs tree, every link, and topic names against Core',
+              '`astryx doctor integration docs`',
+              'Your docs tree, every link, topic names against Core, passages two topics repeat word for word, padding phrases and low-density topics, and written pointers to 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`)',
+              'A link names no doc (`invalid_doc_graph`), two topics repeat a passage word for word (`copied_passage`), prose pads with a listed phrase or falls under the density floor (`doc_fluff`), or prose, a description or summary, or the text of a component doc writes `astryx docs <name>` where a link would be checked (`stray_doc_pointer`)',
             ],
             [
-              '`npx astryx integration verify`',
+              '`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`',
+            ],
+            [
+              '`astryx integration verify`',
               'The packed package holds every file, shows the same contributions, resolves every public import, and declares the CLI it needs',
               'Anything `validate` fails on, no manifest, a file left out of the `.tgz` file, an import that does not resolve, or a missing CLI peer',
               'Anything `validate` warns about, or a component sets `replaces` and the package does not declare the CLI range that turns it on (`component_replaces_needs_cli`)',
@@ -62,30 +68,32 @@ 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 `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. The strict check fails on every copied passage the docs check lists ({@link generic:check-your-docs}). 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.',
-            'Bare `npx astryx doctor` in the package also warns about a doc section over 32 KB, which no check above measures.',
+            '`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: `astryx integration check --strict && astryx integration verify`.',
+            'Bare `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/ci-and-containers.doc.mjs

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/ci-and-containers`: Astryx in CI and containers: no
+ * update checks, caching versions, read-only home folders (spec AST-081 FR6,
+ * FR7, FR10).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'ci-and-containers',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 8,
+  },
+  title: 'CI and containers',
+  category: 'guide',
+  keywords: [
+    'ci',
+    'github actions',
+    'container',
+    'docker',
+    'read-only home',
+    'cache the release cache',
+  ],
+  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.",
+  sections: [
+    {
+      id: 'in-ci',
+      title: 'In CI',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Most CI services set `CI=true`. When `CI` is set to anything but empty, `0`, or `false`, Astryx never checks for updates and never prints a notice; `CI=false`, `CI=0`, and an empty `CI` do not count. `NO_UPDATE_NOTIFIER`, set to anything, does the same anywhere.',
+            "Add `@astryxdesign/cli` to the project as a devDependency at the same version as `@astryxdesign/core`; then CI runs the version pinned in the repo, and nothing is fetched. A global install in a CI image also works: in a project, it runs the project's version.",
+            'Use `--json` for output a script reads; it never carries the answered-by line or a notice.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'cache',
+      title: 'Cache project versions',
+      content: [
+        {
+          type: 'prose',
+          text: "When the project installs its own CLI and you install the project's dependencies first, there is nothing to cache. Astryx downloads into its cache only the CLI version a project whose own CLI cannot start needs, and, outside a project, the Core of a global install for commands that read components. In CI it downloads nothing in the background, so a global install in a CI image fetches that Core on its first component command. To skip those downloads on every run, cache this folder between runs:",
+        },
+        {
+          type: 'table',
+          headers: ['Linux', 'macOS', 'Windows'],
+          rows: [
+            [
+              '`~/.cache/astryx` (or `$XDG_CACHE_HOME/astryx`)',
+              '`~/Library/Caches/astryx`',
+              '`%LOCALAPPDATA%\\astryx\\Cache`',
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      id: 'read-only',
+      title: 'Read-only home folders',
+      content: [
+        {
+          type: 'prose',
+          text: "When the cache cannot be written, a project whose own CLI cannot start is answered by the global install, with a warning naming the folder. Point `XDG_CACHE_HOME` at a writable absolute path, or reinstall the project's dependencies. The global install's daily check and agent guide are skipped quietly when they cannot be written.",
+        },
+      ],
+    },
+    {
+      id: 'more',
+      title: 'More on global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'This page is part of {@link namespace:global}, which explains what global mode is and how each part works.',
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/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.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'cli-command',
+  placement: {parent: 'namespace:configuration', slot: 'guides', order: 15},
+  title: 'CLI command',
+  category: 'guide',
+  keywords: [
+    'cliCommand',
+    'command name',
+    'wrapper',
+    'printed commands',
+    'pnpm exec astryx',
+  ],
+  description:
+    'Name the command your users run the CLI with, so every command the CLI prints in their apps starts with it.',
+  sections: [
+    {
+      id: 'when-to-set-it',
+      title: 'When to set it',
+      content: [
+        {
+          type: 'prose',
+          text: "The CLI ends most answers with the next command to run: a hint, an error fix, a Doctor fix, or a doc example. By default each one starts with a command that reaches the release that answered: what the app's package manager runs, such as `pnpm exec astryx` or `yarn astryx`, when the app's own CLI answered, and otherwise the CLI package pinned to that release, such as `npx @astryxdesign/cli@0.7.2`.",
+        },
+        {
+          type: 'prose',
+          text: 'Set `cliCommand` only when your users run the CLI some other way, such as a wrapper your company ships that runs it with your package loaded. Otherwise the commands the CLI prints send them, and their agents, to a CLI that answers without your package. Most packages leave it out.',
+        },
+      ],
+    },
+    {
+      id: 'set-it',
+      title: 'Set it',
+      content: [
+        {
+          type: 'prose',
+          text: 'Add `cliCommand` to `astryx.integration.mjs`: the command, without a subcommand.',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          code: `// astryx.integration.mjs
+export default {
+  components: './components',
+  cliCommand: 'acme astryx',
+};`,
+        },
+        {
+          type: 'prose',
+          text: 'In an app that installs your package, the CLI then prints every command with it:',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'Error: Theme "ocean" is not added. Run `acme astryx theme add ocean` first.',
+        },
+        {
+          type: 'prose',
+          text: 'That covers hints, errors, suggestions, Doctor fixes, `--help`, the setup reminder, the agent block `init` writes, and doc text. `--json` output keeps every command without a runner, as in `"command": "astryx theme add ocean"`, so a script reads the same fields in every app.',
+        },
+      ],
+    },
+    {
+      id: 'how-the-cli-picks',
+      title: 'How the CLI picks the command',
+      content: [
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'The `cliCommand` of the packages the app loads, when they name one command.',
+            'The command a host tool names when it runs the CLI for the app. Nothing in a plain project names one.',
+            "A command that reaches the release that answered: what the app's package manager runs when the app's own CLI answered, such as `pnpm exec astryx` or `yarn astryx`; `astryx` outside a project when the CLI installed for the computer answered; otherwise the CLI package pinned to that release, such as `npx @astryxdesign/cli@0.7.2` (see {@link generic:who-answers}).",
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Two packages that set the same command agree, and the CLI uses it.',
+        },
+      ],
+    },
+    {
+      id: 'when-two-packages-disagree',
+      title: 'When two packages disagree',
+      content: [
+        {
+          type: 'prose',
+          text: "If two packages an app loads set different commands, the CLI uses neither: it prints commands with what the app's package manager runs, even when a host tool named a command. `astryx doctor` warns in its `cli-command` check and names both packages:",
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `status:  [warn]
+label:   CLI command
+message: Loaded integrations declare different CLI commands: @acme/astryx-widgets (\`acme astryx\`), @other/kit (\`other astryx\`). Neither is used, so printed commands start with \`pnpm exec astryx\`.`,
+        },
+        {
+          type: 'prose',
+          text: 'The app fixes it by removing the package that does not belong, or the packages agree on one command.',
+        },
+      ],
+    },
+    {
+      id: 'check-it',
+      title: 'Check it',
+      content: [
+        {
+          type: 'prose',
+          text: 'An invalid value is ignored, and the rest of your manifest still loads. `astryx doctor integration validate` reports it as `invalid_cli_command`. A valid `cliCommand` is one line of plain text without spaces at either end, at most 120 characters.',
+        },
+        {
+          type: 'prose',
+          text: "In an app that installs your package, `astryx doctor` passes its `cli-command` check and names your package as the one that set the command. A CLI released before this field reports `cliCommand` as an unknown key and prints the package manager's command.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx doctor integration validate\n# In an app that installs the package\nastryx doctor',
+        },
+      ],
+    },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: "In global mode: outside a project, the `cliCommand` of integrations installed for the computer applies; when none is declared, commands start with the plain command of the CLI installed for the computer. Inside a project, only the project's integrations count, so a `cliCommand` from a package installed for the computer never changes the project's printed commands. See {@link namespace:global} and {@link generic:global-integrations}.",
+        },
+      ],
+    },
+  ],
+};

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

@@ -20,4 +20,10 @@ export const docs = {
     guides: {title: 'Guides', accepts: {kinds: ['generic', 'namespace']}},
     reference: {title: 'Reference', accepts: {kinds: ['namespace']}},
   },
+  blocks: [
+    {
+      type: 'prose',
+      text: 'Use the CLI in any folder: install it once for your computer, and every project still gets the release that matches its Core. See {@link namespace:global}.',
+    },
+  ],
 };

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.
  */
 
@@ -27,7 +27,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'bash',
-          code: 'npx astryx integration add codemod rename-delay --to 0.7.0',
+          code: 'astryx integration add codemod rename-delay --to 0.7.0',
         },
         {
           type: 'code',
@@ -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}.",
         },
       ],
     },
@@ -116,22 +116,22 @@ export default {
           type: 'code',
           lang: 'bash',
           code: `# Preview each codemod and the files it would change
-npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets
+astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets
 # Write the changes
-npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply`,
+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',
@@ -143,5 +143,15 @@ Applying integration codemods...
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: "In global mode: inside an app, `upgrade` runs with the release equal to the app's Core, whichever copy of the CLI the user starts, and only the codemods of integrations the app installs run. Outside a project, `upgrade` lists codemods and migrates nothing. See {@link namespace:global} and {@link command:upgrade}.",
+        },
+      ],
+    },
   ],
 };

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

@@ -13,7 +13,7 @@ export const docs = {
   name: 'commands',
   title: 'Commands',
   summary:
-    'Every command and subcommand: usage, options, examples, and exit codes.',
+    'Every command and subcommand: usage, options, examples, exit codes, and what it does outside a project.',
   keywords: ['commands', 'usage', 'options', 'flags'],
   placement: {parent: 'namespace:cli', slot: 'reference', order: 10},
   slots: {
@@ -22,4 +22,10 @@ export const docs = {
   adopts: [
     {source: {group: 'cli/commands', kinds: ['command']}, into: 'commands'},
   ],
+  blocks: [
+    {
+      type: 'prose',
+      text: "In global mode: each command declares its behavior outside projects (`outsideProject`). Most answer like a new project; some write nothing and name the project they need; `doctor`, `init`, and `upgrade` behave differently. Commands with different behavior describe it in their `In global mode:` note, and CLI tests run each command in an empty folder against its declared value. Inside a project, the project's Astryx release runs every command, whichever astryx command you type. See {@link namespace:global}.",
+    },
+  ],
 };

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.
  */
 
@@ -35,6 +35,14 @@ export const docs = {
           type: 'prose',
           text: 'Add writes the entry only when package.json already has an `exports` map, so start every package with `"exports": {}`.',
         },
+        {
+          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. 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',
+          text: "The file name still opens the doc. A name that Core or another doc's file already has stays theirs, and so does a Core name your package replaces: with `Badge.doc.mjs` naming `AcmeBadge`, `astryx component Badge` opens Core's `Badge`, and `--package` with your package name reaches yours.",
+        },
       ],
     },
     {
@@ -43,12 +51,12 @@ 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',
           lang: 'bash',
-          code: 'npx astryx integration verify',
+          code: 'astryx integration verify',
         },
         {
           type: 'list',
@@ -65,5 +73,15 @@ export const docs = {
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: "In global mode: outside a project, imports the CLI prints name packages installed for the computer, which a new app must install before it can build them; inside a project, only packages the project installs are printed. See {@link namespace:global} and {@link generic:global-integrations}.",
+        },
+      ],
+    },
   ],
 };

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.
  */
 
@@ -20,4 +20,10 @@ export const docs = {
       accepts: {kinds: ['generic', 'namespace']},
     },
   },
+  blocks: [
+    {
+      type: 'prose',
+      text: 'In global mode: components from an integration installed for the computer show up outside projects; inside a project, only components from integrations the project installs. See {@link namespace:global} and {@link generic:global-integrations}.',
+    },
+  ],
 };