@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

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

@@ -1,149 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/component-lookups`: exact single and batch component
- * lookup through the CLI and programmatic API.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'component-lookups',
-  placement: {parent: 'namespace:cli', slot: 'guides', order: 5},
-  title: 'Looking up components',
-  category: 'guide',
-  description:
-    'Look up one or several exact component identities, choose a focused projection, and handle complete batch receipts.',
-  sections: [
-    {
-      id: 'several',
-      title: 'Look up several components',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: '`astryx component` accepts exact selectors as a variadic positional argument. With no selector it browses the catalog. With one selector it keeps the normal single-component response. With two or more it prints one complete ordered batch receipt.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          label: 'Several component docs',
-          code: 'astryx component Button Badge Text\nastryx --json component Button Badge Text',
-        },
-        {
-          type: 'prose',
-          text: 'Every selector gets one row in input order. Duplicate selectors stay duplicate rows. A missing or ambiguous component does not hide successful neighbors or stop later selectors from resolving.',
-        },
-        {
-          type: 'prose',
-          text: 'A batch accepts at most 100 selectors, including duplicates, in every projection mode. A larger request returns a top-level `ERR_INVALID_ARGUMENT` before any component resolves. It emits no `component.batch` receipt and no partial results.',
-        },
-        {
-          type: 'prose',
-          text: 'Focused component controls apply to every found row. Use the same control you use for one component:',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          label: 'Focused batch lookups',
-          code: 'astryx --json component Button Card --props\nastryx component Button Card --source\nastryx component Button Card --showcase\nastryx component Button Card --blocks\nastryx component Button Card --detail compact\nastryx component Button Card --lang dense\nastryx component Button Card --package @astryxdesign/core',
-        },
-      ],
-    },
-    {
-      id: 'selectors',
-      title: 'Selector forms',
-      category: 'reference',
-      content: [
-        {
-          type: 'prose',
-          text: 'A selector is an exact component identity, not free-text search. Use one of these forms:',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            '`Button` for an unqualified component name.',
-            '`widgets/Button` for a component in an unscoped package.',
-            '`@acme/widgets/Button` for a component in a scoped package.',
-            '`@acme/widgets@1.2.3/Button` to require that exact installed package version.',
-          ],
-        },
-        {
-          type: 'prose',
-          text: 'A version qualifies the package, never the component. The lookup does not fall through to another installed version. An unqualified name owned by several installed packages is `ambiguous` and lists every candidate. Use a package-qualified selector or `--package` to choose one.',
-        },
-        {
-          type: 'prose',
-          text: '`astryx discover` remains free-text package discovery. Its words form one query; they are not component batch selectors.',
-        },
-      ],
-    },
-    {
-      id: 'output',
-      title: 'Batch output and exit status',
-      category: 'reference',
-      content: [
-        {
-          type: 'prose',
-          text: 'JSON uses `component.batch` with `{count, results}`. Each row echoes `selector` and has one status: `found`, `not_found`, `ambiguous`, or `error`. A found row carries the normal single-component `{type, data}` under `result`. Failed rows carry `code` and `error`, plus `suggestions` or `candidates` when available.',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          label: 'Outcome and duplicate examples',
-          code: 'astryx --json component Button Badge                 # all found, exit 0\nastryx --json component Button MissingWidget         # mixed, exit 1\nastryx --json component MissingWidget MissingPanel   # all failed, exit 1\nastryx --json component Button Button                # two ordered rows, exit 0',
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          label: 'A complete failed JSON receipt',
-          code: 'astryx --json component MissingWidget MissingPanel',
-        },
-        {
-          type: 'code',
-          lang: 'json',
-          code: '{\n  "apiVersion": 1,\n  "type": "component.batch",\n  "data": {\n    "count": 2,\n    "results": [\n      {\n        "selector": "MissingWidget",\n        "status": "not_found",\n        "code": "ERR_UNKNOWN_COMPONENT",\n        "error": "No component named \\"MissingWidget\\""\n      },\n      {\n        "selector": "MissingPanel",\n        "status": "not_found",\n        "code": "ERR_UNKNOWN_COMPONENT",\n        "error": "No component named \\"MissingPanel\\""\n      }\n    ]\n  }\n}',
-        },
-        {
-          type: 'code',
-          lang: 'text',
-          label: 'The same receipt in text mode',
-          code: 'Component batch\n\ncount: 2\n\nResults\n\nMissingWidget\n\nselector: MissingWidget\nstatus:   not_found\ncode:     ERR_UNKNOWN_COMPONENT\nerror:    No component named "MissingWidget"\n\nMissingPanel\n\nselector: MissingPanel\nstatus:   not_found\ncode:     ERR_UNKNOWN_COMPONENT\nerror:    No component named "MissingPanel"',
-        },
-        {
-          type: 'prose',
-          text: 'The CLI emits every row first, then exits 1 when any row is not `found`. This includes mixed receipts and receipts where every row failed. JSON and text use the same exit status. A batch where every row is `found` exits 0.',
-        },
-      ],
-    },
-    {
-      id: 'api',
-      title: 'Programmatic API',
-      category: 'reference',
-      content: [
-        {
-          type: 'prose',
-          text: 'The argument shape chooses the response shape. Omit the argument for the catalog, pass a string for the existing single-component response, and pass an array for `component.batch`. An array always means batch, including empty and one-item arrays, so filtering a selector list cannot silently change the response type. The published `ComponentBatchResponse` specializes the shared `BatchResponse` and `BatchRow` types.',
-        },
-        {
-          type: 'code',
-          lang: 'javascript',
-          code: "import {component} from '@astryxdesign/cli/api';\n\nconst catalog = await component(); // component.list\nconst button = await component('Button'); // component.detail\nconst empty = await component([]); // component.batch, count 0\nconst oneRow = await component(['Button']); // component.batch, count 1\nconst batch = await component(['Button', 'Badge']); // component.batch, count 2\nawait component(Array(101).fill('Button')); // ERR_INVALID_ARGUMENT before lookup",
-        },
-        {
-          type: 'code',
-          lang: 'json',
-          label: 'Exact empty-array response',
-          code: '{\n  "type": "component.batch",\n  "data": {\n    "count": 0,\n    "results": []\n  }\n}',
-        },
-        {
-          type: 'code',
-          lang: 'javascript',
-          label: 'Handle every row without losing partial results',
-          code: "const receipt = await component(['Button', 'MissingWidget']);\n\nfor (const row of receipt.data.results) {\n  if (row.status === 'found') {\n    useComponentDoc(row.selector, row.result);\n  } else if (row.status === 'ambiguous') {\n    choosePackage(row.selector, row.candidates);\n  } else {\n    reportLookupFailure(row.selector, row.code, row.error);\n  }\n}",
-        },
-      ],
-    },
-  ],
-};

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

@@ -1,23 +0,0 @@
-// 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

@@ -1,23 +0,0 @@
-// 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

@@ -1,182 +0,0 @@
-// 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}.',
-        },
-      ],
-    },
-  ],
-};

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

@@ -1,118 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/building-blocks/themes/define-the-theme`:
- * map the palette to tokens, keep light-dark() to colors, and avoid Core internals.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'define-the-theme',
-  placement: {parent: 'namespace:themes', slot: 'guides', order: 30},
-  title: 'Define the theme',
-  category: 'guide',
-  description:
-    'Point theme tokens at the palette, keep light-dark() to colors, and avoid Core internals.',
-  sections: [
-    {
-      id: 'map-the-palette-to-tokens',
-      title: 'Map the palette to tokens',
-      content: [
-        {
-          type: 'prose',
-          text: 'A theme token is a named slot that Astryx components read for a value — `--color-accent` for the accent color, and so on. Components never read your palette directly; they read tokens. Defining a theme means pointing each token at a palette shade, so the components wear your colors.',
-        },
-        {
-          type: 'prose',
-          text: 'Import the palette in `oceanTheme.ts` and point your tokens at its stops. Each token takes a `[light, dark]` pair — the shade to use in light mode and the one in dark mode.',
-        },
-        {
-          type: 'code',
-          lang: 'ts',
-          code: `// themes/ocean/oceanTheme.ts
-import {defineTheme} from '@astryxdesign/core/theme';
-import {palette} from './tokens/ocean.palette';
-
-const {light, dark} = palette.ocean;
-
-export const oceanTheme = defineTheme({
-  name: 'ocean',
-  tokens: {
-    '--color-accent': [light['45'], dark['70']],
-  },
-});`,
-        },
-        {
-          type: 'prose',
-          text: 'Local imports must stay inside the theme folder. One that leaves it, such as `../../shared/colors`, fails with `invalid_theme`, and the theme disappears from `theme list`. `npx astryx theme template` writes a file that explains every `defineTheme` field. For the full token set, scope selectors, and component theming, read {@link generic:theme}.',
-        },
-      ],
-    },
-    {
-      id: 'build-on-another-theme',
-      title: 'Build on another theme',
-      content: [
-        {
-          type: 'prose',
-          text: 'To base a theme on an existing one, `extends` it: import the base theme and override only the tokens you change. The derived theme keeps a live link to the base and inherits its later changes — unlike `--from`, which forks a copy ({@link generic:add-a-theme}).',
-        },
-        {
-          type: 'code',
-          lang: 'ts',
-          code: `import {defineTheme} from '@astryxdesign/core/theme';
-import {oceanTheme} from './oceanTheme';
-
-export const oceanContrastTheme = defineTheme({
-  name: 'ocean-contrast',
-  extends: oceanTheme,
-  tokens: {
-    '--color-accent': ['#0051a3', '#4aa3ff'],
-  },
-});`,
-        },
-      ],
-    },
-    {
-      id: 'keep-light-dark-to-colors',
-      title: 'Keep light-dark() to colors',
-      content: [
-        {
-          type: 'prose',
-          text: 'Each `[light, dark]` pair compiles to a `light-dark()` value, which switches only colors. Give it colors. For a value that is not a plain color — a gradient — put `light-dark()` on each color stop, not around the whole value: a browser without `light-dark()` drops the declaration, and the stop form is the one that degrades safely.',
-        },
-      ],
-    },
-    {
-      id: 'avoid-core-internals',
-      title: 'Do not set Core private variables',
-      content: [
-        {
-          type: 'prose',
-          text: 'Core private variables start with `--_`, such as `--_field-radius`. They are internals and can change in any Core release, so `theme build` reports each one it finds as an `[error]`. Set the standard CSS property instead — `borderRadius`, `padding` — and let the build emit the internal variable where Core needs it.',
-        },
-      ],
-    },
-    {
-      id: 'declare-the-peers',
-      title: 'Declare the peer dependencies',
-      content: [
-        {
-          type: 'prose',
-          text: 'The theme imports `@astryxdesign/core/theme`, so declare Core as a peer dependency, with the range of Core versions you test the theme against — a range, not an exact version, so a Core patch release does not force a republish. `integration add theme` already declared the optional `@astryxdesign/cli` peer that reads themes:',
-        },
-        {
-          type: 'code',
-          lang: 'json',
-          code: `"peerDependencies": {
-  "@astryxdesign/core": "^0.7.0",
-  "@astryxdesign/cli": ">=0.7.0"
-},
-"peerDependenciesMeta": {
-  "@astryxdesign/cli": {"optional": true}
-}`,
-        },
-      ],
-    },
-  ],
-};

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

