@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/api/docs/detail/detail.mjs

@@ -13,7 +13,7 @@
 
 import {linkReferenceTopic} from '../../../foundation/doc-compiler/compile.mjs';
 import {detailView} from '../../../foundation/doc-compiler/lenses.mjs';
-import {referenceTargets, resolveTopicDocs} from '../_adapter.mjs';
+import {referenceTargets, resolveTopicDocs, topicLinks} from '../_adapter.mjs';
 
 /**
  * @param {string} topic
@@ -25,10 +25,18 @@ import {referenceTargets, resolveTopicDocs} from '../_adapter.mjs';
  * @returns {Promise<import('../docs.type.mjs').DocsDetailResponse>}
  */
 export async function detail(topic, options = {}) {
-  const {catalog, node, lang} = await resolveTopicDocs(topic, options);
+  const {catalog, node, lang, entry} = await resolveTopicDocs(topic, options);
   const linked = await linkReferenceTopic(
     node,
     referenceTargets(catalog, lang),
   );
-  return {type: 'docs.detail', data: detailView(linked)};
+  return {
+    type: 'docs.detail',
+    data: {
+      ...detailView(linked),
+      // A guide the docs tree places is read by its route, not its doc name.
+      ...(entry.tree ? {name: entry.name} : {}),
+      links: await topicLinks(catalog, entry),
+    },
+  };
 }

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

@@ -4,9 +4,9 @@
  * @file docs.detail.section leaf — load a single section of a topic.
  *
  * @input A topic name, a section query, and optional {lang, zh, dense}. Resolves
- *   the topic via the shared adapter, finds the section in its lowered compiled
- *   node by its stable key, then by exact title, then by a title that contains
- *   the query, and links only that section.
+ *   the topic via the shared adapter, keeps the 0.6.x first title-substring
+ *   match, then falls back to a stable key or normalized title key, and links
+ *   only that section.
  * @output { type: 'docs.detail.section', data: ReferenceSection } with any
  *   token-ref blocks inlined — matching `astryx --json docs <topic> <section>`.
  *   Throws ERR_UNKNOWN_SECTION when nothing matches, or when the query matches
@@ -50,18 +50,15 @@ export async function section(topic, sectionName, options = {}) {
     );
   }
 
-  const {catalog, node, lang} = await resolveTopicDocs(topic, options);
+  const {catalog, node, lang, entry} = await resolveTopicDocs(topic, options);
   const sections = readerSections(node);
