@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.f04b501

package/api/discover/discover.type.mjs

@@ -6,16 +6,16 @@
  *
  * Invocation                                      -> type discriminator
  * ------------------------------------------------------------------
- * xds --json discover                            -> discover.list
- * xds --json discover @scope/name                -> discover.detail
- * xds --json discover @scope/name/Component      -> discover.detail.doc
- * xds --json discover <searchterm> (1 match)     -> discover.detail.doc
- * xds --json discover <searchterm> (N matches)   -> discover.search
- * (not found)                                    -> CLIError
+ * astryx --json discover                          -> discover.list
+ * astryx --json discover @scope/name              -> discover.detail
+ * astryx --json discover @scope/name/Component    -> discover.detail.doc
+ * astryx --json discover <searchterm> (1 match)   -> discover.detail.doc
+ * astryx --json discover <searchterm> (N matches) -> discover.search
+ * (not found)                                     -> CLIError
  */
 
 /**
- * xds --json discover
+ * astryx --json discover
  * @typedef {object} DiscoverListResponse
  * @property {'discover.list'} type
  * @property {DiscoverListEntry[]} data
@@ -35,21 +35,21 @@
  */
 
 /**
- * xds --json discover @scope/name
+ * astryx --json discover @scope/name
  * @typedef {object} DiscoverDetailResponse
  * @property {'discover.detail'} type
  * @property {DiscoverListEntry} data
  */
 
 /**
- * xds --json discover @scope/name/Component
+ * astryx --json discover @scope/name/Component
  * @typedef {object} DiscoverDetailDocResponse
  * @property {'discover.detail.doc'} type
  * @property {import('@astryxdesign/cli/authoring').ComponentDoc} data
  */
 
 /**
- * xds --json discover <searchterm> (multiple matches)
+ * astryx --json discover <searchterm> (multiple matches)
  * @typedef {object} DiscoverSearchResponse
  * @property {'discover.search'} type
  * @property {{query: string, matches: DiscoverSearchEntry[]}} data

package/api/docs/_adapter.d.mts

@@ -16,34 +16,37 @@
  */
 export function loadDocsCatalog(cwd?: string): Promise<DocsCatalog>;
 /**
- * @param {string} docPath
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ * One topic, lowered for `lang`: overlaid, extensions merged, keys stamped.
+ * Memoized per catalog, so a read that references a topic twice loads it once.
+ * Every read of the catalog shares the memoized node, so it is frozen; the
+ * lenses hand readers copies.
+ * @param {DocsCatalog} catalog
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
  */
-export function loadReferenceDocs(docPath: string, { lang }?: {
-    lang?: string | null;
-}): Promise<import("./docs.type.mjs").DocsDetailResponse["data"]>;
+export function lowerTopic(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, lang?: string | null): Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode>;
 /**
- * Load one catalog entry: its own doc, plus any extension an integration
- * merged onto it, in configuration order.
- *
- * A localization overlay applies to each file before the extensions are
- * merged, so an extension written in the base language stays readable under
- * `--dense`/`--zh` (it replaces its own sections and leaves the rest
- * translated) rather than being dropped.
- *
+ * How a token reference finds its target: the topic it names in `catalog`,
+ * lowered for the same language.
+ * @param {DocsCatalog} catalog
+ * @param {string | null} lang
+ * @returns {(topic: string) => Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode | null>}
+ */
+export function referenceTargets(catalog: DocsCatalog, lang: string | null): (topic: string) => Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode | null>;
+/**
+ * One topic, compiled for `lang`: lowered, then every token reference linked.
+ * @param {DocsCatalog} catalog
  * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
  */
