@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/api/docs/compiled-topics.test.mjs

@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every shipped topic compiles to a plain-JSON node that answers every
+ * docs read exactly as the live one does, and no read can change another read
+ * of the same catalog.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {parseCompiledReferenceNode} from '../../foundation/doc-compiler/ir.mjs';
+import {detailView, indexView} from '../../foundation/doc-compiler/lenses.mjs';
+import {
+  compileTopic,
+  loadDocsCatalog,
+  lowerTopic,
+  overlayLanguages,
+} from './_adapter.mjs';
+
+const SLOW = 60_000;
+
+describe('every shipped topic compiles to plain JSON', () => {
+  it(
+    'survives a JSON round trip with identical responses in every language',
+    async () => {
+      const catalog = await loadDocsCatalog();
+      let compiled = 0;
+      for (const entry of catalog.entries()) {
+        for (const lang of [null, ...overlayLanguages(entry)]) {
+          const lowered = await lowerTopic(catalog, entry, lang);
+          expect(parseCompiledReferenceNode(lowered)).toBe(lowered);
+          const node = await compileTopic(catalog, entry, lang);
+          expect(parseCompiledReferenceNode(node)).toBe(node);
+          const copy = parseCompiledReferenceNode(
+            JSON.parse(JSON.stringify(node)),
+          );
+          expect(JSON.stringify(detailView(copy))).toBe(
+            JSON.stringify(detailView(node)),
+          );
+          expect(JSON.stringify(indexView(copy))).toBe(
+            JSON.stringify(indexView(node)),
+          );
+          compiled += 1;
+        }
+      }
+      expect(compiled).toBeGreaterThan(catalog.entries().length);
+    },
+    SLOW,
+  );
+});
+
+describe('reads that share a catalog', () => {
+  it(
+    'never let one read change another',
+    async () => {
+      const catalog = await loadDocsCatalog();
+      const tokens = catalog.resolve('tokens');
+      const first = detailView(await compileTopic(catalog, tokens));
+      for (const section of first.sections) {
+        section.title = 'EDITED';
+        for (const block of section.content) {
+          if (typeof block.text === 'string') block.text = 'EDITED';
+          if (Array.isArray(block.rows)) block.rows.push(['EDITED']);
+        }
+      }
+      const again = detailView(await compileTopic(catalog, tokens));
+      const index = indexView(await lowerTopic(catalog, tokens));
+      const spacing = detailView(
+        await compileTopic(catalog, catalog.resolve('spacing')),
+      );
+      for (const read of [again, index, spacing]) {
+        expect(JSON.stringify(read)).not.toContain('EDITED');
+      }
+      const lowered = await lowerTopic(catalog, tokens);
+      expect(Object.isFrozen(lowered.doc.sections[0].content)).toBe(true);
+    },
+    SLOW,
+  );
+});

package/api/docs/detail/detail.mjs

@@ -3,69 +3,17 @@
 /**
  * @file docs.detail leaf — load one topic's full reference doc.
  *
- * @input A topic name plus optional {lang, zh, dense}. Resolves and loads the
- *   topic via the shared adapter, then inlines any token-ref blocks.
+ * @input A topic name plus optional {lang, zh, dense, cwd}. Resolves the topic
+ *   via the shared adapter and compiles it with its token references linked.
  * @output { type: 'docs.detail', data: ReferenceDoc } — the full doc with
- *   token-refs resolved, matching `xds --json docs <topic>`.
- * @position Leaf under api/docs. Owns resolveTokenRefs (used only here); shares
- *   discovery/loading/topic-resolution with the section leaf via _adapter.mjs.
+ *   token-refs inlined, matching `astryx --json docs <topic>`.
+ * @position Leaf under api/docs. Reads the compiled node through the detail
+ *   lens; resolution, overlays and extensions happen in the compiler.
  */
 