@@ -1,57 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/components/describe-the-component`:
- * choose and maintain the ComponentDoc shape that matches a component's public
- * source.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
-export const docs = {
-  type: 'namespace',
-  name: 'describe-the-component',
-  placement: {parent: 'namespace:components', slot: 'guides', order: 20},
-  title: 'Describe the component',
-  summary:
-    'Write and maintain the default component doc, then adapt it when one family owns several exports or a member needs its own file.',
-  keywords: [
-    'component doc',
-    'component documentation',
-    'component family',
-    'subcomponent',
-  ],
-  slots: {
-    guides: {
-      title: 'Describe the component',
-      accepts: {kinds: ['generic']},
-    },
-  },
-  blocks: [
-    {
-      type: 'prose',
-      text: 'A component\'s `.doc.mjs` is part of the integration\'s public contract, not optional commentary. Astryx uses it for CLI output and search, and people and agents read it to decide whether the component fits and how to use it.',
-    },
-    {
-      type: 'list',
-      style: 'unordered',
-      items: [
-        'Change the source and its `.doc.mjs` together.',
-        'Update the doc whenever the public name, import, behavior, props, defaults, examples, or accessibility requirements change.',
-        '`integration verify` checks the doc shape and packed import, but it cannot prove the prose still matches the component.',
-      ],
-    },
-    {
-      type: 'prose',
-      text: 'Every component doc has one stable identity and enough usage guidance for a reader to choose it correctly. Pick the shape below that matches your module.',
-    },
-    {
-      type: 'prose',
-      text: 'After every source or doc change, read the component back. This output is what people and agents receive.',
-    },
-    {
-      type: 'code',
-      lang: 'bash',
-      code: 'npx astryx component AcmeCarousel',
-    },
-  ],
-};

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

@@ -1,21 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/docs`: the guides to writing docs for an
- * integration package, which join the same docs tree as the CLI's own
- * (spec:AST-046, spec:AST-047).
- */
-
-/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
-export const docs = {
-  type: 'namespace',
-  name: 'docs',
-  placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 40},
-  title: 'Docs',
-  summary:
-    'Write docs that ship with your package and that people and agents find by search or one level at a time.',
-  keywords: ['writing docs', 'doc topic', 'docs section', 'placement', 'links'],
-  slots: {
-    guides: {title: 'Guides', accepts: {kinds: ['generic']}},
-  },
-};

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