-  const {section: match, candidates} = findDocSection(sections, sectionName);
+  const {section: match} = findDocSection(sections, sectionName);
   if (!match) {
-    const ambiguous = candidates.length > 1;
     throw new AstryxError(
-      ambiguous
-        ? `Section "${sectionName}" matches ${candidates.length} sections in "${topic}". Read one by its key.`
-        : `Section "${sectionName}" not found in "${topic}"`,
-      (ambiguous ? candidates : sections).map(s => ({
-        name: sectionKey(s),
-        reason: s.title,
+      `Section "${sectionName}" not found in "${topic}"`,
+      sections.map(s => ({
+        name: s.title,
+        reason: 'available section',
       })),
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );
@@ -74,5 +71,19 @@ export async function section(topic, sectionName, options = {}) {
     match,
     referenceTargets(catalog, lang),
   );
-  return {type: 'docs.detail.section', data: sectionView(node, linked)};
+  // The moves from one section (spec:AST-047): up to its topic's index, and
+  // across to the sections before and after it.
+  const at = sections.indexOf(match);
+  /** @type {import('../../docs.type.mjs').DocsLinks} */
+  const links = {up: `astryx docs ${entry.name} --index`};
+  if (at > 0) {
+    links.previous = `astryx docs ${entry.name} ${sectionKey(sections[at - 1])}`;
+  }
+  if (at !== -1 && at < sections.length - 1) {
+    links.next = `astryx docs ${entry.name} ${sectionKey(sections[at + 1])}`;
+  }
+  return {
+    type: 'docs.detail.section',
+    data: {...sectionView(node, linked), links},
+  };
 }

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

@@ -30,6 +30,17 @@ describe('docs.detail.section leaf', () => {
     }
     expect(err).toBeInstanceOf(AstryxError);
     expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+    expect(err.suggestions).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: expect.any(String),
+          reason: 'available section',
+        }),
+      ]),
+    );
+    expect(err.suggestions.some(suggestion => /\s/u.test(suggestion.name))).toBe(
+      true,
+    );
   }, SLOW);
 
   it('does not return the first section for an empty section name', async () => {
@@ -50,12 +61,10 @@ describe('docs.detail.section leaf', () => {
     expect(res.data.id).toBe(target.id);
   }, SLOW);
 
-  it('refuses a query that matches more than one section', async () => {
-    const err = await section('theme', 'e').catch(e => e);
-    expect(err).toBeInstanceOf(AstryxError);
-    expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    expect(err.message).toMatch(/matches \d+ sections/);
-    expect(err.suggestions.length).toBeGreaterThan(1);
+  it('keeps a previously accepted ambiguous query on its first match', async () => {
+    const res = await section('theme', 'e');
+    expect(res.type).toBe('docs.detail.section');
+    expect(res.data).toBeDefined();
   }, SLOW);
 
   it.each([null, 'zh', 'dense'])(

package/api/docs/docs.d.mts

@@ -15,7 +15,8 @@
  *   import('./docs.type.mjs').DocsListResponse |
  *   import('./docs.type.mjs').DocsIndexResponse |
  *   import('./docs.type.mjs').DocsDetailResponse |
- *   import('./docs.type.mjs').DocsDetailSectionResponse
+ *   import('./docs.type.mjs').DocsDetailSectionResponse |
+ *   import('./docs.type.mjs').DocsNodeResponse
  * >}
  */
 export function docs(topic?: string, section?: string, options?: {
@@ -24,9 +25,10 @@ export function docs(topic?: string, section?: string, options?: {
     dense?: boolean | undefined;
     index?: boolean | undefined;
     cwd?: string | undefined;
-}): Promise<import("./docs.type.mjs").DocsListResponse | import("./docs.type.mjs").DocsIndexResponse | import("./docs.type.mjs").DocsDetailResponse | import("./docs.type.mjs").DocsDetailSectionResponse>;
+}): Promise<import("./docs.type.mjs").DocsListResponse | import("./docs.type.mjs").DocsIndexResponse | import("./docs.type.mjs").DocsDetailResponse | import("./docs.type.mjs").DocsDetailSectionResponse | import("./docs.type.mjs").DocsNodeResponse>;
 import { list } from './list/list.mjs';
 import { index } from './index/index.mjs';
 import { detail } from './detail/detail.mjs';
 import { section as sectionLeaf } from './detail/section/section.mjs';
-export { list, index, detail, sectionLeaf as section };
+import { node as nodeLeaf } from './node/node.mjs';
+export { list, index, detail, sectionLeaf as section, nodeLeaf as node };

package/api/docs/docs.doc.mjs

@@ -11,22 +11,32 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'docs',
+  namespace: 'cli/api',
   displayName: 'docs()',
   summary:
     'Read the reference docs: list every topic, one topic\'s sections, one section, or a whole topic.',
   description:
-    'No topic lists every reference-doc topic; a topic returns that full ' +
-    'ReferenceDoc; `index: true` returns the topic\'s section index instead ' +
-    '(each section\'s key, title, and summary); a topic plus a section returns ' +
-    'that one section, found by its key, then its exact title, then a unique ' +
-    'part of its title (an ambiguous query is refused). Token-ref blocks are ' +
-    'inlined in every read. The topic set is the CLI\'s own docs plus the ' +
+    'No topic lists every reference-doc topic; a topic returns its whole ' +
+    'ReferenceDoc, and `index: true` returns its section index (each ' +
+    'section\'s key, title, and summary); a topic plus a section returns ' +
+    'that one section. Token-ref blocks are ' +
+    'inlined in every read, and so is a section\'s reference block: the doc it ' +
+    'includes, then the command that opens that doc. 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. ' +
+    'A route opens a node of the docs tree instead: a namespace such as ' +
+    "`cli/api` returns its children one level down, a typed doc such as " +
+    "`cli/api/functions/search` returns its content, and a guide the tree " +
+    'places (`cli/integrations`) 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.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsIndexResponse | DocsDetailResponse | DocsDetailSectionResponse>',
+    'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsIndexResponse | DocsDetailResponse | DocsDetailSectionResponse | DocsNodeResponse>',
   keywords: [
     'docs',
     'documentation',
@@ -42,7 +52,7 @@ export const doc = {
       name: 'topic',
       type: 'string',
       description:
-        "Doc topic to load (e.g. 'principles'). Omit to list all topics.",
+        "Doc topic to load (e.g. 'principles'), or a docs-tree route (e.g. 'cli/api/functions/search'). Omit to list all topics.",
     },
     {
       name: 'section',
@@ -63,13 +73,14 @@ export const doc = {
     {
       name: 'options.dense',
       type: 'boolean',
-      description: 'Return the token-efficient dense doc variant.',
+      description:
+        'Return the token-efficient dense doc variant. It is written to be read whole, so it returns the whole doc.',
     },
     {
       name: 'options.index',
       type: 'boolean',
       description:
-        "Return the topic's section index (each section's key, title, and summary) instead of the whole doc.",
+        "Return the topic's section index (each section's key, title, and summary), even for a topic with one section.",
     },
     {
       name: 'options.cwd',
@@ -82,41 +93,52 @@ export const doc = {
     {
       type: 'docs.list',
       description:
-        'All available reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order.',
+        "Every reference-doc topic in read order, as DocsListEntry[] ({topic, description, package, replaces?}), each readable with docs(topic). meta.namespaces lists the docs tree's top-level namespaces ({topic, description, package}), and meta.notLoaded each package whose docs did not load ({package, message}).",
     },
     {
       type: 'docs.detail',
       description:
-        "One topic's full ReferenceDoc, with token-ref blocks inlined.",
+        "One topic's full ReferenceDoc, with token-ref and reference blocks inlined, plus links.",
     },
     {
       type: 'docs.index',
       description:
-        "One topic's section index (index: true): {name, title, description, sections: [{id, title, summary}]}.",
+        "One topic's section index (index: true): {name, title, description, sections: [{id, title, summary}], links}.",
     },
     {
       type: 'docs.detail.section',
       description:
-        'One ReferenceSection of the topic, found by key or title, with token-ref blocks inlined.',
+        'One ReferenceSection of the topic, found by key or title, with token-ref and reference blocks inlined.',
+    },
+    {
+      type: 'docs.node',
+      description:
+        "A namespace or typed doc in the docs tree, read by its route: {id, route, kind, package, title, summary, breadcrumb, slots, content}. A namespace lists each slot's children one level down; a typed doc carries its content.",
     },
   ],
   throws: [
     {
       code: 'ERR_UNKNOWN_TOPIC',
-      when: 'the topic is not a string or matches no known doc topic',
+      when: 'the topic is not a string, or matches no topic and no docs-tree route',
     },
     {
       code: 'ERR_UNKNOWN_SECTION',
-      when: 'a section is requested but is empty, matches no section, or matches more than one',
+      when: 'a section is requested but is empty, matches no section, matches more than one, or is asked of a docs-tree namespace or typed doc, which have no sections',
     },
   ],
   examples: [
     {label: 'List topics', code: 'const r = await docs();'},
-    {label: 'Load a topic', code: "await docs('principles');"},
+    {label: 'A whole topic', code: "await docs('principles');"},
     {
       label: "A topic's sections",
       code: "await docs('principles', undefined, {index: true});",
     },
+    {label: 'A docs-tree namespace', code: "await docs('cli/api');"},
+    {label: 'One API function', code: "await docs('cli/api/functions/search');"},
+    {
+      label: 'A whole guide from the docs tree',
+      code: "await docs('cli/integrations');",
+    },
     {label: 'One section by key', code: "await docs('tokens', 'spacing');"},
   ],
   command: 'docs',

package/api/docs/docs.mjs

@@ -3,27 +3,35 @@
 /**
  * @file Programmatic API for the docs command.
  *
- * Dispatcher + barrel. `docs()` routes by argument shape into one of four
+ * Dispatcher + barrel. `docs()` routes by argument shape into one of five
  * leaves, each projecting into a single { type, data } envelope:
  *
  *   docs()                                -> list    -> docs.list
  *   docs(topic)                           -> detail  -> docs.detail
  *   docs(topic, undefined, {index: true}) -> index   -> docs.index
  *   docs(topic, section)                  -> section -> docs.detail.section
+ *   docs(route)                           -> node    -> docs.node
  *
- * A topic read returns the whole doc, as it always has. The index is how a
- * reader works progressively instead: list the topic's sections, then read one
- * by its key. The leaves live in list/, index/, detail/, and detail/section/;
- * the discovery, overlay loading, and topic resolution they share sit in
- * _adapter.mjs.
+ * A topic read returns the whole doc, as it always has; `index` returns its
+ * sections, so a reader can open one by its key (spec:AST-047). The CLI's text
+ * view lists the sections by default. A route names a node
+ * of the docs tree (spec:AST-046): a namespace lists its children, a guide the
+ * tree places reads like any topic, and a typed doc prints its content. The
+ * leaves
+ * live in list/, index/, detail/, detail/section/, and node/; the discovery,
+ * overlay loading, and resolution they share sit in _adapter.mjs.
  */
 
 import {list} from './list/list.mjs';
 import {index} from './index/index.mjs';
 import {detail} from './detail/detail.mjs';
 import {section as sectionLeaf} from './detail/section/section.mjs';
+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';
 
-export {list, index, detail, sectionLeaf as section};
+export {list, index, detail, sectionLeaf as section, nodeLeaf as node};
 
 /**
  * @param {string} [topic]
@@ -39,11 +47,39 @@ export {list, index, detail, sectionLeaf as section};
  *   import('./docs.type.mjs').DocsListResponse |
  *   import('./docs.type.mjs').DocsIndexResponse |
  *   import('./docs.type.mjs').DocsDetailResponse |
- *   import('./docs.type.mjs').DocsDetailSectionResponse
+ *   import('./docs.type.mjs').DocsDetailSectionResponse |
+ *   import('./docs.type.mjs').DocsNodeResponse
  * >}
  */
 export async function docs(topic, section, options = {}) {
   if (!topic) return list(options);
+  const found = await resolveDocsArgument(topic, options);
+  if (found.kind === 'node') {
+    // A namespace or a typed doc has no sections: it is one read. `--index`
+    // asks for what the node read already is.
+    if (section) {
+      throw new AstryxError(
+        `"${found.node.route}" has no sections. ${
+          found.node.kind === 'namespace'
+            ? 'Open one of its children instead.'
+            : `Read it whole: astryx docs ${found.node.route}.`
+        }`,
+        found.node.kind === 'namespace'
+          ? found.node.slots.flatMap(slot =>
+              slot.children.map(route => ({
+                name: route,
+                reason: found.tree.get(route)?.summary ?? '',
+              })),
+            )
+          : [{name: found.node.route, reason: found.node.summary}],
+        ERROR_CODES.ERR_UNKNOWN_SECTION,
+      );
+    }
+    return {
+      type: 'docs.node',
+      data: await nodeView(found.catalog, found.tree, found.node),
+    };
+  }
   if (section) return sectionLeaf(topic, section, options);
   if (options.index) return index(topic, options);
   return detail(topic, options);

package/api/docs/docs.test.mjs

@@ -26,11 +26,9 @@ describe('docs() dispatcher routing', () => {
     expect((await docs('')).type).toBe('docs.list');
   }, SLOW);
 
-  it('topic only -> docs.detail', async () => {
+  it('topic only -> docs.detail, the whole doc', async () => {
     const {data} = await docs();
-    const topic = data[0].topic;
-    const r = await docs(topic);
-    expect(r.type).toBe('docs.detail');
+    expect((await docs(data[0].topic)).type).toBe('docs.detail');
   }, SLOW);
 
   it('topic + index -> docs.index', async () => {
@@ -69,6 +67,162 @@ describe('docs() dispatcher routing', () => {
     });
   }, SLOW);
 
+  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', 'unorganized']);
+    for (const entry of res.data) {
+      expect((await docs(entry.topic)).type).toBe('docs.detail');
+    }
+  }, SLOW);
+
+  it('opens a route typed in another case', async () => {
+    const r = await docs('CLI/API');
+    expect(r.type).toBe('docs.node');
+    expect(r.data).toMatchObject({route: 'cli/api', links: {up: 'astryx docs cli'}});
+  }, SLOW);
+
+  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.suggestions.map(s => s.name)).toEqual(['cli/api/functions/search']);
+  }, SLOW);
+
+  it('a namespace route -> docs.node, one level of children', async () => {
+    const r = await docs('cli/api');
+    expect(r.type).toBe('docs.node');
+    expect(r.data).toMatchObject({
+      id: 'astryx:artifact:v1/%40astryxdesign%2Fcli/namespace/api',
+      route: 'cli/api',
+      kind: 'namespace',
+      package: '@astryxdesign/cli',
+      breadcrumb: [{route: 'cli', title: 'Astryx CLI'}],
+      content: [],
+    });
+    expect(r.data.slots.flatMap(slot => slot.children.map(c => c.route))).toEqual([
+      'cli/api/functions',
+      'cli/api/schemas',
+      'cli/api/enums',
+    ]);
+  }, SLOW);
+
+  it('a typed doc route -> docs.node with its content', async () => {
+    const r = await docs('cli/api/functions/search');
+    expect(r.type).toBe('docs.node');
+    expect(r.data).toMatchObject({
+      id: 'astryx:artifact:v1/%40astryxdesign%2Fcli/function/search',
+      kind: 'function',
+      title: 'search()',
+      slots: [],
+    });
+    expect(r.data.breadcrumb.map(link => link.route)).toEqual([
+      'cli',
+      'cli/api',
+      'cli/api/functions',
+    ]);
+    expect(JSON.stringify(r.data.content)).toContain(
+      '`astryx search` runs it. Read it with `astryx docs cli/commands/search`.',
+    );
+  }, SLOW);
+
+  it('a guide the tree places reads like a topic: the whole doc, its index, a section', async () => {
+    expect((await docs('cli/integrations')).type).toBe('docs.detail');
+    const index = await docs('cli/integrations', undefined, {index: true});
+    expect(index).toMatchObject({type: 'docs.index', data: {name: 'cli/integrations'}});
+    expect(index.data.sections.length).toBeGreaterThan(1);
+    expect((await docs('cli/integrations', 'components')).type).toBe(
+      'docs.detail.section',
+    );
+  }, SLOW);
+
+  it('every read carries its moves (spec:AST-047)', async () => {
+    const root = (await docs('cli')).data;
+    expect(root.links).toEqual({up: 'astryx docs'});
+    const leaf = (await docs('cli/api/functions/search')).data;
+    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 index = await docs('cli/integrations', 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',
+      next: 'astryx docs cli/writing-docs',
+    });
+    const first = (await docs('cli/integrations', index.data.sections[0].id)).data;
+    expect(first.links).toEqual({
+      up: 'astryx docs cli/integrations --index',
+      next: `astryx docs cli/integrations ${index.data.sections[1].id}`,
+    });
+    const last = index.data.sections.at(-1).id;
+    const end = (await docs('cli/integrations', last)).data;
+    expect(end.links.next).toBeUndefined();
+    expect(end.links.previous).toBe(
+      `astryx docs cli/integrations ${index.data.sections.at(-2).id}`,
+    );
+    // A flat topic's home is the Unorganized level, and it moves across it.
+    const flat = (await docs('principles')).data.links;
+    expect(flat.up).toBe('astryx docs unorganized');
+    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),
+    );
+  }, SLOW);
+
+  it('names a node by its doc identity; a generated level has id null', async () => {
+    const level = (await docs('cli/api/functions')).data;
+    expect(level).toHaveProperty('id', null);
+    expect(level.route).toBe('cli/api/functions');
+  }, SLOW);
+
+  it("offers a typed doc's related docs as moves", async () => {
+    const fn = (await docs('cli/api/functions/search')).data;
+    expect(fn.links.related).toContain('astryx docs cli/commands/search');
+    const cmd = (await docs('cli/commands/search')).data;
+    expect(cmd.links.related).toContain('astryx docs cli/api/functions/search');
+  }, SLOW);
+
+  it('a topic read returns the whole doc; index returns its sections', async () => {
+    expect((await docs('principles')).type).toBe('docs.detail');
+    const index = await docs('principles', undefined, {index: true});
+    expect(index.type).toBe('docs.index');
+    expect(index.data.sections.length).toBeGreaterThan(1);
+    expect((await docs('principles', undefined, {dense: true})).type).toBe(
+      'docs.detail',
+    );
+  }, 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'})],
+    });
+    expect((await docs()).data.map(entry => entry.topic)).not.toContain(
+      'cli-integrations',
+    );
+  }, SLOW);
+
+  it('a section of a namespace -> ERR_UNKNOWN_SECTION, naming its children', async () => {
+    const err = await docs('cli', 'commands').catch(e => e);
+    expect(err).toBeInstanceOf(AstryxError);
+    expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+    expect(err.suggestions.map(s => s.name)).toEqual([
+      'cli/integrations',
+      'cli/writing-docs',
+      'cli/commands',
+      'cli/api',
+    ]);
+  }, SLOW);
+
+  it('an unknown route suggests the children of the deepest namespace it reaches', async () => {
+    const err = await docs('cli/api/functions/serch').catch(e => e);
+    expect(err.code).toBe('ERR_UNKNOWN_TOPIC');
+    expect(err.suggestions.map(s => s.name)).toContain('cli/api/functions/search');
+    expect(err.suggestions.every(s => s.name.startsWith('cli/api/functions/'))).toBe(true);
+  }, SLOW);
+
   it('non-string topic -> ERR_UNKNOWN_TOPIC (not a raw TypeError)', async () => {
     for (const bad of [123, {}, ['tokens'], true]) {
       const err = await docs(/** @type {any} */ (bad)).catch(e => e);