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

package/authoring/doctypes/_schema.d.mts

@@ -1,16 +1,172 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** New-format stamped component doc (`type: 'component'`). */
+/** Every authored doc-kind discriminant accepted by parseDoc. */
+export const AuthoredDocKindSchema: z.ZodEnum<{
+    function: "function";
+    component: "component";
+    generic: "generic";
+    page: "page";
+    block: "block";
+    schema: "schema";
+    command: "command";
+    enum: "enum";
+    namespace: "namespace";
+}>;
+export namespace AuthoredDocGraphFields {
+    let placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    let aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    let audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
+}
+/** 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;
+}, 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>], "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>;
+    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">;
+/**
+ * New-format stamped component doc (`type: 'component'`): one component's
+ * `props`, or the `components` a group doc documents together. These are the
+ * shapes the published ComponentDoc type allows, and the ones an unstamped doc
+ * may already take.
+ */
 export const ComponentDocKindSchema: z.ZodObject<{
     type: z.ZodLiteral<"component">;
-    props: z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        type: z.ZodString;
-        description: z.ZodString;
-        default: z.ZodOptional<z.ZodString>;
-        required: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$loose>>;
     theming: z.ZodOptional<z.ZodUnknown>;
     playground: z.ZodOptional<z.ZodUnknown>;
     examples: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
@@ -26,9 +182,28 @@ export const ComponentDocKindSchema: z.ZodObject<{
     relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     hidden: z.ZodOptional<z.ZodBoolean>;
     isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
+    props: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+        description: z.ZodString;
+        default: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>>;
+    components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;
-/** New-format stamped function doc (`type: 'function'`) — hooks and CLI/API
- *  functions alike (the discriminant and schema are shared). */
+/** New-format stamped function doc (`type: 'function'`). */
 export const FunctionDocKindSchema: z.ZodObject<{
     type: z.ZodLiteral<"function">;
     params: z.ZodArray<z.ZodObject<{
@@ -55,12 +230,95 @@ export const FunctionDocKindSchema: z.ZodObject<{
     relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     hidden: z.ZodOptional<z.ZodBoolean>;
     isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
 }, z.core.$loose>;
-/** New-format stamped generic reference/topic doc (`type: 'generic'`). */
+/**
+ * A stamped function doc as it loads: as with components, `displayName` may be
+ * missing and `usage` passes through unchecked.
+ *
+ * @typedef {Omit<FunctionDoc, 'type' | 'displayName' | 'usage'>
+ *   & {type: 'function', displayName?: string, usage?: unknown}} LoadedFunctionDoc
+ */
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<
+ *     import('../_shared/contract.js').NamedFields<z.infer<typeof FunctionDocKindSchema>>,
+ *     import('../_shared/contract.js').NamedFields<LoadedFunctionDoc>
+ *   >
+ * >} _FunctionDocDriftLock
+ */
+/**
+ * Every HookDoc is a FunctionDoc, so the one function schema covers both.
+ *
+ * @typedef {import('../_shared/contract.js').Expect<[HookDoc] extends [FunctionDoc] ? true : false>} _HookDocIsFunctionDocLock
+ */
+/**
+ * Stamped generic reference/topic doc (`type: 'generic'`). `title` and
+ * `sections` stay optional at this parser boundary for docs produced by the
+ * shipped v0.3.0 factory-removal codemod. When present, all rich fields and
+ * semantic blocks are validated.
+ */
 export const GenericDocKindSchema: z.ZodObject<{
     type: z.ZodLiteral<"generic">;
+    title: z.ZodOptional<z.ZodString>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        category: z.ZodOptional<z.ZodString>;
+        content: z.ZodArray<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>], "type">>;
+        previewType: z.ZodOptional<z.ZodEnum<{
+            swatch: "swatch";
+            "shadow-box": "shadow-box";
+            "radius-box": "radius-box";
+            "spacing-bar": "spacing-bar";
+            "size-bar": "size-bar";
+            "border-line": "border-line";
+            "duration-bar": "duration-bar";
+            "easing-curve": "easing-curve";
+            "font-sample": "font-sample";
+        }>>;
+    }, z.core.$strict>>>;
     replaces: z.ZodOptional<z.ZodString>;
     extends: z.ZodOptional<z.ZodString>;
+    tokenCategory: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     displayName: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
@@ -73,25 +331,80 @@ export const GenericDocKindSchema: z.ZodObject<{
     relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     hidden: z.ZodOptional<z.ZodBoolean>;
     isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
 }, z.core.$loose>;
-/** New stamped schema doc (`type: 'schema'`) — documents an authored object. */
+/** New stamped schema doc (`type: 'schema'`). */
 export const SchemaDocKindSchema: z.ZodObject<{
     type: z.ZodLiteral<"schema">;
     name: z.ZodString;
     displayName: z.ZodString;
     description: z.ZodString;
     namespace: z.ZodOptional<z.ZodString>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
     appliesTo: z.ZodOptional<z.ZodString>;
-    fields: z.ZodArray<z.ZodType<import("./schema/type").SchemaFieldDoc, any, z.core.$ZodTypeInternals<import("./schema/type").SchemaFieldDoc, any>>>;
+    fields: z.ZodArray<z.ZodType<import("./schema/type.js").SchemaFieldDoc, any, z.core.$ZodTypeInternals<import("./schema/type.js").SchemaFieldDoc, any>>>;
     examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
         label: z.ZodOptional<z.ZodString>;
         code: z.ZodString;
     }, z.core.$loose>>>;
-    notes: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    notes: z.ZodOptional<z.ZodArray<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>], "type">>>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
 }, z.core.$loose>;
