@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/clients/cli/commands/docs.mjs

@@ -3,18 +3,26 @@
 /**
  * @file docs command — Print Astryx reference docs
  *
- * A topic prints its whole doc; `--index` lists its sections instead, so a
- * reader can open one section by its key.
+ * In text, every read is one level: a topic lists its sections, so a reader can
+ * open one section by its key, and `--full` prints the whole topic. `--json`
+ * keeps the docs() contract: a topic returns its whole doc, and `--index` its
+ * sections.
  * Supports --detail (full|compact|brief) and --lang (en|zh|dense).
  *
  * Usage:
  *   astryx docs                          List available topics
- *   astryx docs <topic>                  Print the whole topic
- *   astryx docs <topic> --index          List the topic's sections
+ *   astryx docs <topic>                  List the topic's sections (a topic
+ *                                        with one section prints whole)
  *   astryx docs <topic> <section>        Print one section
+ *   astryx docs <topic> --full           Print the whole topic
+ *   astryx docs <route>                  Open a node of the docs tree, such as
+ *                                        cli, cli/api, or cli/api/functions/search
  */
 
-import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {
+  formatCliCommand,
+  getCliInvocation,
+} from '../../../foundation/env/package-manager.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
 import {
   emit,
@@ -23,10 +31,9 @@ import {
   text,
   code,
   wrapText,
-  displayWidth,
-  WRAP_WIDTH,
 } from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {resultSet} from '../../../foundation/debug/index.mjs';
 import {docs as docsApi} from '../../../api/docs/docs.mjs';
@@ -52,28 +59,6 @@ function formatTable(headers, rows) {
   return `${head}\n${sep}\n${body}`;
 }
 
-/**
- * A table too wide for {@link WRAP_WIDTH}: one `header: cell` line per cell and
- * a blank line between rows, so nothing runs off the side of a terminal.
- * @param {string[]} headers
- * @param {string[][]} rows
- * @returns {string}
- */
-function formatTableVertical(headers, rows) {
-  const width = Math.max(...headers.map(h => h.length)) + 2;
-  return rows
-    .map(row =>
-      headers
-        .map((h, i) =>
-          wrapText(`${`${h}:`.padEnd(width)}${row[i] ?? ''}`, {
-            indent: ' '.repeat(width),
-          }),
-        )
-        .join('\n'),
-    )
-    .join('\n\n');
-}
-
 /**
  * @param {string[]} headers
  * @param {string[][]} rows
@@ -91,7 +76,7 @@ function formatTableCompact(headers, rows) {
 function formatBlock(block, detail) {
   switch (block.type) {
     case 'prose':
-      return wrapText(block.text);
+      return block.text;
 
     case 'heading':
       return `${'#'.repeat(block.level || 3)} ${block.text}`;
@@ -110,12 +95,7 @@ function formatBlock(block, detail) {
       if (detail === 'compact') {
         return formatTableCompact(block.headers, block.rows);
       }
-      {
-        const table = formatTable(block.headers, block.rows);
-        return table.split('\n').some(line => displayWidth(line) > WRAP_WIDTH)
-          ? formatTableVertical(block.headers, block.rows)
-          : table;
-      }
+      return formatTable(block.headers, block.rows);
 
     case 'list': {
       const prefix =
@@ -126,28 +106,16 @@ function formatBlock(block, detail) {
             : block.style === 'do'
               ? () => '+ '
               : () => '- ';
-      return block.items
-        .map((item, i) => {
-          const head = prefix(i);
-          return wrapText(`${head}${item}`, {indent: ' '.repeat(head.length)});
-        })
-        .join('\n');
+      return block.items.map((item, i) => `${prefix(i)}${item}`).join('\n');
     }
 
-    case 'workflow':
-    case 'collection':
-    case 'reference':
-      throw new Error(
-        `Documentation block "${block.type}" requires the compiled graph renderer.`,
-      );
-
     default:
       return null;
   }
 }
 
 /**
- * @param {import('@astryxdesign/cli/authoring').ReferenceSection} section
+ * @param {import('../../../api/docs/docs.type.mjs').DocsReadSection} section
  * @param {'full' | 'compact' | 'brief'} detail
  * @returns {string}
  */
@@ -167,27 +135,44 @@ function formatSection(section, detail) {
 }
 
 /**
- * @param {import('@astryxdesign/cli/authoring').ReferenceDoc} docs
+ * @param {import('../../../api/docs/docs.type.mjs').DocsReadDoc} docs
  * @param {'full' | 'compact' | 'brief'} detail
  * @returns {string}
  */
 function formatReferenceFull(docs, detail) {
   if (detail === 'brief') {
-    const header = wrapText(`${docs.title}: ${docs.description}`);
+    const header = `${docs.title}: ${docs.description}`;
     const sections = docs.sections.map(s => formatSection(s, detail));
     return `${header}\n${sections.join('\n')}`;
   }
 
-  const description = wrapText(docs.description);
   const header =
     detail === 'compact'
-      ? `# ${docs.title}\n${description}`
-      : `# ${docs.title}\n\n${description}`;
+      ? `# ${docs.title}\n${docs.description}`
+      : `# ${docs.title}\n\n${docs.description}`;
   const sections = docs.sections.map(s => formatSection(s, detail));
   const sep = detail === 'compact' ? '\n\n' : '\n\n';
   return `${header}\n\n${sections.join(sep)}`;
 }
 
+/**
+ * The moves a read offers (spec:AST-047), one runnable command per line: up to
+ * the level it sits in, the item before and after it, and the docs it names.
+ * @param {import('../../../api/docs/docs.type.mjs').DocsLinks | undefined} links
+ * @returns {string[]}
+ */
+function linkLines(links) {
+  if (!links) return [];
+  return [
+    `Up: ${formatCliCommand(links.up)}`,
+    ...(links.previous ? [`Previous: ${formatCliCommand(links.previous)}`] : []),
+    ...(links.next ? [`Next: ${formatCliCommand(links.next)}`] : []),
+    ...(links.related ?? []).map(
+      (command, i) => `${i === 0 ? 'Related: ' : '         '}${formatCliCommand(command)}`,
+    ),
+  ];
+}
+
 /**
  * A topic's section index: what the topic is, one line per section with the
  * key to read it by, and how to read further.
@@ -196,21 +181,84 @@ function formatReferenceFull(docs, detail) {
  */
 function emitIndex(index, run) {
   emit(
-    section(index.title, index.description ? wrapText(index.description) : undefined),
+    section(
+      index.title,
+      index.description ? wrapText(index.description) : undefined,
+    ),
+    // Summaries wrap rather than being cut: the summary is how a reader picks
+    // the one section to open.
     records(index.sections, {
       fields: ['id', 'title', 'summary'],
       layout: 'inline',
-      overflow: 'truncate',
     }),
     text(
       [
         `Read one section: ${run} docs ${index.name} <section>`,
-        `Read everything:  ${run} docs ${index.name}`,
+        `Read everything:  ${run} docs ${index.name} --full`,
+        ...linkLines(index.links),
       ].join('\n'),
     ),
   );
 }
 
+/**
+ * One child row of a namespace: its route name, then the doc's own title when
+ * it is not the route name (`assertResponse()`, `search()`), then its summary.
+ * @param {import('../../../api/docs/docs.type.mjs').DocsNodeChild} child
+ * @returns {{name: string, summary: string}}
+ */
+function childRow(child) {
+  return {
+    name: child.name,
+    summary:
+      child.title === child.name ? child.summary : `${child.title}: ${child.summary}`,
+  };
+}
+
+/**
+ * One node of the docs tree. A namespace lists each slot's children, one level
+ * down, with the command to open one; a typed doc prints its content. Both end
+ * with the way back up.
+ * @param {import('../../../api/docs/docs.type.mjs').DocsNode} node
+ * @param {'full' | 'compact' | 'brief'} detail
+ * @param {string} run
+ */
+function emitNode(node, detail, run) {
+  if (node.kind === 'namespace') {
+    emit(
+      section(node.title, wrapText(node.summary)),
+      ...node.slots.flatMap(slot => [
+        // A namespace with one slot titled like itself needs no second heading.
+        ...(node.slots.length === 1 && slot.title === node.title
+          ? []
+          : [section(slot.title)]),
+        records(slot.children.map(childRow), {
+          fields: ['name', 'summary'],
+          layout: 'inline',
+          overflow: 'truncate',
+        }),
+      ]),
+      text(
+        [
+          // A child's route is its parent's route and its name, except a flat
+          // topic in the Unorganized level, which keeps its own name.
+          node.slots.every(slot =>
+            slot.children.every(child => child.route.startsWith(`${node.route}/`)),
+          )
+            ? `Open one: ${run} docs ${node.route}/<name>`
+            : `Open one: ${run} docs <name>`,
+          ...linkLines(node.links),
+        ].join('\n'),
+      ),
+    );
+    return;
+  }
+  emit(
+    code(formatSection({title: node.title, content: node.content}, detail)),
+    text(linkLines(node.links).join('\n')),
+  );
+}
+
 /**
  * What the run answered with. A named topic (or one of its sections) resolves
  * or throws, so it is always a direct match of one doc; the bare form lists
@@ -219,7 +267,8 @@ function emitIndex(index, run) {
  * @param {import('../../../api/docs/docs.type.mjs').DocsListResponse
  *   | import('../../../api/docs/docs.type.mjs').DocsIndexResponse
  *   | import('../../../api/docs/docs.type.mjs').DocsDetailResponse
- *   | import('../../../api/docs/docs.type.mjs').DocsDetailSectionResponse} result
+ *   | import('../../../api/docs/docs.type.mjs').DocsDetailSectionResponse
+ *   | import('../../../api/docs/docs.type.mjs').DocsNodeResponse} result
  * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}
  */
 function summarize(result) {
@@ -239,7 +288,7 @@ export function registerDocs(program) {
     action: async (
       /** @type {string | undefined} */ topic,
       /** @type {string | undefined} */ sectionName,
-      /** @type {{index?: boolean}} */ options = {},
+      /** @type {{index?: boolean, full?: boolean}} */ options = {},
     ) => {
       const run = getCliInvocation();
       const lang = program.opts().lang || null;
@@ -248,14 +297,37 @@ export function registerDocs(program) {
       const detail = program.opts().detail || 'full';
       const json = program.opts().json || false;
 
+      if (options.index && options.full) {
+        return cliError(
+          'Ask for the section list or the whole topic, not both: --index and --full cannot both be set.',
+          {code: ERROR_CODES.ERR_INVALID_ARGUMENT},
+        );
+      }
+      // Text reads one level: a topic lists its sections (one with a single
+      // section prints whole). JSON keeps docs(): the whole topic unless
+      // --index. The dense variant is written to be read whole.
+      const listSections =
+        Boolean(options.index) ||
+        (!json &&
+          !options.full &&
+          !dense &&
+          lang !== 'dense' &&
+          sectionName == null);
       let result;
       try {
         result = await docsApi(topic, sectionName, {
           lang,
           zh,
           dense,
-          index: Boolean(options.index),
+          index: listSections,
         });
+        if (
+          !options.index &&
+          result.type === 'docs.index' &&
+          result.data.sections.length <= 1
+        ) {
+          result = await docsApi(topic, sectionName, {lang, zh, dense});
+        }
       } catch (e) {
         // docs API throws structured errors with {name, reason} suggestions —
         // pass them through untouched so the CLI envelope matches the API.
@@ -275,21 +347,50 @@ export function registerDocs(program) {
 
       switch (result.type) {
         case 'docs.list': {
-          // The text view mirrors the JSON list: one record per topic (topic +
-          // description), then the usage footer as plain prose.
+          // The text view mirrors the JSON list, with the docs tree's
+          // namespaces (`meta.namespaces`) first under their own heading: that
+          // is where the CLI's own docs start, and a namespace reads
+          // differently from a topic.
+          const namespaces = result.meta?.namespaces ?? [];
+          const topics = result.data;
           emit(
-            section('Available docs'),
-            records(result.data, {
-              fields: ['topic', 'description'],
+            ...(namespaces.length > 0
+              ? [
+                  section('Docs tree'),
+                  records(namespaces, {
+                    fields: ['topic', 'description', 'package'],
+                    layout: 'inline',
+                  }),
+                ]
+              : []),
+            section('Topics'),
+            records(topics, {
+              fields: ['topic', 'description', 'package'],
               layout: 'inline',
             }),
             text(
               [
-                `Usage: ${run} docs <topic>                  read the whole topic`,
-                `       ${run} docs <topic> --index          list its sections`,
+                `Usage: ${run} docs <topic>                  list a topic's sections`,
                 `       ${run} docs <topic> <section>        read one section`,
+                `       ${run} docs <topic> --full           read the whole topic`,
+                `       ${run} docs cli/api                  go down the docs tree one level at a time`,
+                `With --json, a topic returns its whole doc; add --index for its section list.`,
               ].join('\n'),
             ),
+            // A package whose doc files did not load has no topics here; say
+            // so, and where to look, instead of leaving them silently missing.
+            ...(result.meta?.notLoaded?.length
+              ? [
+                  section('Not loaded'),
+                  records(result.meta.notLoaded, {
+                    fields: ['package', 'message'],
+                    layout: 'inline',
+                  }),
+                  text(
+                    `Run \`${run} doctor integration docs\` in that package to see every problem.`,
+                  ),
+                ]
+              : []),
           );
           break;
         }
@@ -300,12 +401,25 @@ export function registerDocs(program) {
         }
 
         case 'docs.detail': {
-          emit(code(formatReferenceFull(result.data, detail)));
+          emit(
+            code(formatReferenceFull(result.data, detail)),
+            text(linkLines(result.data.links).join('\n')),
+          );
           break;
         }
 
         case 'docs.detail.section': {
-          emit(code(formatSection(result.data, detail)));
+          // One section ends with its moves: up to its topic's index, and to
+          // the sections before and after it.
+          emit(
+            code(formatSection(result.data, detail)),
+            text(linkLines(result.data.links).join('\n')),
+          );
+          break;
+        }
+
+        case 'docs.node': {
+          emitNode(result.data, detail, run);
           break;
         }
       }

package/clients/cli/commands/docs.test.mjs

@@ -75,7 +75,7 @@ describe('hyphenated doc filenames', () => {
 
   it('returns docs.detail via API for hyphenated topic', async () => {
     const {docs: docsApi} = await import('../../../api/docs/docs.mjs');
-    const result = await docsApi('getting-started');
+    const result = await docsApi('getting-started', undefined, {full: true});
     expect(result.type).toBe('docs.detail');
     expect(result.data).toBeDefined();
     expect(result.data.description).toBeDefined();
@@ -113,6 +113,7 @@ describe('progressive reads', () => {
     expect(status).toBe(0);
     expect(stdout).toMatch(/^principles +\S/m);
     expect(widest(stdout)).toBeLessThanOrEqual(120);
+    expect(stdout).toContain('Usage: pnpm exec astryx docs <topic>');
   }, SLOW);
 
   it("prints a topic's section index with the keys to read by", async () => {
@@ -120,7 +121,7 @@ describe('progressive reads', () => {
     expect(status).toBe(0);
     expect(stdout).toMatch(/^quick-start +Quick Start/m);
     expect(stdout).toContain('docs theme <section>');
-    expect(stdout).toMatch(/Read everything: +\S.* docs theme$/m);
+    expect(stdout).toMatch(/Read everything: +\S.* docs theme --full$/m);
     expect(widest(stdout)).toBeLessThanOrEqual(120);
   }, SLOW);
 
@@ -130,23 +131,23 @@ describe('progressive reads', () => {
     expect(stdout).toMatch(/^## Quick Start/m);
   }, SLOW);
 
-  it('prints the whole topic by default, as before', async () => {
+  it("lists a topic's sections by default; --full prints the whole topic", async () => {
     const index = await runCli(['docs', 'theme', '--index']);
-    const full = await runCli(['docs', 'theme']);
+    expect((await runCli(['docs', 'theme'])).stdout).toBe(index.stdout);
+    const full = await runCli(['docs', 'theme', '--full']);
     expect(full.status).toBe(0);
     expect(full.stdout).toMatch(/^## Quick Start/m);
     expect(full.stdout.length).toBeGreaterThan(index.stdout.length * 3);
-    expect((await runCli(['--detail', 'full', 'docs', 'theme'])).stdout).toBe(
+    expect((await runCli(['--detail', 'full', 'docs', 'theme', '--full'])).stdout).toBe(
       full.stdout,
     );
-    expect(widest(full.stdout.replace(/```[\s\S]*?```/g, ''))).toBeLessThanOrEqual(
-      120,
-    );
   }, SLOW);
 
   it('returns the matching envelopes as JSON', async () => {
     const envelope = async args => JSON.parse((await runCli([...args, '--json'])).stdout);
+    // JSON keeps docs(): a bare read is the whole topic.
     expect((await envelope(['docs', 'theme'])).type).toBe('docs.detail');
+    expect((await envelope(['docs', 'theme', '--full'])).type).toBe('docs.detail');
     expect((await envelope(['docs', 'theme', '--index'])).type).toBe(
       'docs.index',
     );
@@ -156,6 +157,109 @@ describe('progressive reads', () => {
   }, SLOW);
 });
 
+describe('the docs tree, one level at a time', () => {
+  const SLOW = 60_000;
+  /** @param {string} out */
+  const widest = out => Math.max(...out.split('\n').map(line => line.length));
+
+  it('lists the docs tree first, under its own heading, then the topics', async () => {
+    const {status, stdout} = await runCli(['docs']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^Docs tree$/m);
+    expect(stdout).toMatch(/^Topics$/m);
+    expect(stdout).toMatch(/^cli +Commands, programmatic APIs/m);
+    expect(stdout.indexOf('\ncli ')).toBeLessThan(stdout.indexOf('\nprinciples '));
+    expect(stdout).not.toMatch(/^cli-integrations /m);
+  }, SLOW);
+
+  it("shows a child's own name when its route name does not spell it", async () => {
+    const {status, stdout} = await runCli(['docs', 'cli/api/functions']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^assert-response +assertResponse\(\): \S/m);
+    expect(stdout).toMatch(/^search +search\(\): Unified ranked search/m);
+  }, SLOW);
+
+  it('prints a namespace: each slot, its children, and how to go down and up', async () => {
+    const {status, stdout} = await runCli(['docs', 'cli/api']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^API$/m);
+    expect(stdout).toMatch(/^Reference$/m);
+    expect(stdout).toMatch(/^functions +Functions: Every function/m);
+    expect(stdout).toMatch(/^schemas +/m);
+    expect(stdout).toMatch(/^enums +/m);
+    // One level only: no function is listed on the api page.
+    expect(stdout).not.toMatch(/^search +/m);
+    expect(stdout).toMatch(/Open one: .*docs cli\/api\/<name>$/m);
+    expect(stdout).toMatch(/Up: .*docs cli$/m);
+    expect(widest(stdout)).toBeLessThanOrEqual(120);
+  }, SLOW);
+
+  it('prints a typed doc and the way back up', async () => {
+    const {status, stdout} = await runCli(['docs', 'cli/api/functions/search']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^## search\(\)/m);
+    expect(stdout).toContain('Read it with `astryx docs cli/commands/search`.');
+    expect(stdout).toMatch(/Up: .*docs cli\/api\/functions$/m);
+  }, SLOW);
+
+  it('reads the dense variant whole, asked with --dense or with --lang dense', async () => {
+    for (const args of [['--dense', 'docs', 'theme'], ['--lang', 'dense', 'docs', 'theme']]) {
+      const {status, stdout} = await runCli(args);
+      expect(status).toBe(0);
+      expect(stdout).not.toContain('Read one section:');
+    }
+  }, SLOW);
+
+  it('refuses --index with --full', async () => {
+    const both = await runCli(['docs', 'theme', '--index', '--full', '--json']);
+    expect(both.status).toBe(1);
+    expect(JSON.parse(both.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+  }, SLOW);
+
+  it('reads the integration guide by its route, and not by its old name', async () => {
+    const guide = await runCli(['docs', 'cli/integrations', '--index']);
+    expect(guide.status).toBe(0);
+    expect(guide.stdout).toMatch(/Read one section: .*docs cli\/integrations <section>/);
+    // A bare read is one level too: the sections, and how to read it all.
+    const bare = await runCli(['docs', 'cli/integrations']);
+    expect(bare.status).toBe(0);
+    expect(bare.stdout).toBe(guide.stdout);
+    expect(bare.stdout).toMatch(/Read everything: +.*docs cli\/integrations --full$/m);
+    const one = await runCli(['docs', 'cli/integrations', 'codemods']);
+    expect(one.status).toBe(0);
+    expect(one.stdout).toMatch(/^## Codemods$/m);
+    expect(one.stdout).toMatch(/^Up: .*docs cli\/integrations --index$/m);
+    expect(one.stdout).toMatch(/^Previous: .*docs cli\/integrations agent-docs$/m);
+    expect(one.stdout).toMatch(/^Next: .*docs cli\/integrations recording-runs$/m);
+    const full = await runCli(['docs', 'cli/integrations', '--full']);
+    expect(full.status).toBe(0);
+    expect(full.stdout).toMatch(/^## Overview$/m);
+    expect(full.stdout.length).toBeGreaterThan(bare.stdout.length * 4);
+    const old = await runCli(['docs', 'cli-integrations']);
+    expect(old.status).toBe(1);
+    expect(old.stderr).toContain('Unknown topic "cli-integrations"');
+  }, SLOW);
+
+  it('returns docs.node as JSON, and fails a section of a namespace', async () => {
+    const node = JSON.parse((await runCli(['docs', 'cli', '--json'])).stdout);
+    expect(node).toMatchObject({
+      type: 'docs.node',
+      data: {route: 'cli', kind: 'namespace', breadcrumb: []},
+    });
+    expect(node.data.slots.map(slot => slot.name)).toEqual(['guides', 'reference']);
+    const section = await runCli(['docs', 'cli', 'commands', '--json']);
+    expect(section.status).toBe(1);
+    const error = JSON.parse(section.stdout);
+    expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});
+    expect(error.suggestions.map(s => s.name)).toEqual([
+      'cli/integrations',
+      'cli/writing-docs',
+      'cli/commands',
+      'cli/api',
+    ]);
+  }, SLOW);
+});
+
 describe('text width in every language', () => {
   const SLOW = 60_000;
   /** Widest line outside code blocks, in terminal columns. */
@@ -176,14 +280,14 @@ describe('text width in every language', () => {
     return max;
   };
 
-  it.each([
-    [['docs', 'theme', '--index', '--lang', 'zh']],
-    [['docs', 'theme', '--lang', 'zh']],
-    [['--detail', 'full', 'docs', 'theme', '--lang', 'zh']],
-    [['--detail', 'full', 'docs', 'internationalization']],
-    [['--detail', 'full', 'docs', 'styling']],
-  ])('%j fits in 120 columns', async args => {
-    const {status, stdout} = await runCli(args);
+  it('keeps the additive section index within 120 columns', async () => {
+    const {status, stdout} = await runCli([
+      'docs',
+      'theme',
+      '--index',
+      '--lang',
+      'zh',
+    ]);
     expect(status).toBe(0);
     expect(widest(stdout)).toBeLessThanOrEqual(120);
   }, SLOW);

package/clients/cli/commands/doctor-integration-components.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration components',
   displayName: 'astryx doctor integration components',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Warn when integration component names conflict with Core',
   description:
     'Compares one local or installed integration with Core component names. A ' +

package/clients/cli/commands/doctor-integration-docs.doc.mjs

@@ -7,8 +7,8 @@ export const doc = {
   type: 'command',
   name: 'doctor integration docs',
   displayName: 'astryx doctor integration docs',
-  namespace: 'cli',
-  summary: 'Classify integration doc overlaps with Core topics',
+  namespace: 'cli/commands',
+  summary: 'Check an integration\'s docs: the docs tree they add, every link, and overlaps with Core topics',
   description:
     'Reports intentional Core topic replacements and extensions as information. ' +
     'A same-name topic without `replaces` or `extends` is an accidental conflict ' +
@@ -32,7 +32,7 @@ export const doc = {
   ],
   exitCodes: [
     {code: 0, when: 'all Core overlaps are explicitly declared or no overlap exists'},
-    {code: 1, when: 'an overlap is accidental or the integration docs are invalid'},
+    {code: 1, when: 'an overlap is accidental, a doc is invalid, a namespace or placement fails, or a reference block cannot include what it names. A link that names no doc is a warning, and does not change the exit code'},
   ],
   related: ['doctor integration validate', 'docs'],
 };

package/clients/cli/commands/doctor-integration-templates.doc.mjs

@@ -9,13 +9,14 @@ export const doc = {
   type: 'command',
   name: 'doctor integration templates',
   displayName: 'astryx doctor integration templates',
-  namespace: 'cli',
-  summary: 'Warn when integration template ids conflict with Core',
+  namespace: 'cli/commands',
+  summary: 'Validate integration template replacements and Core id overlaps',
   description:
-    'Compares one local or installed integration with the built-in Core page and ' +
-    'block template ids. A conflict is allowed and exits successfully, but the ' +
-    'report recommends renaming and gives the exact --package command required ' +
-    'to select the integration template when the overlap is intentional.',
+    'Validates one local or installed integration against the built-in Core page ' +
+    'and block template ids. Intentional replacements are informational and name ' +
+    'the command for selecting the Core original. Missing targets, ambiguous ' +
+    'replacements, and invalid declarations are errors; undeclared same-id overlaps ' +
+    'remain warnings that require package selection.',
   fn: 'integrationTemplateConflicts',
   args: [
     {
@@ -37,8 +38,14 @@ export const doc = {
     },
   ],
   exitCodes: [
-    {code: 0, when: 'the check completed; template conflicts are warnings'},
-    {code: 1, when: 'the integration or one of its templates is invalid'},
+    {
+      code: 0,
+      when: 'replacement declarations are valid; undeclared id conflicts are warnings',
+    },
+    {
+      code: 1,
+      when: 'the integration, a template, or a replacement declaration is invalid',
+    },
   ],
   related: ['doctor integration validate', 'template'],
 };

package/clients/cli/commands/doctor-integration-validate.doc.mjs

@@ -9,7 +9,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration validate',
   displayName: 'astryx doctor integration validate',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Validate an integration manifest and its contributions',
   description:
     'Validates one integration at a time: the local package rooted at cwd, or an ' +