@astryxdesign/cli 0.4.5-canary.ee6d68d → 0.4.5-canary.fba7b40

package/api/docs/_adapter.d.mts

@@ -2,9 +2,19 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * @returns {Record<string, string>}
+ * The project's topics: the built-in ones plus whatever the configured
+ * integrations contribute.
+ *
+ * A docs read must not depend on a healthy project config. `astryx docs
+ * tokens` answered without loading anything before integrations could
+ * contribute topics, and it still answers when the config is unreadable — the
+ * built-in topics are the floor, and the integration issues surface on the
+ * commands that own them.
+ *
+ * @param {string} [cwd]
+ * @returns {Promise<DocsCatalog>}
  */
-export function discoverTopics(): Record<string, string>;
+export function loadDocsCatalog(cwd?: string): Promise<DocsCatalog>;
 /**
  * @param {string} docPath
  * @param {{lang?: string|null}} [opts]
@@ -14,18 +24,35 @@ export function loadReferenceDocs(docPath: string, { lang }?: {
     lang?: string | null;
 }): Promise<import("./docs.type.mjs").DocsDetailResponse["data"]>;
 /**
- * Discover topics, resolve `topic` to its doc file (throwing `ERR_UNKNOWN_TOPIC`
- * when unmatched), and load that topic's reference doc with any --dense/--zh
- * overlay applied. Shared by the detail and section leaves so topic normalization
- * and unknown-topic handling live in exactly one place.
+ * Load one catalog entry: its own doc, plus any extension an integration
+ * merged onto it, in configuration order.
+ *
+ * A localization overlay applies to each file before the extensions are
+ * merged, so an extension written in the base language stays readable under
+ * `--dense`/`--zh` (it replaces its own sections and leaves the rest
+ * translated) rather than being dropped.
+ *
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {{lang?: string|null}} [opts]
+ * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ */
+export function loadTopicDoc(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, { lang }?: {
+    lang?: string | null;
+}): Promise<import("./docs.type.mjs").DocsDetailResponse["data"]>;
+/**
+ * Resolve `topic` against the project's catalog (throwing `ERR_UNKNOWN_TOPIC`
+ * when unmatched), and load it with any --dense/--zh overlay and any
+ * integration extension applied. Shared by the detail and section leaves so
+ * topic normalization and unknown-topic handling live in exactly one place.
  *
  * @param {string} topic
  * @param {object} [options]
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
  * @returns {Promise<{
- *   topics: Record<string, string>,
+ *   catalog: DocsCatalog,
  *   docsData: import('./docs.type.mjs').DocsDetailResponse['data'],
  * }>}
  */
@@ -33,7 +60,9 @@ export function resolveTopicDocs(topic: string, options?: {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
+    cwd?: string | undefined;
 }): Promise<{
-    topics: Record<string, string>;
+    catalog: DocsCatalog;
     docsData: import("./docs.type.mjs").DocsDetailResponse["data"];
 }>;
+import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';

package/api/docs/_adapter.mjs

@@ -3,35 +3,50 @@
 /**
  * @file Shared doc-loading and topic-resolution helpers for the docs leaves.
  *
- * @input packages/cli/assets/docs/{topic}.doc.mjs and, when a --dense/--zh overlay is
- *   requested, the sibling {topic}.doc.dense.mjs / {topic}.doc.zh.mjs.
- * @output Topic discovery map, overlay-merged reference-doc data, and a combined
- *   resolve step ({topics, docsData}) that the detail and section leaves share.
+ * @input The project's doc catalog — the CLI's own
+ *   packages/cli/assets/docs/{topic}.doc.mjs plus every topic the configured
+ *   integrations contribute — and, when a --dense/--zh overlay is requested,
+ *   the sibling {topic}.doc.dense.mjs / {topic}.doc.zh.mjs.
+ * @output Catalog access, overlay- and extension-merged reference-doc data,
+ *   and a combined resolve step ({catalog, docsData}) that the detail and
+ *   section leaves share.
  * @position Sits beside docs.mjs (api/docs/). Owns everything ≥2 leaves need so
- *   no leaf re-implements discovery, overlay merging, or unknown-topic handling.
+ *   no leaf re-implements resolution, overlay merging, or unknown-topic
+ *   handling. Discovery itself lives in foundation/discovery/docs-discovery,
+ *   which api/search and the agent-docs block read through the same catalog.
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
-import {CLI_ROOT} from '../../foundation/fs/paths.mjs';
+import {Project} from '../../foundation/config/project.mjs';
+import {
+  DocsCatalog,
+  mergeTopic,
+} from '../../foundation/discovery/docs-discovery.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
-const DOCS_DIR = path.join(CLI_ROOT, 'assets', 'docs');
-
 /**
- * @returns {Record<string, string>}
+ * The project's topics: the built-in ones plus whatever the configured
+ * integrations contribute.
+ *
+ * A docs read must not depend on a healthy project config. `astryx docs
+ * tokens` answered without loading anything before integrations could
+ * contribute topics, and it still answers when the config is unreadable — the
+ * built-in topics are the floor, and the integration issues surface on the
+ * commands that own them.
+ *
+ * @param {string} [cwd]
+ * @returns {Promise<DocsCatalog>}
  */
