@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/api/docs/_adapter.d.mts

@@ -50,6 +50,42 @@ export function lowerTopic(catalog: DocsCatalog, entry: DocsTopicEntry, lang?: s
  * @returns {Promise<LinkProblem[]>}
  */
 export function topicLinkProblems(catalog: DocsCatalog, entry: DocsTopicEntry): Promise<LinkProblem[]>;
+/**
+ * One line of a doc's text, such as a topic's or a tree node's summary, with
+ * every inline link resolved against the provider that wrote it (spec:AST-047
+ * FR9). A link that names no doc prints as written; doctor names it.
+ * @param {DocsCatalog} catalog
+ * @param {string} providerId the provider id of the doc the text sits in
+ * @param {string} text
+ * @returns {Promise<string>}
+ */
+export function linkDocText(catalog: DocsCatalog, providerId: string, text: string): Promise<string>;
+/**
+ * A component doc with every inline link in its text fields resolved
+ * (spec:AST-047 FR9): its description, usage, best practices, and each prop's
+ * and example's description. Code fields are shown as written. A Core
+ * component's links resolve against the CLI's own docs provider; an
+ * integration's against that integration's.
+ * @template T
+ * @param {DocsCatalog} catalog
+ * @param {string} providerId the provider id the component's links resolve
+ *   against
+ * @param {T} doc
+ * @returns {Promise<{doc: T, problems: LinkProblem[]}>}
+ */
+export function linkComponentDoc<T>(catalog: DocsCatalog, providerId: string, doc: T): Promise<{
+    doc: T;
+    problems: LinkProblem[];
+}>;
+/**
+ * The provider id a component's doc links resolve against: the CLI's own for
+ * a Core component, else its owner package's (or the provider id its manifest
+ * declares).
+ * @param {string} ownerPackage
+ * @param {string} [providerId]
+ * @returns {string}
+ */
+export function componentLinkProvider(ownerPackage: string, providerId?: string): string;
 /**
  * The project's docs tree: the CLI's own docs plus the namespace docs and
  * placed guides the configured integrations ship (spec:AST-046), built once
@@ -85,6 +121,20 @@ export function docsLinkProblems(catalog: DocsCatalog, tree: DocsTree, { owner,
     owner?: string;
     references?: boolean;
 }): Promise<string[]>;
+/**
+ * What \`astryx doctor integration components\` checks of the links in one
+ * integration's own component docs (spec:AST-047 FR9): each link in a
+ * description, usage, best practice, or prop's or example's description that
+ * names no doc. It prints as written, so each is a warning.
+ * @param {any} integration a loaded integration
+ * @param {Parameters<typeof packageCatalog>[1]} discovered the package's own
+ *   docs, which its components' links may name; null when it ships none
+ * @returns {Promise<Array<{severity: 'warning', message: string}>>}
+ */
+export function packageComponentLinkProblems(integration: any, discovered: Parameters<typeof packageCatalog>[1]): Promise<Array<{
+    severity: "warning";
+    message: string;
+}>>;
 /**
  * What \`astryx doctor integration docs\` checks in one integration's docs: the
  * docs tree they build beside the CLI's (namespaces, placements, routes) and
@@ -320,6 +370,19 @@ export type LinkResolver = import("../../foundation/doc-compiler/links.mjs").Lin
 export type DocIncluder = import("../../foundation/doc-compiler/links.mjs").DocIncluder;
 export type DocsTopicEntry = import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
 import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';
+/**
+ * The catalog one integration package's docs and links read, as doctor checks
+ * it before any app configures it: the CLI's topics, Core's and the package's
+ * components and templates, and the package's own docs.
+ * @param {any} integration
+ * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]} | null} discovered
+ * @returns {DocsCatalog}
+ */
+declare function packageCatalog(integration: any, discovered: {
+    records: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicRecord[];
+    namespaces: import("../../foundation/doc-compiler/tree.mjs").TreeNamespaceInput[];
+    guides: import("../../foundation/doc-compiler/tree.mjs").TreeDocInput[];
+} | null): DocsCatalog;
 import { AstryxError } from '../error.mjs';
 import { OVERLAY_LANGUAGES } from '../../foundation/doc-compiler/read.mjs';
 import { overlayLanguages } from '../../foundation/doc-compiler/read.mjs';

package/api/docs/_adapter.mjs

@@ -40,6 +40,7 @@ import {
 import {sortDiagnostics} from '../../foundation/doc-compiler/diagnostics.mjs';
 import {
   linkBlocks,
+  linkFields,
   parseLinkTarget,
 } from '../../foundation/doc-compiler/links.mjs';
 import {
@@ -69,6 +70,7 @@ import {
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 
 export {OVERLAY_LANGUAGES, overlayLanguages};
 
@@ -264,8 +266,16 @@ function linkTopic(catalog, entry, lang) {
         problems.push(...linked.problems);
         sections.push({...section, content: linked.content});
       }
+      // The topic's own text outside its sections, its description and
+      // summary, resolves against the topic's own provider.
+      const {resolve} = await linkerFor(providerOf(entry));
+      const fields = await linkFields(topicTextFields(raw.doc), resolve);
+      problems.push(...fields.problems);
       return {
-        node: deepFreeze({...raw, doc: {...raw.doc, sections}}),
+        node: deepFreeze({
+          ...raw,
+          doc: {...raw.doc, ...fields.doc, sections},
+        }),
         problems,
       };
     })();
@@ -274,6 +284,82 @@ function linkTopic(catalog, entry, lang) {
   return linked;
 }
 
+/**
+ * The text fields of a topic outside its sections: its description and
+ * summary, those it has.
+ * @param {any} doc
+ * @returns {{description?: string, summary?: string}}
+ */
+function topicTextFields(doc) {
+  /** @type {{description?: string, summary?: string}} */
+  const fields = {};
+  if (typeof doc?.description === 'string')
+    fields.description = doc.description;
+  if (typeof doc?.summary === 'string') fields.summary = doc.summary;
+  return fields;
+}
+
+/**
+ * One line of a doc's text, such as a topic's or a tree node's summary, with
+ * every inline link resolved against the provider that wrote it (spec:AST-047
+ * FR9). A link that names no doc prints as written; doctor names it.
+ * @param {DocsCatalog} catalog
+ * @param {string} providerId the provider id of the doc the text sits in
+ * @param {string} text
+ * @returns {Promise<string>}
+ */
+export async function linkDocText(catalog, providerId, text) {
+  if (typeof text !== 'string' || !text.includes('{@link')) return text;
+  let provider;
+  try {
+    provider = normalizeProviderId(providerId);
+  } catch {
+    return text;
+  }
+  const linked = await linkFields(
+    {description: text},
+    await linkResolver(catalog, provider),
+  );
+  return linked.doc.description ?? text;
+}
+
+/**
+ * A component doc with every inline link in its text fields resolved
+ * (spec:AST-047 FR9): its description, usage, best practices, and each prop's
+ * and example's description. Code fields are shown as written. A Core
+ * component's links resolve against the CLI's own docs provider; an
+ * integration's against that integration's.
+ * @template T
+ * @param {DocsCatalog} catalog
+ * @param {string} providerId the provider id the component's links resolve
+ *   against
+ * @param {T} doc
+ * @returns {Promise<{doc: T, problems: LinkProblem[]}>}
+ */
+export async function linkComponentDoc(catalog, providerId, doc) {
+  if (!JSON.stringify(doc ?? null).includes('{@link')) {
+    return {doc, problems: []};
+  }
+  return linkFields(
+    doc,
+    await linkResolver(catalog, normalizeProviderId(providerId)),
+  );
+}
+
+/**
+ * The provider id a component's doc links resolve against: the CLI's own for
+ * a Core component, else its owner package's (or the provider id its manifest
+ * declares).
+ * @param {string} ownerPackage
+ * @param {string} [providerId]
+ * @returns {string}
+ */
+export function componentLinkProvider(ownerPackage, providerId) {
+  return ownerPackage === CORE_PACKAGE
+    ? CLI_PROVIDER_ID
+    : normalizeProviderId(providerId ?? ownerPackage);
+}
+
 /** @type {WeakMap<DocsCatalog, Promise<DocsTree>>} */
 const treesByCatalog = new WeakMap();
 
@@ -347,12 +433,50 @@ async function buildProjectTree(catalog, fresh) {
     docs: [...cli.docs, ...added.flatMap(each => each.guides)],
     topics: await flatTopicInputs(catalog),
   });
+  // A summary is a doc's text too: each link in it reads as the command that
+  // opens its doc, wherever the tree's summaries print (spec:AST-047 FR9).
+  for (const node of result.nodes.values()) {
+    if (typeof node.summary === 'string' && node.summary.includes('{@link')) {
+      node.summary = await linkSummary(
+        catalog,
+        result,
+        node.providerId,
+        node.summary,
+      );
+    }
+  }
   return {
     ...result,
     diagnostics: sortDiagnostics([...cli.diagnostics, ...result.diagnostics]),
   };
 }
 
