@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/api/docs/docs-homes.test.mjs

@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every Core doc has a named home in the docs tree (spec:AST-046 FR12).
+ *
+ * A reader sees a doc's home in its path (`Guides › Getting started`) and in
+ * its Up move. A flat Core topic sits in Guides or Foundations by the
+ * category it declares, so a new topic with no category, or one the levels
+ * do not know, fails here instead of landing in a catch-all. The integration
+ * guides and their field reference live under `authoring`, and the routes
+ * they left name where they went.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {docs} from './docs.mjs';
+import {TOPIC_LEVELS} from '../../foundation/doc-compiler/tree.mjs';
+
+const CLI = '@astryxdesign/cli';
+const SLOW = 60_000;
+
+describe('every Core doc has a named home', () => {
+  it(
+    'puts each flat Core topic in Guides or Foundations by its category',
+    async () => {
+      const list = await docs();
+      const core = list.data.filter(topic => topic.package === CLI);
+      expect(core.length).toBeGreaterThan(10);
+      /** @type {string[]} */
+      const unfiled = [];
+      for (const topic of core) {
+        const read = await docs(topic.topic);
+        const {category} = read.data;
+        if (category !== 'guide' && category !== 'foundations') {
+          unfiled.push(`${topic.topic} (category ${String(category)})`);
+          continue;
+        }
+        const level =
+          category === 'foundations'
+            ? TOPIC_LEVELS.foundations
+            : TOPIC_LEVELS.guides;
+        expect(read.data.links.up, topic.topic).toBe(
+          `astryx docs ${level.route}`,
+        );
+      }
+      expect(unfiled, 'Core topics with no home: give each a category').toEqual(
+        [],
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'lists each level under a plain name, and no catch-all',
+    async () => {
+      const list = await docs();
+      const roots = (list.meta.namespaces ?? []).map(entry => entry.topic);
+      expect(roots).toEqual(expect.arrayContaining(['guides', 'foundations']));
+      expect(roots).not.toContain('unorganized');
+      const guides = await docs('guides');
+      expect(guides.data).toMatchObject({route: 'guides', title: 'Guides'});
+      expect(guides.data.slots[0].children.map(child => child.route)).toEqual(
+        expect.arrayContaining(['getting-started', 'principles', 'theme']),
+      );
+      const foundations = await docs('foundations');
+      expect(foundations.data.title).toBe('Foundations');
+      expect(
+        foundations.data.slots[0].children.map(child => child.route),
+      ).toEqual(expect.arrayContaining(['color', 'icons', 'spacing']));
+      await expect(docs('unorganized')).rejects.toMatchObject({
+        code: 'ERR_UNKNOWN_TOPIC',
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'keeps everything for integration authors under authoring, and names where an old route went',
+    async () => {
+      const authoring = await docs('authoring');
+      expect(authoring.data).toMatchObject({
+        route: 'authoring',
+        kind: 'namespace',
+        breadcrumb: [],
+        links: {up: 'astryx docs'},
+      });
+      const children = authoring.data.slots.flatMap(slot =>
+        slot.children.map(child => child.route),
+      );
+      expect(children).toEqual(
+        expect.arrayContaining([
+          'authoring/quick-start',
+          'authoring/building-blocks',
+          'authoring/ship',
+          'authoring/help',
+          'authoring/field-reference',
+        ]),
+      );
+      // Every field reference section still opens from the namespace by its
+      // key, as `astryx docs authoring <name>` did on the topic (FR13).
+      const reference = await docs('authoring/field-reference', undefined, {
+        index: true,
+      });
+      const keys = reference.data.sections.map(section => section.id);
+      expect(keys.length).toBeGreaterThan(15);
+      for (const key of keys) {
+        const section = await docs('authoring', key);
+        expect(section.type, key).toBe('docs.detail.section');
+        expect(section.data.id, key).toBe(key);
+      }
+      for (const [old, now] of [
+        ['cli/integrations', 'authoring'],
+        ['cli/integrations/quick-start', 'authoring/quick-start'],
+        ['cli/integrations/ship/publishing', 'authoring/ship/publishing'],
+      ]) {
+        const error = await docs(old).catch(e => e);
+        expect(error).toMatchObject({
+          code: 'ERR_UNKNOWN_TOPIC',
+          message: expect.stringContaining(`It moved to "${now}"`),
+        });
+        // The new route comes first, ahead of the suggestions any unknown
+        // route gets (FR6).
+        expect(error.suggestions[0]).toMatchObject({name: now});
+      }
+    },
+    SLOW,
+  );
+});

package/api/docs/docs.doc.mjs

@@ -28,13 +28,14 @@ export const doc = {
     '`cli/api` returns its children one level down (`depth` reads as many ' +
     'levels as asked, and `detail` how much of each doc below), a typed doc such as ' +
     "`cli/api/functions/search` returns its content, and a guide the tree " +
-    'places (`cli/integrations/quick-start`) reads like any topic. ' +
+    'places (`authoring/quick-start`) reads like any topic. ' +
     'Every read but the list carries `links`, the commands that move from it: ' +
     '`up` to the level it sits in, `previous` and `next` to its neighbors, and, ' +
     '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>',
@@ -161,12 +162,12 @@ export const doc = {
     },
     {
       label: 'A namespace and everything below it, in full',
-      code: "await docs('cli/integrations', undefined, {depth: 'all', detail: 'full'});",
+      code: "await docs('authoring', undefined, {depth: 'all', detail: 'full'});",
     },
     {label: 'One API function', code: "await docs('cli/api/functions/search');"},
     {
       label: 'A whole guide from the docs tree',
-      code: "await docs('cli/integrations/quick-start');",
+      code: "await docs('authoring/quick-start');",
     },
     {label: 'One section by key', code: "await docs('spacing', 'scale');"},
   ],

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(['authoring', 'cli', 'foundations', 'global', 'guides', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
     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);
 
@@ -120,7 +123,13 @@ describe('docs() dispatcher routing', () => {
       kind: 'namespace',
       package: '@astryxdesign/cli',
       breadcrumb: [{route: 'cli', title: 'Astryx CLI'}],
-      content: [],
+      // Its one block points to the host entry's guide.
+      content: [
+        {
+          type: 'prose',
+          text: expect.stringContaining('`astryx docs cli/host-entry`'),
+        },
+      ],
     });
     expect(r.data.slots.flatMap(slot => slot.children.map(c => c.route))).toEqual([
       'cli/api/functions',
@@ -149,8 +158,8 @@ describe('docs() dispatcher routing', () => {
   }, SLOW);
 
   it('a guide the tree places reads like a topic: the whole doc, its index, a section', async () => {
-    // cli/integrations is a namespace of short guides; each guide reads like a topic.
-    const integrations = await docs('cli/integrations');
+    // authoring is a namespace of short guides; each guide reads like a topic.
+    const integrations = await docs('authoring');
     expect(integrations.type).toBe('docs.node');
     const guide = placedGuide(integrations.data);
     expect((await docs(guide)).type).toBe('docs.detail');
@@ -169,7 +178,7 @@ describe('docs() dispatcher routing', () => {
     expect(leaf.links.up).toBe('astryx docs cli/api/functions');
     expect(leaf.links.previous).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
     expect(leaf.links.next).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
-    const integrations = (await docs('cli/integrations')).data;
+    const integrations = (await docs('authoring')).data;
     const guide = placedGuide(integrations);
     const siblings = integrations.slots
       .find(slot => slot.children.some(child => child.route === guide))
@@ -178,7 +187,7 @@ describe('docs() dispatcher routing', () => {
     const index = await docs(guide, undefined, {index: true});
     // A guide moves across its namespace's slot, as any tree node does.
     expect(index.data.links).toEqual({
-      up: 'astryx docs cli/integrations',
+      up: 'astryx docs authoring',
       ...(at > 0 ? {previous: `astryx docs ${siblings[at - 1]}`} : {}),
       ...(at < siblings.length - 1
         ? {next: `astryx docs ${siblings[at + 1]}`}
@@ -195,16 +204,22 @@ describe('docs() dispatcher routing', () => {
     expect(end.links.previous).toBe(
       `astryx docs ${guide} ${index.data.sections.at(-2).id}`,
     );
-    // A flat topic's home is the Unorganized level, and it moves across it.
+    // A flat topic's home is the level for its category, and it moves across it.
     const flat = (await docs('principles')).data.links;
-    expect(flat.up).toBe('astryx docs unorganized');
+    expect(flat.up).toBe('astryx docs guides');
     expect(flat.previous).toMatch(/^astryx docs [a-z-]+$/);
     expect(flat.next).toMatch(/^astryx docs [a-z-]+$/);
-    const home = (await docs('unorganized')).data;
-    expect(home).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
-    expect(home.slots[0].children.map(child => child.route)).toEqual(
-      (await docs()).data.map(entry => entry.topic),
-    );
+    const guides = (await docs('guides')).data;
+    expect(guides).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
+    const foundations = (await docs('foundations')).data;
+    expect(foundations).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
+    // Between them the two levels hold every flat topic, each in list order.
+    const topics = (await docs()).data.map(entry => entry.topic);
+    const held = [guides, foundations].map(level => level.slots[0].children.map(child => child.route));
+    for (const routes of held) {
+      expect(routes).toEqual(topics.filter(topic => routes.includes(topic)));
+    }
+    expect(held.flat().sort()).toEqual([...topics].sort());
   }, SLOW);
 
   it('names a node by its doc identity; a generated level has id null', async () => {
@@ -231,10 +246,9 @@ describe('docs() dispatcher routing', () => {
   }, SLOW);
 
   it("the guide's old flat name is gone, and its error names the new route", async () => {
-    await expect(docs('cli-integrations')).rejects.toMatchObject({
-      code: 'ERR_UNKNOWN_TOPIC',
-      suggestions: [expect.objectContaining({name: 'cli/integrations'})],
-    });
+    const error = await docs('cli-integrations').catch(e => e);
+    expect(error.code).toBe('ERR_UNKNOWN_TOPIC');
+    expect(error.suggestions[0]).toMatchObject({name: 'authoring'});
     expect((await docs()).data.map(entry => entry.topic)).not.toContain(
       'cli-integrations',
     );
@@ -244,11 +258,16 @@ describe('docs() dispatcher routing', () => {
     const err = await docs('cli', 'zzzz-nope').catch(e => e);
     expect(err).toBeInstanceOf(AstryxError);
     expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    // It names every guide below the namespace, at any depth.
     const names = err.suggestions.map(s => s.name);
     expect(names).toContain('cli/component-lookups');
-    expect(names).toContain('cli/integrations/quick-start');
     expect(names.every(name => name.startsWith('cli/'))).toBe(true);
+    // It names every guide below the namespace, at any depth.
+    const deep = await docs('authoring', 'zzzz-nope').catch(e => e);
+    expect(deep.code).toBe('ERR_UNKNOWN_SECTION');
+    const below = deep.suggestions.map(s => s.name);
+    expect(below).toContain('authoring/quick-start');
+    expect(below).toContain('authoring/building-blocks/components/add-a-component');
+    expect(below.every(name => name.startsWith('authoring/'))).toBe(true);
   }, SLOW);
 
   it('an unknown route suggests the children of the deepest namespace it reaches', async () => {

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

@@ -246,7 +246,7 @@ describe('integration docs in the docs tree', () => {
     });
     scaffold({
       ...kit(),
-      'unorganized.doc.mjs': {...NAMESPACE, name: 'unorganized', title: 'Mine', summary: 'Mine.'},
+      'guides.doc.mjs': {...NAMESPACE, name: 'guides', title: 'Mine', summary: 'Mine.'},
       'use-a-theme.doc.mjs': {...NAMESPACE, name: 'use-a-theme', title: 'Acme use-a-theme', summary: 'Acme use-a-theme.'},
       'cli.doc.mjs': flat('cli'),
     });
@@ -254,26 +254,26 @@ describe('integration docs in the docs tree', () => {
     expect(listed.meta.namespaces).toEqual(
       expect.arrayContaining([
         expect.objectContaining({topic: 'cli', package: '@astryxdesign/cli'}),
-        expect.objectContaining({topic: 'unorganized', package: '@astryxdesign/cli'}),
+        expect.objectContaining({topic: 'guides', package: '@astryxdesign/cli'}),
       ]),
     );
-    expect(listed.meta.namespaces.filter(n => ['use-a-theme', 'unorganized'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);
+    expect(listed.meta.namespaces.filter(n => ['use-a-theme', 'guides'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);
     expect(listed.data.map(entry => entry.topic)).not.toContain('cli');
     // Each name opens the CLI's doc, and a CLI topic keeps its home.
     expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
-    expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
+    expect((await docs('guides', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
     const tokens = await docs('use-a-theme', undefined, {cwd: tmpDir});
     expect(tokens.type).toBe('docs.detail');
-    expect(tokens.data.links.up).toBe('astryx docs unorganized');
+    expect(tokens.data.links.up).toBe('astryx docs guides');
     // The project doctor and the package doctor both name the claims.
     const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
     expect(check.status).toBe('warn');
-    expect(check.message).toContain('takes the route "unorganized", which the CLI\'s own docs keep');
+    expect(check.message).toContain('takes the route "guides", which the CLI\'s own docs keep');
     expect(check.message).toContain('takes the route "use-a-theme"');
     expect(check.message).toContain('both have the route "cli"');
     const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
     const graph = result.data.issues.filter(issue => issue.code === 'invalid_doc_graph').map(issue => issue.message).join('\n');
-    expect(graph).toContain('takes the route "unorganized"');
+    expect(graph).toContain('takes the route "guides"');
     expect(graph).toContain('takes the route "use-a-theme"');
     expect(graph).toContain('route "cli"');
   }, SLOW);
@@ -294,16 +294,16 @@ describe('integration docs in the docs tree', () => {
     const nested = path.join(tmpDir, 'node_modules', '@acme', 'kit', 'docs', 'nested');
     fs.mkdirSync(nested, {recursive: true});
     fs.writeFileSync(
-      path.join(nested, 'caps-unorganized.doc.mjs'),
-      `export const docs = ${JSON.stringify(flat('Unorganized'), null, 2)};\n`,
+      path.join(nested, 'caps-guides.doc.mjs'),
+      `export const docs = ${JSON.stringify(flat('Guides'), null, 2)};\n`,
     );
     fs.writeFileSync(
       path.join(nested, 'caps-use-a-theme.doc.mjs'),
       `export const docs = ${JSON.stringify(flat('USE-A-THEME'), null, 2)};\n`,
     );
     expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
-    expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
-    expect((await docs('theme', undefined, {cwd: tmpDir, index: true})).data.links.up).toBe('astryx docs unorganized');
+    expect((await docs('guides', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
+    expect((await docs('theme', undefined, {cwd: tmpDir, index: true})).data.links.up).toBe('astryx docs guides');
     const listed = await docs(undefined, undefined, {cwd: tmpDir});
     expect(listed.data.map(entry => entry.topic.toLowerCase())).not.toContain('cli');
     // Search does not offer a topic whose route another doc owns.
@@ -314,10 +314,10 @@ describe('integration docs in the docs tree', () => {
     const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
     expect(check.status).toBe('warn');
     expect(check.message).toContain('route "CLI"');
-    expect(check.message).toContain('takes the route "Unorganized"');
+    expect(check.message).toContain('takes the route "Guides"');
     // `USE-A-THEME` is the CLI's topic `use-a-theme` in another spelling: the CLI's wins.
     const tokens = await docs('USE-A-THEME', undefined, {cwd: tmpDir, index: true});
-    expect(tokens.data).toMatchObject({name: 'use-a-theme', links: {up: 'astryx docs unorganized'}});
+    expect(tokens.data).toMatchObject({name: 'use-a-theme', links: {up: 'astryx docs guides'}});
     expect(tokens.data.title).not.toBe('Acme USE-A-THEME');
     const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
     const graph = result.data.issues
@@ -325,7 +325,7 @@ describe('integration docs in the docs tree', () => {
       .map(issue => issue.message)
       .join('\n');
     expect(graph).toContain('route "CLI"');
-    expect(graph).toContain('takes the route "Unorganized"');
+    expect(graph).toContain('takes the route "Guides"');
   }, SLOW);
 
   it("keeps a replaced name for the topic that replaces it, over another integration's namespace", async () => {
@@ -420,9 +420,9 @@ describe('integration docs in the docs tree', () => {
     scaffold({
       ...kit(),
       'a-cli.doc.mjs': flat('cli'),
-      'a-unorganized.doc.mjs': flat('Unorganized'),
+      'a-guides.doc.mjs': flat('Guides'),
       'z-b2.doc.mjs': flat('b2', {replaces: 'cli'}),
-      'z-u2.doc.mjs': flat('u2', {replaces: 'Unorganized'}),
+      'z-u2.doc.mjs': flat('u2', {replaces: 'Guides'}),
     });
     // Another package carries the chain on: c3 replaces b2, which replaced cli.
     const three = path.join(tmpDir, 'node_modules', '@acme', 'three');
@@ -440,8 +440,8 @@ describe('integration docs in the docs tree', () => {
     for (const name of ['cli', 'CLI']) {
       expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
     }
-    for (const name of ['unorganized', 'UNORGANIZED']) {
-      expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
+    for (const name of ['guides', 'GUIDES']) {
+      expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
     }
     // The replacement still answers to its own names.
     for (const name of ['b2', 'c3']) {
@@ -456,7 +456,7 @@ describe('integration docs in the docs tree', () => {
     const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
     expect(check.status).toBe('warn');
     expect(check.message).toContain('The topic "c3" answers to "cli" through replaces');
-    expect(check.message).toContain('The topic "u2" answers to "unorganized" through replaces');
+    expect(check.message).toContain('The topic "u2" answers to "guides" through replaces');
     const inPackage = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
     const graph = inPackage.data.issues
       .filter(issue => issue.code === 'invalid_doc_graph')
@@ -519,7 +519,7 @@ describe('integration docs in the docs tree', () => {
     });
     const {data} = await docs('theme', 'acme-theming-notes', {cwd: tmpDir});
     // `generic:integrations` is the extension's own guide, never the CLI's
-    // `cli/integrations`; a provider-qualified link reaches the CLI's topic.
+    // `authoring`; a provider-qualified link reaches the CLI's topic.
     expect(data.content[0].text).toBe(
       'See `astryx docs acme/integrations`, and `astryx docs tokens` for the tokens.',
     );
@@ -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/integrationDocs.test.mjs

@@ -22,6 +22,7 @@ import {docs} from './docs.mjs';
 import {search} from '../search/search.mjs';
 import {loadDocsCatalog} from './_adapter.mjs';
 import {AstryxError} from '../error.mjs';
+import {discoverCoreTemplates} from '../../foundation/discovery/template-adapter.mjs';
 
 const SLOW = 30_000;
 
@@ -110,6 +111,129 @@ describe('integration-contributed topics', () => {
     expect(section.data.title).toBe('Overview');
   }, SLOW);
 
+  it('reads a link to a component or a template as the command that opens it', async () => {
+    scaffold({
+      'using-widgets.doc.mjs': topic({
+        name: 'using-widgets',
+        title: 'Using widgets',
+        sections: [
+          {
+            title: 'Overview',
+            content: [
+              {
+                type: 'prose',
+                text: 'Start with {@link component:AcmeButton} or {@link block:acme-card}, built on {@link @astryxdesign/core:component:Button}.',
+              },
+            ],
+          },
+        ],
+      }),
+    });
+    const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+    fs.writeFileSync(
+      path.join(pkgDir, 'astryx.integration.mjs'),
+      "export default {components: './components', templates: './templates', docs: './docs'};\n",
+    );
+    fs.mkdirSync(path.join(pkgDir, 'components'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeButton', displayName: 'Acme Button', description: 'A button.', props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.tsx'),
+      'export function AcmeButton() { return null; }\n',
+    );
+    fs.mkdirSync(path.join(pkgDir, 'templates'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', 'acme-card.doc.mjs'),
+      "export default {type: 'block', name: 'Acme card', description: 'A card.'};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', 'acme-card.tsx'),
+      'export default function Fixture() { return null; }\n',
+    );
+
+    const detail = await docs('using-widgets', undefined, {cwd: tmpDir, full: true});
+
+    const prose = JSON.stringify(detail.data.sections);
+    expect(prose).toContain('`astryx component AcmeButton --package @acme/widgets`');
+    expect(prose).toContain(
+      '`astryx template acme-card --type block --package @acme/widgets`',
+    );
+    expect(prose).toContain('`astryx component Button`');
+    expect(prose).not.toContain('{@link');
+  }, SLOW);
+
+  it('selects Core in a link only where the bare name would open something else', async () => {
+    const core = await discoverCoreTemplates();
+    const page = core.find(template => template.type === 'page')?.dirName;
+    const block = core.find(template => template.type === 'block')?.dirName;
+    scaffold({
+      'using-widgets.doc.mjs': topic({
+        name: 'using-widgets',
+        title: 'Using widgets',
+        sections: [
+          {
+            title: 'Overview',
+            content: [
+              {
+                type: 'prose',
+                text:
+                  'Core: {@link @astryxdesign/core:component:Button}, {@link @astryxdesign/core:component:Badge}, ' +
+                  `{@link @astryxdesign/core:page:${page}}, {@link @astryxdesign/core:block:${block}}.`,
+              },
+            ],
+          },
+        ],
+      }),
+    });
+    const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
+    // The CLI range that turns component replacement on.
+    fs.writeFileSync(
+      path.join(pkgDir, 'package.json'),
+      JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        peerDependencies: {'@astryxdesign/cli': '>=0.6.7'},
+        peerDependenciesMeta: {'@astryxdesign/cli': {optional: true}},
+      }),
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'astryx.integration.mjs'),
+      "export default {components: './components', templates: './templates', docs: './docs'};\n",
+    );
+    fs.mkdirSync(path.join(pkgDir, 'components'));
+    // AcmeButton replaces Core's Button, so bare `Button` opens AcmeButton.
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeButton', displayName: 'Acme Button', description: 'A button.', replaces: 'Button', props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'AcmeButton.tsx'),
+      'export function AcmeButton() { return null; }\n',
+    );
+    // A page template with a Core page's id makes the bare id ambiguous.
+    fs.mkdirSync(path.join(pkgDir, 'templates'));
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', `${page}.doc.mjs`),
+      "export default {type: 'page', name: 'Acme page', displayName: 'Acme page', description: 'A page.'};\n",
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', `${page}.tsx`),
+      'export default function Fixture() { return null; }\n',
+    );
+
+    const detail = await docs('using-widgets', undefined, {cwd: tmpDir, full: true});
+
+    const prose = JSON.stringify(detail.data.sections);
+    expect(prose).toContain('`astryx component Button --package @astryxdesign/core`');
+    expect(prose).toContain('`astryx component Badge`');
+    expect(prose).toContain(
+      `\`astryx template ${page} --type page --package @astryxdesign/core\``,
+    );
+    expect(prose).toContain(`\`astryx template ${block} --type block\``);
+  }, 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});
@@ -323,7 +447,7 @@ describe('integration-contributed topics', () => {
     // places it.
     expect(top).toContain('troubleshooting');
     expect(
-      top.some(name => /^cli\/integrations\/(?:.+\/)?troubleshooting$/.test(name)),
+      top.some(name => /^authoring\/(?:.+\/)?troubleshooting$/.test(name)),
       top.join(', '),
     ).toBe(true);
   }, 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;