@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/authoring/doctypes/_schema.d.mts

@@ -216,7 +216,6 @@ export const ComponentDocKindSchema: z.ZodObject<{
     theming: z.ZodOptional<z.ZodUnknown>;
     playground: z.ZodOptional<z.ZodUnknown>;
     examples: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
-    replaces: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     displayName: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
@@ -317,7 +316,6 @@ export const FunctionDocKindSchema: z.ZodObject<{
 export const GenericDocKindSchema: z.ZodObject<{
     type: z.ZodLiteral<"generic">;
     title: z.ZodOptional<z.ZodString>;
-    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         title: z.ZodString;
@@ -386,6 +384,7 @@ export const GenericDocKindSchema: z.ZodObject<{
     import: z.ZodOptional<z.ZodString>;
     group: z.ZodOptional<z.ZodString>;
     category: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     parent: z.ZodOptional<z.ZodString>;
     relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     hidden: z.ZodOptional<z.ZodBoolean>;
@@ -841,6 +840,7 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     displayName: z.ZodOptional<z.ZodString>;
     group: z.ZodOptional<z.ZodString>;
     category: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
     hidden: z.ZodOptional<z.ZodBoolean>;
     hiddenComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -865,7 +865,6 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     }>>;
     title: z.ZodString;
     description: z.ZodString;
-    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sections: z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         title: z.ZodString;

package/authoring/doctypes/_schema.mjs

@@ -307,7 +307,6 @@ const ComponentBaseSchema = z
     theming: z.unknown().optional(),
     playground: z.unknown().optional(),
     examples: z.array(z.unknown()).optional(),
-    replaces: z.string().min(1).optional(),
   })
   .passthrough();
 
@@ -415,9 +414,6 @@ export const GenericDocKindSchema = z
     ...BaseDocFields,
     type: z.literal('generic'),
     title: nonEmptyString.optional(),
-    // Search terms the title and sections do not use; `astryx search` matches
-    // them as keywords of the whole topic (ReferenceDoc `keywords`).
-    keywords: z.array(z.string()).optional(),
     sections: z.array(ReferenceSectionSchema).min(1).optional(),
     replaces: nonEmptyString.optional(),
     extends: nonEmptyString.optional(),
@@ -734,8 +730,6 @@ const LegacyBaseDocSchema = z.object({
 const LegacyReferenceDocSchema = LegacyBaseDocSchema.extend({
   title: nonEmptyString,
   description: z.string(),
-  // As on the stamped schema: search terms for the whole topic.
-  keywords: z.array(z.string()).optional(),
   sections: z.array(ReferenceSectionSchema).min(1),
   replaces: nonEmptyString.optional(),
   extends: nonEmptyString.optional(),

package/authoring/doctypes/base/graph-fields.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   displayName: 'Authored doc graph fields',
   namespace: 'authoring',
   description:
-    "Fields every authored doc kind can declare for the docs tree: `placement`, plus two reserved fields, `aliases` and `audience`. The docs tree reads `placement` for every guide, the CLI's and each integration's. Nothing reads `aliases` or `audience` today: a reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
+    "Placement, compatibility aliases, and audience: fields every authored doc kind declares for the docs tree. The docs tree reads `placement` for every guide, the CLI's and each integration's; aliases and audience are not built yet. A reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
   appliesTo: 'Every supported .doc.mjs object',
   fields: [
     {
@@ -45,13 +45,13 @@ export const doc = {
       name: 'aliases',
       type: 'string[]',
       description:
-        'Reserved: prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Nothing reads it today, and a topic that sets it fails to load.',
+        'Prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Not read yet: a topic that sets it fails to load.',
     },
     {
       name: 'audience',
       type: "'public' | 'internal'",
       description:
-        "Reserved: which docs bundle includes this doc ('public' when omitted). Nothing reads it today, and a topic that sets it fails to load.",
+        "Which docs bundle includes this doc ('public' when omitted). Not read yet: a topic that sets it fails to load.",
       default: "'public'",
     },
   ],

package/authoring/doctypes/base/type.ts

@@ -39,11 +39,9 @@ export interface DocPlacement {
 export interface AuthoredDocGraphFields {
   /** The doc's one parent in the docs tree: a namespace of its own package. */
   placement?: DocPlacement;
-  /** Reserved: prior routes or names the docs tree will keep resolving.
-   *  Nothing reads it yet. */
+  /** Prior routes or names the docs tree will keep resolving. Not read yet. */
   aliases?: string[];
-  /** Reserved: docs bundle audience; omit for public docs. Nothing reads it
-   *  yet. */
+  /** Docs bundle audience; omit for public docs. Not read yet. */
   audience?: DocAudience;
 }
 

package/authoring/doctypes/command/command.doc.mjs

@@ -151,7 +151,7 @@ export const doc = {
       name: 'subcommands',
       type: 'string[]',
       description:
-        'Subcommand names (for command groups like `theme`).',
+        'Subcommand names (for command groups like `theme` / `layout`).',
     },
     {
       name: 'examples',

package/authoring/doctypes/command/type.ts

@@ -75,7 +75,7 @@ export interface CommandDoc extends AuthoredDocGraphFields {
   args?: CommandArgDoc[];
   /** Flags/options. */
   options?: CommandOptionDoc[];
-  /** Subcommand names (for command groups like `theme`). */
+  /** Subcommand names (for command groups like `theme` / `layout`). */
   subcommands?: string[];
   /** Terminal examples. */
   examples?: CommandExampleDoc[];

package/authoring/doctypes/component/component.doc.mjs

@@ -52,12 +52,6 @@ export const doc = {
       description:
         'Exact public package specifier consumers use to import an integration-owned component. The packed-package gate resolves this specifier and verifies it exports the component name.',
     },
-    {
-      name: 'replaces',
-      type: 'string',
-      description:
-        "Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, lists, search, swizzle, and issue routing. The Core original stays reachable with `--package @astryxdesign/core`. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.",
-    },
     {
       name: 'keywords',
       type: 'string[]',

package/authoring/doctypes/component/type.ts

@@ -48,14 +48,6 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {
   displayName: string;
   /** Exact consumer import specifier for integration-owned components. */
   import?: string;
-  /** Integration components only: the exact `name` of the Core ComponentDoc
-   *  this component takes over for unqualified lookup, so every app that loads
-   *  the integration gets this component from component detail, lists, search,
-   *  swizzle, and issue routing. The Core original stays reachable with
-   *  `--package @astryxdesign/core`. Set it only to intentionally own a Core
-   *  identity; give an alternative or variant its own name instead. Older CLIs
-   *  that do not read `replaces` keep the component under its own name. */
-  replaces?: string;
   /** Search keywords for CLI discovery. Terms a developer might type when
    *  looking for this component: synonyms, related UI concepts, and common
    *  names from other design systems (MUI, Chakra, Radix, and others).

package/authoring/doctypes/reference/reference.doc.mjs

@@ -51,13 +51,6 @@ export const doc = {
       type: 'string',
       description: "Navigation category: 'guide' or 'foundations'.",
     },
-    {
-      name: 'keywords',
-      type: 'string[]',
-      description:
-        "Words a reader may search for that the title and sections do not use: a synonym, a task, or another library's name for the same thing. `astryx search` matches each as a keyword of the whole topic, so an exact one ranks the topic like its own title does.",
-      example: "['dark mode', 'color scheme']",
-    },
     {
       name: 'replaces',
       type: 'string',

package/authoring/doctypes/reference/type.ts

@@ -127,11 +127,6 @@ export interface ReferenceDoc extends AuthoredDocGraphFields {
   description: string;
   /** Navigation category: 'guide' or 'foundations'. */
   category?: string;
-  /** Words a reader may search for that the title and sections do not use:
-   *  a synonym, a task ("dark mode"), or another library's name for the same
-   *  thing. `astryx search` matches each as a keyword of the whole topic, so
-   *  an exact one ranks the topic like its own title does. */
-  keywords?: string[];
   /** Name of an existing topic this doc takes the place of. Authored by an
    *  integration whose guide should be served instead of the built-in one —
    *  `replaces: 'getting-started'` on a doc named `getting-started` swaps the

package/authoring/doctypes/schema/schema.doc.mjs

@@ -49,7 +49,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "The group that reads this doc: 'authoring' for a file an author writes (a section of {@link generic:authoring}), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
+        "The group that reads this doc: 'authoring' for a file an author writes (a section of `astryx docs authoring`), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',
@@ -162,7 +162,7 @@ export const doc = {
       type: '{ dir: string }',
       description: 'Where component sources live.',
       fields: [
-        {name: 'components.dir', type: 'string', description: 'Glob root for Acme*.tsx files.', required: true},
+        {name: 'components.dir', type: 'string', description: 'Glob root for XDS*.tsx files.', required: true},
       ],
     },
   ],

package/authoring/doctypes/template/template.doc.mjs

@@ -56,7 +56,7 @@ export const doc = {
       name: 'replaces',
       type: 'string',
       description:
-        "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field, drop that template, and hide the package's doc topics.",
+        "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field and withhold the package's templates and doc topics.",
     },
     {
       name: 'isReady',

package/authoring/doctypes/template/type.ts

@@ -33,8 +33,8 @@ export interface BaseTemplateDoc extends AuthoredDocGraphFields {
    *  replaces for unqualified lookup (find it with
    *  `astryx --json template --list --package @astryxdesign/core`). The Core
    *  original stays selectable with `--package @astryxdesign/core`. Needs
-   *  `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field,
-   *  drop that template, and hide the package's doc topics. */
+   *  `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field and
+   *  withhold the package's templates and doc topics. */
   replaces?: string;
   /** Whether this template is ready for use. Templates with
    *  isReady: false show as "(WIP)" in the gallery and CLI. */

package/authoring/index.d.mts

@@ -3,7 +3,6 @@
 
 export { parseConfig } from "./config/parse.mjs";
 export { parseIntegration } from "./integration/parse.mjs";
-export { parseDiscoverCatalog } from "./discover/parse.mjs";
 export { parseCodemod } from "./codemod/parse.mjs";
 export { parseDebugEvent } from "./debug/parse.mjs";
 export { parseDoc } from "./doctypes/parse.mjs";

package/authoring/index.d.ts

@@ -44,15 +44,6 @@ export type {
   GapReportTarget,
   GapReportHandlerReceipt,
 } from './gap-report/type.js'; // gap-report handler contract
-export type {
-  DiscoverSource,
-  DiscoverSourceContext,
-  DiscoverCatalog,
-  DiscoverPackage,
-  DiscoverVersion,
-  DiscoverContribution,
-  DiscoverKind,
-} from './discover/type.js'; // discover source contract
 export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type.js'; // codemods/*
 
 // ═══════════════════════════════════════════════════════════════════════
@@ -76,7 +67,6 @@ export {
   parseGapReportHandler,
   parseGapReportReceipt,
 } from './gap-report/parse.mjs';
-export {parseDiscoverCatalog} from './discover/parse.mjs';
 export {parseCodemod} from './codemod/parse.mjs';
 export {parseDebugEvent} from './debug/parse.mjs';
 

package/authoring/index.mjs

@@ -20,7 +20,6 @@ export {
   parseGapReportHandler,
   parseGapReportReceipt,
 } from './gap-report/parse.mjs';
-export {parseDiscoverCatalog} from './discover/parse.mjs';
 export {parseCodemod} from './codemod/parse.mjs';
 export {parseDebugEvent} from './debug/parse.mjs';
 export {parseDoc} from './doctypes/parse.mjs';

package/authoring/integration/integration.doc.mjs

@@ -23,49 +23,48 @@ export const doc = {
       name: 'providerId',
       type: 'string',
       description:
-        'The name that marks this package as the source of everything it contributes. Leave it out to use the package name from package.json. Set it to the old name only during a rename, so the IDs of what the package already contributed stay the same. If two packages use the same name here, the one you are working on wins; otherwise the one the CLI reads first wins, and the CLI warns about the other.',
+        'Stable logical provider ID. Omit to use package.json#name; set it to the prior package name only when an explicit rename must preserve artifact IDs. If two packages claim the same ID, the package being authored is used, otherwise the first-loaded one, and the CLI warns about the other.',
       example: "'@acme/widgets'",
     },
     {
       name: 'components',
       type: 'string',
       description:
-        'The folder that holds your components and their docs, relative to package.json.',
+        'Relative path to the components/docs root (resolved to absolute).',
       example: "'./src/components'",
     },
     {
       name: 'templates',
       type: 'string',
       description:
-        'The folder that holds your templates, relative to package.json.',
+        'Relative path to the templates root (resolved to absolute).',
       example: "'./src/templates'",
     },
     {
       name: 'codemods',
       type: 'string',
-      description:
-        'The folder that holds your codemods, relative to package.json.',
+      description: 'Relative path to the codemods root (resolved to absolute).',
       example: "'./codemods'",
     },
     {
       name: 'docs',
       type: 'string',
       description:
-        'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} in it shows up in `astryx docs` next to the built-in topics; a topic can also set `replaces` or `extends` to take over a built-in topic or add to it.',
+        'Relative path to the reference-docs (topics) root (resolved to absolute). Every {topic}.doc.{ts,mjs,js} under it is served by `astryx docs` beside the built-in topics; a topic may also declare `replaces` or `extends` to take the place of a built-in one or merge onto it.',
       example: "'./docs'",
     },
     {
       name: 'themes',
       type: 'string',
       description:
-        'The folder that holds your themes, relative to package.json, with one folder per theme. Each theme folder has the theme source and a matching .doc.mjs file with the same name. Installed themes show up in `astryx theme list` and can be copied with `astryx theme add`.',
+        'Relative path to a source-theme root with one directory per theme slug. Each directory contains a source module and mandatory same-stem, strongly typed .doc.mjs descriptor. Installed themes appear in `astryx theme list` and can be copied with `astryx theme add`.',
       example: "'./themes'",
     },
     {
       name: 'agentDocs',
       type: '{ append?: readonly string[] }',
       description:
-        'Lines of guidance your package adds to the end of the agent instructions the CLI manages. The CLI owns the heading, labels, bullets, and which files it writes.',
+        'Static package guidance appended to the end of the managed agent block. The CLI owns the section heading, package labels, bullets, target files, and writes.',
       example: "{ append: ['Run acme verify.'] }",
     },
     {
@@ -95,10 +94,9 @@ export const doc = {
     {
       type: 'prose',
       text:
-        'The provider name defaults to the package name in package.json. ' +
-        'During a rename, set `providerId` to the old package name so the IDs ' +
-        'of what the package already contributed stay the same. The package ' +
-        'version always comes from package.json.',
+        'Provider identity defaults to package.json#name. During an explicit ' +
+        'package rename, set `providerId` to the prior canonical package name so ' +
+        'existing artifact IDs remain stable. Package version always comes from package.json.',
     },
     {
       type: 'prose',

package/clients/cli/command-result-coverage.test.mjs

@@ -29,17 +29,17 @@ import {program} from './index.mjs';
 import {reportsResult, reportsResultVia} from './lib/define-command.mjs';
 
 /**
- * Commands with no action of their own: a group that prints its subcommand
- * list and does nothing else has no run to report on.
+ * Commands with no action of their own: bare `astryx layout` prints its
+ * subcommand list and does nothing else, so there is no run to report on.
  *
  * Pinned as a SET rather than skipped silently — if a command joins this list,
  * that is a real change to what the CLI does and it should be read, not
- * absorbed. Every group ships an action today: `theme`, for instance, HAS one
- * — the one that rejects an unknown subcommand — so it goes through the
- * converter like any other. Its bare form prints help and never returns from
- * that action, which the recorder covers where help is recorded, not here.
+ * absorbed. (`theme` is deliberately NOT here: it HAS an action — the one that
+ * rejects an unknown subcommand — so it goes through the converter like any
+ * other. Its bare form prints help and never returns from that action, which
+ * the recorder covers where help is recorded, not here.)
  */
-const NO_ACTION_OF_THEIR_OWN = [];
+const NO_ACTION_OF_THEIR_OWN = ['layout'];
 
 /**
  * Commands that record for themselves instead of returning a descriptor.

package/clients/cli/commands/component/index.mjs

@@ -38,7 +38,6 @@ import {doc as componentFn} from '../../../../api/component/component.doc.mjs';
  *
  * @typedef {(
  *   | import('../../../../api/component/component.type.mjs').ComponentListResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentBatchResponse
  *   | import('../../../../api/component/component.type.mjs').ComponentDetailResponse
  *   | import('../../../../api/component/component.type.mjs').ComponentDetailPropsResponse
  *   | import('../../../../api/component/component.type.mjs').ComponentDetailSourceResponse
@@ -68,11 +67,6 @@ function summarize(result) {
       );
       return resultSet({count, resultKind: 'component'});
     }
-    case 'component.batch':
-      return resultSet({
-        count: result.data.results.filter(row => row.status === 'found').length,
-        resultKind: 'component',
-      });
     case 'component.detail':
     case 'component.detail.props':
     case 'component.detail.source':
@@ -88,103 +82,19 @@ function summarize(result) {
   }
 }
 
-/**
- * Project one single-component API result through the existing formatter kit.
- * @param {import('../../../../api/component/component.type.mjs').ComponentSingleResponse} result
- * @param {string} requestedName
- * @param {'full'|'compact'|'brief'} detail
- * @param {ReturnType<typeof resolveTheme>} themeData
- * @returns {import('../../formatters/index.mjs').Block[]}
- */
-function componentDetailBlocks(result, requestedName, detail, themeData) {
-  const resolvedName = (requestedName.split('/').pop() ?? requestedName).replace(
-    /^XDS/,
-    '',
-  );
-  switch (result.type) {
-    case 'component.detail': {
-      /** @type {import('../../formatters/index.mjs').Block[]} */
-      const out = [];
-      if (result.data.parentDoc) {
-        out.push(record(result.data, {fields: ['parentDoc']}));
-      }
-      out.push(
-        detail === 'brief'
-          ? code(
-              formatBrief(result.data, resolvedName, result.data.import, {
-                themeData,
-              }),
-            )
-          : detail === 'compact'
-            ? code(
-                formatCompact(result.data, resolvedName, result.data.import),
-              )
-            : code(
-                formatFull(result.data, {
-                  themeData,
-                  importHint: result.data.import,
-                }),
-              ),
-      );
-      return out;
-    }
-    case 'component.detail.props':
-      return [code(formatProps({props: result.data}, resolvedName))];
-    case 'component.detail.source':
-    case 'component.detail.showcase':
-      return [code(result.data.source)];
-    case 'component.detail.blocks': {
-      const {showcase, examples, related} = result.data;
-      /** @type {import('../../formatters/index.mjs').Block[]} */
-      const out = [];
-      if (showcase) {
-        out.push(
-          section('Showcase'),
-          record(showcase, {fields: ['displayName', 'description']}),
-        );
-      }
-      if (examples.length > 0) {
-        out.push(
-          section('Examples'),
-          records(examples, {fields: ['name', 'description']}),
-        );
-      }
-      if (related.length > 0) {
-        out.push(
-          section(
-            `Related: ${related.length} blocks that use ${result.data.component}`,
-          ),
-          list(related.map(block => block.name)),
-        );
-      }
-      if (!showcase && examples.length === 0 && related.length === 0) {
-        out.push(text(`No blocks found for ${result.data.component}`));
-      }
-      return out;
-    }
-    default:
-      return [];
-  }
-}
-
 /**
  * @param {import('commander').Command} program
  */
 export function registerComponent(program) {
   defineCommand(program, componentCommand, {
     fn: componentFn,
-    action: async (
-      /** @type {string[] | undefined} */ names,
-      /** @type {{list?: boolean, category?: string, props?: boolean, source?: boolean, showcase?: boolean, blocks?: boolean, package?: string}} */ options,
-    ) => {
+    action: async (/** @type {string | undefined} */ name, /** @type {{list?: boolean, category?: string, props?: boolean, source?: boolean, showcase?: boolean, blocks?: boolean, package?: string}} */ options) => {
       const run = getCliInvocation();
-      const name = names?.length === 1 ? names[0] : undefined;
-      const apiInput = !names?.length ? undefined : name ?? names;
       const zh = program.opts().zh || false;
       const dense = program.opts().dense || false;
       const lang = program.opts().lang || null;
       const detailSource = program.getOptionValueSource('detail');
-      const isListView = options.list || options.category || !names?.length;
+      const isListView = options.list || options.category || !name;
       // Default detail level is full for single-component view, brief for list views.
       // (List views are scannable name lists; users can opt into compact/full.)
       let detail = program.opts().detail || 'full';
@@ -209,7 +119,7 @@ export function registerComponent(program) {
       /** @type {ComponentResult} */
       let result;
       try {
-        result = /** @type {ComponentResult} */ (await componentApi(apiInput, {
+        result = /** @type {ComponentResult} */ (await componentApi(name, {
           cwd: process.cwd(),
           list: options.list,
           category: options.category,
@@ -227,12 +137,6 @@ export function registerComponent(program) {
       }
 
       const answered = summarize(result);
-      if (
-        result.type === 'component.batch' &&
-        result.data.results.some(row => row.status !== 'found')
-      ) {
-        process.exitCode = 1;
-      }
       if (json) {
         jsonOut(result);
         return answered;
@@ -248,7 +152,7 @@ export function registerComponent(program) {
       const listFooter = text(
         [
           `Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`,
-          `Usage: ${run} component <name> [name...]`,
+          `Usage: ${run} component <name>`,
         ].join('\n'),
       );
 
@@ -327,65 +231,64 @@ export function registerComponent(program) {
           break;
         }
 
-        case 'component.batch': {
+        case 'component.detail': {
+          const resolvedName = (name || '').replace(/^XDS/, '');
+          const importHint = result.data.import;
+          if (result.data.parentDoc) emit(record(result.data, {fields: ['parentDoc']}));
+          const doc =
+            detail === 'brief'
+              ? code(formatBrief(result.data, resolvedName, importHint, {themeData}))
+              : detail === 'compact'
+                ? code(formatCompact(result.data, resolvedName, importHint))
+                : code(formatFull(result.data, {themeData, importHint}));
+          emit(doc);
+          break;
+        }
+
+        case 'component.detail.props': {
+          const resolvedName = (name || '').replace(/^XDS/, '');
+          emit(code(formatProps({props: result.data}, resolvedName)));
+          break;
+        }
+
+        case 'component.detail.source': {
+          emit(code(result.data.source));
+          break;
+        }
+
+        case 'component.detail.showcase': {
+          emit(code(result.data.source));
+          break;
+        }
+
+        case 'component.detail.blocks': {
+          const {showcase, examples, related} = result.data;
           /** @type {import('../../formatters/index.mjs').Block[]} */
-          const out = [
-            section('Component batch'),
-            record({count: result.data.count}),
-            section('Results'),
-          ];
-          for (const row of result.data.results) {
-            out.push(section(row.selector));
-            if (row.status === 'found') {
-              out.push(
-                record(row, {fields: ['selector', 'status']}),
-                section('Result'),
-                ...componentDetailBlocks(
-                  row.result,
-                  row.selector,
-                  detail,
-                  themeData,
-                ),
-              );
-              continue;
-            }
+          const out = [];
+          if (showcase) {
             out.push(
-              record(row, {
-                fields: ['selector', 'status', 'code', 'error'],
-              }),
+              section('Showcase'),
+              record(showcase, {fields: ['displayName', 'description']}),
             );
-            if (row.status === 'ambiguous') {
-              out.push(
-                section('Candidates'),
-                records(row.candidates, {
-                  fields: ['package', 'component', 'kind', 'installed'],
-                }),
-              );
-            } else if (row.suggestions?.length) {
-              out.push(
-                section('Suggestions'),
-                records(row.suggestions, {fields: ['name', 'reason']}),
-              );
-            }
+          }
+          if (examples.length > 0) {
+            out.push(
+              section('Examples'),
+              records(examples, {fields: ['name', 'description']}),
+            );
+          }
+          if (related.length > 0) {
+            out.push(
+              section(`Related: ${related.length} blocks that use ${result.data.component}`),
+              list(related.map(b => b.name)),
+            );
+          }
+          if (!showcase && examples.length === 0 && related.length === 0) {
+            out.push(text(`No blocks found for ${result.data.component}`));
           }
           emit(...out);
           break;
         }
-
-        case 'component.detail':
-        case 'component.detail.props':
-        case 'component.detail.source':
-        case 'component.detail.showcase':
-        case 'component.detail.blocks':
-          emit(
-            ...componentDetailBlocks(
-              result,
-              name ?? '',
-              detail,
-              themeData,
-            ),
-          );
-          break;
       }
       return answered;
     },