@astryxdesign/cli 0.6.3-canary.35a722f → 0.6.3-canary.395846b

package/api/docs/detail/section/section.mjs

@@ -4,9 +4,9 @@
  * @file docs.detail.section leaf — load a single section of a topic.
  *
  * @input A topic name, a section query, and optional {lang, zh, dense}. Resolves
- *   the topic via the shared adapter, keeps the 0.6.x first title-substring
- *   match, then falls back to a stable key or normalized title key, and links
- *   only that section.
+ *   the topic via the shared adapter, finds the section in its lowered compiled
+ *   node by its stable key, then by exact title, then by a title that contains
+ *   the query, and links only that section.
  * @output { type: 'docs.detail.section', data: ReferenceSection } with any
  *   token-ref blocks inlined — matching `astryx --json docs <topic> <section>`.
  *   Throws ERR_UNKNOWN_SECTION when nothing matches, or when the query matches
@@ -17,7 +17,10 @@
 
 import {AstryxError} from '../../../error.mjs';
 import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
-import {findDocSection} from '../../../../foundation/discovery/docs-section-key.mjs';
+import {
+  findDocSection,
+  sectionKey,
+} from '../../../../foundation/discovery/docs-section-key.mjs';
 import {linkReferenceSection} from '../../../../foundation/doc-compiler/compile.mjs';
 import {
   readerSections,
@@ -49,13 +52,16 @@ export async function section(topic, sectionName, options = {}) {
 
   const {catalog, node, lang} = await resolveTopicDocs(topic, options);
   const sections = readerSections(node);
-  const {section: match} = findDocSection(sections, sectionName);
+  const {section: match, candidates} = findDocSection(sections, sectionName);
   if (!match) {
+    const ambiguous = candidates.length > 1;
     throw new AstryxError(
-      `Section "${sectionName}" not found in "${topic}"`,
-      sections.map(s => ({
-        name: s.title,
-        reason: 'available section',
+      ambiguous
+        ? `Section "${sectionName}" matches ${candidates.length} sections in "${topic}". Read one by its key.`
+        : `Section "${sectionName}" not found in "${topic}"`,
+      (ambiguous ? candidates : sections).map(s => ({
+        name: sectionKey(s),
+        reason: s.title,
       })),
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );

package/api/docs/detail/section/section.test.mjs

@@ -30,17 +30,6 @@ describe('docs.detail.section leaf', () => {
     }
     expect(err).toBeInstanceOf(AstryxError);
     expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    expect(err.suggestions).toEqual(
-      expect.arrayContaining([
-        expect.objectContaining({
-          name: expect.any(String),
-          reason: 'available section',
-        }),
-      ]),
-    );
-    expect(err.suggestions.some(suggestion => /\s/u.test(suggestion.name))).toBe(
-      true,
-    );
   }, SLOW);
 
   it('does not return the first section for an empty section name', async () => {
@@ -61,10 +50,12 @@ describe('docs.detail.section leaf', () => {
     expect(res.data.id).toBe(target.id);
   }, SLOW);
 
-  it('keeps a previously accepted ambiguous query on its first match', async () => {
-    const res = await section('theme', 'e');
-    expect(res.type).toBe('docs.detail.section');
-    expect(res.data).toBeDefined();
+  it('refuses a query that matches more than one section', async () => {
+    const err = await section('theme', 'e').catch(e => e);
+    expect(err).toBeInstanceOf(AstryxError);
+    expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+    expect(err.message).toMatch(/matches \d+ sections/);
+    expect(err.suggestions.length).toBeGreaterThan(1);
   }, SLOW);
 
   it.each([null, 'zh', 'dense'])(

package/api/doctor/doctor.mjs

@@ -994,7 +994,7 @@ export async function checkDocsProgressiveDisclosure(ctx) {
     return {
       id,
       label,
-      status: 'warn',
+      status: 'fail',
       message: joinProblems(problems),
       fix: 'Fix the doc each problem names; split a section that is too large into smaller ones, each with its own key.',
     };

package/api/doctor/doctor.test.mjs

@@ -391,7 +391,7 @@ describe('checkDocsProgressiveDisclosure', () => {
     expect(c.message).toMatch(/^\d+ topics: /);
   }, SLOW);
 
-  it('warns on an invalid doc an integration contributed', async () => {
+  it('fails on an invalid doc an integration contributed', async () => {
     const c = await checkDocsProgressiveDisclosure({
       docsCatalogIssues: [
         {
@@ -402,13 +402,13 @@ describe('checkDocsProgressiveDisclosure', () => {
         },
       ],
     });
-    expect(c.status).toBe('warn');
+    expect(c.status).toBe('fail');
     expect(c.message).toBe('@acme/widgets: bad.doc.mjs exports no doc');
   });
 
-  it('warns when the docs catalog cannot be built', async () => {
+  it('fails when the docs catalog cannot be built', async () => {
     const c = await checkDocsProgressiveDisclosure({docsCatalogError: 'boom'});
-    expect(c.status).toBe('warn');
+    expect(c.status).toBe('fail');
     expect(c.message).toContain('boom');
   });
 
@@ -436,7 +436,7 @@ describe('checkDocsProgressiveDisclosure', () => {
       }),
       docsCatalogIssues: [],
     });
-    expect(c.status).toBe('warn');
+    expect(c.status).toBe('fail');
     expect(c.message).toMatch(/^2 problems: /);
     expect(c.message).toContain('huge everything: 41 KB, over the 32 KB one read may return');
     expect(c.message).toContain('broken: ');
@@ -812,7 +812,7 @@ describe('checkDocsProgressiveDisclosure languages', () => {
       docsCatalog: DocsCatalog.fromBuiltins({deploying: path.join(dir, 'deploying.doc.mjs')}),
       docsCatalogIssues: [],
     });
-    expect(c.status).toBe('warn');
+    expect(c.status).toBe('fail');
     expect(c.message).toContain('deploying [zh]: zh overlay broken');
     expect(c.message).toContain('deploying [dense] overview: 41 KB');
     expect(c.message).not.toMatch(/deploying overview:/);

package/authoring/doctypes/_schema.d.mts

@@ -25,7 +25,7 @@ export namespace AuthoredDocGraphFields {
         internal: "internal";
     }>>;
 }
-/** Runtime schema for the stable content-block union published in 0.6.x. */
+/** Runtime schema for every existing and V1 semantic content block. */
 export const ReferenceContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"prose">;
     text: z.ZodString;
@@ -55,74 +55,6 @@ 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>;
@@ -303,6 +235,41 @@ 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";
@@ -384,6 +351,41 @@ 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;
@@ -468,6 +470,41 @@ 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;
@@ -840,6 +877,41 @@ 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";
@@ -861,7 +933,6 @@ 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;
@@ -873,7 +944,6 @@ 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,7 +15,6 @@ 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 */
@@ -162,7 +161,7 @@ const ReferenceBlockSchema = z
   })
   .strict();
 
-/** Runtime schema for the stable content-block union published in 0.6.x. */
+/** Runtime schema for every existing and V1 semantic content block. */
 export const ReferenceContentBlockSchema = z.discriminatedUnion('type', [
   ProseBlockSchema,
   HeadingBlockSchema,
@@ -170,23 +169,6 @@ 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,
@@ -201,15 +183,6 @@ export const NamespaceContentBlockSchema = 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(),
@@ -632,7 +605,7 @@ export const NamespaceDocKindSchema = z
           .strict(),
       )
       .optional(),
-    blocks: z.array(NamespaceContentBlockSchema).optional(),
+    blocks: z.array(ReferenceContentBlockSchema).optional(),
   })
   .strict()
   .superRefine((doc, context) => {

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

@@ -71,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(
-      /x\.doc\.mjs is invalid/u,
+      /unsupported type "widget"/,
     );
   });
 });

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

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

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

@@ -134,30 +134,32 @@ describe('NamespaceDoc', () => {
   });
 });
 
-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);
+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',
+    ]);
   });
 
-  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: [],
-    });
+  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,
+    );
   });
 });