-export function loadTopicDoc(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, { lang }?: {
-    lang?: string | null;
-}): Promise<import("./docs.type.mjs").DocsDetailResponse["data"]>;
+export function compileTopic(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, lang?: string | null): Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode>;
 /**
  * Resolve `topic` against the project's catalog (throwing `ERR_UNKNOWN_TOPIC`
- * when unmatched), and load it with any --dense/--zh overlay and any
- * integration extension applied. Shared by the detail and section leaves so
- * topic normalization and unknown-topic handling live in exactly one place.
+ * when unmatched) and lower it with any --dense/--zh overlay and any
+ * integration extension applied. Shared by the leaves so topic normalization
+ * and unknown-topic handling live in exactly one place.
  *
  * @param {string} topic
  * @param {object} [options]
@@ -53,7 +56,8 @@ export function loadTopicDoc(entry: import("../../foundation/discovery/docs-disc
  * @param {string} [options.cwd]
  * @returns {Promise<{
  *   catalog: DocsCatalog,
- *   docsData: import('./docs.type.mjs').DocsDetailResponse['data'],
+ *   node: import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode,
+ *   lang: string | null,
  * }>}
  */
 export function resolveTopicDocs(topic: string, options?: {
@@ -63,6 +67,10 @@ export function resolveTopicDocs(topic: string, options?: {
     cwd?: string | undefined;
 }): Promise<{
     catalog: DocsCatalog;
-    docsData: import("./docs.type.mjs").DocsDetailResponse["data"];
+    node: import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode;
+    lang: string | null;
 }>;
 import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';
+import { OVERLAY_LANGUAGES } from '../../foundation/doc-compiler/read.mjs';
+import { overlayLanguages } from '../../foundation/doc-compiler/read.mjs';
+export { OVERLAY_LANGUAGES, overlayLanguages };

package/api/docs/_adapter.mjs

@@ -7,26 +7,33 @@
  *   packages/cli/assets/docs/{topic}.doc.mjs plus every topic the configured
  *   integrations contribute — and, when a --dense/--zh overlay is requested,
  *   the sibling {topic}.doc.dense.mjs / {topic}.doc.zh.mjs.
- * @output Catalog access, overlay- and extension-merged reference-doc data,
- *   and a combined resolve step ({catalog, docsData}) that the detail and
- *   section leaves share.
- * @position Sits beside docs.mjs (api/docs/). Owns everything ≥2 leaves need so
- *   no leaf re-implements resolution, overlay merging, or unknown-topic
- *   handling. Discovery itself lives in foundation/discovery/docs-discovery,
- *   which api/search and the agent-docs block read through the same catalog.
+ * @output Catalog access, the compiler input for a topic, and the compiled
+ *   node for it: lowered (overlaid, extensions merged, keys stamped) or linked
+ *   (token references resolved too), memoized per catalog.
+ * @position Sits beside docs.mjs (api/docs/). Hands topics to
+ *   foundation/doc-compiler (which loads their files) and memoizes the nodes
+ *   per catalog, so no leaf, doctor check or search loads, merges, or resolves
+ *   docs on its own. Discovery itself lives in
+ *   foundation/discovery/docs-discovery, which the catalog comes from.
  */
 
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
 import {Project} from '../../foundation/config/project.mjs';
+import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
 import {
-  DocsCatalog,
-  mergeTopic,
-} from '../../foundation/discovery/docs-discovery.mjs';
+  linkReferenceTopic,
+  lowerReferenceTopic,
+} from '../../foundation/doc-compiler/compile.mjs';
+import {
+  deepFreeze,
+  loadTopicInput,
+  OVERLAY_LANGUAGES,
+  overlayLanguages,
+} from '../../foundation/doc-compiler/read.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
+export {OVERLAY_LANGUAGES, overlayLanguages};
+
 /**
  * The project's topics: the built-in ones plus whatever the configured
  * integrations contribute.
@@ -50,92 +57,78 @@ export async function loadDocsCatalog(cwd = process.cwd()) {
 }
 
 /**
- * @param {string} docPath
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ * The overlay a read applies: none for the authored language.
+ * @param {string | null | undefined} lang
+ * @returns {string | null}
  */
-export async function loadReferenceDocs(docPath, {lang} = {}) {
-  const mod = await import(pathToFileURL(docPath).href);
-  const docs = mod.docs ?? mod.default;
-  if (!lang || lang === 'en') return docs;
-
-  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;
+function overlayLanguage(lang) {
+  return lang && lang !== 'en' ? lang : null;
+}
 
-  const translationMod = await import(pathToFileURL(translationPath).href);
-  const translation = translationMod.docsZh || translationMod.docsDense;
-  if (!translation) return docs;
+/** @type {WeakMap<DocsCatalog, Map<string, Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>>>} */
+const loweredByCatalog = new WeakMap();
 
-  // Overlays are keyed to a base section by title (`section`), not by array
-  // position. Position-keying silently grafted each overlay title onto whatever
-  // base section happened to share its index, so an overlay that omitted or
-  // reordered a section corrupted every section after it — `docs tokens --dense`
-  // printed the colour table under a "Spacing" heading (#2182). An overlay may
-  // now cover any subset of sections, in any order; sections it does not name
-  // keep their base content.
-  /** @type {Map<string, any>} */
-  const bySection = new Map();
-  for (const ts of translation.sections ?? []) {
-    if (ts?.section != null) bySection.set(ts.section, ts);
+/**
+ * One topic, lowered for `lang`: overlaid, extensions merged, keys stamped.
+ * Memoized per catalog, so a read that references a topic twice loads it once.
+ * Every read of the catalog shares the memoized node, so it is frozen; the
+ * lenses hand readers copies.
+ * @param {DocsCatalog} catalog
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
+ */
+export function lowerTopic(catalog, entry, lang = null) {
+  const overlay = overlayLanguage(lang);
+  let cache = loweredByCatalog.get(catalog);
+  if (!cache) {
+    cache = new Map();
+    loweredByCatalog.set(catalog, cache);
   }
+  const key = `${entry.name.toLowerCase()}\u0000${overlay ?? ''}`;
+  let lowered = cache.get(key);
+  if (!lowered) {
+    lowered = loadTopicInput(entry, overlay).then(input =>
+      deepFreeze(lowerReferenceTopic(input)),
+    );
+    cache.set(key, lowered);
+  }
+  return lowered;
+}
 
-  return {
-    ...docs,
-    description: translation.description || docs.description,
-    sections: docs.sections.map(
-      (/** @type {import('@astryxdesign/cli/authoring').ReferenceSection} */ section) => {
-        const ts = bySection.get(section.title);
-        if (!ts) return section;
-        return {
-          ...section,
-          title: ts.title || section.title,
-          content: section.content.map(
-            (
-              /** @type {import('@astryxdesign/cli/authoring').ReferenceContentBlock} */ block,
-              /** @type {number} */ bi,
-            ) => {
-              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};
-              return block;
-            },
-          ),
-        };
-      },
-    ),
+/**
+ * How a token reference finds its target: the topic it names in `catalog`,
+ * lowered for the same language.
+ * @param {DocsCatalog} catalog
+ * @param {string | null} lang
+ * @returns {(topic: string) => Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode | null>}
+ */
+export function referenceTargets(catalog, lang) {
+  return async topic => {
+    const target = catalog.resolve(topic);
+    return target ? lowerTopic(catalog, target, lang) : null;
   };
 }
 
 /**
- * Load one catalog entry: its own doc, plus any extension an integration
- * merged onto it, in configuration order.
- *
- * A localization overlay applies to each file before the extensions are
- * merged, so an extension written in the base language stays readable under
- * `--dense`/`--zh` (it replaces its own sections and leaves the rest
- * translated) rather than being dropped.
- *
+ * One topic, compiled for `lang`: lowered, then every token reference linked.
+ * @param {DocsCatalog} catalog
  * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
- * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('./docs.type.mjs').DocsDetailResponse['data']>}
+ * @param {string | null} [lang]
+ * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
  */
-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}));
-  }
-  return doc;
+export async function compileTopic(catalog, entry, lang = null) {
+  return linkReferenceTopic(
+    await lowerTopic(catalog, entry, lang),
+    referenceTargets(catalog, lang),
+  );
 }
 
 /**
  * Resolve `topic` against the project's catalog (throwing `ERR_UNKNOWN_TOPIC`
- * when unmatched), and load it with any --dense/--zh overlay and any
- * integration extension applied. Shared by the detail and section leaves so
- * topic normalization and unknown-topic handling live in exactly one place.
+ * when unmatched) and lower it with any --dense/--zh overlay and any
+ * integration extension applied. Shared by the leaves so topic normalization
+ * and unknown-topic handling live in exactly one place.
  *
  * @param {string} topic
  * @param {object} [options]
@@ -145,7 +138,8 @@ export async function loadTopicDoc(entry, {lang} = {}) {
  * @param {string} [options.cwd]
  * @returns {Promise<{
  *   catalog: DocsCatalog,
- *   docsData: import('./docs.type.mjs').DocsDetailResponse['data'],
+ *   node: import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode,
+ *   lang: string | null,
  * }>}
  */
 export async function resolveTopicDocs(topic, options = {}) {
@@ -165,6 +159,6 @@ export async function resolveTopicDocs(topic, options = {}) {
     );
   }
 
-  const docsData = await loadTopicDoc(entry, {lang: effectiveLang});
-  return {catalog, docsData};
+  const node = await lowerTopic(catalog, entry, effectiveLang);
+  return {catalog, node, lang: effectiveLang};
 }

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} from '../_adapter.mjs';
 
 /**
  * @param {string} topic
@@ -77,7 +25,10 @@ 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} = await resolveTopicDocs(topic, options);
+  const linked = await linkReferenceTopic(
+    node,
+    referenceTargets(catalog, lang),
+  );
+  return {type: 'docs.detail', data: detailView(linked)};
 }

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, 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.
+ * @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,30 @@ 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} = await resolveTopicDocs(topic, options);
+  const sections = readerSections(node);
+  const {section: match, candidates} = findDocSection(sections, sectionName);
   if (!match) {
+    const ambiguous = candidates.length > 1;
     throw new AstryxError(
-      `Section "${sectionName}" not found in "${topic}"`,
-      docsData.sections.map(s => ({name: s.title, reason: 'available section'})),
+      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,
+      })),
       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),
+  );
+  return {type: 'docs.detail.section', data: sectionView(node, linked)};
 }