@astryxdesign/cli 0.4.5 → 0.4.6-canary.f1d4034

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @xds/cli
 
+# 0.4.6
+
+#### New Features
+
+- An integration can contribute reference-doc topics: point `docs` at a root in `astryx.integration.*` and every `{topic}.doc.{ts,mjs,js}` under it is served by `astryx docs`, indexed by `astryx search`, and named in the agent-docs block, beside the built-in topics. A topic may also declare `replaces: '<topic>'` to take over an existing one (renaming it leaves the old name resolving as an alias) or `extends: '<topic>'` to merge onto one section by section. A name that collides without declaring either is an `invalid_doc` issue rather than a silent override, and `validate-integration` reports it. (#5311)
+  Also fixes the agent-docs block's topic list, which scanned for `\w+` and so silently dropped every hyphenated topic — `getting-started`, `cli-integrations`, `browser-support`, `styling-libraries` and `working-with-ai` were missing from every block ever written, and an agent cannot ask for a topic it was never told about.
+- Five dashboard page templates: `dashboard-cohort-funnel`, `dashboard-data`, `dashboard-executive-summary`, `dashboard-project-status` and `dashboard-service-monitoring`. Each is a complete page — layout, realistic sample data, and the component choices that go with the shape of the data — so `astryx template <name>` gives you something to edit rather than a blank frame (#5245).
+
+#### Fixes
+
+- `component` built the import specifier for an integration component by joining the package name and the component name, which assumes every component is exported from a subpath named after itself. Components are commonly grouped behind a single entry point named after the concept, so the suggested import pointed at a subpath the package does not export and did not resolve (#4810).
+  The specifier is now resolved against the owning package's `exports` map, keyed on the directory the component's doc file sits in, and falls back to the package root when that directory is not an exported subpath. A specifier a doc file states for itself is also no longer overwritten.
+- The upgrade codemod no longer collapses significant JSX whitespace when it renames an element tag. Renaming `<OldName>` next to text and a `{expression}` (e.g. `hello {name} world`) previously dropped the adjacent space (`hello {name}world`); element-tag renames are now spliced into the output so the surrounding JSX is left untouched (#5149).
+- The XDS-prefix codemod no longer produces a file that will not compile. Dropping the prefix renames `XDSButton` to `Button`, but if the file already had a local binding called `Button` the rewrite collided with it and shadowed one of the two. The import is now aliased instead, so both survive and the file still typechecks (#5225).
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @ejhammond
+- @josephfarina
+- @kentonquatman
+- @rubyycheung
+
+---
+
 # 0.4.5
 
 ---

package/api/component/_adapter.d.mts

@@ -12,6 +12,7 @@
  * @property {any[]} [components]
  * @property {{description?: string}} [usage]
  * @property {any} [theming]
+ * @property {string} [import] set when the doc states its own import specifier
  */
 /**
  * Options object for `loadDocs`, matching its declared parameter shape (used
@@ -29,6 +30,12 @@
  * @property {string|undefined} issuesUrl
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null} integration
  */
+/**
+ * What ownership shaping needs from an owner. The core and legacy-external
+ * paths synthesize a bare `{package, sourcePath}` rather than resolving a full
+ * {@link ComponentOwner}, so everything past those two is optional here.
+ * @typedef {Partial<ComponentOwner> & {package: string, sourcePath: string|null}} OwnershipSubject
+ */
 /**
  * A back-compat external package discovered via `pkg.astryx.docs`.
  * @typedef {{name: string, category: string, docsDir: string}} ExternalPackageRef
@@ -152,15 +159,12 @@ export function extractProps(docs: LoadedComponentDoc): any[];
  * swizzleable source file exists for the owner). Existing doc fields (name,
  * usage, props, …) are preserved.
  * @param {LoadedComponentDoc} docs
- * @param {{package: string, sourcePath: string|null}} owner
+ * @param {OwnershipSubject} owner
  * @param {string} componentName
  * @param {string} coreDir
  * @returns {import('./component.type.mjs').ComponentDetailResponse['data']}
  */
-export function withOwnership(docs: LoadedComponentDoc, owner: {
-    package: string;
-    sourcePath: string | null;
-}, componentName: string, coreDir: string): import("./component.type.mjs").ComponentDetailResponse["data"];
+export function withOwnership(docs: LoadedComponentDoc, owner: OwnershipSubject, componentName: string, coreDir: string): import("./component.type.mjs").ComponentDetailResponse["data"];
 /**
  * When the caller asked for "Code" but the resolved doc is for "CodeBlock"
  * (parent), scope the response to just the matching sub-component. Returns the
@@ -193,6 +197,10 @@ export type LoadedComponentDoc = {
         description?: string;
     } | undefined;
     theming?: any;
+    /**
+     * set when the doc states its own import specifier
+     */
+    import?: string | undefined;
 };
 /**
  * Options object for `loadDocs`, matching its declared parameter shape (used
@@ -215,6 +223,15 @@ export type ComponentOwner = {
     issuesUrl: string | undefined;
     integration: import("../../foundation/integrations/integrations.mjs").LoadedIntegration | null;
 };
+/**
+ * What ownership shaping needs from an owner. The core and legacy-external
+ * paths synthesize a bare `{package, sourcePath}` rather than resolving a full
+ * {@link ComponentOwner}, so everything past those two is optional here.
+ */
+export type OwnershipSubject = Partial<ComponentOwner> & {
+    package: string;
+    sourcePath: string | null;
+};
 /**
  * A back-compat external package discovered via `pkg.astryx.docs`.
  */

package/api/component/_adapter.mjs

@@ -18,6 +18,8 @@
  * deduped, so each leaf stays a thin projection.
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {findCoreDir, discoverExternalPackages} from '../../foundation/fs/paths.mjs';
 import {
@@ -48,6 +50,7 @@ export {CORE_PACKAGE};
  * @property {any[]} [components]
  * @property {{description?: string}} [usage]
  * @property {any} [theming]
+ * @property {string} [import] set when the doc states its own import specifier
  */
 
 /**
@@ -68,6 +71,13 @@ export {CORE_PACKAGE};
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null} integration
  */
 
+/**
+ * What ownership shaping needs from an owner. The core and legacy-external
+ * paths synthesize a bare `{package, sourcePath}` rather than resolving a full
+ * {@link ComponentOwner}, so everything past those two is optional here.
+ * @typedef {Partial<ComponentOwner> & {package: string, sourcePath: string|null}} OwnershipSubject
+ */
+
 /**
  * A back-compat external package discovered via `pkg.astryx.docs`.
  * @typedef {{name: string, category: string, docsDir: string}} ExternalPackageRef
@@ -357,7 +367,7 @@ export function extractProps(docs) {
  * swizzleable source file exists for the owner). Existing doc fields (name,
  * usage, props, …) are preserved.
  * @param {LoadedComponentDoc} docs
- * @param {{package: string, sourcePath: string|null}} owner
+ * @param {OwnershipSubject} owner
  * @param {string} componentName
  * @param {string} coreDir
  * @returns {import('./component.type.mjs').ComponentDetailResponse['data']}
@@ -366,15 +376,53 @@ export function withOwnership(docs, owner, componentName, coreDir) {
   const importSpec =
     owner.package === CORE_PACKAGE
       ? resolveImportPath(coreDir, componentName)
-      : `${owner.package}/${componentName}`;
+      : resolveIntegrationImportPath(owner, componentName);
   return /** @type {any} */ ({
     ...docs,
     package: owner.package,
-    import: importSpec,
+    // A doc file may state its own specifier, e.g. when one entry point exports
+    // several components. Only fall back to a resolved one when it does not.
+    import: docs.import ?? importSpec,
     sourceAvailable: owner.sourcePath != null,
   });
 }
 
+/**
+ * Resolve the specifier an integration component is imported from, against the
+ * owning package's `exports` map.
+ *
+ * A component lives in a directory that need not share its name — several
+ * components can be exported from one entry point — so the specifier has to
+ * come from the directory the doc file sits in, checked against `exports`,
+ * rather than from the component name. Falls back to the package root when the
+ * directory is not an exported subpath, matching what a consumer would have to
+ * write by hand.
+ *
+ * @param {OwnershipSubject} owner
+ * @param {string} componentName
+ * @returns {string}
+ */
+function resolveIntegrationImportPath(owner, componentName) {
+  const packageDir = owner.integration?.__packageDir;
+  const directory = owner.docPath
+    ? path.basename(path.dirname(owner.docPath))
+    : componentName;
+  if (!packageDir) {
+    return owner.package;
+  }
+  try {
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8'),
+    );
+    if (manifest.exports?.[`./${directory}`]) {
+      return `${owner.package}/${directory}`;
+    }
+  } catch {
+    // An unreadable or malformed manifest is not worth failing a lookup over.
+  }
+  return owner.package;
+}
+
 /**
  * When the caller asked for "Code" but the resolved doc is for "CodeBlock"
  * (parent), scope the response to just the matching sub-component. Returns the

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 {};