package/authoring/doctypes/namespace/type.ts

@@ -7,10 +7,7 @@
  */
 
 import type {AuthoredDocGraphFields, AuthoredDocKind} from '../base/type.js';
-import type {
-  GraphContentBlock,
-  ReferenceContentBlock,
-} from '../reference/type.js';
+import type {ReferenceContentBlock} from '../reference/type.js';
 
 /** Which providers may contribute appearances to a namespace slot. */
 export type NamespaceProviderScope = 'same' | 'configured';
@@ -70,5 +67,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 | GraphContentBlock)[];
+  blocks?: ReferenceContentBlock[];
 }

package/authoring/doctypes/parse.mjs

@@ -67,9 +67,8 @@ export function parseDoc(input, label = 'doc') {
     case 'theme':
       return parseTheme(input, label);
     case undefined:
-    default:
-      // 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);
+    default:
+      throw new Error(`${label} has unsupported type ${JSON.stringify(type)}.`);
   }
 }

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

@@ -95,7 +95,7 @@ export const doc = {
           name: 'sections[].content',
           type: 'ReferenceContentBlock[]',
           description:
-            '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.',
+            '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.',
           required: true,
         },
         {
@@ -144,7 +144,7 @@ export const docs = {
     },
     {
       type: 'prose',
-      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.',
+      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.',
     },
     {
       type: 'code',
@@ -156,9 +156,7 @@ 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 GraphContentBlock =
+  | { type: 'token-ref'; topic: string; section: string }
   | { 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,13 +41,8 @@ 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.
+ * A content block within a reference doc section or namespace.
  * 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.
@@ -60,6 +55,9 @@ export type GraphContentBlock =
  * { 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 =
@@ -82,7 +80,10 @@ 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).

package/authoring/index.d.ts

@@ -131,7 +131,6 @@ export type {
   // reference
   ReferenceSection,
   ReferenceContentBlock,
-  GraphContentBlock,
   ReferenceTokenPreviewType,
   ReferenceTranslationDoc,
   WorkflowStep,