@astryxdesign/cli 0.6.3-canary.ebaebc4 → 0.6.3-canary.ee13359

package/authoring/doctypes/_schema.d.mts

@@ -25,7 +25,7 @@ export namespace AuthoredDocGraphFields {
         internal: "internal";
     }>>;
 }
-/** Runtime schema for every existing and V1 semantic content block. */
+/** Runtime schema for the stable content-block union published in 0.6.x. */
 export const ReferenceContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"prose">;
     text: z.ZodString;
@@ -55,6 +55,74 @@ export const ReferenceContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"token-ref">;
     topic: z.ZodString;
     section: z.ZodString;
+}, z.core.$strict>], "type">;
+/** Runtime schema for graph-only blocks used by NamespaceDoc. */
+export const GraphContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"workflow">;
+    title: z.ZodOptional<z.ZodString>;
+    steps: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        references: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"collection">;
+    title: z.ZodOptional<z.ZodString>;
+    source: z.ZodObject<{
+        slot: z.ZodString;
+    }, z.core.$strict>;
+    presentation: z.ZodOptional<z.ZodEnum<{
+        list: "list";
+        cards: "cards";
+        compact: "compact";
+    }>>;
+    whenEmpty: z.ZodOptional<z.ZodEnum<{
+        show: "show";
+        omit: "omit";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"reference">;
+    target: z.ZodString;
+    projection: z.ZodOptional<z.ZodObject<{
+        fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    presentation: z.ZodOptional<z.ZodEnum<{
+        compact: "compact";
+        summary: "summary";
+        full: "full";
+    }>>;
+}, z.core.$strict>], "type">;
+/** Namespace content accepts both stable reference blocks and graph-only blocks. */
+export const NamespaceContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"prose">;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"heading">;
+    level: z.ZodUnion<readonly [z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>]>;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"code">;
+    lang: z.ZodString;
+    code: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"table">;
+    headers: z.ZodArray<z.ZodString>;
+    rows: z.ZodArray<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"list">;
+    style: z.ZodEnum<{
+        ordered: "ordered";
+        unordered: "unordered";
+        do: "do";
+        dont: "dont";
+    }>;
+    items: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"token-ref">;
+    topic: z.ZodString;
+    section: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"workflow">;
     title: z.ZodOptional<z.ZodString>;