@@ -1,28 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/templates/document-the-template`:
- * document page and block templates for discovery and correct reuse.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
-export const docs = {
-  type: 'namespace',
-  name: 'document-the-template',
-  placement: {parent: 'namespace:templates', slot: 'build', order: 20},
-  title: 'Document the template',
-  summary:
-    'Write the doc that helps people and agents find, choose, and trust your template: its name, description, readiness, preview, and any Core replacement.',
-  keywords: [
-    'template doc',
-    'template documentation',
-    'page template',
-    'block template',
-  ],
-  slots: {
-    guides: {
-      title: 'Guides',
-      accepts: {kinds: ['generic']},
-    },
-  },
-};

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

@@ -1,68 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/integrations/building-blocks/themes/document-the-theme`:
- * document a theme by extending the core theme topic, not in agent guidance.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
-  type: 'generic',
-  name: 'document-the-theme',
-  placement: {parent: 'namespace:themes', slot: 'guides', order: 50},
-  title: 'Document the theme',
-  category: 'guide',
-  description:
-    'Document a theme by extending the core theme topic, so an app reads it in `astryx docs theme`.',
-  sections: [
-    {
-      id: 'extend-the-theme-topic',
-      title: 'Extend the core theme topic',
-      content: [
-        {
-          type: 'prose',
-          text: 'Give your theme a doc topic that extends the core `theme` topic, so an app that lists your package sees your theme at the end of `astryx docs theme`. Add it with `extends: \'theme\'` ({@link generic:extend-or-replace}).',
-        },
-        {
-          type: 'code',
-          lang: 'javascript',
-          code: `// docs/ocean-theme.doc.mjs
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export default {
-  type: 'generic',
-  name: 'ocean-theme',
-  extends: 'theme',
-  title: 'Ocean theme',
-  description: 'Use the Ocean theme from @acme/astryx-widgets.',
-  sections: [
-    {
-      id: 'use-the-ocean-theme',
-      title: 'Use the Ocean theme',
-      content: [
-        {
-          type: 'prose',
-          text: "Add \`@acme/astryx-widgets\` to the app's dependencies and apply the Ocean theme with \`<Theme theme={oceanTheme}>\`.",
-        },
-      ],
-    },
-  ],
-};`,
-        },
-        {
-          type: 'prose',
-          text: 'Keep the section short: how to add the package, apply the theme ({@link generic:use-a-theme-in-an-app}), and — if the theme uses a custom font — which fonts the app must load ({@link generic:fonts-and-assets}). Extend `theme` rather than a topic another package replaces, or an app that lists that package first drops your section.',
-        },
-      ],
-    },
-    {
-      id: 'not-agent-guidance',
-      title: 'Not agent guidance',
-      content: [
-        {
-          type: 'prose',
-          text: 'Do not put theme usage in `agentDocs`. Agent lines land in every app\'s agent file and are for guidance needed every session; a theme\'s install-and-use steps belong in a doc topic that people and agents read on demand. See {@link generic:agent-guidance}.',
-        },
-      ],
-    },
-  ],
-};