@astryxdesign/cli 0.4.5 → 0.4.6-canary.cea9ecd

package/assets/templates/pages/dashboard-service-monitoring/template.doc.mjs

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'page',
+  name: 'Service Monitoring Dashboard',
+  displayName: 'Service Monitoring Dashboard',
+  description:
+    'Live-ops service-health dashboard: traffic-light KPI tiles with sparklines, and multi-line latency and request-volume charts with a 1h/1d/7d window, beside a triage rail split into two independently scrolling sections: active alerts over a worst-first per-service breakdown with inline status coloring. Global environment, region, and auto-refresh controls; the rail folds into the content column as two cards below 1024px.',
+  isReady: false,
+  category: 'Dashboard - Monitoring',
+};

package/authoring/doctypes/_schema.d.mts

@@ -57,6 +57,8 @@ export const FunctionDocKindSchema: z.ZodObject<{
 /** New-format stamped generic reference/topic doc (`type: 'generic'`). */
 export const GenericDocKindSchema: z.ZodObject<{
     type: z.ZodLiteral<"generic">;
+    replaces: z.ZodOptional<z.ZodString>;
+    extends: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     displayName: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;

package/authoring/doctypes/_schema.mjs

@@ -94,6 +94,11 @@ export const GenericDocKindSchema = z
   .object({
     ...BaseDocFields,
     type: z.literal('generic'),
+    // Declared rather than left to the passthrough: these two are read by
+    // docs discovery to resolve one topic against another, so a non-string
+    // should fail at the load boundary, not halfway through resolution.
+    replaces: z.string().optional(),
+    extends: z.string().optional(),
   })
   .passthrough();
 

package/authoring/doctypes/reference/reference.doc.mjs

@@ -51,6 +51,20 @@ export const doc = {
       type: 'string',
       description: "Navigation category: 'guide' or 'foundations'.",
     },
+    {
+      name: 'replaces',
+      type: 'string',
+      description:
+        "Name of an existing topic this doc takes the place of. Authored by an integration that serves its own guide instead of the built-in one: on a doc of the same name it swaps the content, and on a doc of another name it also leaves the old name as an alias so `astryx docs <old>` still resolves. Exclusive with `extends`.",
+      example: "'getting-started'",
+    },
+    {
+      name: 'extends',
+      type: 'string',
+      description:
+        'Name of an existing topic this doc merges onto, section by section: a section whose title matches one in the base replaces it, a section the base does not have is appended. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.',
+      example: "'theme'",
+    },
     {
       name: 'sections',
       type: 'ReferenceSection[]',

package/authoring/doctypes/reference/type.ts

@@ -68,6 +68,18 @@ export interface ReferenceDoc {
   description: string;
   /** Navigation category: 'guide' or 'foundations'. */
   category?: string;
+  /** Name of an existing topic this doc takes the place of. Authored by an
+   *  integration whose guide should be served instead of the built-in one —
+   *  `replaces: 'getting-started'` on a doc named `getting-started` swaps the
+   *  content, and on a doc named something else swaps it and leaves the old
+   *  name as an alias, so `astryx docs getting-started` still resolves.
+   *  Ignored on a built-in topic (there is nothing above it to replace). */
+  replaces?: string;
+  /** Name of an existing topic this doc merges onto, section by section: a
+   *  section whose title matches one in the base replaces it, and a section
+   *  the base does not have is appended. For correcting or adding to a topic
+   *  rather than owning it — `replaces` and `extends` are exclusive. */
+  extends?: string;
   /** Ordered sections that make up the doc. */
   sections: ReferenceSection[];
   /** Token category for foundational docs that map to a token section.

package/authoring/doctypes/template/type.ts

@@ -94,6 +94,8 @@ export type TemplateCategory =
   | 'Dashboard - Tabbed'
   | 'Dashboard - Filterable'
   | 'Dashboard - Portfolio'
+  | 'Dashboard - Project Status'
+  | 'Dashboard - Funnel & Cohort'
   // Table
   | 'Table - Basic'
   | 'Table - Grouped'

package/authoring/integration/integration.doc.mjs

@@ -15,7 +15,8 @@ export const doc = {
   description:
     'The astryx.integration.* manifest that sits beside an integration ' +
     "package's package.json. Points the CLI at the package's components, " +
-    'templates, and codemods, and where to file issues. Every field is optional.',
+    'templates, codemods, and doc topics, and where to file issues. Every ' +
+    'field is optional.',
   appliesTo: 'astryx.integration.{ts,mjs,js}',
   fields: [
     {
@@ -38,6 +39,13 @@ export const doc = {
       description: 'Relative path to the codemods root (resolved to absolute).',
       example: "'./codemods'",
     },
+    {
+      name: 'docs',
+      type: 'string',
+      description:
+        'Relative path to the reference-docs (topics) root (resolved to absolute). Every {topic}.doc.{ts,mjs,js} under it is served by `astryx docs` beside the built-in topics; a topic may also declare `replaces` or `extends` to take the place of a built-in one or merge onto it.',
+      example: "'./docs'",
+    },
     {
       name: 'issuesUrl',
       type: 'string',
@@ -52,6 +60,7 @@ export const doc = {
   components: './src/components',
   templates: './src/templates',
   codemods: './codemods',
+  docs: './docs',
   issuesUrl: 'https://github.com/acme/widgets/issues',
 };`,
     },

package/authoring/integration/parse.d.mts

@@ -27,6 +27,7 @@ declare const integrationSchema: z.ZodObject<{
     components: z.ZodOptional<z.ZodString>;
     templates: z.ZodOptional<z.ZodString>;
     codemods: z.ZodOptional<z.ZodString>;
+    docs: z.ZodOptional<z.ZodString>;
     issuesUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export {};

package/authoring/integration/parse.mjs

@@ -16,6 +16,7 @@ const integrationSchema = z
     components: z.string().optional(),
     templates: z.string().optional(),
     codemods: z.string().optional(),
+    docs: z.string().optional(),
     issuesUrl: z.string().url().optional(),
   })
   .strict();

package/authoring/integration/parse.test.mjs

@@ -26,6 +26,7 @@ describe('parseIntegration (load boundary)', () => {
     expect(parseIntegration({components: './src'})).toEqual({
       components: './src',
     });
+    expect(parseIntegration({docs: './docs'})).toEqual({docs: './docs'});
     expect(() =>
       parseIntegration({components: './c', issuesUrl: 'https://example.com/i'}),
     ).not.toThrow();

package/authoring/integration/type.ts

@@ -14,6 +14,11 @@ export interface AstryxIntegration {
   templates?: string;
   /** Relative path to the codemods root (resolved to absolute). */
   codemods?: string;
+  /** Relative path to the reference-docs (topics) root (resolved to
+   *  absolute). Every `{topic}.doc.{ts,mjs,js}` under it is a topic the CLI
+   *  serves from `astryx docs`, alongside the built-in ones. A topic may also
+   *  `replace` or `extend` a built-in topic; see the ReferenceDoc type. */
+  docs?: string;
   /** Where to file issues/feedback for this integration. */
   issuesUrl?: string;
 }

package/clients/cli/commands/component-ownership.test.mjs

@@ -47,7 +47,12 @@ const INTEGRATION_ISSUES = 'https://example.com/meta/issues';
  * Returns the absolute `components` dir so the Project.load mock can hand back a
  * resolved integration entry.
  */
-function createFixture({withSource = true, extraComponent = null} = {}) {
+function createFixture({
+  withSource = true,
+  extraComponent = null,
+  packageExports = null,
+  entryPoint = null,
+} = {}) {
   const realCoreDir = path.resolve(import.meta.dirname, '..', '..', '..', '..', 'core');
   const coreDir = path.join(tmpDir, 'packages', 'core');
   fs.mkdirSync(path.dirname(coreDir), {recursive: true});
@@ -58,7 +63,11 @@ function createFixture({withSource = true, extraComponent = null} = {}) {
   fs.mkdirSync(compDir, {recursive: true});
   fs.writeFileSync(
     path.join(intDir, 'package.json'),
-    JSON.stringify({name: INTEGRATION_NAME, version: '1.2.3'}),
+    JSON.stringify({
+      name: INTEGRATION_NAME,
+      version: '1.2.3',
+      ...(packageExports ? {exports: packageExports} : {}),
+    }),
   );
   fs.writeFileSync(
     path.join(compDir, 'MetaAppShell.doc.mjs'),
@@ -81,6 +90,20 @@ function createFixture({withSource = true, extraComponent = null} = {}) {
     );
   }
 
+  // A component whose directory is an entry point exporting several
+  // components, so the directory name and the component name differ.
+  if (entryPoint) {
+    const entryDir = path.join(compDir, entryPoint.directory);
+    fs.mkdirSync(entryDir, {recursive: true});
+    const ownSpecifier = entryPoint.importSpec
+      ? `\n  import: '${entryPoint.importSpec}',`
+      : '';
+    fs.writeFileSync(
+      path.join(entryDir, `${entryPoint.component}.doc.mjs`),
+      `export const docs = {\n  name: '${entryPoint.component}',${ownSpecifier}\n  usage: { description: '${entryPoint.component} from an entry point.' },\n};\n`,
+    );
+  }
+
   const integration = {
     name: INTEGRATION_NAME,
     version: '1.2.3',
@@ -88,6 +111,7 @@ function createFixture({withSource = true, extraComponent = null} = {}) {
     templates: undefined,
     codemods: undefined,
     issuesUrl: INTEGRATION_ISSUES,
+    __packageDir: intDir,
   };
   projectLoadMock.mockResolvedValue({
     integrations: [INTEGRATION_NAME],
@@ -162,7 +186,9 @@ describe('component() — integration ownership via config', () => {
     expect(result.data.name).toBe('MetaAppShell');
     expect(result.data.package).toBe(INTEGRATION_NAME);
     expect(result.data.sourceAvailable).toBe(true);
-    expect(result.data.import).toBe(`${INTEGRATION_NAME}/MetaAppShell`);
+    // This fixture declares no `exports`, so there is no subpath to import
+    // from and the specifier is the package root.
+    expect(result.data.import).toBe(INTEGRATION_NAME);
   });
 
   it('--package resolves the integration component', async () => {
@@ -217,6 +243,40 @@ describe('component() — integration ownership via config', () => {
     expect(result.data.package).toBe(INTEGRATION_NAME);
   });
 
+  it('resolves the import specifier against the package exports map', async () => {
+    // The doc sits in a `Toolbar` directory but the component is
+    // `ToolbarSearch`, so a specifier built from the component name would
+    // point at a subpath the package does not export.
+    createFixture({
+      packageExports: {'.': './index.js', './Toolbar': './components/Toolbar/index.js'},
+      entryPoint: {directory: 'Toolbar', component: 'ToolbarSearch'},
+    });
+    const result = await component('ToolbarSearch', {cwd: tmpDir});
+    expect(result.data.import).toBe(`${INTEGRATION_NAME}/Toolbar`);
+  });
+
+  it('falls back to the package root when the directory is not an exported subpath', async () => {
+    createFixture({
+      packageExports: {'.': './index.js'},
+      entryPoint: {directory: 'Toolbar', component: 'ToolbarSearch'},
+    });
+    const result = await component('ToolbarSearch', {cwd: tmpDir});
+    expect(result.data.import).toBe(INTEGRATION_NAME);
+  });
+
+  it('keeps a specifier the doc file states for itself', async () => {
+    createFixture({
+      packageExports: {'.': './index.js', './Toolbar': './components/Toolbar/index.js'},
+      entryPoint: {
+        directory: 'Toolbar',
+        component: 'ToolbarSearch',
+        importSpec: `${INTEGRATION_NAME}/Toolbar/Search`,
+      },
+    });
+    const result = await component('ToolbarSearch', {cwd: tmpDir});
+    expect(result.data.import).toBe(`${INTEGRATION_NAME}/Toolbar/Search`);
+  });
+
   it('JSON list includes integration components as {name, package} objects', async () => {
     createFixture();
     const result = await component(undefined, {cwd: tmpDir, list: true});

package/clients/cli/commands/theme-build.doc.mjs

@@ -19,7 +19,7 @@ export const doc = {
     'Compiles a file that calls defineTheme() into a scoped CSS file, a JS module, and ' +
     'type declarations: the exact CSS the <Theme> runtime emits. Takes any number of theme ' +
     'files and compiles them in one process, in argument order, stopping at the first ' +
-    'failure — an app with several themes does not need a shell loop. With --check it writes ' +
+    'failure; an app with several themes does not need a shell loop. With --check it writes ' +
     'nothing and instead reports whether the committed outputs have drifted from source. ' +
     'When a separate build step emits the icon registry, --icons-specifier declares the ' +
     'fully specified module path that the generated JS should import.',

package/foundation/agent-docs/agent-docs.d.mts

@@ -102,16 +102,28 @@ export function detectStylingSystem(targetDir: string): "stylex" | "tailwind" |
  * configured (see {@link detectStylingSystem}) so the agent never reaches for a
  * styling path that isn't compiled here.
  *
+ * `topics` is the project's doc-topic list. Passing it is what puts an
+ * integration's topics — including one it contributed in place of a built-in —
+ * in front of the agent by name; without it the block falls back to the CLI's
+ * own topics, because resolving a project's catalog is async and this is not.
+ *
+ * Either way the list now includes the hyphenated topics. The fallback scan
+ * matched `\w+`, which does not match `-`, so five real topics were missing
+ * from every block ever written — `getting-started` and `cli-integrations`
+ * among them. An agent cannot ask for a topic it was never told about, and
+ * `getting-started` is the one it should reach for first.
+ *
  * @param {string} version
- * @param {{coreDir?: string|null, invocation?: string, stylingSystem?: 'stylex'|'tailwind'|'css', zh?: boolean, lang?: string}} [options]
+ * @param {{coreDir?: string|null, invocation?: string, stylingSystem?: 'stylex'|'tailwind'|'css', zh?: boolean, lang?: string, topics?: string[]}} [options]
  * @returns {string}
  */
-export function generateCompressedIndex(version: string, { coreDir, invocation, stylingSystem }?: {
+export function generateCompressedIndex(version: string, { coreDir, invocation, stylingSystem, topics }?: {
     coreDir?: string | null;
     invocation?: string;
     stylingSystem?: "stylex" | "tailwind" | "css";
     zh?: boolean;
     lang?: string;
+    topics?: string[];
 }): string;
 /**
  * Get Astryx version from core package.
@@ -186,12 +198,16 @@ export function removeAgentDocs(targetDir: string): void;
  * @param {string} [options.agent] - Tool preset: 'claude', 'cursor', 'codex', 'hermes', 'all'
  * @param {string[]} [options.paths] - Explicit paths (overrides agent/auto-detect)
  * @param {boolean} [options.onlyReplace] - Only update files that already have Astryx markers (for upgrades)
+ * @param {string[]} [options.topics] - Doc topics to list in the block; defaults
+ *   to the CLI's own. Pass the project's catalog (`(await project.docs()).names()`)
+ *   so an integration's topics reach the agent.
  * @returns {string[]} List of files written
  */
-export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, onlyReplace }?: {
+export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, onlyReplace, topics }?: {
     zh?: boolean | undefined;
     lang?: string | undefined;
     agent?: string | undefined;
     paths?: string[] | undefined;
     onlyReplace?: boolean | undefined;
+    topics?: string[] | undefined;
 }): string[];

package/foundation/agent-docs/agent-docs.mjs

@@ -299,11 +299,22 @@ export function detectStylingSystem(targetDir) {
  * configured (see {@link detectStylingSystem}) so the agent never reaches for a
  * styling path that isn't compiled here.
  *
+ * `topics` is the project's doc-topic list. Passing it is what puts an
+ * integration's topics — including one it contributed in place of a built-in —
+ * in front of the agent by name; without it the block falls back to the CLI's
+ * own topics, because resolving a project's catalog is async and this is not.
+ *
+ * Either way the list now includes the hyphenated topics. The fallback scan
+ * matched `\w+`, which does not match `-`, so five real topics were missing
+ * from every block ever written — `getting-started` and `cli-integrations`
+ * among them. An agent cannot ask for a topic it was never told about, and
+ * `getting-started` is the one it should reach for first.
+ *
  * @param {string} version
- * @param {{coreDir?: string|null, invocation?: string, stylingSystem?: 'stylex'|'tailwind'|'css', zh?: boolean, lang?: string}} [options]
+ * @param {{coreDir?: string|null, invocation?: string, stylingSystem?: 'stylex'|'tailwind'|'css', zh?: boolean, lang?: string, topics?: string[]}} [options]
  * @returns {string}
  */
-export function generateCompressedIndex(version, {coreDir, invocation = getCliInvocation(), stylingSystem = 'css'} = {}) {
+export function generateCompressedIndex(version, {coreDir, invocation = getCliInvocation(), stylingSystem = 'css', topics} = {}) {
   const run = invocation;
   const lines = [MARKER_START];
 
@@ -377,13 +388,18 @@ export function generateCompressedIndex(version, {coreDir, invocation = getCliIn
   lines.push(`  component --list   ${componentCount} components by category`);
   lines.push('  template --list    page + block recipes');
   const docsDir = path.join(CLI_ROOT, 'assets', 'docs');
-  if (fs.existsSync(docsDir)) {
-    const topics = fs.readdirSync(docsDir)
-      .map(f => f.match(/^(\w+)\.doc\.mjs$/))
-      .filter(/** @returns {m is RegExpMatchArray} */ (m) => m != null)
-      .map(m => m[1])
-      .sort();
-    if (topics.length > 0) lines.push(`  docs <topic>       ${topics.join(', ')}`);
+  const resolvedTopics =
+    topics ??
+    (fs.existsSync(docsDir)
+      ? fs
+          .readdirSync(docsDir)
+          .map(f => f.match(/^([\w-]+)\.doc\.mjs$/))
+          .filter(/** @returns {m is RegExpMatchArray} */ (m) => m != null)
+          .map(m => m[1])
+          .sort()
+      : []);
+  if (resolvedTopics.length > 0) {
+    lines.push(`  docs <topic>       ${resolvedTopics.join(', ')}`);
   }
   lines.push('  swizzle <Name>     eject component source for deep customization');
   lines.push('  upgrade --apply    run after any @astryxdesign/core bump');
@@ -566,14 +582,17 @@ export function removeAgentDocs(targetDir) {
  * @param {string} [options.agent] - Tool preset: 'claude', 'cursor', 'codex', 'hermes', 'all'
  * @param {string[]} [options.paths] - Explicit paths (overrides agent/auto-detect)
  * @param {boolean} [options.onlyReplace] - Only update files that already have Astryx markers (for upgrades)
+ * @param {string[]} [options.topics] - Doc topics to list in the block; defaults
+ *   to the CLI's own. Pass the project's catalog (`(await project.docs()).names()`)
+ *   so an integration's topics reach the agent.
  * @returns {string[]} List of files written
  */
-export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onlyReplace = false} = {}) {
+export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onlyReplace = false, topics} = {}) {
   const coreDir = findCoreDir(targetDir);
   const version = getXdsVersion(coreDir);
   const invocation = getCliInvocation(targetDir);
   const stylingSystem = detectStylingSystem(targetDir);
-  const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, invocation, stylingSystem});
+  const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, invocation, stylingSystem, topics});
   /** @type {string[]} */
   const written = [];
 

package/foundation/agent-docs/agent-docs.test.mjs

@@ -117,6 +117,44 @@ describe('generateCompressedIndex', () => {
     // The header defines the mapping; the bare "run every command as `npx astryx`" footgun must be absent.
     expect(result).not.toContain('npx astryx <cmd>');
   });
+
+  /** The `docs <topic>  a, b, c` line of the block. */
+  function topicLine(block) {
+    return (
+      block.split('\n').find(line => line.trimStart().startsWith('docs <topic>')) ?? ''
+    );
+  }
+
+  it('names the hyphenated topics, which the scan used to drop', () => {
+    // The fallback scan matched `\w+`, which does not match `-`, so five real
+    // topics were missing from every block ever written. An agent cannot ask
+    // for a topic it was never told about, and `getting-started` — the one it
+    // should reach for first — was one of them.
+    const line = topicLine(generateCompressedIndex('1.0.0'));
+    for (const topic of [
+      'getting-started',
+      'cli-integrations',
+      'browser-support',
+      'styling-libraries',
+      'working-with-ai',
+    ]) {
+      expect(line).toContain(topic);
+    }
+  });
+
+  it('lists the topics it is given, so an integration’s reach the agent', () => {
+    const line = topicLine(
+      generateCompressedIndex('1.0.0', {topics: ['tokens', 'deploying']}),
+    );
+    expect(line).toContain('tokens, deploying');
+    // The project's catalog replaces the built-in scan rather than adding to it:
+    // a topic an integration replaced must not also be listed under its old name.
+    expect(line).not.toContain('typography');
+  });
+
+  it('omits the line entirely when the project has no topics', () => {
+    expect(topicLine(generateCompressedIndex('1.0.0', {topics: []}))).toBe('');
+  });
 });
 
 describe('detectStylingSystem', () => {

package/foundation/config/project.d.mts

@@ -99,6 +99,21 @@ export class Project {
      * @returns {Promise<Array<object>>}
      */
     templates(): Promise<Array<object>>;
+    /**
+     * The CLI's own doc topics plus the ones the configured integrations
+     * contribute, resolved into one catalog: additions, replacements (with the
+     * replaced name left as an alias), and extensions merged in configuration
+     * order. Same skip+warn policy as its siblings — a broken integration
+     * contributes no topics and its issues are collected. Memoized per instance.
+     *
+     * Two problems can only be seen with every integration in hand, so they are
+     * raised here rather than in the per-integration validators: a topic that
+     * collides with one another package already provides, and a `replaces` /
+     * `extends` that names a topic nothing provides.
+     *
+     * @returns {Promise<DocsCatalog>}
+     */
+    docs(): Promise<DocsCatalog>;
     /**
      * Core registry transforms + integration codemods for an upgrade range.
      * Wraps getTransformsBetween (core) and discoverIntegrationCodemods /
@@ -152,3 +167,4 @@ export class Project {
 export type ProjectIntegrationIssue = import("../integrations/issue").AstryxIntegrationIssue & {
     package: string;
 };
+import { DocsCatalog } from '../discovery/docs-discovery.mjs';

package/foundation/config/project.mjs

@@ -6,16 +6,16 @@
  * `Project` is the one entry point a command uses to read everything it needs
  * about a consumer's project: the validated config surface, the configured
  * integrations, and the resolved discovery sets (components, templates,
- * codemods) — plus issue routing (issuesUrl) and the accumulated integration
- * issues. It replaces the old `loadConfig(cwd)` plain-object loader and the
- * per-command fan-out into the various discovery helpers.
+ * codemods, docs) — plus issue routing (issuesUrl) and the accumulated
+ * integration issues. It replaces the old `loadConfig(cwd)` plain-object loader
+ * and the per-command fan-out into the various discovery helpers.
  *
  * Design:
  *   - `Project.load(cwd, {cache})` is the async factory (constructors can't be
  *     async). It does what loadConfig did — find the config sibling-of
  *     package.json, import + validate it, load the configured integrations —
  *     and nothing more. Discovery is LAZY.
- *   - Discovery methods (components/templates/codemods) are MEMOIZED per
+ *   - Discovery methods (components/templates/codemods/docs) are MEMOIZED per
  *     instance (via the pluggable cache) and orchestrate the EXISTING discovery
  *     functions — Project never reimplements discovery.
  *   - SKIP + WARN policy: as a discovery method runs, per-integration work is
@@ -45,6 +45,10 @@ import {
   discoverAll as discoverTemplates,
   discoverIntegrationTemplatesForOne,
 } from '../discovery/template-adapter.mjs';
+import {
+  DocsCatalog,
+  discoverIntegrationDocs,
+} from '../discovery/docs-discovery.mjs';
 import {getTransformsBetween} from '../../assets/codemods/registry.mjs';
 import {
   discoverIntegrationCodemods,
@@ -454,6 +458,63 @@ export class Project {
     });
   }
 
+  /**
+   * The CLI's own doc topics plus the ones the configured integrations
+   * contribute, resolved into one catalog: additions, replacements (with the
+   * replaced name left as an alias), and extensions merged in configuration
+   * order. Same skip+warn policy as its siblings — a broken integration
+   * contributes no topics and its issues are collected. Memoized per instance.
+   *
+   * Two problems can only be seen with every integration in hand, so they are
+   * raised here rather than in the per-integration validators: a topic that
+   * collides with one another package already provides, and a `replaces` /
+   * `extends` that names a topic nothing provides.
+   *
+   * @returns {Promise<DocsCatalog>}
+   */
+  async docs() {
+    return this.#memo('docs', async () => {
+      const catalog = DocsCatalog.fromBuiltins();
+
+      for (const integration of this.#loadedIntegrations) {
+        await this.#collectIssues(integration);
+        const pkg = this.#pkgLabel(integration);
+        const hadError = this.#issues.some(
+          i => i.package === pkg && i.severity === 'error',
+        );
+        if (hadError) continue;
+        if (!integration?.docs) continue;
+        try {
+          const {records, errors} = await discoverIntegrationDocs(integration);
+          for (const e of errors) {
+            this.#pushIssue(pkg, {
+              code: 'invalid_doc',
+              severity: 'error',
+              message: e.message,
+            });
+          }
+          // Any unusable doc withdraws the whole package's topics, matching
+          // how a bad template withdraws its package's templates: a partial
+          // docs contribution is the state where a `replaces` silently does
+          // nothing and a reader gets the topic it was meant to replace.
+          if (errors.length > 0) continue;
+          for (const record of records) {
+            const issue = catalog.add(record);
+            if (issue) this.#pushIssue(pkg, issue);
+          }
+        } catch (err) {
+          this.#pushIssue(pkg, {
+            code: 'invalid_doc',
+            severity: 'error',
+            message: errorMessage(err),
+          });
+        }
+      }
+
+      return catalog;
+    });
+  }
+
   /**
    * Core registry transforms + integration codemods for an upgrade range.
    * Wraps getTransformsBetween (core) and discoverIntegrationCodemods /