@astryxdesign/cli 0.6.3-canary.d774400 → 0.6.3-canary.d7eed85

package/api/docs/_adapter.d.mts

@@ -23,8 +23,9 @@ export function builtinCatalog(): DocsCatalog;
 /**
  * One topic, lowered for `lang` with every link between docs resolved
  * (spec:AST-047 FR9): an inline `{@link <target>}` reads as the command that
- * opens its doc, and a `reference` or `workflow` block carries the doc it
- * names. Memoized per catalog and frozen, like the lowered node.
+ * opens its doc, and a `reference` block carries the doc it names and the
+ * `content` it includes of it. Memoized per catalog and frozen, like the
+ * lowered node.
  * @param {DocsCatalog} catalog
  * @param {DocsTopicEntry} entry
  * @param {string | null} [lang]
@@ -51,9 +52,8 @@ export function projectTree(catalog: DocsCatalog, { fresh }?: {
     fresh?: boolean;
 }): Promise<DocsTree>;
 /**
- * How a doc's links find their targets (spec:AST-047 FR9): a doc in the
- * project's docs tree by its identity, or a flat topic by its provider and
- * name. A target that matches neither is a problem, never a guess.
+ * How a doc's links find their targets (spec:AST-047 FR9), as
+ * {@link docFinder} finds them: each resolves to the link a read shows.
  * @param {DocsCatalog} catalog
  * @param {string} fromProvider the provider id of the doc the links sit in
  * @returns {Promise<LinkResolver>}
@@ -64,11 +64,15 @@ export function linkResolver(catalog: DocsCatalog, fromProvider: string): Promis
  * guide the tree places, and each typed doc.
  * @param {DocsCatalog} catalog
  * @param {DocsTree} tree
- * @param {{owner?: string}} [options] `owner`: only the docs this package owns
+ * @param {{owner?: string, references?: boolean}} [options] `owner`: only the
+ *   docs this package owns. `references`: instead of the links, each reference
+ *   block that cannot include what it names; a reader loses that content,
+ *   where a link that names no doc still prints as written
  * @returns {Promise<string[]>}
  */
