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

package/foundation/response/error-codes.d.mts

@@ -75,6 +75,8 @@ export function allErrorCodes(): string[];
  *   | 'ERR_UNKNOWN_FEATURE'
  *   | 'ERR_UNKNOWN_CODEMOD'
  *   | 'ERR_CODEMOD_FAILED'
+ *   | 'ERR_CODEMOD_PROTECTED'
+ *   | 'ERR_CODEMOD_PROTECTION_SOURCE'
  *   | 'ERR_NOT_FOUND'
  *   | 'ERR_NO_DOC'
  *   | 'ERR_NO_SHOWCASE'
@@ -107,4 +109,4 @@ export const ERROR_CODES: Readonly<Record<ErrorCode, ErrorCode>>;
 /**
  * Stable error-code string union. Append-only.
  */
-export type ErrorCode = ("ERR_UNKNOWN" | "ERR_UNKNOWN_COMMAND" | "ERR_UNKNOWN_SUBCOMMAND" | "ERR_INVALID_OPTION" | "ERR_INVALID_ARGUMENT" | "ERR_MISSING_ARGUMENT" | "ERR_INVALID_LANG" | "ERR_INVALID_DETAIL" | "ERR_NODE_VERSION" | "ERR_CORE_NOT_FOUND" | "ERR_CORE_INCOMPATIBLE" | "ERR_UNKNOWN_COMPONENT" | "ERR_UNKNOWN_HOOK" | "ERR_UNKNOWN_TOPIC" | "ERR_UNKNOWN_SECTION" | "ERR_UNKNOWN_CATEGORY" | "ERR_UNKNOWN_TEMPLATE" | "ERR_AMBIGUOUS_TEMPLATE" | "ERR_AMBIGUOUS_COMPONENT" | "ERR_AMBIGUOUS_THEME" | "ERR_UNKNOWN_THEME" | "ERR_INTEGRATION_ROOT_CONFLICT" | "ERR_INTEGRATION_EXPORT_CONFLICT" | "ERR_UNKNOWN_PACKAGE" | "ERR_UNKNOWN_AGENT" | "ERR_UNKNOWN_FEATURE" | "ERR_UNKNOWN_CODEMOD" | "ERR_CODEMOD_FAILED" | "ERR_NOT_FOUND" | "ERR_NO_DOC" | "ERR_NO_SHOWCASE" | "ERR_NO_SOURCE" | "ERR_INVALID_DOC" | "ERR_FILE_NOT_FOUND" | "ERR_FILE_EXISTS" | "ERR_PATH_TRAVERSAL" | "ERR_WRITE_FAILED" | "ERR_THEME_INVALID" | "ERR_THEME_LOAD" | "ERR_PALETTE_GENERATION" | "ERR_VERSION_DETECT" | "ERR_INVALID_VERSION" | "ERR_DEP_MISSING" | "ERR_GH_CLI" | "ERR_UNKNOWN_POST" | "ERR_FETCH_FAILED" | "ERR_LAYOUT_PARSE" | "ERR_LAYOUT_INVALID" | "ERR_UNCLASSIFIED_EXIT" | "ERR_SIGNAL_TERMINATED");
+export type ErrorCode = ("ERR_UNKNOWN" | "ERR_UNKNOWN_COMMAND" | "ERR_UNKNOWN_SUBCOMMAND" | "ERR_INVALID_OPTION" | "ERR_INVALID_ARGUMENT" | "ERR_MISSING_ARGUMENT" | "ERR_INVALID_LANG" | "ERR_INVALID_DETAIL" | "ERR_NODE_VERSION" | "ERR_CORE_NOT_FOUND" | "ERR_CORE_INCOMPATIBLE" | "ERR_UNKNOWN_COMPONENT" | "ERR_UNKNOWN_HOOK" | "ERR_UNKNOWN_TOPIC" | "ERR_UNKNOWN_SECTION" | "ERR_UNKNOWN_CATEGORY" | "ERR_UNKNOWN_TEMPLATE" | "ERR_AMBIGUOUS_TEMPLATE" | "ERR_AMBIGUOUS_COMPONENT" | "ERR_AMBIGUOUS_THEME" | "ERR_UNKNOWN_THEME" | "ERR_INTEGRATION_ROOT_CONFLICT" | "ERR_INTEGRATION_EXPORT_CONFLICT" | "ERR_UNKNOWN_PACKAGE" | "ERR_UNKNOWN_AGENT" | "ERR_UNKNOWN_FEATURE" | "ERR_UNKNOWN_CODEMOD" | "ERR_CODEMOD_FAILED" | "ERR_CODEMOD_PROTECTED" | "ERR_CODEMOD_PROTECTION_SOURCE" | "ERR_NOT_FOUND" | "ERR_NO_DOC" | "ERR_NO_SHOWCASE" | "ERR_NO_SOURCE" | "ERR_INVALID_DOC" | "ERR_FILE_NOT_FOUND" | "ERR_FILE_EXISTS" | "ERR_PATH_TRAVERSAL" | "ERR_WRITE_FAILED" | "ERR_THEME_INVALID" | "ERR_THEME_LOAD" | "ERR_PALETTE_GENERATION" | "ERR_VERSION_DETECT" | "ERR_INVALID_VERSION" | "ERR_DEP_MISSING" | "ERR_GH_CLI" | "ERR_UNKNOWN_POST" | "ERR_FETCH_FAILED" | "ERR_LAYOUT_PARSE" | "ERR_LAYOUT_INVALID" | "ERR_UNCLASSIFIED_EXIT" | "ERR_SIGNAL_TERMINATED");

