@astryxdesign/cli 0.6.3-canary.6ef7b74 → 0.6.3-canary.6f03d72

package/README.md

@@ -403,8 +403,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `component.detail.blocks`         | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                                                                    |
 | `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                                                                                       |
 | `docs.detail`                     | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                                                                                 |
-| `docs.index`                      | One topic's section index (--index): each section's key, title, and one-line summary.                                                                                                                                                                                                         |
-| `docs.detail.section`             | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined.                                                                                                                                                                                                        |
+| `docs.detail.section`             | A single ReferenceSection of a topic: the first whose title contains the section query.                                                                                                                                                                                                       |
 | `blog.list`                       | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                                                                      |
 | `blog.detail`                     | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                                                                     |
 | `discover.list`                   | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                            |

package/api/docs/_adapter.d.mts

@@ -39,12 +39,6 @@ export function loadReferenceDocs(docPath: string, { lang }?: {
 export function loadTopicDoc(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, { lang }?: {
     lang?: string | null;
 }): Promise<import("./docs.type.mjs").DocsDetailResponse["data"]>;
-/**
- * The overlay languages a topic ships for its own file or any extension.
- * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @returns {string[]}
- */
-export function overlayLanguages(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): string[];
 /**
  * Resolve `topic` against the project's catalog (throwing `ERR_UNKNOWN_TOPIC`
  * when unmatched), and load it with any --dense/--zh overlay and any
@@ -60,7 +54,6 @@ export function overlayLanguages(entry: import("../../foundation/discovery/docs-
  * @returns {Promise<{
  *   catalog: DocsCatalog,
  *   docsData: import('./docs.type.mjs').DocsDetailResponse['data'],
- *   lang: string | null,
  * }>}
  */
 export function resolveTopicDocs(topic: string, options?: {
@@ -71,8 +64,5 @@ export function resolveTopicDocs(topic: string, options?: {
 }): Promise<{
     catalog: DocsCatalog;
     docsData: import("./docs.type.mjs").DocsDetailResponse["data"];
-    lang: string | null;
 }>;
-/** The localized overlays a docs read can apply. */
-export const OVERLAY_LANGUAGES: string[];
 import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';

package/api/docs/_adapter.mjs

@@ -23,16 +23,9 @@ import {Project} from '../../foundation/config/project.mjs';
 import {
   DocsCatalog,
   mergeTopic,
-  problemsInTopic,
-  withSourceTitle,
 } from '../../foundation/discovery/docs-discovery.mjs';
-import {
-  sectionKeyProblems,
-  withSectionKeys,
-} from '../../foundation/discovery/docs-section-key.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
-import {parseDoc} from '../../authoring/doctypes/parse.mjs';
 
 /**
  * The project's topics: the built-in ones plus whatever the configured
@@ -63,20 +56,13 @@ export async function loadDocsCatalog(cwd = process.cwd()) {
  */
 export async function loadReferenceDocs(docPath, {lang} = {}) {
   const mod = await import(pathToFileURL(docPath).href);
-  const parsed = parseDoc(mod.docs ?? mod.default, path.basename(docPath));
-  if (!('sections' in parsed)) {
-    throw new Error(`${path.basename(docPath)} is not a reference document.`);
-  }
-  const problems = problemsInTopic(parsed);
-  if (problems.length > 0) {
-    throw new Error(
-      `${path.basename(docPath)} is invalid: ${problems.join('; ')}`,
-    );
-  }
-  const docs = parsed;
+  const docs = mod.docs ?? mod.default;
   if (!lang || lang === 'en') return docs;
 
-  const translationPath = overlayPath(docPath, lang);
+  const dir = path.dirname(docPath);
+  const base = path.basename(docPath, '.doc.mjs');
+  const locale = lang === 'dense' ? 'dense' : lang;
+  const translationPath = path.join(dir, `${base}.doc.${locale}.mjs`);
   if (!fs.existsSync(translationPath)) return docs;
 
   const translationMod = await import(pathToFileURL(translationPath).href);
@@ -100,12 +86,10 @@ export async function loadReferenceDocs(docPath, {lang} = {}) {
     ...docs,
     description: translation.description || docs.description,
     sections: docs.sections.map(
-      (
-        /** @type {import('@astryxdesign/cli/authoring').ReferenceSection} */ section,
-      ) => {
+      (/** @type {import('@astryxdesign/cli/authoring').ReferenceSection} */ section) => {
         const ts = bySection.get(section.title);
         if (!ts) return section;
-        const localized = {
+        return {
           ...section,
           title: ts.title || section.title,
           content: section.content.map(
@@ -115,15 +99,12 @@ export async function loadReferenceDocs(docPath, {lang} = {}) {
             ) => {
               const tb = ts.content?.[bi];
               if (!tb) return block;
-              if (tb.type === 'prose' && block.type === 'prose')
-                return {...block, text: tb.text};
-              if (tb.type === 'list' && block.type === 'list')
-                return {...block, items: tb.items};
+              if (tb.type === 'prose' && block.type === 'prose') return {...block, text: tb.text};
+              if (tb.type === 'list' && block.type === 'list') return {...block, items: tb.items};
               return block;
             },
           ),
         };
-        return withSourceTitle(localized, section.title);
       },
     ),
   };
@@ -146,44 +127,8 @@ export async function loadTopicDoc(entry, {lang} = {}) {
   let doc = await loadReferenceDocs(entry.path, {lang});
   for (const extension of entry.extensions) {
     doc = mergeTopic(doc, await loadReferenceDocs(extension.path, {lang}));
-    // Merging matches on keys, so this holds unless merge itself regresses.
-    const problems = sectionKeyProblems(doc.sections);
-    if (problems.length > 0) {
-      throw new Error(
-        `${path.basename(extension.path)}, extending ${entry.name}, leaves two sections with one key: ${problems.join('; ')}`,
-      );
-    }
   }
-  // Derived keys are stamped only now, so they never take part in merging.
-  return withSectionKeys(doc);
-}
-
-/** The localized overlays a docs read can apply. */
-export const OVERLAY_LANGUAGES = ['zh', 'dense'];
-
-/**
- * Where the `lang` overlay of a doc file lives: `{topic}.doc.{lang}.mjs`.
- * @param {string} docPath
- * @param {string} lang
- * @returns {string}
- */
-function overlayPath(docPath, lang) {
-  return path.join(
-    path.dirname(docPath),
-    `${path.basename(docPath, '.doc.mjs')}.doc.${lang}.mjs`,
-  );
-}
-
-/**
- * The overlay languages a topic ships for its own file or any extension.
- * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @returns {string[]}
- */
-export function overlayLanguages(entry) {
-  const files = [entry.path, ...entry.extensions.map(ext => ext.path)];
-  return OVERLAY_LANGUAGES.filter(lang =>
-    files.some(file => fs.existsSync(overlayPath(file, lang))),
-  );
+  return doc;
 }
 
 /**
@@ -201,7 +146,6 @@ export function overlayLanguages(entry) {
  * @returns {Promise<{
  *   catalog: DocsCatalog,
  *   docsData: import('./docs.type.mjs').DocsDetailResponse['data'],
- *   lang: string | null,
  * }>}
  */
 export async function resolveTopicDocs(topic, options = {}) {
@@ -222,5 +166,5 @@ export async function resolveTopicDocs(topic, options = {}) {
   }
 
   const docsData = await loadTopicDoc(entry, {lang: effectiveLang});
-  return {catalog, docsData, lang: effectiveLang};
+  return {catalog, docsData};
 }

package/api/docs/detail/detail.d.mts

@@ -1,21 +1,6 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/**
- * 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. It
- * names the section by key or authored title, so it resolves in every language.
- * @param {import('../docs.type.mjs').DocsDetailResponse['data']} docsData
- * @param {import('../../../foundation/discovery/docs-discovery.mjs').DocsCatalog} catalog
- * @param {{lang?: string | null}} [options]
- * @returns {Promise<import('../docs.type.mjs').DocsDetailResponse['data']>}
- */
-export function resolveTokenRefs(docsData: import("../docs.type.mjs").DocsDetailResponse["data"], catalog: import("../../../foundation/discovery/docs-discovery.mjs").DocsCatalog, { lang }?: {
-    lang?: string | null;
-}): Promise<import("../docs.type.mjs").DocsDetailResponse["data"]>;
 /**
  * @param {string} topic
  * @param {object} [options]

package/api/docs/detail/detail.mjs

@@ -12,25 +12,18 @@
  */
 
 import {loadTopicDoc, resolveTopicDocs} from '../_adapter.mjs';
-import {
-  sectionKey,
-  sourceTitle,
-  withSourceTitle,
-} from '../../../foundation/discovery/docs-section-key.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. It
- * names the section by key or authored title, so it resolves in every language.
+ * 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
- * @param {{lang?: string | null}} [options]
  * @returns {Promise<import('../docs.type.mjs').DocsDetailResponse['data']>}
  */
-export async function resolveTokenRefs(docsData, catalog, {lang = null} = {}) {
+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];
@@ -43,12 +36,10 @@ export async function resolveTokenRefs(docsData, catalog, {lang = null} = {}) {
           newContent.push({type: 'prose', text: `[token-ref: unknown topic "${block.topic}"]`});
           continue;
         }
-        const refDocs = await loadTopicDoc(refEntry, {lang});
-        const wanted = block.section.toLowerCase();
+        const refDocs = await loadTopicDoc(refEntry);
         const refSection = refDocs.sections.find(
           (/** @type {import('@astryxdesign/cli/authoring').ReferenceSection} */ s) =>
-            sectionKey(s) === block.section ||
-            sourceTitle(s).toLowerCase() === wanted,
+            s.title.toLowerCase() === block.section.toLowerCase(),
         );
         if (!refSection) {
           newContent.push({type: 'prose', text: `[token-ref: section "${block.section}" not found in "${block.topic}"]`});
@@ -61,20 +52,14 @@ export async function resolveTokenRefs(docsData, catalog, {lang = null} = {}) {
         }
         // If the referenced section has a previewType, attach it to our section
         if (refSection.previewType && !section.previewType) {
-          resolved.sections[si] = withSourceTitle(
-            {...section, previewType: refSection.previewType, content: newContent},
-            sourceTitle(section),
-          );
+          resolved.sections[si] = {...section, previewType: refSection.previewType, content: newContent};
         }
       } else {
         newContent.push(block);
       }
     }
     if (resolved.sections[si] === section) {
-      resolved.sections[si] = withSourceTitle(
-        {...section, content: newContent},
-        sourceTitle(section),
-      );
+      resolved.sections[si] = {...section, content: newContent};
     } else {
       resolved.sections[si].content = newContent;
     }
@@ -92,7 +77,7 @@ export async function resolveTokenRefs(docsData, catalog, {lang = null} = {}) {
  * @returns {Promise<import('../docs.type.mjs').DocsDetailResponse>}
  */
 export async function detail(topic, options = {}) {
-  const {catalog, docsData, lang} = await resolveTopicDocs(topic, options);
-  const resolved = await resolveTokenRefs(docsData, catalog, {lang});
+  const {catalog, docsData} = await resolveTopicDocs(topic, options);
+  const resolved = await resolveTokenRefs(docsData, catalog);
   return {type: 'docs.detail', data: resolved};
 }

package/api/docs/detail/section/section.d.mts

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

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

@@ -1,31 +1,25 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file docs.detail.section leaf — load a single section of a topic.
+ * @file docs.detail.section leaf — load a single named 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 section by its
- *   stable key, then by exact title, then by a title that contains the query.
- * @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).
+ *   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.
  */
 
 import {AstryxError} from '../../../error.mjs';
 import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
-import {
-  findDocSection,
-  sectionKey,
-} from '../../../../foundation/discovery/docs-section-key.mjs';
 import {resolveTopicDocs} from '../../_adapter.mjs';
-import {resolveTokenRefs} from '../detail.mjs';
 
 /**
  * @param {string} topic
- * @param {string} sectionName a section key, or a title (or part of one)
+ * @param {string} sectionName
  * @param {object} [options]
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
@@ -34,9 +28,10 @@ import {resolveTokenRefs} from '../detail.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. 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.
+  // 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.
   if (typeof sectionName !== 'string' || !sectionName.trim()) {
     throw new AstryxError(
       'A section name is required',
@@ -44,31 +39,16 @@ export async function section(topic, sectionName, options = {}) {
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );
   }
-  const {catalog, docsData, lang} = await resolveTopicDocs(topic, options);
+  const {docsData} = await resolveTopicDocs(topic, options);
 
-  const {section: match, candidates} = findDocSection(
-    docsData.sections,
-    sectionName,
-  );
+  const normalizedSection = sectionName.toLowerCase();
+  const match = docsData.sections.find(s => s.title.toLowerCase().includes(normalizedSection));
   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 : docsData.sections).map(s => ({
-        name: sectionKey(s),
-        reason: s.title,
-      })),
+      `Section "${sectionName}" not found in "${topic}"`,
+      docsData.sections.map(s => ({name: s.title, reason: 'available section'})),
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );
   }
-  // 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.
-  const {sections} = await resolveTokenRefs(
-    {...docsData, sections: [match]},
-    catalog,
-    {lang},
-  );
-  return {type: 'docs.detail.section', data: sections[0]};
+  return {type: 'docs.detail.section', data: match};
 }

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

@@ -10,7 +10,6 @@
 import {describe, it, expect} from 'vitest';
 import {section} from './section.mjs';
 import {AstryxError} from '../../../error.mjs';
-import {loadDocsCatalog, loadTopicDoc} from '../../_adapter.mjs';
 
 const SLOW = 30_000;
 
@@ -40,43 +39,4 @@ describe('docs.detail.section leaf', () => {
       code: 'ERR_UNKNOWN_SECTION',
     });
   }, SLOW);
-
-  it('reads a section by its stable key', async () => {
-    const doc = await loadTopicDoc((await loadDocsCatalog()).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('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);
-  }, 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 loadTopicDoc(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,12 +8,9 @@
  * @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
  * >}
@@ -22,11 +19,9 @@ 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").DocsIndexResponse | import("./docs.type.mjs").DocsDetailResponse | import("./docs.type.mjs").DocsDetailSectionResponse>;
+}): Promise<import("./docs.type.mjs").DocsListResponse | import("./docs.type.mjs").DocsDetailResponse | import("./docs.type.mjs").DocsDetailSectionResponse>;
 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 };
+export { list, detail, sectionLeaf as section };

package/api/docs/docs.doc.mjs

@@ -13,20 +13,18 @@ export const doc = {
   name: 'docs',
   displayName: 'docs()',
   summary:
-    'Read the reference docs: list every topic, one topic\'s sections, one section, or a whole topic.',
+    'Read the reference docs: list every topic, one topic, or a single section of a 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 ' +
+    '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 ' +
     'ones the project\'s configured integrations contribute, including any ' +
     'topic an integration replaces or extends, so it depends on the cwd. ' +
     'Overlay options select localized or dense variants.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsIndexResponse | DocsDetailResponse | DocsDetailSectionResponse>',
+    'docs(topic?: string, section?: string, options?: DocsOptions): Promise<DocsListResponse | DocsDetailResponse | DocsDetailSectionResponse>',
   keywords: [
     'docs',
     'documentation',
@@ -48,7 +46,7 @@ export const doc = {
       name: 'section',
       type: 'string',
       description:
-        "Section to return: its key (from the topic's index), its title, or a unique part of its title (case-insensitive).",
+        'Section within the topic to return; matches the first section title that contains this (case-insensitive).',
     },
     {
       name: 'options.lang',
@@ -65,12 +63,6 @@ export const doc = {
       type: 'boolean',
       description: 'Return the token-efficient dense doc variant.',
     },
-    {
-      name: 'options.index',
-      type: 'boolean',
-      description:
-        "Return the topic's section index (each section's key, title, and summary) instead of the whole doc.",
-    },
     {
       name: 'options.cwd',
       type: 'string',
@@ -89,15 +81,10 @@ export const doc = {
       description:
         "One topic's full ReferenceDoc, with token-ref blocks inlined.",
     },
-    {
-      type: 'docs.index',
-      description:
-        "One topic's section index (index: true): {name, title, description, sections: [{id, title, summary}]}.",
-    },
     {
       type: 'docs.detail.section',
       description:
-        'One ReferenceSection of the topic, found by key or title, with token-ref blocks inlined.',
+        'A single ReferenceSection of the topic: the first whose title contains the section query.',
     },
   ],
   throws: [
@@ -107,17 +94,13 @@ export const doc = {
     },
     {
       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 or matches no section title in the topic',
     },
   ],
   examples: [
     {label: 'List topics', code: 'const r = await docs();'},
     {label: 'Load a topic', code: "await docs('principles');"},
-    {
-      label: "A topic's sections",
-      code: "await docs('principles', undefined, {index: true});",
-    },
-    {label: 'One section by key', code: "await docs('tokens', 'spacing');"},
+    {label: 'One section', code: "await docs('tokens', 'spacing');"},
   ],
   command: 'docs',
   related: ['search', 'component', 'hook', 'template'],

package/api/docs/docs.mjs

@@ -3,27 +3,24 @@
 /**
  * @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 three
  * 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()                 -> list    -> docs.list
+ *   docs(topic)            -> detail  -> docs.detail
+ *   docs(topic, section)   -> section -> docs.detail.section
  *
- * 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.
+ * 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.
  */
 
 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};
+export {list, detail, sectionLeaf as section};
 
 /**
  * @param {string} [topic]
@@ -32,12 +29,9 @@ export {list, index, 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
  * >}
@@ -45,6 +39,5 @@ export {list, index, detail, sectionLeaf as section};
 export async function docs(topic, section, options = {}) {
   if (!topic) return list(options);
   if (section) return sectionLeaf(topic, section, options);
-  if (options.index) return index(topic, options);
   return detail(topic, options);
 }

package/api/docs/docs.test.mjs

@@ -33,12 +33,6 @@ describe('docs() dispatcher routing', () => {
     expect(r.type).toBe('docs.detail');
   }, SLOW);
 
-  it('topic + index -> docs.index', async () => {
-    const {data} = await docs();
-    const r = await docs(data[0].topic, undefined, {index: true});
-    expect(r.type).toBe('docs.index');
-  }, SLOW);
-
   it('topic + section -> docs.detail.section', async () => {
     const {data} = await docs();
     let routed = null;