-export function docsLinkProblems(catalog: DocsCatalog, tree: DocsTree, { owner }?: {
+export function docsLinkProblems(catalog: DocsCatalog, tree: DocsTree, { owner, references }?: {
     owner?: string;
+    references?: boolean;
 }): Promise<string[]>;
 /**
  * What \`astryx doctor integration docs\` checks in one integration's docs: the
@@ -93,6 +97,22 @@ export function packageDocsProblems(integration: {
  * @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>;
+/**
+ * Each reference block in one integration's docs that cannot include what it
+ * names (spec:AST-047 FR9): a target that names no doc, a field its schema
+ * does not have, or a projection its doc cannot take. A reader would lose
+ * that content, so `astryx doctor integration docs` fails on each.
+ * @param {{name: string}} integration
+ * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]}} discovered
+ * @returns {Promise<string[]>}
+ */
+export function packageReferenceProblems(integration: {
+    name: string;
+}, discovered: {
+    records: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicRecord[];
+    namespaces: import("../../foundation/doc-compiler/tree.mjs").TreeNamespaceInput[];
+    guides: import("../../foundation/doc-compiler/tree.mjs").TreeDocInput[];
+}): Promise<string[]>;
 /**
  * One topic, compiled for `lang`: lowered, then every token reference linked.
  * @param {DocsCatalog} catalog
@@ -245,10 +265,32 @@ export function resolveTopicDocs(topic: unknown, options?: {
     lang: string | null;
     entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
 }>;
+/**
+ * A doc a link found: what a read shows of the link, and the typed doc behind
+ * it when a reference block can include it.
+ */
+export type FoundDoc = {
+    link: import("../../foundation/doc-compiler/links.mjs").DocLink;
+    /**
+     * the doc's kind
+     */
+    kind: string;
+    /**
+     * a
+     * schema, command, function, or enum doc: a leaf of the docs tree (`tree`),
+     * or a section of `astryx docs authoring`; null for any other kind
+     */
+    typed: {
+        doc: any;
+        providerId: string;
+        tree: boolean;
+    } | null;
+};
 export type DocsTree = import("../../foundation/doc-compiler/tree.mjs").DocsTree;
 export type TreeNode = import("../../foundation/doc-compiler/tree.mjs").TreeNode;
 export type LinkProblem = import("../../foundation/doc-compiler/links.mjs").LinkProblem;
 export type LinkResolver = import("../../foundation/doc-compiler/links.mjs").LinkResolver;
+export type DocIncluder = import("../../foundation/doc-compiler/links.mjs").DocIncluder;
 export type DocsTopicEntry = import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
 import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';
 import { AstryxError } from '../error.mjs';

package/api/docs/_adapter.mjs

@@ -47,6 +47,12 @@ import {
   cliDocIndex,
   cliDocSection,
 } from '../../foundation/discovery/cli-self-docs.mjs';
+import {
+  loadAuthoringSelfDocs,
+  schemaFieldTable,
+  selfDocSection,
+} from '../../foundation/discovery/authoring-self-docs.mjs';
+import {CLI_PROVIDER_ID} from '../../foundation/identity/providers.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
@@ -119,6 +125,7 @@ function lowerRawTopic(catalog, entry, lang = null) {
  * @typedef {import('../../foundation/doc-compiler/tree.mjs').TreeNode} TreeNode
  * @typedef {import('../../foundation/doc-compiler/links.mjs').LinkProblem} LinkProblem
  * @typedef {import('../../foundation/doc-compiler/links.mjs').LinkResolver} LinkResolver
+ * @typedef {import('../../foundation/doc-compiler/links.mjs').DocIncluder} DocIncluder
  * @typedef {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} DocsTopicEntry
  */
 
@@ -146,8 +153,9 @@ function providerOf(entry) {
 /**
  * One topic, lowered for `lang` with every link between docs resolved
  * (spec:AST-047 FR9): an inline `{@link <target>}` reads as the command that
- * opens its doc, and a `reference` or `workflow` block carries the doc it
- * names. Memoized per catalog and frozen, like the lowered node.
+ * opens its doc, and a `reference` block carries the doc it names and the
+ * `content` it includes of it. Memoized per catalog and frozen, like the
+ * lowered node.
  * @param {DocsCatalog} catalog
  * @param {DocsTopicEntry} entry
  * @param {string | null} [lang]
@@ -183,16 +191,19 @@ function linkTopic(catalog, entry, lang) {
   if (!linked) {
     linked = (async () => {
       const raw = await lowerRawTopic(catalog, entry, lang);
-      /** @type {Map<string, LinkResolver>} */
-      const resolvers = new Map();
+      /** @type {Map<string, {resolve: LinkResolver, include: DocIncluder}>} */
+      const linkers = new Map();
       /** @param {string} provider */
-      const resolverFor = async provider => {
-        let resolve = resolvers.get(provider);
-        if (!resolve) {
-          resolve = await linkResolver(catalog, provider);
-          resolvers.set(provider, resolve);
+      const linkerFor = async provider => {
+        let linker = linkers.get(provider);
+        if (!linker) {
+          linker = {
+            resolve: await linkResolver(catalog, provider),
+            include: await docIncluder(catalog, provider),
+          };
+          linkers.set(provider, linker);
         }
-        return resolve;
+        return linker;
       };
       /** @type {LinkProblem[]} */
       const problems = [];
@@ -202,12 +213,14 @@ function linkTopic(catalog, entry, lang) {
       // base topic's.
       for (const section of raw.doc.sections) {
         const provider = raw.sectionProviders?.[section.id];
+        const {resolve, include} = await linkerFor(
+          provider == null ? providerOf(entry) : normalizeProviderId(provider),
+        );
         const linked = await linkBlocks(
           section.content,
-          await resolverFor(
-            provider == null ? providerOf(entry) : normalizeProviderId(provider),
-          ),
+          resolve,
           {section: section.id ?? section.title},
+          include,
         );
         problems.push(...linked.problems);
         sections.push({...section, content: linked.content});
@@ -332,15 +345,52 @@ function identitiesOf(tree) {
   return index;
 }
 
+/**
+ * The CLI's authoring docs, by kind and name. `astryx docs authoring` reads
+ * each as one section keyed by its name, so a link to one opens that section.
+ * Loaded once per process, like the CLI's tree files.
+ * @type {Promise<Map<string, any>> | undefined}
+ */
+let authoringDocs;
+
+/**
+ * The CLI authoring doc a link names, while `astryx docs authoring` is the
+ * CLI's own topic.
+ * @param {DocsCatalog} catalog
+ * @param {string} kind
+ * @param {string} name
+ * @returns {Promise<any | null>}
+ */
+async function authoringDoc(catalog, kind, name) {
+  if (catalog.resolve('authoring')?.package !== CLI_PROVIDER_ID) return null;
+  authoringDocs ??= loadAuthoringSelfDocs().then(
+    ({loaded}) =>
+      new Map(loaded.map(({doc}) => [`${doc.type}\u0000${doc.name}`, doc])),
+  );
+  return (await authoringDocs).get(`${kind}\u0000${name}`) ?? null;
+}
+
+/**
+ * A doc a link found: what a read shows of the link, and the typed doc behind
+ * it when a reference block can include it.
+ * @typedef {object} FoundDoc
+ * @property {import('../../foundation/doc-compiler/links.mjs').DocLink} link
+ * @property {string} kind the doc's kind
+ * @property {{doc: any, providerId: string, tree: boolean} | null} typed a
+ *   schema, command, function, or enum doc: a leaf of the docs tree (`tree`),
+ *   or a section of `astryx docs authoring`; null for any other kind
+ */
+
 /**
  * How a doc's links find their targets (spec:AST-047 FR9): a doc in the
- * project's docs tree by its identity, or a flat topic by its provider and
- * name. A target that matches neither is a problem, never a guess.
+ * project's docs tree by its identity, a CLI authoring doc (a section of
+ * `astryx docs authoring`), or a flat topic by its provider and name. A
+ * target that matches none is a problem, never a guess.
  * @param {DocsCatalog} catalog
  * @param {string} fromProvider the provider id of the doc the links sit in
- * @returns {Promise<LinkResolver>}
+ * @returns {Promise<(target: string) => Promise<FoundDoc | {problem: string}>>}
  */
-export async function linkResolver(catalog, fromProvider) {
+async function docFinder(catalog, fromProvider) {
   const identities = identitiesOf(await projectTree(catalog));
   return async target => {
     const parsed = parseLinkTarget(target);
@@ -356,12 +406,36 @@ export async function linkResolver(catalog, fromProvider) {
     const node = identities.get(identityKey(provider, parsed.kind, parsed.name));
     if (node) {
       return {
-        target,
-        id: /** @type {string} */ (node.id),
-        route: node.route,
-        title: node.title,
-        summary: node.summary,
-        command: `astryx docs ${node.route}`,
+        link: {
+          target,
+          id: /** @type {string} */ (node.id),
+          route: node.route,
+          title: node.title,
+          summary: node.summary,
+          command: `astryx docs ${node.route}`,
+        },
+        kind: node.kind,
+        typed: node.ref?.selfDoc
+          ? {doc: node.ref.selfDoc, providerId: node.providerId, tree: true}
+          : null,
+      };
+    }
+    const authored =
+      provider === CLI_PROVIDER_ID
+        ? await authoringDoc(catalog, parsed.kind, parsed.name)
+        : null;
+    if (authored) {
+      return {
+        link: {
+          target,
+          id: createDocId(provider, authored.type, authored.name),
+          route: 'authoring',
+          title: authored.displayName ?? authored.name,
+          summary: authored.description ?? '',
+          command: `astryx docs authoring ${authored.name}`,
+        },
+        kind: parsed.kind,
+        typed: {doc: authored, providerId: CLI_PROVIDER_ID, tree: false},
       };
     }
     if (parsed.kind === 'generic') {
@@ -383,12 +457,16 @@ export async function linkResolver(catalog, fromProvider) {
           // link still opens it.
         }
         return {
-          target,
-          id: createDocId(provider, 'generic', parsed.name),
-          route: entry.name,
-          title,
-          summary,
-          command: `astryx docs ${entry.name}`,
+          link: {
+            target,
+            id: createDocId(provider, 'generic', parsed.name),
+            route: entry.name,
+            title,
+            summary,
+            command: `astryx docs ${entry.name}`,
+          },
+          kind: 'generic',
+          typed: null,
         };
       }
     }
@@ -398,20 +476,158 @@ export async function linkResolver(catalog, fromProvider) {
   };
 }
 
+/**
+ * How a doc's links find their targets (spec:AST-047 FR9), as
+ * {@link docFinder} finds them: each resolves to the link a read shows.
+ * @param {DocsCatalog} catalog
+ * @param {string} fromProvider the provider id of the doc the links sit in
+ * @returns {Promise<LinkResolver>}
+ */
+export async function linkResolver(catalog, fromProvider) {
+  const find = await docFinder(catalog, fromProvider);
+  return async target => {
+    const found = await find(target);
+    return 'problem' in found ? found : found.link;
+  };
+}
+
+/** How a problem names a doc kind that a reference block cannot include. */
+const KIND_NAMES = /** @type {Record<string, string>} */ ({
+  generic: 'topic',
+  namespace: 'namespace',
+});
+
+/**
+ * How a topic's reference blocks include the docs they name (spec:AST-047
+ * FR9): a schema, command, function, or enum doc as `astryx docs` prints
+ * it, narrowed by the block's projection and presentation, with the included
+ * doc's own links resolved against its own provider. Any other doc shows its
+ * title and summary. Each part a block names that it cannot include is a
+ * problem, and a read marks where it is missing; a target that names no doc
+ * is the resolver's problem.
+ * @param {DocsCatalog} catalog
+ * @param {string} fromProvider the provider id of the doc the blocks sit in
+ * @returns {Promise<DocIncluder>}
+ */
+async function docIncluder(catalog, fromProvider) {
+  const find = await docFinder(catalog, fromProvider);
+  const tree = await projectTree(catalog);
+  return async block => {
+    const found = await find(block.target);
+    if ('problem' in found) return {content: [], problems: []};
+    return includedContent(catalog, tree, block, found);
+  };
+}
+
+/**
+ * What one reference block includes of the doc it found.
+ * @param {DocsCatalog} catalog
+ * @param {DocsTree} tree
+ * @param {any} block
+ * @param {FoundDoc} found
+ * @returns {Promise<{content: any[], problems: string[]}>}
+ */
+async function includedContent(catalog, tree, block, found) {
+  /** @type {string[]} */
+  const problems = [];
+  const {fields, sections} = block.projection ?? {};
+  const presentation = block.presentation ?? 'full';
+  if (sections != null) {
+    problems.push(
+      'projection.sections: a reference block does not include topic sections; reference a schema, command, function, or enum doc, and name the fields of a schema with projection.fields',
+    );
+  }
+  const typed = found.typed;
+  if (typed == null) {
+    // A reference shows any other doc only by its title and summary.
+    if (fields != null || (block.presentation ?? 'summary') !== 'summary') {
+      problems.push(
+        `"${block.target}" is a ${KIND_NAMES[found.kind] ?? `${found.kind} doc`}, which a reference block shows only by its title and summary; remove the projection and the presentation, or reference a schema, command, function, or enum doc`,
+      );
+    }
+    return {content: [], problems};
+  }
+  if (presentation === 'summary') {
+    if (fields != null) {
+      problems.push(
+        "projection.fields: a summary includes no fields; remove projection.fields or presentation: 'summary'",
+      );
+    }
+    return {content: [], problems};
+  }
+  /** @type {any[]} */
+  let content;
+  if (fields != null && typed.doc.type === 'schema') {
+    /** @type {Map<string, any>} */
+    const byName = new Map(
+      (typed.doc.fields ?? []).map((/** @type {any} */ field) => [
+        field.name,
+        field,
+      ]),
+    );
+    const selected = [];
+    /** @type {any[]} */
+    const missing = [];
+    for (const name of fields) {
+      const field = byName.get(name);
+      if (field) {
+        selected.push(field);
+        continue;
+      }
+      problems.push(
+        `projection.fields: "${name}" is not a field of ${found.link.title} (${block.target}). Its fields: ${[...byName.keys()].join(', ')}`,
+      );
+      missing.push({
+        type: 'prose',
+        text: `[reference: field "${name}" not found in "${block.target}"]`,
+      });
+    }
+    const table = schemaFieldTable(selected);
+    content = [...(table ? [table] : []), ...missing];
+  } else {
+    if (fields != null) {
+      problems.push(
+        `projection.fields: names the fields of a schema doc, and "${block.target}" is a ${typed.doc.type} doc; remove it to include the whole doc`,
+      );
+    }
+    content = typed.tree
+      ? cliDocSection(typed.doc, typedDocIndex(tree)).content
+      : selfDocSection(typed.doc).content;
+  }
+  if (presentation === 'compact') {
+    content = content.filter(each => each?.type !== 'code');
+  }
+  // The included doc's own links resolve against its own provider. A link in
+  // it that names no doc is that doc's problem, reported where it is written.
+  const linked = await linkBlocks(
+    content,
+    await linkResolver(catalog, typed.providerId),
+  );
+  return {content: linked.content, problems};
+}
+
 /**
  * Every link in the project's docs that names no doc: in each topic, each
  * guide the tree places, and each typed doc.
  * @param {DocsCatalog} catalog
  * @param {DocsTree} tree
- * @param {{owner?: string}} [options] `owner`: only the docs this package owns
+ * @param {{owner?: string, references?: boolean}} [options] `owner`: only the
+ *   docs this package owns. `references`: instead of the links, each reference
+ *   block that cannot include what it names; a reader loses that content,
+ *   where a link that names no doc still prints as written
  * @returns {Promise<string[]>}
  */
-export async function docsLinkProblems(catalog, tree, {owner} = {}) {
+export async function docsLinkProblems(
+  catalog,
+  tree,
+  {owner, references = false} = {},
+) {
   /** @type {string[]} */
   const problems = [];
   /** @param {string} where @param {LinkProblem[]} found */
   const note = (where, found) => {
     for (const problem of found) {
+      if ((problem.include === true) !== references) continue;
       problems.push(
         `${where}${problem.section ? ` \u00a7 ${problem.section}` : ''}: ${problem.message}`,
       );
@@ -487,6 +703,28 @@ export function referenceTargets(catalog, lang) {
   };
 }
 
+/**
+ * Each reference block in one integration's docs that cannot include what it
+ * names (spec:AST-047 FR9): a target that names no doc, a field its schema
+ * does not have, or a projection its doc cannot take. A reader would lose
+ * that content, so `astryx doctor integration docs` fails on each.
+ * @param {{name: string}} integration
+ * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]}} discovered
+ * @returns {Promise<string[]>}
+ */
+export async function packageReferenceProblems(integration, discovered) {
+  const catalog = DocsCatalog.fromBuiltins();
+  for (const record of discovered.records) catalog.add(record);
+  catalog.addTreeInputs({
+    namespaces: discovered.namespaces.map(input => ({...input, rank: 1})),
+    guides: discovered.guides.map(input => ({...input, rank: 1})),
+  });
+  return docsLinkProblems(catalog, await projectTree(catalog), {
+    owner: integration.name,
+    references: true,
+  });
+}
+
 /**
  * One topic, compiled for `lang`: lowered, then every token reference linked.
  * @param {DocsCatalog} catalog
@@ -535,6 +773,20 @@ const typedDocIndexes = new WeakMap();
  */
 export async function nodeContent(catalog, tree, node) {
   if (!node.ref?.selfDoc) return {content: [], problems: []};
+  const resolve = await linkResolver(catalog, node.providerId);
+  return linkBlocks(
+    cliDocSection(node.ref.selfDoc, typedDocIndex(tree)).content,
+    resolve,
+  );
+}
+
+/**
+ * The index a typed doc's content reads its cross-links from: every typed doc
+ * in the tree. Built once per tree.
+ * @param {DocsTree} tree
+ * @returns {ReturnType<typeof cliDocIndex>}
+ */
+function typedDocIndex(tree) {
   let index = typedDocIndexes.get(tree);
   if (!index) {
     index = cliDocIndex(
@@ -544,8 +796,7 @@ export async function nodeContent(catalog, tree, node) {
     );
     typedDocIndexes.set(tree, index);
   }
-  const resolve = await linkResolver(catalog, node.providerId);
-  return linkBlocks(cliDocSection(node.ref.selfDoc, index).content, resolve);
+  return index;
 }
 
 /**

package/api/docs/docs.doc.mjs

@@ -20,7 +20,8 @@ export const doc = {
     '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. The topic set is the CLI\'s own docs plus the ' +
+    '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 ' +
@@ -97,7 +98,7 @@ export const doc = {
     {
       type: 'docs.detail',
       description:
-        "One topic's full ReferenceDoc, with token-ref blocks inlined, plus links.",
+        "One topic's full ReferenceDoc, with token-ref and reference blocks inlined, plus links.",
     },
     {
       type: 'docs.index',
@@ -107,7 +108,7 @@ export const doc = {
     {
       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',

package/api/docs/docs.type.d.mts

@@ -67,15 +67,31 @@ export type DocsDetailResponse = {
     /**
      *   the whole doc, and the moves from it
      */
-    data: import("@astryxdesign/cli/authoring").ReferenceDoc & {
+    data: DocsReadDoc & {
         links: DocsLinks;
     };
 };
+/**
+ * A topic section as a read returns it. A read inlines each token reference
+ * and each `reference` block the author wrote, so its content holds only the
+ * stable ReferenceContentBlock kinds.
+ */
+export type DocsReadSection = Omit<import("@astryxdesign/cli/authoring").ReferenceSection, "content"> & {
+    content: import("@astryxdesign/cli/authoring").ReferenceContentBlock[];
+};
+/**
+ * A topic as a read returns it: every section a {@link DocsReadSection}.
+ */
+export type DocsReadDoc = Omit<import("@astryxdesign/cli/authoring").ReferenceDoc, "sections"> & {
+    sections: DocsReadSection[];
+};
 /**
  * The doc a link opens (spec:AST-047 FR9). A docs read resolves every link:
- * an inline `{@link  <target>}` reads as `link.command`, a `reference` block
- * carries `link` (null when the target names no doc), and each `workflow` step
- * carries `links`, one per reference.
+ * an inline `{@link  <target>}` reads as `link.command`, a `reference` block in
+ * a namespace doc carries `link` (null when the target names no doc), and each
+ * `workflow` step carries `links`, one per reference. A topic read inlines a
+ * section's `reference` block as the doc it includes, then a line naming where
+ * that comes from and the command that opens it.
  */
 export type DocLink = import("../../foundation/doc-compiler/links.mjs").DocLink;
 /**
@@ -146,7 +162,7 @@ export type DocsDetailSectionResponse = {
      *   the section, and the moves from it: up to its topic's index, and across to
      *   the sections before and after it
      */
-    data: import("@astryxdesign/cli/authoring").ReferenceSection & {
+    data: DocsReadSection & {
         links: DocsLinks;
     };
 };

package/api/docs/docs.type.mjs

@@ -56,15 +56,31 @@
  * astryx --json docs <topic>
  * @typedef {object} DocsDetailResponse
  * @property {'docs.detail'} type
- * @property {import('@astryxdesign/cli/authoring').ReferenceDoc & {links: DocsLinks}} data
+ * @property {DocsReadDoc & {links: DocsLinks}} data
  *   the whole doc, and the moves from it
  */
 
+/**
+ * A topic section as a read returns it. A read inlines each token reference
+ * and each `reference` block the author wrote, so its content holds only the
+ * stable ReferenceContentBlock kinds.
+ * @typedef {Omit<import('@astryxdesign/cli/authoring').ReferenceSection, 'content'>
+ *   & {content: import('@astryxdesign/cli/authoring').ReferenceContentBlock[]}} DocsReadSection
+ */
+
+/**
+ * A topic as a read returns it: every section a {@link DocsReadSection}.
+ * @typedef {Omit<import('@astryxdesign/cli/authoring').ReferenceDoc, 'sections'>
+ *   & {sections: DocsReadSection[]}} DocsReadDoc
+ */
+
 /**
  * The doc a link opens (spec:AST-047 FR9). A docs read resolves every link:
- * an inline `{@link <target>}` reads as `link.command`, a `reference` block
- * carries `link` (null when the target names no doc), and each `workflow` step
- * carries `links`, one per reference.
+ * an inline `{@link <target>}` reads as `link.command`, a `reference` block in
+ * a namespace doc carries `link` (null when the target names no doc), and each
+ * `workflow` step carries `links`, one per reference. A topic read inlines a
+ * section's `reference` block as the doc it includes, then a line naming where
+ * that comes from and the command that opens it.
  * @typedef {import('../../foundation/doc-compiler/links.mjs').DocLink} DocLink
  */
 
@@ -110,7 +126,7 @@
  * astryx --json docs <topic> <section>
  * @typedef {object} DocsDetailSectionResponse
  * @property {'docs.detail.section'} type
- * @property {import('@astryxdesign/cli/authoring').ReferenceSection & {links: DocsLinks}} data
+ * @property {DocsReadSection & {links: DocsLinks}} data
  *   the section, and the moves from it: up to its topic's index, and across to
  *   the sections before and after it
  */

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

@@ -151,7 +151,15 @@ describe('integration docs in the docs tree', () => {
         title: 'Broken',
         description: 'A topic whose block no topic may hold.',
         sections: [
-          {title: 'Only', content: [{type: 'reference', target: 'generic:setup'}]},
+          {
+            title: 'Only',
+            content: [
+              {
+                type: 'workflow',
+                steps: [{title: 'Set up', references: ['generic:setup']}],
+              },
+            ],
+          },
         ],
       },
     });