-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 {import('../../../foundation/discovery/docs-discovery.mjs').DocsCatalog} catalog
- * @returns {Promise<import('../docs.type.mjs').DocsDetailResponse['data']>}
- */
-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];
-    /** @type {import('@astryxdesign/cli/authoring').ReferenceContentBlock[]} */
-    const newContent = [];
-    for (const block of section.content) {
-      if (block.type === 'token-ref') {
-        const refEntry = catalog.resolve(block.topic);
-        if (!refEntry) {
-          newContent.push({type: 'prose', text: `[token-ref: unknown topic "${block.topic}"]`});
-          continue;
-        }
-        const refDocs = await loadTopicDoc(refEntry);
-        const refSection = refDocs.sections.find(
-          (/** @type {import('@astryxdesign/cli/authoring').ReferenceSection} */ s) =>
-            s.title.toLowerCase() === block.section.toLowerCase(),
-        );
-        if (!refSection) {
-          newContent.push({type: 'prose', text: `[token-ref: section "${block.section}" not found in "${block.topic}"]`});
-          continue;
-        }
-        // Inline the referenced section's content blocks (tables, prose, etc.)
-        // and carry over the previewType
-        for (const refBlock of refSection.content) {
-          newContent.push(refBlock);
-        }
-        // If the referenced section has a previewType, attach it to our section
-        if (refSection.previewType && !section.previewType) {
-          resolved.sections[si] = {...section, previewType: refSection.previewType, content: newContent};
-        }
-      } else {
-        newContent.push(block);
-      }
-    }
-    if (resolved.sections[si] === section) {
-      resolved.sections[si] = {...section, content: newContent};
-    } else {
-      resolved.sections[si].content = newContent;
-    }
-  }
-  return resolved;
-}
+import {linkReferenceTopic} from '../../../foundation/doc-compiler/compile.mjs';
+import {detailView} from '../../../foundation/doc-compiler/lenses.mjs';
+import {referenceTargets, resolveTopicDocs, topicLinks} from '../_adapter.mjs';
 
 /**
  * @param {string} topic
@@ -77,7 +25,18 @@ async function resolveTokenRefs(docsData, catalog) {
  * @returns {Promise<import('../docs.type.mjs').DocsDetailResponse>}
  */
 export async function detail(topic, options = {}) {
-  const {catalog, docsData} = await resolveTopicDocs(topic, options);
-  const resolved = await resolveTokenRefs(docsData, catalog);
-  return {type: 'docs.detail', data: resolved};
+  const {catalog, node, lang, entry} = await resolveTopicDocs(topic, options);
+  const linked = await linkReferenceTopic(
+    node,
+    referenceTargets(catalog, lang),
+  );
+  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.d.mts

@@ -3,7 +3,7 @@
 
 /**
  * @param {string} topic
- * @param {string} sectionName
+ * @param {string} sectionName a section key, or a title (or part of one)
  * @param {object} [options]
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]

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

@@ -1,25 +1,36 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file docs.detail.section leaf — load a single named section of a topic.
+ * @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
- *   and loads the topic via the shared adapter, then finds the first section
- *   whose title contains the (case-insensitive) query.
- * @output { type: 'docs.detail.section', data: ReferenceSection } — matching
- *   `xds --json docs <topic> <section>`. Throws ERR_UNKNOWN_SECTION when no
- *   section title matches.
- * @position Leaf nested under api/docs/detail. Shares discovery/loading/
- *   topic-resolution with the detail leaf via _adapter.mjs.
+ *   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
+ *   more than one section (the candidates come back as suggestions).
+ * @position Leaf nested under api/docs/detail. Shares topic resolution with the
+ *   detail leaf via _adapter.mjs and reads through the compiler's lenses.
  */
 
 import {AstryxError} from '../../../error.mjs';
 import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
-import {resolveTopicDocs} from '../../_adapter.mjs';
+import {
+  findDocSection,
+  sectionKey,
+} from '../../../../foundation/discovery/docs-section-key.mjs';
+import {linkReferenceSection} from '../../../../foundation/doc-compiler/compile.mjs';
+import {
+  readerSections,
+  sectionView,
+} from '../../../../foundation/doc-compiler/lenses.mjs';
+import {referenceTargets, resolveTopicDocs} from '../../_adapter.mjs';
 
 /**
  * @param {string} topic
- * @param {string} sectionName
+ * @param {string} sectionName a section key, or a title (or part of one)
  * @param {object} [options]
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
@@ -28,10 +39,9 @@ import {resolveTopicDocs} from '../../_adapter.mjs';
  * @returns {Promise<import('../../docs.type.mjs').DocsDetailSectionResponse>}
  */
 export async function section(topic, sectionName, options = {}) {
-  // An empty section name must error, not resolve to the first section via
-  // `.includes('')`. The docs() dispatcher routes a falsy section to detail, but
-  // the leaf must be safe on its own. A non-string would also throw a raw
-  // TypeError below (`.toLowerCase()`) → downgrades to ERR_UNKNOWN.
+  // An empty section name must error, not resolve to the first section. The
+  // docs() dispatcher routes a falsy section to the topic, but the leaf must be
+  // safe on its own; a non-string would otherwise throw a raw TypeError.
   if (typeof sectionName !== 'string' || !sectionName.trim()) {
     throw new AstryxError(
       'A section name is required',
@@ -39,16 +49,41 @@ export async function section(topic, sectionName, options = {}) {
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );
   }
-  const {docsData} = await resolveTopicDocs(topic, options);
 
-  const normalizedSection = sectionName.toLowerCase();
-  const match = docsData.sections.find(s => s.title.toLowerCase().includes(normalizedSection));
+  const {catalog, node, lang, entry} = await resolveTopicDocs(topic, options);
+  const sections = readerSections(node);
+  const {section: match} = findDocSection(sections, sectionName);
   if (!match) {
     throw new AstryxError(
       `Section "${sectionName}" not found in "${topic}"`,
-      docsData.sections.map(s => ({name: s.title, reason: 'available section'})),
+      sections.map(s => ({
+        name: s.title,
+        reason: 'available section',
+      })),
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );
   }
-  return {type: 'docs.detail.section', data: match};
+
+  // A section read on its own inlines its token refs, as the whole topic does;
+  // otherwise a section that is only a token-ref prints blank. Only this
+  // section is linked, so a broken reference elsewhere cannot fail the read.
+  const linked = await linkReferenceSection(
+    match,
+    referenceTargets(catalog, lang),
+  );
+  // 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

@@ -10,6 +10,7 @@
 import {describe, it, expect} from 'vitest';
 import {section} from './section.mjs';
 import {AstryxError} from '../../../error.mjs';
+import {loadDocsCatalog, lowerTopic} from '../../_adapter.mjs';
 
 const SLOW = 30_000;
 
@@ -29,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 () => {
@@ -39,4 +51,42 @@ describe('docs.detail.section leaf', () => {
       code: 'ERR_UNKNOWN_SECTION',
     });
   }, SLOW);
+
+  it('reads a section by its stable key', async () => {
+    const catalog = await loadDocsCatalog();
+    const {doc} = await lowerTopic(catalog, catalog.resolve('theme'));
+    const target = doc.sections[doc.sections.length - 1];
+    const res = await section('theme', target.id);
+    expect(res.data.title).toBe(target.title);
+    expect(res.data.id).toBe(target.id);
+  }, SLOW);
+
+  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'])(
+    'inlines token refs when a section is read on its own (lang %s)',
+    async lang => {
+      const catalog = await loadDocsCatalog();
+      let checked = 0;
+      for (const entry of catalog.entries()) {
+        const {doc} = await lowerTopic(catalog, entry);
+        for (const own of doc.sections) {
+          if (!own.content.some(block => block.type === 'token-ref')) continue;
+          const res = await section(entry.name, own.id, lang ? {lang} : {});
+          expect(res.data.content.length).toBeGreaterThan(0);
+          expect(res.data.content.some(block => block.type === 'token-ref')).toBe(
+            false,
+          );
+          expect(JSON.stringify(res.data.content)).not.toContain('[token-ref:');
+          checked += 1;
+        }
+      }
+      expect(checked).toBeGreaterThan(0);
+    },
+    SLOW,
+  );
 });