package/foundation/response/error-codes.d.ts

@@ -34,6 +34,8 @@ export type ErrorCode =
   | 'ERR_UNKNOWN_FEATURE'
   | 'ERR_UNKNOWN_CODEMOD'
   | 'ERR_CODEMOD_FAILED'
+  | 'ERR_CODEMOD_PROTECTED'
+  | 'ERR_CODEMOD_PROTECTION_SOURCE'
   | 'ERR_NOT_FOUND'
   | 'ERR_NO_DOC'
   | 'ERR_NO_SHOWCASE'

package/foundation/response/error-codes.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'enum',
   name: 'error-codes',
   displayName: 'Error Codes',
-  namespace: 'cli',
+  namespace: 'cli/api',
   description:
     'Stable, append-only machine-readable error codes on the --json error envelope (envelope.code). Codes never change or get removed; branch on these, not on prose.',
   members: [
@@ -154,6 +154,16 @@ export const doc = {
       value: 'ERR_CODEMOD_FAILED',
       description: 'One or more codemods failed during an upgrade run.',
     },
+    {
+      value: 'ERR_CODEMOD_PROTECTED',
+      description:
+        'A required codemod change remains blocked by a protected consumer file.',
+    },
+    {
+      value: 'ERR_CODEMOD_PROTECTION_SOURCE',
+      description:
+        'A working-tree protection declaration could not be read or parsed.',
+    },
     {
       value: 'ERR_NOT_FOUND',
       description:
@@ -187,8 +197,7 @@ export const doc = {
     },
     {
       value: 'ERR_FILE_EXISTS',
-      description:
-        'Refused to overwrite an existing file in non-interactive mode.',
+      description: 'Refused to overwrite an existing file.',
     },
     {
       value: 'ERR_PATH_TRAVERSAL',
@@ -204,7 +213,7 @@ export const doc = {
     {
       value: 'ERR_THEME_INVALID',
       description:
-        'A theme definition or contributed theme catalog is invalid.',
+        'A theme definition or contributed theme descriptor is invalid.',
     },
     {
       value: 'ERR_THEME_LOAD',

package/foundation/response/error-codes.mjs

@@ -64,6 +64,8 @@
  *   | 'ERR_UNKNOWN_FEATURE'
  *   | 'ERR_UNKNOWN_CODEMOD'
  *   | 'ERR_CODEMOD_FAILED'
+ *   | 'ERR_CODEMOD_PROTECTED'
+ *   | 'ERR_CODEMOD_PROTECTION_SOURCE'
  *   | 'ERR_NOT_FOUND'
  *   | 'ERR_NO_DOC'
  *   | 'ERR_NO_SHOWCASE'
@@ -161,6 +163,10 @@ export const ERROR_CODES = Object.freeze({
   ERR_UNKNOWN_CODEMOD: 'ERR_UNKNOWN_CODEMOD',
   /** One or more codemods failed during an upgrade run. */
   ERR_CODEMOD_FAILED: 'ERR_CODEMOD_FAILED',
+  /** A required codemod change remains blocked by a protected consumer file. */
+  ERR_CODEMOD_PROTECTED: 'ERR_CODEMOD_PROTECTED',
+  /** A working-tree protection declaration could not be read or parsed. */
+  ERR_CODEMOD_PROTECTION_SOURCE: 'ERR_CODEMOD_PROTECTION_SOURCE',
   /** A generic discover/lookup query matched nothing in any package. */
   ERR_NOT_FOUND: 'ERR_NOT_FOUND',
 
@@ -177,7 +183,7 @@ export const ERROR_CODES = Object.freeze({
   // ── Filesystem ───────────────────────────────────────────────────
   /** A required input file did not exist. */
   ERR_FILE_NOT_FOUND: 'ERR_FILE_NOT_FOUND',
-  /** Refused to overwrite an existing file in non-interactive mode. */
+  /** Refused to overwrite an existing file. */
   ERR_FILE_EXISTS: 'ERR_FILE_EXISTS',
   /** A path escaped its allowed root, or a name contained traversal markers. */
   ERR_PATH_TRAVERSAL: 'ERR_PATH_TRAVERSAL',
@@ -185,7 +191,7 @@ export const ERROR_CODES = Object.freeze({
   ERR_WRITE_FAILED: 'ERR_WRITE_FAILED',
 
   // ── Theme build ──────────────────────────────────────────────────
-  /** A theme definition or contributed theme catalog is invalid. */
+  /** A theme definition or contributed theme descriptor is invalid. */
   ERR_THEME_INVALID: 'ERR_THEME_INVALID',
   /** A theme file could not be loaded / parsed into a defineTheme result. */
   ERR_THEME_LOAD: 'ERR_THEME_LOAD',

package/foundation/response/error-codes.test.mjs

@@ -15,6 +15,9 @@
  */
 
 import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import {ERROR_CODES, isErrorCode, allErrorCodes} from './error-codes.mjs';
 import {runCli} from '../../test-utils/run-cli.mjs';
 
@@ -75,20 +78,126 @@ describe('error-codes taxonomy', () => {
   });
 });
 
+describe('error codes: shipped set', () => {
+  // Every code a release has published. INV3: a shipped code is never removed
+  // or respelled. Add a code here once it ships; never delete an entry.
+  const SHIPPED = [
+    'ERR_AMBIGUOUS_COMPONENT',
+    'ERR_AMBIGUOUS_TEMPLATE',
+    'ERR_AMBIGUOUS_THEME',
+    'ERR_CODEMOD_FAILED',
+    'ERR_CODEMOD_PROTECTED',
+    'ERR_CODEMOD_PROTECTION_SOURCE',
+    'ERR_CORE_INCOMPATIBLE',
+    'ERR_CORE_NOT_FOUND',
+    'ERR_DEP_MISSING',
+    'ERR_FETCH_FAILED',
+    'ERR_FILE_EXISTS',
+    'ERR_FILE_NOT_FOUND',
+    'ERR_GH_CLI',
+    'ERR_INTEGRATION_EXPORT_CONFLICT',
+    'ERR_INTEGRATION_ROOT_CONFLICT',
+    'ERR_INVALID_ARGUMENT',
+    'ERR_INVALID_DETAIL',
+    'ERR_INVALID_DOC',
+    'ERR_INVALID_LANG',
+    'ERR_INVALID_OPTION',
+    'ERR_INVALID_VERSION',
+    'ERR_LAYOUT_INVALID',
+    'ERR_LAYOUT_PARSE',
+    'ERR_MISSING_ARGUMENT',
+    'ERR_NODE_VERSION',
+    'ERR_NOT_FOUND',
+    'ERR_NO_DOC',
+    'ERR_NO_SHOWCASE',
+    'ERR_NO_SOURCE',
+    'ERR_PALETTE_GENERATION',
+    'ERR_PATH_TRAVERSAL',
+    'ERR_SIGNAL_TERMINATED',
+    'ERR_THEME_INVALID',
+    'ERR_THEME_LOAD',
+    'ERR_UNCLASSIFIED_EXIT',
+    'ERR_UNKNOWN',
+    'ERR_UNKNOWN_AGENT',
+    'ERR_UNKNOWN_CATEGORY',
+    'ERR_UNKNOWN_CODEMOD',
+    'ERR_UNKNOWN_COMMAND',
+    'ERR_UNKNOWN_COMPONENT',
+    'ERR_UNKNOWN_FEATURE',
+    'ERR_UNKNOWN_HOOK',
+    'ERR_UNKNOWN_PACKAGE',
+    'ERR_UNKNOWN_POST',
+    'ERR_UNKNOWN_SECTION',
+    'ERR_UNKNOWN_SUBCOMMAND',
+    'ERR_UNKNOWN_TEMPLATE',
+    'ERR_UNKNOWN_THEME',
+    'ERR_UNKNOWN_TOPIC',
+    'ERR_VERSION_DETECT',
+    'ERR_WRITE_FAILED',
+  ];
+
+  it('still carries every shipped code, spelled the same', () => {
+    const missing = SHIPPED.filter(
+      code => !isErrorCode(code) || ERROR_CODES[code] !== code,
+    );
+    expect(missing, 'shipped codes removed or respelled').toEqual([]);
+  });
+});
+
 describe('error codes: end-to-end JSON envelopes', () => {
   const cases = [
-    {name: 'unknown component', args: ['component', 'Bogus', '--json'], code: 'ERR_UNKNOWN_COMPONENT'},
-    {name: 'unknown hook', args: ['hook', 'bogusHook', '--json'], code: 'ERR_UNKNOWN_HOOK'},
-    {name: 'unknown topic', args: ['docs', 'bogusTopic', '--json'], code: 'ERR_UNKNOWN_TOPIC'},
-    {name: 'unknown template', args: ['template', 'bogusTemplate', '--json'], code: 'ERR_UNKNOWN_TEMPLATE'},
-    {name: 'unknown command', args: ['bogus-cmd', '--json'], code: 'ERR_UNKNOWN_COMMAND'},
-    {name: 'invalid --lang', args: ['docs', 'color', '--lang', 'fr', '--json'], code: 'ERR_INVALID_LANG'},
-    {name: 'invalid --detail', args: ['docs', 'color', '--detail', 'bogus', '--json'], code: 'ERR_INVALID_DETAIL'},
-    {name: 'unknown option', args: ['component', 'Button', '--bogus-flag', '--json'], code: 'ERR_INVALID_OPTION'},
-    {name: 'missing argument', args: ['theme', 'build', '--json'], code: 'ERR_MISSING_ARGUMENT'},
+    {
+      name: 'unknown component',
+      args: ['component', 'Bogus', '--json'],
+      code: 'ERR_UNKNOWN_COMPONENT',
+    },
+    {
+      name: 'unknown hook',
+      args: ['hook', 'bogusHook', '--json'],
+      code: 'ERR_UNKNOWN_HOOK',
+    },
+    {
+      name: 'unknown topic',
+      args: ['docs', 'bogusTopic', '--json'],
+      code: 'ERR_UNKNOWN_TOPIC',
+    },
+    {
+      name: 'unknown template',
+      args: ['template', 'bogusTemplate', '--json'],
+      code: 'ERR_UNKNOWN_TEMPLATE',
+    },
+    {
+      name: 'unknown command',
+      args: ['bogus-cmd', '--json'],
+      code: 'ERR_UNKNOWN_COMMAND',
+    },
+    {
+      name: 'invalid --lang',
+      args: ['docs', 'color', '--lang', 'fr', '--json'],
+      code: 'ERR_INVALID_LANG',
+    },
+    {
+      name: 'invalid --detail',
+      args: ['docs', 'color', '--detail', 'bogus', '--json'],
+      code: 'ERR_INVALID_DETAIL',
+    },
+    {
+      name: 'unknown option',
+      args: ['component', 'Button', '--bogus-flag', '--json'],
+      code: 'ERR_INVALID_OPTION',
+    },
+    {
+      name: 'missing argument',
+      args: ['theme', 'build', '--json'],
+      code: 'ERR_MISSING_ARGUMENT',
+    },
     // `theme` is not on the --json allowlist, so --json on any theme subcommand
     // is rejected at the preAction gate with a stable invalid-option code.
-    {name: 'json not supported', args: ['theme', 'bogus-sub', '--json'], code: 'ERR_INVALID_OPTION'},
+    {
+      name: 'json not supported',
+      args: ['theme', 'bogus-sub', '--json'],
+      code: 'ERR_INVALID_OPTION',
+    },
   ];
 
   for (const {name, args, code} of cases) {
@@ -104,6 +213,24 @@ describe('error codes: end-to-end JSON envelopes', () => {
     });
   }
 
+  it('a filesystem failure carries a registered code, never the Node errno', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-errno-'));
+    try {
+      // A file where the target directory should be: mkdir fails with ENOTDIR.
+      fs.writeFileSync(path.join(dir, 'blocker'), 'x');
+      const {status, stdout} = await runCli(
+        ['template', 'dashboard', 'blocker/out', '--json'],
+        {cwd: dir},
+      );
+      expect(status).toBe(1);
+      const env = envelope(stdout);
+      expect(env.error).toMatch(/ENOTDIR/);
+      expect(isErrorCode(env.code)).toBe(true);
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  });
+
   it('every error envelope carries a code (even unmatched paths fall back to ERR_UNKNOWN)', async () => {
     const {stdout} = await runCli(['component', 'Bogus', '--json']);
     const env = envelope(stdout);

package/foundation/response/json-contract.test.mjs

@@ -112,6 +112,17 @@ describe('json envelope shape', () => {
     });
   });
 
+  it('toErrorEnvelope never emits an unregistered code', () => {
+    // A Node system error carries `code: 'EACCES'`; that is not an Astryx code.
+    const sysErr = Object.assign(new Error('EACCES: permission denied'), {
+      code: 'EACCES',
+    });
+    expect(toErrorEnvelope(sysErr).code).toBe('ERR_UNKNOWN');
+    expect(toErrorEnvelope('boom', undefined, 'ENOENT').code).toBe('ERR_UNKNOWN');
+    const docErr = Object.assign(new Error('no doc'), {code: 'ERR_NO_DOC'});
+    expect(toErrorEnvelope(docErr, undefined, 'ENOENT').code).toBe('ERR_NO_DOC');
+  });
+
   it('toErrorEnvelope includes suggestions when present', () => {
     const env = toErrorEnvelope('x', [{name: 'Button', reason: 'close match'}]);
     expect(env.suggestions).toEqual([{name: 'Button', reason: 'close match'}]);

package/foundation/response/json.d.mts

@@ -50,8 +50,10 @@ export function jsonOut(response: {
  *
  * The `code` is resolved in priority order: an explicit `code` argument,
  * then a `code` property carried on a thrown Error/AstryxError, then the
- * generic `ERR_UNKNOWN` fallback. It always appears on the envelope so
- * consumers can branch on it unconditionally.
+ * generic `ERR_UNKNOWN` fallback. Only a registered code (error-codes.mjs) is
+ * taken from either source, so a Node system error's `ENOENT` never reaches
+ * the envelope. It always appears on the envelope so consumers can branch on
+ * it unconditionally.
  *
  * @param {unknown} err
  * @param {import('./base').Suggestion[]} [suggestions]

package/foundation/response/json.mjs

@@ -28,7 +28,7 @@
  * Version of the JSON envelope contract. Bump on breaking shape changes so
  * consumers can negotiate. Exposed on every envelope as `apiVersion`.
  */
-import {ERROR_CODES} from './error-codes.mjs';
+import {ERROR_CODES, isErrorCode} from './error-codes.mjs';
 import {recordEnvelope, setOutcome} from '../debug/index.mjs';
 
 export const API_VERSION = 1;
@@ -118,8 +118,10 @@ export function jsonOut(response) {
  *
  * The `code` is resolved in priority order: an explicit `code` argument,
  * then a `code` property carried on a thrown Error/AstryxError, then the
- * generic `ERR_UNKNOWN` fallback. It always appears on the envelope so
- * consumers can branch on it unconditionally.
+ * generic `ERR_UNKNOWN` fallback. Only a registered code (error-codes.mjs) is
+ * taken from either source, so a Node system error's `ENOENT` never reaches
+ * the envelope. It always appears on the envelope so consumers can branch on
+ * it unconditionally.
  *
  * @param {unknown} err
  * @param {import('./base').Suggestion[]} [suggestions]
@@ -130,13 +132,9 @@ export function jsonOut(response) {
 export function toErrorEnvelope(err, suggestions, code) {
   const message =
     err instanceof Error ? err.message : typeof err === 'string' ? err : String(err);
-  const resolvedCode =
-    code ||
-    (err && typeof err === 'object' &&
-    typeof (/** @type {any} */ (err).code) === 'string'
-      ? /** @type {any} */ (err).code
-      : undefined) ||
-    ERROR_CODES.ERR_UNKNOWN;
+  const carried =
+    err && typeof err === 'object' ? /** @type {any} */ (err).code : undefined;
+  const resolvedCode = [code, carried].find(isErrorCode) ?? ERROR_CODES.ERR_UNKNOWN;
   /** @type {any} */
   const env = {apiVersion: API_VERSION, error: message, code: resolvedCode};
   if (Array.isArray(suggestions) && suggestions.length) env.suggestions = suggestions;

package/foundation/response/response-types.doc.d.mts

@@ -5,7 +5,11 @@
  * @file EnumDoc for the `type` discriminant carried on every --json success
  * envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
  * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
- * switches on `type` to narrow the `data` payload.
+ * switches on `type` to narrow the `data` payload. Descriptions follow the
+ * currently published response projection, not a future package-version boundary.
+ *
+ * @input Public response discriminants and their currently released payloads.
+ * @output Generated consumer reference for every typed JSON success response.
  * @position packages/cli/foundation/response — enum documentation
  */
 /** @type {import('@astryxdesign/cli/authoring').EnumDoc} */

package/foundation/response/response-types.doc.mjs

@@ -4,7 +4,11 @@
  * @file EnumDoc for the `type` discriminant carried on every --json success
  * envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
  * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
- * switches on `type` to narrow the `data` payload.
+ * switches on `type` to narrow the `data` payload. Descriptions follow the
+ * currently published response projection, not a future package-version boundary.
+ *
+ * @input Public response discriminants and their currently released payloads.
+ * @output Generated consumer reference for every typed JSON success response.
  * @position packages/cli/foundation/response — enum documentation
  */
 
@@ -13,7 +17,7 @@ export const doc = {
   type: 'enum',
   name: 'response-types',
   displayName: 'Response Types',
-  namespace: 'cli',
+  namespace: 'cli/api',
   description:
     'The `type` discriminant present on every --json success envelope. Consumers switch on it to narrow `data`.',
   members: [
@@ -36,7 +40,7 @@ export const doc = {
     {
       value: 'component.detail',
       description:
-        "One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).",
+        "One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc).",
     },
     {
       value: 'component.detail.props',
@@ -61,22 +65,27 @@ export const doc = {
     {
       value: 'docs.list',
       description:
-        'All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.',
+        "All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load.",
     },
     {
       value: 'docs.detail',
       description:
-        "One topic's full ReferenceDoc, with token-ref blocks inlined.",
+        "One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).",
     },
     {
       value: 'docs.index',
       description:
-        "One topic's section index (--index): each section's key, title, and one-line summary.",
+        "One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).",
     },
     {
       value: 'docs.detail.section',
       description:
-        'One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined.',
+        'One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it).',
+    },
+    {
+      value: 'docs.node',
+      description:
+        "One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names).",
     },
 
     // blog (read from the published RSS feed)
@@ -95,40 +104,46 @@ export const doc = {
     {
       value: 'discover.list',
       description:
-        'The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
+        'The integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
     },
     {
       value: 'discover.detail',
-      description: 'A single external package entry, for an @scope/name query.',
+      description:
+        'One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it.',
     },
     {
       value: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.',
+        'The validated ComponentDoc for one installed component, for an @scope/name/Component query.',
+    },
+    {
+      value: 'discover.item',
+      description:
+        'One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package.',
     },
     {
       value: 'discover.search',
       description:
-        'The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.',
+        'The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list.',
     },
 
     // search
     {
       value: 'search',
       description:
-        'The echoed query, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit` (domain, name, score, reason, description, follow-up command, and import path where relevant).',
+        'The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title, parent (the command that opens the level above), package (for a docs-tree hit), and, for a hit on one section, section (docs), or displayName and kind (templates).',
     },
 
     // build
     {
       value: 'build.help',
       description:
-        'A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.',
+        'The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation.',
     },
     {
       value: 'build.kit',
       description:
-        'The grouped composition kit: echoed query, hasResults/matchCount/directMatch fields (matchCount is the total matched, never a cap read back), the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.',
+        "The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, command, basis, reason, alternatives, ...}, pages (search's closest templates), blocks and domain as SearchResultEntry[], frame, foundation, and hint {reason, commands} when thin.",
     },
 
     // swizzle
@@ -151,14 +166,14 @@ export const doc = {
     {
       value: 'gap-report.file',
       description:
-        'An aggregate receipt with overall status, the selected package and issues URL, ordered per-handler deliveries, and filedCount/routedOnlyCount totals.',
+        'An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project | integration | fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.',
     },
 
     // template
     {
       value: 'template.list',
       description:
-        'Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.',
+        'The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list.',
     },
     {
       value: 'template.show',
@@ -198,7 +213,7 @@ export const doc = {
     {
       value: 'theme.build',
       description:
-        'A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.',
+        'A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load).',
     },
     {
       value: 'theme.build.check',
@@ -228,7 +243,7 @@ export const doc = {
     {
       value: 'theme.targets',
       description:
-        'The whole themeable surface: the echoed filter, the component count, and one entry per theming target — {key, className, component, props, states}, where props and states are its legal override keys.',
+        'The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key.',
     },
     {
       value: 'theme.palette.generate',
@@ -257,7 +272,7 @@ export const doc = {
     {
       value: 'manifest',
       description:
-        'The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.',
+        'The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.',
     },
 
     // doctor
@@ -276,7 +291,7 @@ export const doc = {
     {
       value: 'integration.pack-check',
       description:
-        'The packed-package check: package identity, tarball facts, local and packed contribution inventories, and issues.',
+        'The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].',
     },
     {
       value: 'integration.validate',
@@ -286,7 +301,7 @@ export const doc = {
     {
       value: 'integration.template-conflicts',
       description:
-        'The integration identity, structural issues, and non-blocking conflicts where an integration template id is also owned by Core; each conflict includes the exact package-qualified command.',
+        'The integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.',
     },
     {
       value: 'integration.component-conflicts',
@@ -296,7 +311,7 @@ export const doc = {
     {
       value: 'integration.doc-conflicts',
       description:
-        'The integration identity, structural issues, and Core doc overlaps classified as intentional replacements, intentional extensions, or accidental same-name conflicts.',
+        'The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` | `error`) and `relationship` (`replaces` | `extends` | `accidental`).',
     },
 
     // layout (XLE/XLO)