+/**
+ * One summary with each inline link resolved to the command that opens its
+ * doc, against the provider that wrote it. A link that names no doc prints as
+ * written; doctor names it where it checks the doc's own fields.
+ * @param {DocsCatalog} catalog
+ * @param {DocsTree} tree
+ * @param {string} providerId
+ * @param {string} summary
+ * @returns {Promise<string>}
+ */
+async function linkSummary(catalog, tree, providerId, summary) {
+  if (!summary.includes('{@link')) return summary;
+  let provider;
+  try {
+    provider = normalizeProviderId(providerId);
+  } catch {
+    return summary;
+  }
+  const find = docFinderOver(catalog, tree, provider, false);
+  const linked = await linkFields({summary}, async target => {
+    const found = await find(target);
+    return 'problem' in found ? found : found.link;
+  });
+  return linked.doc.summary;
+}
+
 /** @type {WeakMap<DocsTree, Map<string, TreeNode>>} */
 const identitiesByTree = new WeakMap();
 
@@ -430,10 +554,34 @@ async function authoringDoc(catalog, kind, name) {
  * @returns {Promise<(target: string) => Promise<FoundDoc | {problem: string}>>}
  */
 async function docFinder(catalog, fromProvider) {
-  const identities = identitiesOf(await projectTree(catalog));
+  return docFinderOver(catalog, await projectTree(catalog), fromProvider);
+}
+
+/**
+ * {@link docFinder} over a tree already built, so building the tree can
+ * resolve the links in its own summaries.
+ * @param {DocsCatalog} catalog
+ * @param {DocsTree} tree
+ * @param {string} fromProvider
+ * @param {boolean} [summaries] resolve the links in a found flat topic's
+ *   summary; off while a summary is itself being resolved, so two summaries
+ *   that link each other cannot loop
+ * @returns {(target: string) => Promise<FoundDoc | {problem: string}>}
+ */
+function docFinderOver(catalog, tree, fromProvider, summaries = true) {
+  const identities = identitiesOf(tree);
   return async target => {
     const parsed = parseLinkTarget(target);
-    if ('error' in parsed) return {problem: parsed.error};
+    if ('error' in parsed)
+      return {
+        problem: bareLinkHint(
+          parsed.error,
+          target,
+          catalog,
+          identities,
+          fromProvider,
+        ),
+      };
     let provider;
     try {
       provider = normalizeProviderId(parsed.provider ?? fromProvider);
@@ -442,7 +590,9 @@ async function docFinder(catalog, fromProvider) {
         problem: `"${target}" names "${parsed.provider}", which is not a provider id: an npm package name, or the \`providerId\` its manifest declares`,
       };
     }
-    const node = identities.get(identityKey(provider, parsed.kind, parsed.name));
+    const node = identities.get(
+      identityKey(provider, parsed.kind, parsed.name),
+    );
     if (node) {
       return {
         link: {
@@ -491,6 +641,14 @@ async function docFinder(catalog, fromProvider) {
           const raw = await lowerRawTopic(catalog, entry);
           title = raw.doc.title ?? title;
           summary = raw.doc.description ?? summary;
+          if (summaries) {
+            summary = await linkSummary(
+              catalog,
+              tree,
+              providerOf(entry),
+              summary,
+            );
+          }
         } catch {
           // The topic budget check reports a topic that does not load; the
           // link still opens it.
@@ -516,8 +674,20 @@ async function docFinder(catalog, fromProvider) {
         parsed.kind,
         parsed.name,
       );
-      if (link)
+      if (link) {
+        // The summary is the target doc's own text, so its links resolve
+        // against the target's provider, never the linking doc's: a Core
+        // component's against the CLI's docs, like its other fields.
+        if (summaries && link.summary.includes('{@link')) {
+          link.summary = await linkSummary(
+            catalog,
+            tree,
+            provider === CORE_COMPONENT_PROVIDER ? CLI_PROVIDER_ID : provider,
+            link.summary,
+          );
+        }
         return {link: {target, ...link}, kind: parsed.kind, typed: null};
+      }
     }
     const searchType =
       parsed.kind === 'component'
@@ -531,6 +701,54 @@ async function docFinder(catalog, fromProvider) {
   };
 }
 
+/**
+ * What a link written as a bare name (`{@link deploying}`) should say
+ * instead: the exact target to write when a topic or tree doc has that
+ * name, or that none does.
+ * @param {string} error the parse error
+ * @param {string} target the target as written
+ * @param {DocsCatalog} catalog
+ * @param {Map<string, any>} identities
+ * @param {string} fromProvider
+ * @returns {string}
+ */
+function bareLinkHint(error, target, catalog, identities, fromProvider) {
+  const name = typeof target === 'string' ? target.trim() : '';
+  if (!name || name.includes(':') || /\s/.test(name)) return error;
+  /** @param {string} provider */
+  const normal = provider => {
+    try {
+      return normalizeProviderId(provider);
+    } catch {
+      return provider;
+    }
+  };
+  const from = normal(fromProvider);
+  /** @param {string} provider @param {string} kind @param {string} named */
+  const written = (provider, kind, named) =>
+    `{@link ${normal(provider) === from ? '' : `${provider}:`}${kind}:${named}}`;
+  const entry = catalog.resolve(name);
+  if (entry) {
+    return `${error}. "${name}" is a topic: write \`${written(entry.providerId ?? entry.package, 'generic', entry.name)}\`.`;
+  }
+  const node = [...identities.values()].find(
+    each => String(each.name).toLowerCase() === name.toLowerCase(),
+  );
+  if (node) {
+    return `${error}. "${name}" is a ${node.kind === 'generic' ? 'topic' : `${node.kind} doc`}: write \`${written(node.providerId, node.kind, node.name)}\`.`;
+  }
+  return `${error}, and no topic is named "${name}". Link a doc that exists, as \`{@link generic:<topic>}\` (\`astryx docs\` lists the topics), or remove the link.`;
+}
+
+/** The provider Core's components and templates belong to. */
+const CORE_COMPONENT_PROVIDER = (() => {
+  try {
+    return normalizeProviderId(CORE_PACKAGE);
+  } catch {
+    return CORE_PACKAGE;
+  }
+})();
+
 /** The doc kinds no docs tree holds: components and templates. */
 const CONTRIBUTED_KINDS = new Set(['component', 'page', 'block']);
 
@@ -861,7 +1079,7 @@ export async function docsLinkProblems(
     for (const problem of found) {
       if ((problem.include === true) !== references) continue;
       problems.push(
-        `${where}${problem.section ? ` \u00a7 ${problem.section}` : ''}: ${problem.message}`,
+        `${where}${problem.section ? ` \u00a7 ${problem.section}` : ''}${problem.field ? ` (${problem.field})` : ''}: ${problem.message}`,
       );
     }
   };
@@ -896,6 +1114,83 @@ export async function docsLinkProblems(
   return problems;
 }
 
+/**
+ * The catalog one integration package's docs and links read, as doctor checks
+ * it before any app configures it: the CLI's topics, Core's and the package's
+ * components and templates, and the package's own docs.
+ * @param {any} integration
+ * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]} | null} discovered
+ * @returns {DocsCatalog}
+ */
+function packageCatalog(integration, discovered) {
+  const catalog = DocsCatalog.fromBuiltins();
+  catalog.setContributions(() => packageContributions(integration));
+  if (discovered) {
+    for (const record of discovered.records) catalog.add(record);
+    catalog.addTreeInputs({
+      namespaces: discovered.namespaces.map(input => ({...input, rank: 1})),
+      guides: discovered.guides.map(input => ({...input, rank: 1})),
+    });
+  }
+  return catalog;
+}
+
+/**
+ * What \`astryx doctor integration components\` checks of the links in one
+ * integration's own component docs (spec:AST-047 FR9): each link in a
+ * description, usage, best practice, or prop's or example's description that
+ * names no doc. It prints as written, so each is a warning.
+ * @param {any} integration a loaded integration
+ * @param {Parameters<typeof packageCatalog>[1]} discovered the package's own
+ *   docs, which its components' links may name; null when it ships none
+ * @returns {Promise<Array<{severity: 'warning', message: string}>>}
+ */
+export async function packageComponentLinkProblems(integration, discovered) {
+  const catalog = packageCatalog(integration, discovered);
+  return (await componentLinkProblems(catalog, integration.name)).map(
+    message => ({severity: /** @type {const} */ ('warning'), message}),
+  );
+}
+
+/**
+ * Each link in a package's own component docs that names no doc. A family doc
+ * that documents several components is read once.
+ * @param {DocsCatalog} catalog
+ * @param {string} owner the package whose component docs are read
+ * @returns {Promise<string[]>}
+ */
+async function componentLinkProblems(catalog, owner) {
+  const contributions = await catalog.contributions();
+  /** @type {string[]} */
+  const problems = [];
+  const seen = new Set();
+  for (const record of contributions?.components ?? []) {
+    if (record.package !== owner || !record.docPath) continue;
+    if (seen.has(record.docPath)) continue;
+    seen.add(record.docPath);
+    /** @type {any} */
+    let doc;
+    try {
+      doc = await loadComponentDoc(record.docPath);
+    } catch {
+      // The components check reports a doc that does not load.
+      continue;
+    }
+    const linked = await linkComponentDoc(
+      catalog,
+      componentLinkProvider(record.package, record.providerId),
+      doc,
+    );
+    const name = typeof doc?.name === 'string' ? doc.name : record.name;
+    for (const problem of linked.problems) {
+      problems.push(
+        `component ${name}${problem.field ? ` (${problem.field})` : ''}: ${problem.message}`,
+      );
+    }
+  }
+  return problems;
+}
+
 /**
  * What \`astryx doctor integration docs\` checks in one integration's docs: the
  * docs tree they build beside the CLI's (namespaces, placements, routes) and
@@ -907,13 +1202,7 @@ export async function docsLinkProblems(
  * @returns {Promise<Array<{severity: 'error' | 'warning', message: string}>>}
  */
 export async function packageDocsProblems(integration, discovered) {
-  const catalog = DocsCatalog.fromBuiltins();
-  catalog.setContributions(() => packageContributions(integration));
-  for (const record of discovered.records) catalog.add(record);
-  catalog.addTreeInputs({
-    namespaces: discovered.namespaces.map(input => ({...input, rank: 1})),
-    guides: discovered.guides.map(input => ({...input, rank: 1})),
-  });
+  const catalog = packageCatalog(integration, discovered);
   const tree = await projectTree(catalog);
   /** @type {Array<{severity: 'error' | 'warning', message: string}>} */
   const problems = tree.diagnostics
@@ -1136,7 +1425,8 @@ export async function topicLinks(catalog, entry) {
   const tree = await projectTree(catalog);
   const node = tree.get(entry.tree ? (entry.route ?? entry.name) : entry.name);
   const placed =
-    node && (entry.tree ? node.kind === 'generic' : node.ref?.flatTopic === entry.name);
+    node &&
+    (entry.tree ? node.kind === 'generic' : node.ref?.flatTopic === entry.name);
   return placed ? placeLinks(tree, node) : {up: topicUp(entry)};
 }
 
@@ -1159,7 +1449,8 @@ export async function resolveDocsArgument(topic, {cwd} = {}) {
   const tree = await projectTree(catalog);
   const owner = nameOwner(tree, catalog, topic);
   if (owner == null) return {kind: 'unknown', catalog};
-  if (owner.kind === 'topic') return {kind: 'topic', catalog, entry: owner.entry};
+  if (owner.kind === 'topic')
+    return {kind: 'topic', catalog, entry: owner.entry};
   return treeArgument(catalog, tree, owner.node);
 }
 
@@ -1306,7 +1597,7 @@ export async function unknownTopicError(topic, catalog) {
 export function notLoaded(catalog) {
   const packages = [...new Set(catalog.issues.map(issue => issue.package))];
   if (packages.length === 0) return '';
-  return `. The docs of ${packages.join(', ')} did not load; run \`astryx doctor integration docs\` in that package to see why.`;
+  return `. The docs of ${packages.join(', ')} did not load; run \`${formatCliCommand('doctor integration docs')}\` in that package to see why.`;
 }
 
 /**
@@ -1324,7 +1615,7 @@ export async function resolveTopicDocs(topic, options = {}) {
   if (found.kind !== 'topic') {
     throw found.kind === 'node'
       ? new AstryxError(
-          `"${found.node.route}" is a ${found.node.kind === 'namespace' ? 'namespace' : `${found.node.kind} doc`} in the docs tree, not a topic. Read it with \`astryx docs ${found.node.route}\`.`,
+          `"${found.node.route}" is a ${found.node.kind === 'namespace' ? 'namespace' : `${found.node.kind} doc`} in the docs tree, not a topic. Read it with \`${formatCliCommand(`docs ${found.node.route}`)}\`.`,
           undefined,
           ERROR_CODES.ERR_UNKNOWN_TOPIC,
         )
@@ -1359,7 +1650,10 @@ export async function integrationDocTypes(integration, cwd) {
   if (report.status !== 'checked' || unread.length === 0) return report;
   // A root its reader cannot read serves no doc; say so rather than skip it.
   const rel = (/** @type {string} */ file) =>
-    path.relative(packageDir ?? cwd, file).split(path.sep).join('/') || '.';
+    path
+      .relative(packageDir ?? cwd, file)
+      .split(path.sep)
+      .join('/') || '.';
   return {
     ...report,
     unchecked: [

package/api/docs/docs.doc.mjs

@@ -34,7 +34,8 @@ export const doc = {
     'for a typed doc, `related` to the docs it names (its command or function, ' +
     'and its related docs); `previous` and `next` ' +
     'to the section or node before and after it. ' +
-    'Overlay options select localized or dense variants.',
+    'Overlay options select localized or dense variants.' +
+    " In global mode: with `cwd` outside a project, doc topics from integrations installed next to this CLI package globally are listed too; inside a project, only the project's own integrations count. See {@link namespace:global} and {@link generic:computer-integrations}.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsIndexResponse | DocsDetailResponse | DocsDetailSectionResponse | DocsNodeResponse>',

package/api/docs/docs.mjs

@@ -34,6 +34,7 @@ import {node as nodeLeaf, nodeView} from './node/node.mjs';
 import {resolveDocsArgument} from './_adapter.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
+import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 
 export {list, index, detail, sectionLeaf as section, nodeLeaf as node};
 
@@ -108,7 +109,7 @@ export async function docs(topic, section, options = {}) {
         return namespaceSection(found.tree, found.node, section, options);
       }
       throw new AstryxError(
-        `"${found.node.route}" has no sections. Read it whole: astryx docs ${found.node.route}.`,
+        `"${found.node.route}" has no sections. Read it whole: ${formatCliCommand(`docs ${found.node.route}`)}.`,
         [{name: found.node.route, reason: found.node.summary}],
         ERROR_CODES.ERR_UNKNOWN_SECTION,
       );

package/api/docs/docs.test.mjs

@@ -11,6 +11,7 @@
 import {describe, it, expect} from 'vitest';
 import {docs} from './docs.mjs';
 import {AstryxError} from '../error.mjs';
+import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 
 const SLOW = 30_000;
 
@@ -92,7 +93,7 @@ describe('docs() dispatcher routing', () => {
 
   it("lists the docs tree's namespaces in meta, so every data entry reads as a topic", async () => {
     const res = await docs();
-    expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography', 'unorganized']);
+    expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'global', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography', 'unorganized']);
     for (const entry of res.data) {
       expect((await docs(entry.topic)).type).toBe('docs.detail');
     }
@@ -107,7 +108,9 @@ describe('docs() dispatcher routing', () => {
   it('a section of a typed doc -> ERR_UNKNOWN_SECTION, suggesting the doc itself', async () => {
     const err = await docs('cli/api/functions/search', 'x').catch(e => e);
     expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    expect(err.message).toContain('astryx docs cli/api/functions/search');
+    expect(err.message).toContain(
+      formatCliCommand('docs cli/api/functions/search'),
+    );
     expect(err.suggestions.map(s => s.name)).toEqual(['cli/api/functions/search']);
   }, SLOW);
 

package/api/docs/integration-tree.test.mjs

@@ -569,4 +569,26 @@ describe('integration docs in the docs tree', () => {
     expect(check.status).toBe('warn');
     expect(check.message).toContain('both have the route "cli"');
   }, SLOW);
+
+  it('says what to write for a link that names a doc by its bare name, and when no doc has that name', async () => {
+    scaffold({
+      ...kit(),
+      'bare.doc.mjs': guide('bare', {
+        sections: [
+          {
+            title: 'Overview',
+            content: [{type: 'prose', text: 'Read {@link deploy}, then {@link nosuchtopic}.'}],
+          },
+        ],
+      }),
+    });
+    const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
+    const graph = result.data.issues.filter(issue => issue.code === 'invalid_doc_graph').map(issue => issue.message);
+    expect(graph).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('"deploy" is a topic: write `{@link generic:deploy}`.'),
+        expect.stringContaining('no topic is named "nosuchtopic"'),
+      ]),
+    );
+  }, SLOW);
 });

package/api/docs/list/list.mjs

@@ -15,7 +15,12 @@
  */
 
 import {loadTopicFile} from '../../../foundation/doc-compiler/read.mjs';
-import {holdsOwnName, loadDocsCatalog, projectTree} from '../_adapter.mjs';
+import {
+  holdsOwnName,
+  linkDocText,
+  loadDocsCatalog,
+  projectTree,
+} from '../_adapter.mjs';
 
 /**
  * @param {object} [options]
@@ -39,7 +44,12 @@ export async function list({cwd} = {}) {
     /** @type {import('../docs.type.mjs').DocsListEntry} */
     const listed = {
       topic: entry.name,
-      description,
+      // A link in the description reads as the command that opens its doc.
+      description: await linkDocText(
+        catalog,
+        entry.providerId ?? entry.package,
+        description,
+      ),
       package: entry.package,
     };
     if (entry.replaces != null) listed.replaces = entry.replaces;

package/api/docs/reference-blocks.test.mjs

@@ -276,9 +276,7 @@ describe('a reference block in a topic section', () => {
       expect(status).toBe(0);
       expect(stdout).toMatch(/^Field +\| Type +\| Required +\| Description/m);
       expect(stdout).toMatch(/^components +\| string +\| no +\| /m);
-      expect(stdout).toContain(
-        'From Astryx Integration: `astryx docs authoring integration`',
-      );
+      expect(stdout).toContain(' docs authoring integration`');
     },
     SLOW,
   );