@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

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

@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/checks`: what each package check
+ * proves, what fails and what only warns, and one command to run them all.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'checks',
+  placement: {parent: 'namespace:ship', slot: 'guides', order: 20},
+  title: 'Check an integration',
+  category: 'guide',
+  keywords: ['check before publishing', 'validate an integration', 'ci'],
+  description:
+    'Pick the check for each problem, learn what fails and what only warns, and run every check in CI.',
+  sections: [
+    {
+      id: 'pick-a-check',
+      title: 'Pick a check',
+      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.',
+        },
+        {
+          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',
+              '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',
+            ],
+            [
+              '`npx astryx doctor integration components`',
+              'No component name clashes with a Core component',
+              'Core is not installed (`core_not_found`)',
+              'A name clashes with Core',
+            ],
+            [
+              '`npx 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',
+              'A topic takes a Core topic name without `replaces` or `extends`, a doc is invalid (`invalid_doc`), or a namespace or placement fails, which hides the doc (`invalid_doc_graph`)',
+              'A link names no doc (`invalid_doc_graph`)',
+            ],
+            [
+              '`npx astryx integration 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',
+            ],
+          ],
+        },
+        {
+          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.',
+        },
+      ],
+    },
+    {
+      id: 'run-every-check-in-ci',
+      title: 'Run every check in CI',
+      content: [
+        {
+          type: 'prose',
+          text: 'Chain the five checks so the first failure stops the run. Install devDependencies first, because the components check needs Core.',
+        },
+        {
+          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',
+        },
+        {
+          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.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'what-integration-verify-does',
+      title: 'Verify the packed package',
+      content: [
+        {
+          type: 'prose',
+          text: '`integration verify` packs your package with npm, unpacks it into a temporary app, and checks that the app sees everything your source has. It publishes nothing and leaves no `.tgz` file or temporary folder behind.',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            '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 fails a package that ships a docs section, a placed guide, a template `replaces`, a doc section with an `id`, or a theme without an `@astryxdesign/cli` peer of `>=0.7.0`.',
+          ],
+        },
+        {
+          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}.',
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,147 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/codemods`: add codemods to an
+ * integration package, and know which of them `astryx upgrade` runs in an app.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'codemods',
+  placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 50},
+  title: 'Codemods',
+  category: 'guide',
+  keywords: ['breaking change', 'migrate apps', 'integration codemod'],
+  description:
+    'Ship codemods that `astryx upgrade` runs to migrate app code, and know which of them an app runs.',
+  sections: [
+    {
+      id: 'add-a-codemod',
+      title: 'Add a codemod',
+      content: [
+        {
+          type: 'prose',
+          text: '`integration add codemod` writes a codemod into a folder named after a version. Apps run it with `astryx upgrade` to migrate their code.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx integration add codemod rename-delay --to 0.7.0',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `codemods/
+  0.7.0/
+    rename-delay.mjs         # the codemod
+    rename-delay.test.mjs    # skipped: a test file
+    __tests__/               # skipped: a test folder`,
+        },
+        {
+          type: 'prose',
+          text: "The first add declares `codemods: './codemods'` in `astryx.integration.mjs`. The codemod's id is its path inside the version folder, without the extension: `rename-delay`. An id must be unique across all version folders in the package.",
+        },
+        {
+          type: 'prose',
+          text: 'The loader skips `*.test.*`, `*.spec.*`, and `*.fixture.*` files and everything under `__tests__/` or `__fixtures__/`, so tests can sit beside the codemod. The folder name decides when an app runs the codemod; see "Choose when a codemod runs".',
+        },
+      ],
+    },
+    {
+      id: 'write-the-transform',
+      title: 'Write the transform',
+      content: [
+        {
+          type: 'prose',
+          text: 'A codemod default-exports a plain object with a `type`, a `title`, and a `transform` function. `transform` returns the new source, or `null` to leave the file as it is.',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          code: `// codemods/0.7.0/rename-delay.mjs
+/** @type {import('@astryxdesign/cli/authoring').AstryxCodemod} */
+export default {
+  type: 'code',
+  title: 'Rename AcmeCarousel delay to interval',
+  description: 'Renames the delay prop on AcmeCarousel.',
+  fileExtensions: ['.tsx', '.jsx'],
+  transform(file, api) {
+    const j = api.jscodeshift;
+    const root = j(file.source);
+    const props = root
+      .find(j.JSXOpeningElement, {name: {name: 'AcmeCarousel'}})
+      .find(j.JSXAttribute, {name: {name: 'delay'}});
+    if (props.size() === 0) return null;
+    props.forEach(path => {
+      path.node.name.name = 'interval';
+    });
+    return root.toSource();
+  },
+};`,
+        },
+        {
+          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}.",
+        },
+      ],
+    },
+    {
+      id: 'which-codemods-run',
+      title: 'Choose when a codemod runs',
+      content: [
+        {
+          type: 'prose',
+          text: "Two rules decide whether an app's `astryx upgrade` runs your codemods: the app's Core versions, and whether the app names your package.",
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            "Version folders are matched against the app's `@astryxdesign/core` versions, not your package's version. `upgrade --from <version>` runs each folder above `--from`, up to and including the Core version installed in the app. With Core 0.7.0 installed, `--from 0.6.3` runs `0.7.0/`, and `--from 0.7.0` runs nothing. A folder named after your own release, such as `1.0.0/`, waits until the app has Core 1.0.0.",
+            '`upgrade` runs your codemods only when the app lists your package in `integrations` in its `astryx.config`, or passes `--integration @acme/astryx-widgets`. Having your package installed is not enough: the run then skips your codemods with no warning.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'run-codemods-in-an-app',
+      title: 'Run codemods in an app',
+      content: [
+        {
+          type: 'prose',
+          text: 'An app previews codemods with `astryx upgrade` and writes the changes with `--apply`. Without `--apply`, nothing on disk changes.',
+        },
+        {
+          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
+# Write the changes
+npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply`,
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `Integrations: @acme/astryx-widgets
+1 codemod to run (dry run)
+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`.",
+        },
+        {
+          type: 'prose',
+          text: '`--from` is the Core version the app had before it upgraded. The run scans `./src` unless the app passes `--path`, and it never writes a file the app marks as generated, vendored, or ignored; see {@link command:upgrade}. `upgrade --list` shows only Core codemods.',
+        },
+        {
+          type: 'prose',
+          text: "An integration manifest has no `hooks` field. Commands that run after codemods, such as a formatter, are the app's to set, in `hooks.postCodemod` in its `astryx.config`.",
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,113 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/describe-the-component/component-family`:
+ * author one ComponentDoc for several public exports in a component family.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'component-family',
+  placement: {
+    parent: 'namespace:describe-the-component',
+    slot: 'guides',
+    order: 30,
+  },
+  title: 'Component family',
+  category: 'guide',
+  description:
+    'Adapt a single-component doc when one module exposes several public components or hooks that belong to one family.',
+  sections: [
+    {
+      id: 'choose-the-family-shape',
+      title: 'Choose the family shape',
+      content: [
+        {
+          type: 'prose',
+          text: 'Start with a complete single-component doc. Convert its top-level `props` into a `components` array only when one source module or component directory exposes several public components or hooks as one family. The family doc keeps the shared usage guidance; each array entry owns one public export.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Put the primary or most-used export first.',
+            'Use a full entry when this file owns that export\'s description and signature.',
+            'Use `props` for a component entry. Use `params` and `returns` for a hook entry.',
+            'Do not add private implementation helpers or exports that people should not use directly.',
+          ],
+        },
+        {
+          type: 'reference',
+          target: 'schema:component-doc',
+          projection: {fields: ['components']},
+          presentation: 'full',
+        },
+      ],
+    },
+    {
+      id: 'document-the-family-inline',
+      title: 'Document the family inline',
+      content: [
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'components/AcmeTabs.doc.mjs',
+          code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export default {
+  type: 'component',
+  name: 'AcmeTabs',
+  displayName: 'Acme Tabs',
+  import: '@acme/astryx-widgets/components/AcmeTabs',
+  usage: {
+    description:
+      'Switches between related views without leaving the page.',
+  },
+  components: [
+    {
+      name: 'AcmeTabs',
+      displayName: 'Acme Tabs',
+      description: 'Owns selection and lays out the tab list and panels.',
+      props: [
+        {
+          name: 'value',
+          type: 'string',
+          description: 'The selected tab value.',
+          required: true,
+        },
+      ],
+    },
+    {
+      name: 'AcmeTab',
+      displayName: 'Acme Tab',
+      description: 'Selects one view in Acme Tabs.',
+      props: [
+        {
+          name: 'value',
+          type: 'string',
+          description: 'The value this tab selects.',
+          required: true,
+        },
+      ],
+    },
+  ],
+};`,
+        },
+        {
+          type: 'prose',
+          text: 'The public module named by `import` must export every component or hook named by a full entry.',
+        },
+      ],
+    },
+    {
+      id: 'give-a-member-its-own-file',
+      title: 'Give a member its own file',
+      content: [
+        {
+          type: 'prose',
+          text: 'When one family member needs its own doc, replace its full entry with `{name: \'MemberName\'}` and move the details into a sibling doc. The parent keeps the family relationship without copying the child\'s content. Continue with {@link generic:subcomponent}.',
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/component-imports`: make an
+ * integration component's documented import resolve from the packed package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'component-imports',
+  placement: {parent: 'namespace:components', slot: 'guides', order: 30},
+  title: 'Resolve the import',
+  category: 'guide',
+  description:
+    'Keep the component doc import and package exports map aligned, then verify the packed package.',
+  sections: [
+    {
+      id: 'export-the-component',
+      title: 'Export the component',
+      content: [
+        {
+          type: 'prose',
+          text: 'Apps copy the component doc\'s `import` field into their code, so that exact specifier must resolve from your packed package. `integration add` writes it together with an `exports` entry in package.json.',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'package.json',
+          code: `"exports": {
+  "./components/AcmeCarousel": "./components/AcmeCarousel.tsx"
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'Add writes the entry only when package.json already has an `exports` map, so start every package with `"exports": {}`.',
+        },
+      ],
+    },
+    {
+      id: 'verify-the-packed-import',
+      title: 'Verify the packed import',
+      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.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx integration verify',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`component_import_unresolvable` means the exports map has no entry for the documented import.',
+            '`component_export_missing` means the module does not export the documented name, or package.json has no exports map.',
+            '`typescript_extension_in_specifier` means the public import ends in `.ts` or `.tsx`.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'To import from the package root, set `import: \'@acme/astryx-widgets\'` and re-export the component from the file that `exports["."]` points to. See {@link command:integration verify}.',
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components`: guides for adding and
+ * documenting components in an integration package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'components',
+  placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 10},
+  title: 'Components',
+  summary:
+    'Add components to an integration, document their public contract, and make them work in every app that installs the package.',
+  keywords: ['integration component', 'ship a component', 'component docs'],
+  slots: {
+    guides: {
+      title: 'Components',
+      accepts: {kinds: ['generic', 'namespace']},
+    },
+  },
+};

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

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @file astryx docs cli/integrations/building-blocks/configuration — set how your integration behaves. */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'configuration',
+  placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 60},
+  title: 'Configuration',
+  summary:
+    'Set how your integration behaves in an app: agent guidance, debug and gap reports, and more as it grows.',
+  keywords: ['configuration', 'agent guidance', 'debug', 'gap reports'],
+  slots: {
+    guides: {title: 'Configuration', accepts: {kinds: ['generic', 'namespace']}},
+  },
+  blocks: [
+    {
+      type: 'prose',
+      text: 'Beyond the things you ship, an integration can set how it behaves in an app: the guidance it gives the AI agents working there, and the record it keeps of each CLI run. Open one below to set it up.',
+    },
+  ],
+};

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

@@ -0,0 +1,182 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/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.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'debug-and-gap-reports',
+  placement: {parent: 'namespace:configuration', slot: 'guides', order: 20},
+  title: 'Debug and gap reports',
+  category: 'guide',
+  keywords: ['gap report', 'debug handler'],
+  description:
+    'Receive a record of each CLI run in apps that use your package, and handle the gap reports they send about it.',
+  sections: [
+    {
+      id: 'record-runs-with-debug',
+      title: 'Record runs with debug',
+      content: [
+        {
+          type: 'prose',
+          text: 'Export a `debug` function from `astryx.integration.mjs`, and the CLI calls it once for each command run in an app that loads your package.',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          code: `// astryx.integration.mjs
+import {appendFileSync} from 'node:fs';
+
+/** @param {import('@astryxdesign/cli/authoring').DebugEvent} event */
+export function debug(event) {
+  if (event.outcome !== 'ok') {
+    appendFileSync('acme-failed-runs.ndjson', JSON.stringify(event) + '\\n');
+  }
+}
+
+export default {
+  components: './components',
+};`,
+        },
+        {
+          type: 'prose',
+          text: 'The event is a `DebugEvent` with `command`, `outcome`, `exitCode`, `durationMs`, `error`, and more, its values scrubbed (`redacted: true`). Every field is in {@link generic:authoring}.',
+        },
+        {
+          type: 'prose',
+          text: "Keep the function synchronous: the CLI calls it as the process exits and never waits for a promise. The app's own `debug` handler runs first, then yours. A handler that throws is skipped, and the command's output and exit code stay the same.",
+        },
+        {
+          type: 'prose',
+          text: "An app records every command only when its `astryx.config` names `integrations` or `debug`, as listing your package does. Otherwise your handler runs only for commands that load the app's project, such as `component` and `docs`, and not for `--version` or a mistyped command. In an app whose config names neither word, each of those commands also prints a warning on stderr.",
+        },
+        {
+          type: 'prose',
+          text: '`debug` is a named export, not a manifest field, so a CLI that does not know it ignores it and loads the rest of your manifest.',
+        },
+      ],
+    },
+    {
+      id: 'turn-off-debug-in-an-app',
+      title: 'Turn off debug in an app',
+      content: [
+        {
+          type: 'prose',
+          text: "An app can refuse every integration's `debug` handler and keep its own. It sets `inheritDebug` in its package.json:",
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          code: '{"astryx": {"inheritDebug": false}}',
+        },
+        {
+          type: 'prose',
+          text: 'From then on, your handler no longer runs in that app.',
+        },
+      ],
+    },
+    {
+      id: 'handle-gap-reports',
+      title: 'Handle gap reports',
+      content: [
+        {
+          type: 'prose',
+          text: 'Export a `gapReport` handler, and `astryx gap-report` in an app sends it each gap report, such as a missing component or variant. The handler files the report and returns a receipt.',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          code: `/** @type {import('@astryxdesign/cli/authoring').GapReportHandler} */
+export const gapReport = {
+  audience: 'public',
+  async handle(report, {signal}) {
+    if (report.target.package !== '@acme/astryx-widgets') return {status: 'skipped'};
+    const body = JSON.stringify(report);
+    const response = await fetch('https://tracker.example.com/issues', {method: 'POST', body, signal});
+    const {url} = await response.json();
+    return {status: 'filed', url};
+  },
+};`,
+        },
+        {
+          type: 'prose',
+          text: 'Every handler in the app gets every report, so check `report.target.package` and skip reports about other packages. The receipt `status` is one of:',
+        },
+        {
+          type: 'table',
+          headers: ['`status`', 'Meaning'],
+          rows: [
+            [
+              '`filed`',
+              'You created or queued the report. Return `url` or `message`.',
+            ],
+            [
+              '`routed_only`',
+              'You point the caller to where to file it. `url` is required.',
+            ],
+            ['`skipped`', 'You chose not to act, for example on a duplicate.'],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'The CLI waits 30 seconds, then aborts `signal`. A throw, a timeout, or an invalid receipt fails your delivery, and the command exits 1; the other handlers still run. Like `debug`, `gapReport` is a named export that older CLIs ignore.',
+        },
+      ],
+    },
+    {
+      id: 'ask-before-filing-in-public',
+      title: 'Ask before filing in public',
+      content: [
+        {
+          type: 'prose',
+          text: "Set `audience: 'public'` when your handler writes somewhere the public can read. The CLI runs it only when the caller passes `--confirm-public`; an `'internal'` handler always runs.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: "npx astryx gap-report AcmeCarousel --category missing_variant --reason 'Need a vertical layout'",
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `handlerType: integration
+handler:     @acme/astryx-widgets
+audience:    public
+status:      consent_required
+message:     Rerun with --confirm-public to file this report.`,
+        },
+        {
+          type: 'prose',
+          text: 'With `--confirm-public`, the same delivery reads `status: filed` and shows your `url`. The report goes to the package named by `--package`, else the package that owns the component, else Core.',
+        },
+      ],
+    },
+    {
+      id: 'fall-back-to-issues-url',
+      title: 'Fall back to issuesUrl',
+      content: [
+        {
+          type: 'prose',
+          text: "When the app has no `gapReport` handler at all, the CLI routes the report to the target package's `issuesUrl` from its manifest instead.",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'A GitHub issues URL, such as `https://github.com/acme/widgets/issues`, gets an issue filed with the GitHub CLI, `gh`, once the caller passes `--confirm-public`.',
+            'Any other URL comes back as a `routed_only` receipt for the caller to open.',
+            'With no `issuesUrl`, the command fails: `Package "@acme/astryx-widgets" provides neither a report handler nor an issues URL.`',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'One handler anywhere in the app, from the app or from any package, turns the fallback off for every report. See {@link command:gap-report}.',
+        },
+      ],
+    },
+  ],
+};