-/** New stamped command doc (`type: 'command'`) — a function's terminal binding;
- *  references a FunctionDoc via `fn`. */
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<
+ *     import('../_shared/contract.js').NamedFields<z.infer<typeof SchemaDocKindSchema>>,
+ *     import('../_shared/contract.js').NamedFields<SchemaDoc & {type: 'schema'}>
+ *   >
+ * >} _SchemaDocDriftLock
+ */
+/** New stamped command doc (`type: 'command'`). */
 export const CommandDocKindSchema: z.ZodObject<{
     type: z.ZodLiteral<"command">;
     name: z.ZodString;
@@ -99,7 +412,6 @@ export const CommandDocKindSchema: z.ZodObject<{
     summary: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     namespace: z.ZodOptional<z.ZodString>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
     fn: z.ZodOptional<z.ZodString>;
     args: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -127,24 +439,200 @@ export const CommandDocKindSchema: z.ZodObject<{
         when: z.ZodString;
     }, z.core.$loose>>>;
     related: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    notes: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    notes: z.ZodOptional<z.ZodArray<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>], "type">>>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
 }, z.core.$loose>;
-/** New stamped enum doc (`type: 'enum'`) — a closed vocabulary (error codes,
- *  response-type discriminants). */
+/**
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<
+ *     import('../_shared/contract.js').NamedFields<z.infer<typeof CommandDocKindSchema>>,
+ *     import('../_shared/contract.js').NamedFields<CommandDoc & {type: 'command'}>
+ *   >
+ * >} _CommandDocDriftLock
+ */
+/** New stamped enum doc (`type: 'enum'`). */
 export const EnumDocKindSchema: z.ZodObject<{
     type: z.ZodLiteral<"enum">;
     name: z.ZodString;
     displayName: z.ZodString;
     description: z.ZodString;
     namespace: z.ZodOptional<z.ZodString>;
-    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
     members: z.ZodArray<z.ZodObject<{
         value: z.ZodString;
         description: z.ZodString;
         deprecated: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
 }, z.core.$loose>;
-/** The permissive legacy union (sub-component first, then hook, multi, single). */
+/** The one new authored doctype: a hierarchy and layout owner. */
+export const NamespaceDocKindSchema: z.ZodObject<{
+    type: z.ZodLiteral<"namespace">;
+    name: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodString;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    slots: z.ZodRecord<z.ZodString, z.ZodObject<{
+        title: z.ZodString;
+        accepts: z.ZodObject<{
+            kinds: z.ZodArray<z.ZodEnum<{
+                function: "function";
+                component: "component";
+                generic: "generic";
+                page: "page";
+                block: "block";
+                schema: "schema";
+                command: "command";
+                enum: "enum";
+                namespace: "namespace";
+            }>>;
+            providers: z.ZodOptional<z.ZodEnum<{
+                same: "same";
+                configured: "configured";
+            }>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    adopts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        source: z.ZodObject<{
+            group: z.ZodString;
+            kinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                function: "function";
+                component: "component";
+                generic: "generic";
+                page: "page";
+                block: "block";
+                schema: "schema";
+                command: "command";
+                enum: "enum";
+                namespace: "namespace";
+            }>>>;
+        }, z.core.$strict>;
+        into: z.ZodString;
+        groupBy: z.ZodOptional<z.ZodLiteral<"kind">>;
+    }, z.core.$strict>>>;
+    blocks: z.ZodOptional<z.ZodArray<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>;
+        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;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
+}, z.core.$strict>;
+/** The permissive legacy union (sub-component, hook, multi, single, then reference). */
 export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     name: z.ZodString;
     displayName: z.ZodOptional<z.ZodString>;
@@ -163,6 +651,16 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
     subComponentOf: z.ZodString;
     description: z.ZodString;
     props: z.ZodArray<z.ZodObject<{
@@ -191,6 +689,16 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
     params: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         type: z.ZodString;
@@ -222,6 +730,16 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
     components: z.ZodArray<z.ZodUnknown>;
 }, z.core.$loose>, z.ZodObject<{
     name: z.ZodString;
@@ -242,6 +760,16 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
     relatedHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
     props: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         type: z.ZodString;
@@ -249,5 +777,172 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
         default: z.ZodOptional<z.ZodString>;
         required: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
+}, z.core.$loose>, z.ZodObject<{
+    name: z.ZodString;
+    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>>;
+    usage: z.ZodOptional<z.ZodUnknown>;
+    playground: z.ZodOptional<z.ZodUnknown>;
+    theming: z.ZodOptional<z.ZodUnknown>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    showcase: z.ZodOptional<z.ZodUnknown>;
+    parent: z.ZodOptional<z.ZodString>;
+    relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relatedHooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
+    title: z.ZodString;
+    description: z.ZodString;
+    sections: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        category: z.ZodOptional<z.ZodString>;
+        content: z.ZodArray<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>], "type">>;
+        previewType: z.ZodOptional<z.ZodEnum<{
+            swatch: "swatch";
+            "shadow-box": "shadow-box";
+            "radius-box": "radius-box";
+            "spacing-bar": "spacing-bar";
+            "size-bar": "size-bar";
+            "border-line": "border-line";
+            "duration-bar": "duration-bar";
+            "easing-curve": "easing-curve";
+            "font-sample": "font-sample";
+        }>>;
+    }, z.core.$strict>>;
+    replaces: z.ZodOptional<z.ZodString>;
+    extends: z.ZodOptional<z.ZodString>;
+    tokenCategory: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>]>;
+export type AuthoredDocGraphFieldsType = import("./base/type.js").AuthoredDocGraphFields;
+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;
+export type HookDoc = import("./hook/type.js").HookDoc;
+export type FunctionDoc = import("./function/type.js").FunctionDoc;
+export type SchemaDoc = import("./schema/type.js").SchemaDoc;
+export type CommandDoc = import("./command/type.js").CommandDoc;
+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:
+ * `displayName` may be missing, `category` is any string, `usage`, `theming`,
+ * `playground` and `examples` pass through unchecked, and a doc has `props`,
+ * `components`, or both; each `components` entry needs only a `name`. Every
+ * other field matches the published type.
+ */
+export type LoadedComponentDoc = Omit<SingleComponentDoc, "type" | "displayName" | "category" | "usage" | "theming" | "examples" | "playground" | "props"> & {
+    type: "component";
+    displayName?: string;
+    category?: string;
+    usage?: unknown;
+    theming?: unknown;
+    examples?: unknown[];
+    playground?: unknown;
+    props?: ComponentPropDoc[];
+    components?: Array<{
+        name: string;
+    }>;
+};
+export type _ComponentDocDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<import("../_shared/contract.js").NamedFields<z.infer<typeof ComponentDocKindSchema>>, import("../_shared/contract.js").NamedFields<LoadedComponentDoc>>>;
+/**
+ * A stamped function doc as it loads: as with components, `displayName` may be
+ * missing and `usage` passes through unchecked.
+ */
+export type LoadedFunctionDoc = Omit<FunctionDoc, "type" | "displayName" | "usage"> & {
+    type: "function";
+    displayName?: string;
+    usage?: unknown;
+};
+export type _FunctionDocDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<import("../_shared/contract.js").NamedFields<z.infer<typeof FunctionDocKindSchema>>, import("../_shared/contract.js").NamedFields<LoadedFunctionDoc>>>;
+/**
+ * Every HookDoc is a FunctionDoc, so the one function schema covers both.
+ */
+export type _HookDocIsFunctionDocLock = import("../_shared/contract.js").Expect<[HookDoc] extends [FunctionDoc] ? true : false>;
+/**
+ * A stamped generic doc as the load check accepts it. `title`, `description`
+ * and `sections` may be missing, as in docs the v0.3.0 factory-removal codemod
+ * produced; `parseReference` then fills them (title from `displayName` or
+ * `name`, an empty description, no sections), so its result is a full
+ * ReferenceDoc. Only a doc with a description and sections is a usable topic
+ * (see `problemsInTopic`).
+ */
+export type LoadedReferenceDoc = Omit<ReferenceDoc, "type" | "title" | "description" | "sections"> & {
+    type: "generic";
+} & Partial<Pick<ReferenceDoc, "title" | "description" | "sections">>;
+export type _ReferenceDocDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<import("../_shared/contract.js").NamedFields<z.infer<typeof GenericDocKindSchema>>, import("../_shared/contract.js").NamedFields<LoadedReferenceDoc>>>;
+export type _SchemaDocDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<import("../_shared/contract.js").NamedFields<z.infer<typeof SchemaDocKindSchema>>, import("../_shared/contract.js").NamedFields<SchemaDoc & {
+    type: "schema";
+}>>>;
+export type _CommandDocDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<import("../_shared/contract.js").NamedFields<z.infer<typeof CommandDocKindSchema>>, import("../_shared/contract.js").NamedFields<CommandDoc & {
+    type: "command";
+}>>>;
+export type _EnumDocDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<import("../_shared/contract.js").NamedFields<z.infer<typeof EnumDocKindSchema>>, import("../_shared/contract.js").NamedFields<EnumDoc & {
+    type: "enum";
+}>>>;
+export type _NamespaceDocDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof NamespaceDocKindSchema>, NamespaceDoc>>;
 import { z } from 'zod';
+declare const _AuthoredDocGraphSchema: z.ZodObject<{
+    placement: z.ZodOptional<z.ZodObject<{
+        parent: z.ZodString;
+        slot: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        public: "public";
+        internal: "internal";
+    }>>;
+}, z.core.$strict>;
+export {};