package/api/docs/docs.d.mts

@@ -8,20 +8,27 @@
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {boolean} [options.index] return the topic's section index instead of
+ *   the whole doc
  * @param {string} [options.cwd]
  * @returns {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').DocsDetailSectionResponse |
+ *   import('./docs.type.mjs').DocsNodeResponse
  * >}
  */
 export function docs(topic?: string, section?: string, options?: {
     lang?: string | undefined;
     zh?: boolean | undefined;
     dense?: boolean | undefined;
+    index?: boolean | undefined;
     cwd?: string | undefined;
-}): Promise<import("./docs.type.mjs").DocsListResponse | 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, 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,20 +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, or a single section of a topic.',
+    'Read the reference docs: list every topic, one topic\'s sections, one section, or a whole topic.',
   description:
-    '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. 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 | DocsDetailResponse | DocsDetailSectionResponse>',
+    'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsIndexResponse | DocsDetailResponse | DocsDetailSectionResponse | DocsNodeResponse>',
   keywords: [
     'docs',
     'documentation',
@@ -40,13 +52,13 @@ 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',
       type: 'string',
       description:
-        'Section within the topic to return; matches the first section title that contains this (case-insensitive).',
+        "Section to return: its key (from the topic's index), its title, or a unique part of its title (case-insensitive).",
     },
     {
       name: 'options.lang',
@@ -61,7 +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), even for a topic with one section.",
     },
     {
       name: 'options.cwd',
@@ -74,33 +93,53 @@ 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}], links}.",
     },
     {
       type: 'docs.detail.section',
       description:
-        'A single ReferenceSection of the topic: the first whose title contains the section query.',
+        '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 or matches no section title in the topic',
+      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: 'One section', code: "await docs('tokens', 'spacing');"},
+    {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',
   related: ['search', 'component', 'hook', 'template'],

package/api/docs/docs.mjs

@@ -3,24 +3,35 @@
 /**
  * @file Programmatic API for the docs command.
  *
- * Dispatcher + barrel. `docs()` routes by argument shape into one of three
+ * 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, section)   -> section -> docs.detail.section
+ *   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
  *
- * The leaves live in list/, detail/, and detail/section/; the discovery,
- * overlay loading, and topic resolution they share sit in _adapter.mjs. This
- * module keeps the same `docs` export (and re-exports the leaves) so
- * api/index.mjs and the CLI consumer import from here unchanged.
+ * 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, detail, sectionLeaf as section};
+export {list, index, detail, sectionLeaf as section, nodeLeaf as node};
 
 /**
  * @param {string} [topic]
@@ -29,15 +40,47 @@ export {list, detail, sectionLeaf as section};
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
+ * @param {boolean} [options.index] return the topic's section index instead of
+ *   the whole doc
  * @param {string} [options.cwd]
  * @returns {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').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);
 }