-export function discoverTopics() {
-  /** @type {Record<string, string>} */
-  const topics = Object.create(null);
-  if (!fs.existsSync(DOCS_DIR)) return topics;
-  for (const file of fs.readdirSync(DOCS_DIR)) {
-    const match = file.match(/^([\w-]+)\.doc\.mjs$/);
-    if (match) topics[match[1]] = path.join(DOCS_DIR, file);
+export async function loadDocsCatalog(cwd = process.cwd()) {
+  try {
+    const project = await Project.load(cwd);
+    return await project.docs();
+  } catch {
+    return DocsCatalog.fromBuiltins();
   }
-  return topics;
 }
 
 /**
@@ -41,7 +56,7 @@ export function discoverTopics() {
  */
 export async function loadReferenceDocs(docPath, {lang} = {}) {
   const mod = await import(pathToFileURL(docPath).href);
-  const docs = mod.docs;
+  const docs = mod.docs ?? mod.default;
   if (!lang || lang === 'en') return docs;
 
   const dir = path.dirname(docPath);
@@ -96,46 +111,60 @@ export async function loadReferenceDocs(docPath, {lang} = {}) {
 }
 
 /**
- * Discover topics, resolve `topic` to its doc file (throwing `ERR_UNKNOWN_TOPIC`
- * when unmatched), and load that topic's reference doc with any --dense/--zh
- * overlay applied. Shared by the detail and section leaves so topic normalization
- * and unknown-topic handling live in exactly one place.
+ * Load one catalog entry: its own doc, plus any extension an integration
+ * merged onto it, in configuration order.
+ *
+ * A localization overlay applies to each file before the extensions are
+ * merged, so an extension written in the base language stays readable under
+ * `--dense`/`--zh` (it replaces its own sections and leaves the rest
+ * translated) rather than being dropped.
+ *
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {{lang?: string|null}} [opts]
+ * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ */
+export async function loadTopicDoc(entry, {lang} = {}) {
+  let doc = await loadReferenceDocs(entry.path, {lang});
+  for (const extension of entry.extensions) {
+    doc = mergeTopic(doc, await loadReferenceDocs(extension.path, {lang}));
+  }
+  return doc;
+}
+
+/**
+ * Resolve `topic` against the project's catalog (throwing `ERR_UNKNOWN_TOPIC`
+ * when unmatched), and load it with any --dense/--zh overlay and any
+ * integration extension applied. Shared by the detail and section leaves so
+ * topic normalization and unknown-topic handling live in exactly one place.
  *
  * @param {string} topic
  * @param {object} [options]
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
  * @returns {Promise<{
- *   topics: Record<string, string>,
+ *   catalog: DocsCatalog,
  *   docsData: import('./docs.type.mjs').DocsDetailResponse['data'],
  * }>}
  */
 export async function resolveTopicDocs(topic, options = {}) {
-  const {lang = null, zh = false, dense = false} = options;
+  const {lang = null, zh = false, dense = false, cwd} = options;
   const effectiveLang = lang || (dense ? 'dense' : zh ? 'zh' : null);
-  const topics = discoverTopics();
+  const catalog = await loadDocsCatalog(cwd);
 
-  // A public API caller could pass a non-string topic; `.toLowerCase()` below
-  // would throw a raw TypeError (no ERR_* code → downgrades to ERR_UNKNOWN).
-  // Surface the same stable code the unknown-topic path uses.
-  if (typeof topic !== 'string') {
+  // A public API caller could pass a non-string topic; `resolve` answers
+  // undefined for one, which lands on the same stable code as an unknown name
+  // rather than a raw TypeError (which downgrades to ERR_UNKNOWN).
+  const entry = catalog.resolve(topic);
+  if (!entry) {
     throw new AstryxError(
       `Unknown topic "${String(topic)}"`,
-      Object.keys(topics).map(t => ({name: t, reason: 'available topic'})),
-      ERROR_CODES.ERR_UNKNOWN_TOPIC,
-    );
-  }
-
-  const normalized = topic.toLowerCase();
-  if (!topics[normalized]) {
-    throw new AstryxError(
-      `Unknown topic "${topic}"`,
-      Object.keys(topics).map(t => ({name: t, reason: 'available topic'})),
+      catalog.names().map(t => ({name: t, reason: 'available topic'})),
       ERROR_CODES.ERR_UNKNOWN_TOPIC,
     );
   }
 
-  const docsData = await loadReferenceDocs(topics[normalized], {lang: effectiveLang});
-  return {topics, docsData};
+  const docsData = await loadTopicDoc(entry, {lang: effectiveLang});
+  return {catalog, docsData};
 }

package/api/docs/detail/detail.d.mts

@@ -7,10 +7,12 @@
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
  * @returns {Promise<import('../docs.type.mjs').DocsDetailResponse>}
  */
 export function detail(topic: string, options?: {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
+    cwd?: string | undefined;
 }): Promise<import("../docs.type.mjs").DocsDetailResponse>;

package/api/docs/detail/detail.mjs

@@ -11,17 +11,19 @@
  *   discovery/loading/topic-resolution with the section leaf via _adapter.mjs.
  */
 
-import {pathToFileURL} from 'node:url';
-import {resolveTopicDocs} from '../_adapter.mjs';
+import {loadTopicDoc, resolveTopicDocs} from '../_adapter.mjs';
 
 /**
  * Resolve token-ref blocks by inlining the referenced section's table.
  * This allows section docs to reference token tables without duplicating data.
+ *
+ * The reference is resolved through the catalog, so a topic may point at one
+ * an integration contributed (or replaced) rather than only at a built-in.
  * @param {import('../docs.type.mjs').DocsDetailResponse['data']} docsData
- * @param {Record<string, string>} topics
+ * @param {import('../../../foundation/discovery/docs-discovery.mjs').DocsCatalog} catalog
  * @returns {Promise<import('../docs.type.mjs').DocsDetailResponse['data']>}
  */
-async function resolveTokenRefs(docsData, topics) {
+async function resolveTokenRefs(docsData, catalog) {
   const resolved = {...docsData, sections: [...docsData.sections]};
   for (let si = 0; si < resolved.sections.length; si++) {
     const section = resolved.sections[si];
@@ -29,13 +31,12 @@ async function resolveTokenRefs(docsData, topics) {
     const newContent = [];
     for (const block of section.content) {
       if (block.type === 'token-ref') {
-        const refPath = topics[block.topic];
-        if (!refPath) {
+        const refEntry = catalog.resolve(block.topic);
+        if (!refEntry) {
           newContent.push({type: 'prose', text: `[token-ref: unknown topic "${block.topic}"]`});
           continue;
         }
-        const refMod = await import(pathToFileURL(refPath).href);
-        const refDocs = refMod.docs;
+        const refDocs = await loadTopicDoc(refEntry);
         const refSection = refDocs.sections.find(
           (/** @type {import('@astryxdesign/cli/authoring').ReferenceSection} */ s) =>
             s.title.toLowerCase() === block.section.toLowerCase(),
@@ -72,10 +73,11 @@ async function resolveTokenRefs(docsData, topics) {
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
  * @returns {Promise<import('../docs.type.mjs').DocsDetailResponse>}
  */
 export async function detail(topic, options = {}) {
-  const {topics, docsData} = await resolveTopicDocs(topic, options);
-  const resolved = await resolveTokenRefs(docsData, topics);
+  const {catalog, docsData} = await resolveTopicDocs(topic, options);
+  const resolved = await resolveTokenRefs(docsData, catalog);
   return {type: 'docs.detail', data: resolved};
 }

package/api/docs/detail/section/section.d.mts

@@ -8,10 +8,12 @@
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
  * @returns {Promise<import('../../docs.type.mjs').DocsDetailSectionResponse>}
  */
 export function section(topic: string, sectionName: string, options?: {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
+    cwd?: string | undefined;
 }): Promise<import("../../docs.type.mjs").DocsDetailSectionResponse>;

package/api/docs/detail/section/section.mjs

@@ -24,6 +24,7 @@ import {resolveTopicDocs} from '../../_adapter.mjs';
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
  * @returns {Promise<import('../../docs.type.mjs').DocsDetailSectionResponse>}
  */
 export async function section(topic, sectionName, options = {}) {

package/api/docs/docs.d.mts

@@ -8,6 +8,7 @@
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
  * @returns {Promise<
  *   import('./docs.type.mjs').DocsListResponse |
  *   import('./docs.type.mjs').DocsDetailResponse |
@@ -18,6 +19,7 @@ export function docs(topic?: string, section?: string, options?: {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
+    cwd?: string | undefined;
 }): Promise<import("./docs.type.mjs").DocsListResponse | import("./docs.type.mjs").DocsDetailResponse | import("./docs.type.mjs").DocsDetailSectionResponse>;
 import { list } from './list/list.mjs';
 import { detail } from './detail/detail.mjs';

package/api/docs/docs.doc.mjs

@@ -18,7 +18,10 @@ export const doc = {
     'Routes on its arguments: no topic lists every reference-doc topic; a topic ' +
     'returns that full ReferenceDoc (with token-ref blocks inlined); a topic ' +
     'plus a section returns the first section whose title contains the ' +
-    '(case-insensitive) query. Overlay options select localized or dense variants.',
+    '(case-insensitive) query. The topic set is the CLI\'s own docs plus the ' +
+    'ones the project\'s configured integrations contribute — including any ' +
+    'topic an integration replaces or extends — so it depends on the cwd. ' +
+    'Overlay options select localized or dense variants.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsDetailResponse | DocsDetailSectionResponse>',
@@ -60,12 +63,18 @@ export const doc = {
       type: 'boolean',
       description: 'Return the token-efficient dense doc variant.',
     },
+    {
+      name: 'options.cwd',
+      type: 'string',
+      description:
+        "Project directory whose configured integrations contribute topics. Defaults to process.cwd(); an unreadable config falls back to the CLI's own topics.",
+    },
   ],
   returns: [
     {
       type: 'docs.list',
       description:
-        'All available reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.',
+        'All available reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order.',
     },
     {
       type: 'docs.detail',

package/api/docs/docs.mjs

@@ -29,6 +29,7 @@ export {list, detail, sectionLeaf as section};
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {string} [options.cwd]
  * @returns {Promise<
  *   import('./docs.type.mjs').DocsListResponse |
  *   import('./docs.type.mjs').DocsDetailResponse |
@@ -36,7 +37,7 @@ export {list, detail, sectionLeaf as section};
  * >}
  */
 export async function docs(topic, section, options = {}) {
-  if (!topic) return list();
+  if (!topic) return list(options);
   if (section) return sectionLeaf(topic, section, options);
   return detail(topic, options);
 }

package/api/docs/docs.type.d.mts

@@ -11,6 +11,16 @@ export type DocsListResponse = {
 export type DocsListEntry = {
     topic: string;
     description: string;
+    /**
+     * the package that owns this topic —
+     * '@astryxdesign/cli' for a built-in one, else the contributing integration
+     */
+    package: string;
+    /**
+     * the topic this one took the place of, when it
+     * was contributed as a replacement
+     */
+    replaces?: string | undefined;
 };
 /**
  * xds --json docs <topic>
@@ -33,4 +43,9 @@ export type DocsOptions = {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
+    /**
+     * project directory whose configured integrations
+     * contribute topics; defaults to process.cwd()
+     */
+    cwd?: string | undefined;
 };

package/api/docs/docs.type.mjs

@@ -23,6 +23,10 @@
  * @typedef {object} DocsListEntry
  * @property {string} topic
  * @property {string} description
+ * @property {string} package the package that owns this topic —
+ *   '@astryxdesign/cli' for a built-in one, else the contributing integration
+ * @property {string} [replaces] the topic this one took the place of, when it
+ *   was contributed as a replacement
  */
 
 /**
@@ -45,6 +49,8 @@
  * @property {string} [lang]
  * @property {boolean} [zh]
  * @property {boolean} [dense]
+ * @property {string} [cwd] project directory whose configured integrations
+ *   contribute topics; defaults to process.cwd()
  */
 
 export {};

package/api/docs/integrationDocs.test.mjs

@@ -0,0 +1,208 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file End-to-end tests for integration-contributed doc topics: a scaffolded
+ * consumer project whose configured integration ships a `docs` root, read back
+ * through the public surfaces — `docs()`, `search()`, and the agent-docs block.
+ *
+ * The unit-level rules (what a docs root contributes, what the catalog does
+ * with `replaces`/`extends`) are covered in
+ * foundation/discovery/docs-discovery.test.mjs. What is pinned here is that a
+ * contributed topic is indistinguishable from a built-in one at the surfaces
+ * an agent actually reads.
+ *
+ * Fixtures live under a repo-local temp dir, not /tmp, because Vite refuses to
+ * dynamically import a module from outside the project root.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {docs} from './docs.mjs';
+import {search} from '../search/search.mjs';
+import {loadDocsCatalog} from './_adapter.mjs';
+import {AstryxError} from '../error.mjs';
+
+const SLOW = 30_000;
+
+let tmpDir;
+
+/** A minimal, valid topic. */
+function topic(fields) {
+  return {
+    type: 'generic',
+    name: 'deploying',
+    title: 'Deploying',
+    description: 'How to ship an app built with Acme widgets.',
+    category: 'guide',
+    sections: [
+      {title: 'Overview', content: [{type: 'prose', text: 'Push the button.'}]},
+    ],
+    ...fields,
+  };
+}
+
+/**
+ * A consumer project that configures one integration, optionally with a docs
+ * root holding the given topics.
+ * @param {Record<string, object|string>} [topics] file name → doc
+ * @param {{config?: string}} [options]
+ */
+function scaffold(topics, {config} = {}) {
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    config ?? "export default {integrations: ['@acme/widgets']};\n",
+  );
+
+  const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(pkgDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default ${JSON.stringify(topics ? {docs: './docs'} : {})};\n`,
+  );
+
+  if (topics) {
+    const docsDir = path.join(pkgDir, 'docs');
+    fs.mkdirSync(docsDir, {recursive: true});
+    for (const [file, doc] of Object.entries(topics)) {
+      fs.writeFileSync(
+        path.join(docsDir, file),
+        typeof doc === 'string'
+          ? doc
+          : `export const docs = ${JSON.stringify(doc, null, 2)};\n`,
+      );
+    }
+  }
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-integration-docs-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('integration-contributed topics', () => {
+  it('lists and reads like a built-in topic, naming its owner', async () => {
+    scaffold({'deploying.doc.mjs': topic()});
+
+    const listed = await docs(undefined, undefined, {cwd: tmpDir});
+    const entry = listed.data.find(t => t.topic === 'deploying');
+    expect(entry).toMatchObject({
+      topic: 'deploying',
+      description: 'How to ship an app built with Acme widgets.',
+      package: '@acme/widgets',
+    });
+    // The built-in topics keep their own owner.
+    expect(listed.data.find(t => t.topic === 'tokens').package).toBe('@astryxdesign/cli');
+
+    const detail = await docs('deploying', undefined, {cwd: tmpDir});
+    expect(detail.type).toBe('docs.detail');
+    expect(detail.data.sections[0].content[0].text).toBe('Push the button.');
+
+    const section = await docs('deploying', 'overview', {cwd: tmpDir});
+    expect(section.data.title).toBe('Overview');
+  }, SLOW);
+
+  it('is invisible to a project that does not configure the integration', async () => {
+    scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {};\n'});
+    const listed = await docs(undefined, undefined, {cwd: tmpDir});
+    expect(listed.data.some(t => t.topic === 'deploying')).toBe(false);
+  }, SLOW);
+
+  it('serves the replacement of a built-in topic, and says what it replaced', async () => {
+    scaffold({
+      'getting-started.doc.mjs': topic({
+        name: 'getting-started',
+        replaces: 'getting-started',
+        title: 'Getting started',
+        description: 'Install Acme widgets.',
+        sections: [
+          {title: 'Install', content: [{type: 'prose', text: 'yarn add @acme/widgets'}]},
+        ],
+      }),
+    });
+
+    const detail = await docs('getting-started', undefined, {cwd: tmpDir});
+    expect(detail.data.sections.map(s => s.title)).toEqual(['Install']);
+    expect(detail.data.sections[0].content[0].text).toBe('yarn add @acme/widgets');
+
+    const listed = await docs(undefined, undefined, {cwd: tmpDir});
+    const entries = listed.data.filter(t => t.topic === 'getting-started');
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      package: '@acme/widgets',
+      replaces: 'getting-started',
+    });
+  }, SLOW);
+
+  it('keeps the replaced name resolving when the replacement renames it', async () => {
+    scaffold({
+      'setup.doc.mjs': topic({name: 'setup', replaces: 'getting-started'}),
+    });
+    const byOldName = await docs('getting-started', undefined, {cwd: tmpDir});
+    const byNewName = await docs('setup', undefined, {cwd: tmpDir});
+    expect(byOldName.data.name).toBe('setup');
+    expect(byNewName.data.name).toBe('setup');
+  }, SLOW);
+
+  it('merges an extension into the topic it extends', async () => {
+    const builtin = await docs('theme');
+    const baseSectionTitle = builtin.data.sections[0].title;
+    scaffold({
+      'theme-internal.doc.mjs': topic({
+        name: 'theme-internal',
+        extends: 'theme',
+        sections: [
+          {title: baseSectionTitle, content: [{type: 'prose', text: 'Use the Acme theme.'}]},
+          {title: 'Acme themes', content: [{type: 'prose', text: 'Three of them.'}]},
+        ],
+      }),
+    });
+
+    const extended = await docs('theme', undefined, {cwd: tmpDir});
+    // The extension is not a topic of its own.
+    expect((await docs(undefined, undefined, {cwd: tmpDir})).data.some(
+      t => t.topic === 'theme-internal',
+    )).toBe(false);
+    expect(extended.data.sections[0].content[0].text).toBe('Use the Acme theme.');
+    expect(extended.data.sections.at(-1).title).toBe('Acme themes');
+    // Everything the extension did not name is still the base doc's.
+    expect(extended.data.sections.length).toBe(builtin.data.sections.length + 1);
+  }, SLOW);
+
+  it('offers the contributed topics as suggestions on an unknown one', async () => {
+    scaffold({'deploying.doc.mjs': topic()});
+    await expect(docs('nope-not-a-topic', undefined, {cwd: tmpDir})).rejects.toBeInstanceOf(
+      AstryxError,
+    );
+    try {
+      await docs('nope-not-a-topic', undefined, {cwd: tmpDir});
+    } catch (err) {
+      expect(err.suggestions.map(s => s.name)).toContain('deploying');
+    }
+  }, SLOW);
+
+  it('indexes a contributed topic in search', async () => {
+    scaffold({'deploying.doc.mjs': topic()});
+    const {data} = await search('deploying', {cwd: tmpDir, type: 'doc'});
+    expect(data.results[0]).toMatchObject({
+      domain: 'doc',
+      name: 'deploying',
+      command: 'astryx docs deploying',
+    });
+  }, SLOW);
+
+  it("falls back to the CLI's own topics when the project config is unreadable", async () => {
+    scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {integrations: 42};\n'});
+    const catalog = await loadDocsCatalog(tmpDir);
+    expect(catalog.resolve('tokens')).toBeTruthy();
+    expect(catalog.resolve('deploying')).toBeUndefined();
+  }, SLOW);
+});

package/api/docs/list/list.d.mts

@@ -2,6 +2,10 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
+ * @param {object} [options]
+ * @param {string} [options.cwd]
  * @returns {Promise<import('../docs.type.mjs').DocsListResponse>}
  */
-export function list(): Promise<import("../docs.type.mjs").DocsListResponse>;
+export function list({ cwd }?: {
+    cwd?: string | undefined;
+}): Promise<import("../docs.type.mjs").DocsListResponse>;