@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db7b338

package/authoring/doctypes/function/function.doc.mjs

@@ -57,7 +57,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "Docs namespace path. Defaults (e.g. 'cli/api') applied by the docs index.",
+        "The `astryx docs` topic that reads this doc. The CLI's API functions use 'cli/api' (the section `api-<name>` of the `cli` topic). Every function doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that no topic reads.",
     },
     {
       name: 'aliases',

package/authoring/doctypes/function/type.ts

@@ -62,7 +62,7 @@ export interface FunctionDoc extends AuthoredDocGraphFields {
   summary?: string;
   /** Longer description. */
   description?: string;
-  /** Docs namespace path. Defaults (e.g. 'cli/api') applied by the docs index. */
+  /** The `astryx docs` topic that reads this doc. The CLI's API functions use 'cli/api' (the section `api-<name>` of the `cli` topic). Every function doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that no topic reads. */
   namespace?: string;
   /** Alternate slugs that also resolve to this doc. */
   aliases?: string[];

package/authoring/doctypes/hook/type.ts

@@ -23,10 +23,10 @@ import type {
  * Standalone hooks (e.g. useMediaQuery, useFocusTrap, useOverflow) get
  * their own {hookName}.doc.mjs file and use this type.
  *
- * Every hook .doc.mjs must export a single `docs` constant:
+ * Every new hook .doc.mjs default-exports a stamped object:
  *
  *   /\*\* @type {import('@astryxdesign/cli/authoring').HookDoc} \*\/
- *   export const docs = { ... };
+ *   export default { type: 'function', ... };
  */
 export interface HookDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant for the stamped default-export format

package/authoring/doctypes/load-contract.test.mjs

@@ -49,7 +49,7 @@ const EXAMPLES = Object.fromEntries(
 
 describe('load check vs published type', () => {
   it('locks every doc kind', () => {
-    const source = ['_schema.mjs', 'template/parse.mjs']
+    const source = ['_schema.mjs', 'template/parse.mjs', 'theme/parse.mjs']
       .map(file => fs.readFileSync(path.join(HERE, file), 'utf8'))
       .join('\n');
     expect(Object.keys(LOCKS).sort()).toEqual([...KINDS].sort());
@@ -57,6 +57,7 @@ describe('load check vs published type', () => {
       ...Object.values(LOCKS),
       '_AuthoredDocKindDriftLock',
       '_HookDocIsFunctionDocLock',
+      '_ThemeDocDriftLock',
     ];
     for (const lock of locks) {
       expect(source, `${lock} is missing`).toMatch(
@@ -70,7 +71,7 @@ describe('load check vs published type', () => {
       expect(() => parseDoc(EXAMPLES[kind], `${kind}.doc.mjs`)).not.toThrow();
     }
     expect(() => parseDoc({type: 'widget', name: 'x'}, 'x.doc.mjs')).toThrow(
-      /unsupported type "widget"/,
+      /x\.doc\.mjs is invalid/u,
     );
   });
 });

package/authoring/doctypes/namespace/namespace.doc.mjs

@@ -78,9 +78,9 @@ export const doc = {
     },
     {
       name: 'blocks',
-      type: 'ReferenceContentBlock[]',
+      type: '(ReferenceContentBlock | GraphContentBlock)[]',
       description:
-        'Ordered layout content. V1 adds only workflow, collection, and reference to the existing prose, heading, code, table, list, and token-ref blocks.',
+        'Ordered layout content. Graph-only workflow, collection, and reference blocks are available here without widening the stable ReferenceContentBlock union used by existing topic renderers.',
     },
   ],
   examples: [

package/authoring/doctypes/namespace/parse.test.mjs

@@ -134,32 +134,30 @@ describe('NamespaceDoc', () => {
   });
 });
 
-describe('semantic blocks in existing docs', () => {
-  it('accepts workflow, collection, and reference in a ReferenceDoc section', () => {
-    const parsed = parseReference({
-      type: 'generic',
-      name: 'publishing',
-      title: 'Publishing',
-      description: 'Publish an integration.',
-      sections: [
-        {
-          id: 'start',
-          title: 'Start',
-          content: namespaceDoc.blocks,
-        },
-      ],
-    });
-    expect(parsed.sections[0].id).toBe('start');
-    expect(parsed.sections[0].content.map(block => block.type)).toEqual([
-      'workflow',
-      'collection',
-      'reference',
-    ]);
+describe('semantic graph blocks', () => {
+  it('keeps graph-only blocks out of the stable ReferenceDoc section union', () => {
+    expect(() =>
+      parseReference({
+        type: 'generic',
+        name: 'publishing',
+        title: 'Publishing',
+        description: 'Publish an integration.',
+        sections: [
+          {
+            id: 'start',
+            title: 'Start',
+            content: namespaceDoc.blocks,
+          },
+        ],
+      }),
+    ).toThrow(/Invalid discriminator value/u);
   });
 
-  it('rejects an unknown stamped doc kind instead of treating it as legacy', () => {
-    expect(() => parseDoc({type: 'choice', name: 'x', props: []})).toThrow(
-      /unsupported type "choice"/u,
-    );
+  it('keeps shape-sniffing an unknown stamp for 0.6.x compatibility', () => {
+    expect(parseDoc({type: 'choice', name: 'x', props: []})).toMatchObject({
+      type: 'choice',
+      name: 'x',
+      props: [],
+    });
   });
 });

package/authoring/doctypes/namespace/type.ts

@@ -7,7 +7,10 @@
  */
 
 import type {AuthoredDocGraphFields, AuthoredDocKind} from '../base/type.js';
-import type {ReferenceContentBlock} from '../reference/type.js';
+import type {
+  GraphContentBlock,
+  ReferenceContentBlock,
+} from '../reference/type.js';
 
 /** Which providers may contribute appearances to a namespace slot. */
 export type NamespaceProviderScope = 'same' | 'configured';
@@ -67,5 +70,5 @@ export interface NamespaceDoc extends AuthoredDocGraphFields {
   /** Optional source-adoption rules for otherwise-unplaced docs. */
   adopts?: NamespaceAdoptionRule[];
   /** Ordered renderer-neutral content and collection blocks. */
-  blocks?: ReferenceContentBlock[];
+  blocks?: (ReferenceContentBlock | GraphContentBlock)[];
 }

package/authoring/doctypes/parse.d.mts

@@ -10,6 +10,7 @@
 /** @typedef {import('./types.js').CommandDoc} CommandDoc */
 /** @typedef {import('./types.js').EnumDoc} EnumDoc */
 /** @typedef {import('./types.js').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./types.js').ThemeDoc} ThemeDoc */
 /**
  * Validate an unknown loaded doc value into its typed shape, or throw.
  * Dispatches on the stamped `type`; unstamped docs fall back to
@@ -18,9 +19,9 @@
  *
  * @param {unknown} input
  * @param {string} [label]
- * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc}
+ * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc | ThemeDoc}
  */
-export function parseDoc(input: unknown, label?: string): ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc;
+export function parseDoc(input: unknown, label?: string): ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc | ThemeDoc;
 export type ComponentDoc = import("./types.js").ComponentDoc;
 export type HookDoc = import("./types.js").HookDoc;
 export type FunctionDoc = import("./types.js").FunctionDoc;
@@ -30,3 +31,4 @@ export type SchemaDoc = import("./types.js").SchemaDoc;
 export type CommandDoc = import("./types.js").CommandDoc;
 export type EnumDoc = import("./types.js").EnumDoc;
 export type NamespaceDoc = import("./types.js").NamespaceDoc;
+export type ThemeDoc = import("./types.js").ThemeDoc;

package/authoring/doctypes/parse.mjs

@@ -4,8 +4,8 @@
  * @file The doc load boundary. `parseDoc` validates an unknown loaded doc value
  * into its typed shape (or throws a readable error), dispatching on the stamped
  * `type` and falling back to legacy shape-sniffing for unstamped docs. Its
- * acceptance set matches the old permissive `ComponentDocSchema` exactly, so
- * every existing `.doc.*` keeps loading unchanged.
+ * acceptance set preserves the old permissive `ComponentDocSchema` while new
+ * stamped kinds, including `theme`, use their sealed parser.
  */
 
 import {parseComponent} from './component/parse.mjs';
@@ -16,6 +16,7 @@ import {parseSchema} from './schema/parse.mjs';
 import {parseCommand} from './command/parse.mjs';
 import {parseEnum} from './enum/parse.mjs';
 import {parseNamespace} from './namespace/parse.mjs';
+import {parseTheme} from './theme/parse.mjs';
 import {parseLegacyDoc} from './legacy.mjs';
 
 /** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
@@ -27,6 +28,7 @@ import {parseLegacyDoc} from './legacy.mjs';
 /** @typedef {import('./types.js').CommandDoc} CommandDoc */
 /** @typedef {import('./types.js').EnumDoc} EnumDoc */
 /** @typedef {import('./types.js').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./types.js').ThemeDoc} ThemeDoc */
 
 /**
  * Validate an unknown loaded doc value into its typed shape, or throw.
@@ -36,7 +38,7 @@ import {parseLegacyDoc} from './legacy.mjs';
  *
  * @param {unknown} input
  * @param {string} [label]
- * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc}
+ * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc | ThemeDoc}
  */
 export function parseDoc(input, label = 'doc') {
   const type =
@@ -62,9 +64,12 @@ export function parseDoc(input, label = 'doc') {
       return parseEnum(input, label);
     case 'namespace':
       return parseNamespace(input, label);
+    case 'theme':
+      return parseTheme(input, label);
     case undefined:
-      return parseLegacyDoc(input, label);
     default:
-      throw new Error(`${label} has unsupported type ${JSON.stringify(type)}.`);
+      // 0.6.x shape-sniffed unknown stamps. Keep accepting them through the
+      // patch compatibility window; canonical writers emit a known stamp.
+      return parseLegacyDoc(input, label);
   }
 }

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

@@ -62,7 +62,7 @@ export const doc = {
       name: 'extends',
       type: 'string',
       description:
-        'Name of an existing topic this doc merges onto, section by section: a section whose title matches one in the base replaces it, a section the base does not have is appended. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.',
+        "Name of an existing topic this doc merges onto, section by section: a section whose title matches one in the base replaces it, a section the base does not have is appended. The topic keeps the base's title and description. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.",
       example: "'theme'",
     },
     {
@@ -95,7 +95,7 @@ export const doc = {
           name: 'sections[].content',
           type: 'ReferenceContentBlock[]',
           description:
-            'Ordered content blocks: prose, heading, code, table, list, and token-ref. workflow, collection, and reference are declared for the docs graph and parse, but a topic that uses one fails to load until the docs graph ships.',
+            'Ordered content blocks: prose, heading, code, table, list, and token-ref. Graph-only workflow, collection, and reference blocks are available through GraphContentBlock on NamespaceDoc, without widening this stable union.',
           required: true,
         },
         {
@@ -144,7 +144,7 @@ export const docs = {
     },
     {
       type: 'prose',
-      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. workflow, collection, and reference are declared for the docs graph: they parse, but topic loading rejects them until the docs graph ships. choice, callout, and checklist remain invalid. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
+      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, the stable discriminated union of prose, heading, code, table, list, and token-ref. Docs-graph-only workflow, collection, and reference blocks are exported separately as GraphContentBlock and accepted by NamespaceDoc. choice, callout, and checklist remain invalid. ReferenceContentBlock is also reused by the `notes` field on SchemaDoc and CommandDoc.',
     },
     {
       type: 'code',
@@ -156,7 +156,9 @@ export const docs = {
   | { type: 'code'; lang: string; code: string; label?: string }
   | { type: 'table'; headers: string[]; rows: string[][] }
   | { type: 'list'; style: 'ordered' | 'unordered' | 'do' | 'dont'; items: string[] }
-  | { type: 'token-ref'; topic: string; section: string }
+  | { type: 'token-ref'; topic: string; section: string };
+
+type GraphContentBlock =
   | { type: 'workflow'; title?: string; steps: WorkflowStep[] }
   | { type: 'collection'; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
   | { type: 'reference'; target: string; projection?: {fields?: string[]; sections?: string[]} };`,

package/authoring/doctypes/reference/type.ts

@@ -41,8 +41,13 @@ export interface ReferenceDocBlock {
   presentation?: 'summary' | 'compact' | 'full';
 }
 
+/** Graph-only content blocks. These are additive and do not widen the stable
+ * {@link ReferenceContentBlock} union consumed by existing exhaustive renderers. */
+export type GraphContentBlock =
+  WorkflowDocBlock | CollectionDocBlock | ReferenceDocBlock;
+
 /**
- * A content block within a reference doc section or namespace.
+ * A content block within a reference doc section.
  * Ordered arrays of these blocks form renderer-neutral documentation content.
  * A new semantic kind must ship with every renderer or fail visibly at a legacy
  * reader boundary until that renderer is available.
@@ -55,9 +60,6 @@ export interface ReferenceDocBlock {
  * { type: 'table', headers: ['Token', 'Value'], rows: [['--spacing-4', '16px']] }
  * { type: 'list', style: 'do', items: ['Use semantic tokens'] }
  * { type: 'token-ref', topic: 'tokens', section: 'Color Tokens' }
- * { type: 'workflow', steps: [{title: 'Validate', references: ['command:doctor']}] }
- * { type: 'collection', source: {slot: 'guides'}, presentation: 'cards' }
- * { type: 'reference', target: 'schema:integration', projection: {fields: ['docs']} }
  * ```
  */
 export type ReferenceContentBlock =
@@ -80,10 +82,7 @@ export type ReferenceContentBlock =
       topic: string;
       /** Section title to pull from that topic. e.g. `'Color Tokens'` */
       section: string;
-    }
-  | WorkflowDocBlock
-  | CollectionDocBlock
-  | ReferenceDocBlock;
+    };
 
 /**
  * A reference documentation file (.doc.mjs).
@@ -93,10 +92,10 @@ export type ReferenceContentBlock =
  * they aren't tied to a specific component — just drop a .doc.mjs file
  * in the docs/ directory and it shows up in `astryx docs`.
  *
- * Every reference .doc.mjs must export a single `docs` constant:
+ * Every new reference .doc.mjs default-exports a stamped object:
  *
  *   /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} *\/
- *   export const docs = { ... };
+ *   export default { type: 'generic', ... };
  */
 export interface ReferenceDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant for the stamped default-export format

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

@@ -49,7 +49,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "Docs namespace path (e.g. 'cli' | 'authoring'). Defaults are applied by the docs index; set explicitly to place the schema.",
+        "The `astryx docs` topic 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 section `api-<name>` of the `cli` topic). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that no topic reads.",
     },
     {
       name: 'aliases',

package/authoring/doctypes/schema/type.ts

@@ -47,8 +47,7 @@ export interface SchemaDoc extends AuthoredDocGraphFields {
   displayName: string;
   /** One-line summary shown in listings. */
   description: string;
-  /** Docs namespace path (e.g. 'cli' | 'authoring'). Defaults are applied by
-   *  the docs index; set explicitly to place the schema. */
+  /** The `astryx docs` topic 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 section `api-<name>` of the `cli` topic). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that no topic reads. */
   namespace?: string;
   /** Alternate slugs that also resolve to this doc (back-compat). */
   aliases?: string[];

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

@@ -18,7 +18,7 @@ export const doc = {
     "(type: 'page') for full page templates and BlockTemplateDoc (type: 'block') for " +
     'editable compositions. A block can stand alone or use `exampleFor` to attach ' +
     'to one component; `isShowcase` requires that component ownership.',
-  appliesTo: '<Name>.template.mjs',
+  appliesTo: '<Name>.doc.mjs',
   fields: [
     {
       name: 'type',
@@ -123,7 +123,7 @@ export const doc = {
     {
       label: 'Page template',
       code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
+export default {
   type: 'page',
   name: 'Dashboard',
   displayName: 'Dashboard',
@@ -135,7 +135,7 @@ export const doc = {
     {
       label: 'Block template (component example)',
       code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
-export const doc = {
+export default {
   type: 'block',
   name: 'ButtonGroupExample',
   displayName: 'Button Group Example',

package/authoring/doctypes/theme/parse.d.mts

@@ -0,0 +1,35 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Compile-time drift lock: the sealed schema must infer exactly ThemeDoc.
+ *
+ * @typedef {import('../../_shared/contract.js').Expect<
+ *   import('../../_shared/contract.js').Equal<
+ *     z.infer<typeof themeDocSchema>,
+ *     ThemeDoc
+ *   >
+ * >} _ThemeDocDriftLock
+ */
+/**
+ * Validate an unknown value as a theme descriptor, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {ThemeDoc}
+ */
+export function parseTheme(input: unknown, label?: string): ThemeDoc;
+/**
+ * Compile-time drift lock: the sealed schema must infer exactly ThemeDoc.
+ */
+export type _ThemeDocDriftLock = import("../../_shared/contract.js").Expect<import("../../_shared/contract.js").Equal<z.infer<typeof themeDocSchema>, ThemeDoc>>;
+export type ThemeDoc = import("./type.js").ThemeDoc;
+import { z } from 'zod';
+declare const themeDocSchema: z.ZodObject<{
+    type: z.ZodLiteral<"theme">;
+    name: z.ZodString;
+    displayName: z.ZodString;
+    description: z.ZodString;
+    maintained: z.ZodBoolean;
+}, z.core.$strict>;
+export {};

package/authoring/doctypes/theme/parse.mjs

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Theme doc parser (stamped `type: 'theme'`). Zod is sealed here;
+ * theme discovery calls `parseTheme` at the descriptor load boundary.
+ *
+ * @input an unknown loaded or statically extracted theme descriptor
+ * @output a validated ThemeDoc or a readable schema error
+ * @position packages/cli/authoring/doctypes/theme — descriptor load boundary
+ */
+
+import {z} from 'zod';
+import {formatZodError} from '../../_shared/errors.mjs';
+
+/** @typedef {import('./type.js').ThemeDoc} ThemeDoc */
+
+/** @param {string} field */
+const nonBlank = field =>
+  z.string().refine(value => value.trim() !== '', {
+    message: `${field} must not be blank`,
+    abort: true,
+  });
+
+const themeDocSchema = z
+  .object({
+    type: z.literal('theme'),
+    name: nonBlank('name').regex(
+      /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u,
+      'name must be lowercase kebab-case starting with a letter',
+    ),
+    displayName: nonBlank('displayName'),
+    // Blank is allowed, as the released catalog allowed it.
+    description: z.string(),
+    maintained: z.boolean(),
+  })
+  .strict();
+
+/** Zod skips `__proto__` when it looks for unknown keys. */
+const PROTO_KEY_ISSUE = {
+  code: /** @type {const} */ ('unrecognized_keys'),
+  keys: ['__proto__'],
+  path: [],
+  message: 'Unrecognized key: "__proto__"',
+};
+
+/**
+ * Compile-time drift lock: the sealed schema must infer exactly ThemeDoc.
+ *
+ * @typedef {import('../../_shared/contract.js').Expect<
+ *   import('../../_shared/contract.js').Equal<
+ *     z.infer<typeof themeDocSchema>,
+ *     ThemeDoc
+ *   >
+ * >} _ThemeDocDriftLock
+ */
+
+/**
+ * Validate an unknown value as a theme descriptor, or throw.
+ *
+ * @param {unknown} input
+ * @param {string} [label]
+ * @returns {ThemeDoc}
+ */
+export function parseTheme(input, label = 'theme') {
+  const result = themeDocSchema.safeParse(input);
+  const protoKey =
+    input !== null &&
+    typeof input === 'object' &&
+    Object.hasOwn(input, '__proto__');
+  if (result.success && !protoKey) return result.data;
+  const issues = [
+    ...(result.error?.issues ?? []),
+    ...(protoKey ? [PROTO_KEY_ISSUE] : []),
+  ];
+  throw new Error(formatZodError(label, new z.ZodError(issues)));
+}

package/authoring/doctypes/theme/theme.doc.d.mts

@@ -0,0 +1,9 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for the ThemeDoc authoring type.
+ * @position packages/cli/authoring/doctypes/theme — doc-type documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

package/authoring/doctypes/theme/theme.doc.mjs

@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for the ThemeDoc authoring type.
+ * @position packages/cli/authoring/doctypes/theme — doc-type documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'theme-doc',
+  displayName: 'ThemeDoc',
+  namespace: 'authoring',
+  description:
+    'The strongly typed descriptor for one integration or CLI-bundled source theme.',
+  appliesTo: '<theme-source-stem>.doc.mjs',
+  fields: [
+    {
+      name: 'type',
+      type: "'theme'",
+      description: 'Doc-kind discriminant.',
+      required: true,
+    },
+    {
+      name: 'name',
+      type: 'string',
+      description:
+        'Lower-kebab CLI theme identity. Must match the descriptor parent directory.',
+      required: true,
+      example: "'ocean'",
+    },
+    {
+      name: 'displayName',
+      type: 'string',
+      description: 'Human-readable name shown by theme listings.',
+      required: true,
+      example: "'Ocean'",
+    },
+    {
+      name: 'description',
+      type: 'string',
+      description: 'One-line summary shown by theme listings.',
+      required: true,
+    },
+    {
+      name: 'maintained',
+      type: 'boolean',
+      description: 'Whether the owning package actively maintains this theme.',
+      required: true,
+    },
+  ],
+  examples: [
+    {
+      label: 'A theme descriptor beside oceanTheme.ts',
+      code: `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'ocean',
+  displayName: 'Ocean',
+  description: 'Cool blue surfaces with crisp contrast.',
+  maintained: true,
+};`,
+    },
+  ],
+  notes: [
+    {
+      type: 'prose',
+      text: 'ThemeDoc is static metadata. Default-export one object with literal string and boolean fields; discovery validates it without executing the descriptor or theme source.',
+    },
+    {
+      type: 'prose',
+      text: 'The descriptor and source share one stem. For oceanTheme.doc.mjs, discovery requires exactly one oceanTheme source module and a named oceanTheme runtime export.',
+    },
+    {
+      type: 'prose',
+      text: 'The parent theme directory, including this descriptor, is the complete copy and pack boundary. Nested source, palettes, assets, and receipts need no second file list.',
+    },
+  ],
+};

package/authoring/doctypes/theme/type.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Theme contribution descriptor type.
+ *
+ * A theme descriptor is a strongly typed `.doc.mjs` beside its same-stem theme
+ * source. The shared stem identifies the source entry and required named runtime
+ * export. The lower-kebab parent directory and `name` identify the CLI theme.
+ *
+ * @input metadata authored beside one source theme
+ * @output the public ThemeDoc contract
+ * @position packages/cli/authoring/doctypes/theme — theme descriptor vocabulary
+ */
+
+/**
+ * The descriptor for one source theme contributed by an integration or bundled
+ * with the CLI.
+ *
+ * @example
+ * ```
+ * /** @type {import('@astryxdesign/cli/authoring').ThemeDoc} *\/
+ * export default {
+ *   type: 'theme',
+ *   name: 'ocean',
+ *   displayName: 'Ocean',
+ *   description: 'Cool blue surfaces with crisp contrast.',
+ *   maintained: true,
+ * };
+ * ```
+ */
+export interface ThemeDoc {
+  /** Doc-kind discriminant. */
+  type: 'theme';
+  /** Stable CLI identity. Must be lower-kebab and match the parent directory. */
+  name: string;
+  /** Human-readable name shown by theme listings. */
+  displayName: string;
+  /** One-line summary shown by theme listings. */
+  description: string;
+  /** Whether the owning package actively maintains this theme. */
+  maintained: boolean;
+}

package/authoring/doctypes/types.ts

@@ -3,7 +3,7 @@
 /**
  * @file Doc-type vocabulary barrel. Each kind's types live in one `type.ts`
  * under its folder (`base/` shared leaves, then `component/`, `hook/`,
- * `reference/`, `template/`); this re-exports them as the full doc vocabulary
+ * `reference/`, `template/`, `theme/`); this re-exports them as the full doc vocabulary
  * behind `@astryxdesign/cli/authoring`.
  */
 
@@ -17,3 +17,4 @@ export type * from './template/type.js';
 export type * from './schema/type.js';
 export type * from './command/type.js';
 export type * from './enum/type.js';
+export type * from './theme/type.js';

package/authoring/gap-report/gap-report.doc.d.mts

@@ -0,0 +1,12 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for GapReportHandler, the handler `astryx gap-report` calls.
+ * @input The GapReportHandler type beside it (`type.ts`), which `parse.mjs`
+ *   validates.
+ * @output The `gap-report-handler` section of `astryx docs authoring`.
+ * @position packages/cli/authoring/gap-report — schema documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;