@@ -235,41 +303,6 @@ export const GenericDocKindSchema: z.ZodObject<{
             type: z.ZodLiteral<"token-ref">;
             topic: z.ZodString;
             section: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            type: z.ZodLiteral<"workflow">;
-            title: z.ZodOptional<z.ZodString>;
-            steps: z.ZodArray<z.ZodObject<{
-                title: z.ZodString;
-                description: z.ZodOptional<z.ZodString>;
-                references: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$strict>>;
-        }, z.core.$strict>, z.ZodObject<{
-            type: z.ZodLiteral<"collection">;
-            title: z.ZodOptional<z.ZodString>;
-            source: z.ZodObject<{
-                slot: z.ZodString;
-            }, z.core.$strict>;
-            presentation: z.ZodOptional<z.ZodEnum<{
-                list: "list";
-                cards: "cards";
-                compact: "compact";
-            }>>;
-            whenEmpty: z.ZodOptional<z.ZodEnum<{
-                show: "show";
-                omit: "omit";
-            }>>;
-        }, z.core.$strict>, z.ZodObject<{
-            type: z.ZodLiteral<"reference">;
-            target: z.ZodString;
-            projection: z.ZodOptional<z.ZodObject<{
-                fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$strict>>;
-            presentation: z.ZodOptional<z.ZodEnum<{
-                compact: "compact";
-                summary: "summary";
-                full: "full";
-            }>>;
         }, z.core.$strict>], "type">>;
         previewType: z.ZodOptional<z.ZodEnum<{
             swatch: "swatch";
@@ -351,41 +384,6 @@ export const SchemaDocKindSchema: z.ZodObject<{
         type: z.ZodLiteral<"token-ref">;
         topic: z.ZodString;
         section: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"workflow">;
-        title: z.ZodOptional<z.ZodString>;
-        steps: z.ZodArray<z.ZodObject<{
-            title: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
-            references: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"collection">;
-        title: z.ZodOptional<z.ZodString>;
-        source: z.ZodObject<{
-            slot: z.ZodString;
-        }, z.core.$strict>;
-        presentation: z.ZodOptional<z.ZodEnum<{
-            list: "list";
-            cards: "cards";
-            compact: "compact";
-        }>>;
-        whenEmpty: z.ZodOptional<z.ZodEnum<{
-            show: "show";
-            omit: "omit";
-        }>>;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"reference">;
-        target: z.ZodString;
-        projection: z.ZodOptional<z.ZodObject<{
-            fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
-        presentation: z.ZodOptional<z.ZodEnum<{
-            compact: "compact";
-            summary: "summary";
-            full: "full";
-        }>>;
     }, z.core.$strict>], "type">>>;
     placement: z.ZodOptional<z.ZodObject<{
         parent: z.ZodString;
@@ -470,41 +468,6 @@ export const CommandDocKindSchema: z.ZodObject<{
         type: z.ZodLiteral<"token-ref">;
         topic: z.ZodString;
         section: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"workflow">;
-        title: z.ZodOptional<z.ZodString>;
-        steps: z.ZodArray<z.ZodObject<{
-            title: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
-            references: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"collection">;
-        title: z.ZodOptional<z.ZodString>;
-        source: z.ZodObject<{
-            slot: z.ZodString;
-        }, z.core.$strict>;
-        presentation: z.ZodOptional<z.ZodEnum<{
-            list: "list";
-            cards: "cards";
-            compact: "compact";
-        }>>;
-        whenEmpty: z.ZodOptional<z.ZodEnum<{
-            show: "show";
-            omit: "omit";
-        }>>;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"reference">;
-        target: z.ZodString;
-        projection: z.ZodOptional<z.ZodObject<{
-            fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
-        presentation: z.ZodOptional<z.ZodEnum<{
-            compact: "compact";
-            summary: "summary";
-            full: "full";
-        }>>;
     }, z.core.$strict>], "type">>>;
     placement: z.ZodOptional<z.ZodObject<{
         parent: z.ZodString;
@@ -877,41 +840,6 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
             type: z.ZodLiteral<"token-ref">;
             topic: z.ZodString;
             section: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            type: z.ZodLiteral<"workflow">;
-            title: z.ZodOptional<z.ZodString>;
-            steps: z.ZodArray<z.ZodObject<{
-                title: z.ZodString;
-                description: z.ZodOptional<z.ZodString>;
-                references: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$strict>>;
-        }, z.core.$strict>, z.ZodObject<{
-            type: z.ZodLiteral<"collection">;
-            title: z.ZodOptional<z.ZodString>;
-            source: z.ZodObject<{
-                slot: z.ZodString;
-            }, z.core.$strict>;
-            presentation: z.ZodOptional<z.ZodEnum<{
-                list: "list";
-                cards: "cards";
-                compact: "compact";
-            }>>;
-            whenEmpty: z.ZodOptional<z.ZodEnum<{
-                show: "show";
-                omit: "omit";
-            }>>;
-        }, z.core.$strict>, z.ZodObject<{
-            type: z.ZodLiteral<"reference">;
-            target: z.ZodString;
-            projection: z.ZodOptional<z.ZodObject<{
-                fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                sections: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$strict>>;
-            presentation: z.ZodOptional<z.ZodEnum<{
-                compact: "compact";
-                summary: "summary";
-                full: "full";
-            }>>;
         }, z.core.$strict>], "type">>;
         previewType: z.ZodOptional<z.ZodEnum<{
             swatch: "swatch";
@@ -933,6 +861,7 @@ export type AuthoredDocGraphFieldsType = import("./base/type.js").AuthoredDocGra
 export type AuthoredDocKind = import("./base/type.js").AuthoredDocKind;
 export type NamespaceDoc = import("./namespace/type.js").NamespaceDoc;
 export type ReferenceContentBlock = import("./reference/type.js").ReferenceContentBlock;
+export type GraphContentBlock = import("./reference/type.js").GraphContentBlock;
 export type ReferenceDoc = import("./reference/type.js").ReferenceDoc;
 export type SingleComponentDoc = import("./component/type.js").SingleComponentDoc;
 export type ComponentPropDoc = import("./base/type.js").ComponentPropDoc;
@@ -944,6 +873,7 @@ export type EnumDoc = import("./enum/type.js").EnumDoc;
 export type _AuthoredDocKindDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof AuthoredDocKindSchema>, AuthoredDocKind>>;
 export type _AuthoredDocGraphDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof _AuthoredDocGraphSchema>, AuthoredDocGraphFieldsType>>;
 export type _ReferenceContentBlockDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof ReferenceContentBlockSchema>, ReferenceContentBlock>>;
+export type _GraphContentBlockDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof GraphContentBlockSchema>, GraphContentBlock>>;
 /**
  * A stamped component doc as it loads. The loader accepts what the unstamped
  * format always accepted, so stamping an existing doc never breaks it:

package/authoring/doctypes/_schema.mjs

@@ -15,6 +15,7 @@ import {z} from 'zod';
 /** @typedef {import('./base/type.js').AuthoredDocKind} AuthoredDocKind */
 /** @typedef {import('./namespace/type.js').NamespaceDoc} NamespaceDoc */
 /** @typedef {import('./reference/type.js').ReferenceContentBlock} ReferenceContentBlock */
+/** @typedef {import('./reference/type.js').GraphContentBlock} GraphContentBlock */
 /** @typedef {import('./reference/type.js').ReferenceDoc} ReferenceDoc */
 /** @typedef {import('./component/type.js').SingleComponentDoc} SingleComponentDoc */
 /** @typedef {import('./base/type.js').ComponentPropDoc} ComponentPropDoc */
@@ -161,7 +162,7 @@ const ReferenceBlockSchema = z
   })
   .strict();
 
-/** Runtime schema for every existing and V1 semantic content block. */
+/** Runtime schema for the stable content-block union published in 0.6.x. */
 export const ReferenceContentBlockSchema = z.discriminatedUnion('type', [
   ProseBlockSchema,
   HeadingBlockSchema,
@@ -169,6 +170,23 @@ export const ReferenceContentBlockSchema = z.discriminatedUnion('type', [
   TableBlockSchema,
   ListBlockSchema,
   TokenReferenceBlockSchema,
+]);
+
+/** Runtime schema for graph-only blocks used by NamespaceDoc. */
+export const GraphContentBlockSchema = z.discriminatedUnion('type', [
+  WorkflowBlockSchema,
+  CollectionBlockSchema,
+  ReferenceBlockSchema,
+]);
+
+/** Namespace content accepts both stable reference blocks and graph-only blocks. */
+export const NamespaceContentBlockSchema = z.discriminatedUnion('type', [
+  ProseBlockSchema,
+  HeadingBlockSchema,
+  CodeBlockSchema,
+  TableBlockSchema,
+  ListBlockSchema,
+  TokenReferenceBlockSchema,
   WorkflowBlockSchema,
   CollectionBlockSchema,
   ReferenceBlockSchema,
@@ -183,6 +201,15 @@ export const ReferenceContentBlockSchema = z.discriminatedUnion('type', [
  * >} _ReferenceContentBlockDriftLock
  */
 
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<
+ *     z.infer<typeof GraphContentBlockSchema>,
+ *     GraphContentBlock
+ *   >
+ * >} _GraphContentBlockDriftLock
+ */
+
 const ReferenceSectionSchema = z
   .object({
     id: nonEmptyString.optional(),
@@ -605,7 +632,7 @@ export const NamespaceDocKindSchema = z
           .strict(),
       )
       .optional(),
-    blocks: z.array(ReferenceContentBlockSchema).optional(),
+    blocks: z.array(NamespaceContentBlockSchema).optional(),
   })
   .strict()
   .superRefine((doc, context) => {

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

@@ -12,25 +12,27 @@ export const doc = {
   displayName: 'Authored doc graph fields',
   namespace: 'authoring',
   description:
-    'Placement, compatibility aliases, and audience: fields every authored doc kind declares for the docs graph. The docs graph is not built yet, so nothing reads them: a reference topic 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: [
     {
       name: 'placement',
       type: 'DocPlacement',
       description:
-        'Requests one canonical parent in the docs graph. Not read yet: a topic that sets it fails to load.',
+        "Names the doc's one parent in the docs tree: a namespace of the same package, one of its slots, and an order. Read for every guide, the CLI's and each integration's: a guide with `placement` gets a route in the tree instead of a flat topic name, and cannot also `replaces` or `extends` a topic. In the CLI's own topic directory a topic that sets it fails to load: the CLI keeps its guides in its docs tree directory. Commands, API functions, schemas, and enums do not set it: the tree adopts each by its `namespace`.",
       fields: [
         {
           name: 'placement.parent',
           type: 'string',
-          description: 'Stable reference to the requested parent namespace.',
+          description:
+            'The parent namespace: `namespace:<name>` in the same package.',
           required: true,
         },
         {
           name: 'placement.slot',
           type: 'string',
-          description: 'Named slot owned by the parent namespace.',
+          description:
+            "A slot the parent namespace declares; it must accept this doc's kind. Optional when the parent has one slot.",
         },
         {
           name: 'placement.order',
@@ -43,7 +45,7 @@ export const doc = {
       name: 'aliases',
       type: 'string[]',
       description:
-        'Prior names or routes the docs graph will keep resolving to this doc, without creating another identity. Not read yet: 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',
@@ -56,7 +58,7 @@ export const doc = {
   notes: [
     {
       type: 'prose',
-      text: 'Unknown fields: `component`, `function`, `generic`, `schema`, `command` and `enum` docs accept a field they do not know, and nothing reads it, so a doc written for a newer CLI still loads here. `page`, `block` and `namespace` docs refuse one. Sections and content blocks refuse one in every doc.',
+      text: 'Unknown fields: `component`, `function`, `generic`, `schema`, `command` and `enum` docs accept a field they do not know, and nothing reads it, so a doc written for a newer CLI still loads here. `page`, `block` and `namespace` docs refuse one, as do `theme` descriptors. Sections and content blocks refuse one in every doc.',
     },
   ],
 };

package/authoring/doctypes/base/type.ts

@@ -31,14 +31,15 @@ export interface DocPlacement {
 }
 
 /**
- * Graph metadata shared by every authored doc kind. Reserved for the docs
- * graph, which is not built yet: nothing reads these fields, and a reference
- * topic that sets one fails to load.
+ * Tree metadata shared by every authored doc kind. The docs tree reads
+ * `placement` for every guide, the CLI's and each integration's
+ * (spec:AST-046); nothing reads `aliases` or `audience` yet. A reference topic
+ * outside the docs tree that sets one fails to load.
  */
 export interface AuthoredDocGraphFields {
-  /** Requested canonical parent in the docs graph. Not read yet. */
+  /** The doc's one parent in the docs tree: a namespace of its own package. */
   placement?: DocPlacement;
-  /** Prior routes or names the docs graph will keep resolving. Not read yet. */
+  /** Prior routes or names the docs tree will keep resolving. Not read yet. */
   aliases?: string[];
   /** Docs bundle audience; omit for public docs. Not read yet. */
   audience?: DocAudience;

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

@@ -54,7 +54,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "Docs namespace path. Defaults to 'cli' when applied by the docs index.",
+        "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's commands use 'cli/commands', which the docs tree adopts: each is the leaf `cli/commands/<name>`. Every command doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',

package/authoring/doctypes/command/type.ts

@@ -65,7 +65,7 @@ export interface CommandDoc extends AuthoredDocGraphFields {
   summary: string;
   /** Longer help body / when-to-use. */
   description?: string;
-  /** Docs namespace path. Defaults to 'cli' when applied by the docs index. */
+  /** The group that reads this doc. The CLI's commands use 'cli/commands', which the docs tree adopts: each is the leaf `cli/commands/<name>`. Every command doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads. */
   namespace?: string;
   /** Alternate slugs that also resolve to this doc. */
   aliases?: string[];
@@ -81,7 +81,7 @@ export interface CommandDoc extends AuthoredDocGraphFields {
   examples?: CommandExampleDoc[];
   /** Documented exit codes. */
   exitCodes?: {code: number; when: string}[];
-  /** Related command names. */
+  /** Related command names; the CLI links each to its doc. */
   related?: string[];
   /** Freeform prose/notes. */
   notes?: ReferenceContentBlock[];

package/authoring/doctypes/component/type.ts

@@ -146,10 +146,10 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {
 /**
  * The documentation type for a component directory's {Name}.doc.mjs file.
  *
- * Every .doc.mjs must export a single `docs` constant of this type:
+ * Every new .doc.mjs default-exports a stamped object of this type:
  *
  *   /\*\* \@type \{import('@astryxdesign/cli/authoring').ComponentDoc\} *\/
- *   export const docs = \{ ... \};
+ *   export default \{ type: 'component', ... \};
  *
  * Use SingleComponentDoc (with `props`) for single-component directories.
  * Use MultiComponentDoc (with `components`) for multi-component directories.

package/authoring/doctypes/doctypes-new.test.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Tests for the new authoring doc-types (schema/command/enum) and the
+ * @file Tests for the new authoring doc-types (schema/command/enum/theme) and the
  * generalized `function` doc (hooks + CLI/API functions sharing the schema).
  */
 
@@ -12,6 +12,7 @@ import {
   parseCommand,
   parseEnum,
   parseFunction,
+  parseTheme,
 } from '../index.mjs';
 
 describe('SchemaDoc', () => {
@@ -22,13 +23,21 @@ describe('SchemaDoc', () => {
     description: 'Project config.',
     appliesTo: 'astryx.config.{ts,mjs,js}',
     fields: [
-      {name: 'integrations', type: 'string[]', description: 'Packages to load.'},
+      {
+        name: 'integrations',
+        type: 'string[]',
+        description: 'Packages to load.',
+      },
       {
         name: 'hooks',
         type: 'object',
         description: 'Lifecycle hooks.',
         fields: [
-          {name: 'hooks.postCodemod', type: 'PostCodemodHook[]', description: 'Runs after codemods.'},
+          {
+            name: 'hooks.postCodemod',
+            type: 'PostCodemodHook[]',
+            description: 'Runs after codemods.',
+          },
         ],
       },
     ],
@@ -63,8 +72,16 @@ describe('CommandDoc', () => {
     fn: 'search',
     args: [{name: 'query', param: 'query', required: true}],
     options: [
-      {flag: '--type <domain>', param: 'options.type', choices: ['component', 'hook']},
-      {flag: '--json', cliOnly: true, description: 'Emit the typed JSON envelope.'},
+      {
+        flag: '--type <domain>',
+        param: 'options.type',
+        choices: ['component', 'hook'],
+      },
+      {
+        flag: '--json',
+        cliOnly: true,
+        description: 'Emit the typed JSON envelope.',
+      },
     ],
     examples: [{label: 'Terminal', cli: 'astryx search button --json'}],
     exitCodes: [{code: 1, when: 'invalid --type'}],
@@ -90,6 +107,29 @@ describe('EnumDoc', () => {
   });
 });
 
+describe('ThemeDoc', () => {
+  const doc = {
+    type: 'theme',
+    name: 'ocean',
+    displayName: 'Ocean',
+    description: 'Cool blue surfaces with crisp contrast.',
+    maintained: true,
+  };
+
+  it('accepts a complete theme descriptor and dispatches through parseDoc', () => {
+    expect(parseTheme(doc)).toEqual(doc);
+    expect(parseDoc(doc)).toEqual(doc);
+  });
+
+  it('rejects non-kebab identity and missing required metadata', () => {
+    expect(() => parseTheme({...doc, name: 'OceanTheme'})).toThrow(
+      /lowercase kebab-case/,
+    );
+    const {maintained: _maintained, ...missingMaintained} = doc;
+    expect(() => parseTheme(missingMaintained)).toThrow(/maintained/);
+  });
+});
+
 describe('generalized FunctionDoc', () => {
   it('accepts an API function whose returns are envelope entries (no field name)', () => {
     const apiFn = {
@@ -98,7 +138,9 @@ describe('generalized FunctionDoc', () => {
       name: 'search',
       displayName: 'search()',
       importPath: '@astryxdesign/cli/api',
-      params: [{name: 'query', type: 'string', description: 'Term.', required: true}],
+      params: [
+        {name: 'query', type: 'string', description: 'Term.', required: true},
+      ],
       returns: [{type: 'search', description: 'query + ranked results[]'}],
       throws: [{code: 'ERR_INVALID_ARGUMENT', when: 'empty query'}],
     };

package/authoring/doctypes/enum/enum.doc.mjs

@@ -49,7 +49,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "Docs namespace path. Defaults to 'cli' when applied by the docs index.",
+        "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's enums use 'cli/api', which the docs tree adopts by kind: each is the leaf `cli/api/enums/<name>`. Every enum doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',

package/authoring/doctypes/enum/type.ts

@@ -32,7 +32,7 @@ export interface EnumDoc extends AuthoredDocGraphFields {
   displayName: string;
   /** One-line summary shown in listings. */
   description: string;
-  /** Docs namespace path. Defaults to 'cli' when applied by the docs index. */
+  /** The group that reads this doc. The CLI's enums use 'cli/api', which the docs tree adopts by kind: each is the leaf `cli/api/enums/<name>`. Every enum doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads. */
   namespace?: string;
   /** Alternate slugs that also resolve to this doc. */
   aliases?: string[];

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.",
+        "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's API functions use 'cli/api', which the docs tree adopts by kind: each is the leaf `cli/api/functions/<name>`. Every function doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',
@@ -201,7 +201,8 @@ export const doc = {
     {
       name: 'related',
       type: 'string[]',
-      description: 'Related function/command names.',
+      description:
+        'Related function names; the CLI links each to its doc. Name the CLI command with `command`, not here.',
     },
     {
       name: 'relatedComponents',

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 group that reads this doc. The CLI's API functions use 'cli/api', which the docs tree adopts by kind: each is the leaf `cli/api/functions/<name>`. Every function doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads. */
   namespace?: string;
   /** Alternate slugs that also resolve to this doc. */
   aliases?: string[];
@@ -84,7 +84,8 @@ export interface FunctionDoc extends AuthoredDocGraphFields {
   usage?: UsageDoc;
   /** The CLI command that wraps this function, e.g. 'search'. */
   command?: string;
-  /** Related function/command names. */
+  /** Related function names; the CLI links each to its doc. Name the CLI
+   *  command with `command`, not here. */
   related?: string[];
   /** Component names this is commonly used with (hooks). */
   relatedComponents?: 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,
     );
   });
 });