@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

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

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').EnumDoc} EnumDoc */
+/** @typedef {import('../types.js').EnumDoc} EnumDoc */
 /**
  * Validate an unknown value as a stamped enum doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {EnumDoc}
  */
 export function parseEnum(input: unknown, label?: string): EnumDoc;
-export type EnumDoc = import("../types").EnumDoc;
+export type EnumDoc = import("../types.js").EnumDoc;

package/authoring/doctypes/enum/parse.mjs

@@ -8,7 +8,7 @@
 import {EnumDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').EnumDoc} EnumDoc */
+/** @typedef {import('../types.js').EnumDoc} EnumDoc */
 
 /**
  * Validate an unknown value as a stamped enum doc, or throw.

package/authoring/doctypes/enum/type.ts

@@ -5,7 +5,7 @@
  * discriminants). Colocated next to the source of truth it documents.
  */
 
-import type {AuthoredDocGraphFields} from '../base/type';
+import type {AuthoredDocGraphFields} from '../base/type.js';
 
 /** One member of an enumerated vocabulary. */
 export interface EnumMemberDoc {
@@ -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',
@@ -250,6 +251,10 @@ export const doc = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: 'When it loads, a stamped function doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+    },
     {
       type: 'prose',
       text: "The `type` discriminant is 'function' for both flavors. Set `kind: 'hook'` or `kind: 'api'` to drive docsite sectioning; it is inferred from `importPath` when omitted.",

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

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').FunctionDoc} FunctionDoc */
+/** @typedef {import('../types.js').FunctionDoc} FunctionDoc */
 /**
  * Validate an unknown value as a stamped function doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {FunctionDoc}
  */
 export function parseFunction(input: unknown, label?: string): FunctionDoc;
-export type FunctionDoc = import("../types").FunctionDoc;
+export type FunctionDoc = import("../types.js").FunctionDoc;

package/authoring/doctypes/function/parse.mjs

@@ -14,7 +14,7 @@
 
 import {parseHook} from '../hook/parse.mjs';
 
-/** @typedef {import('../types').FunctionDoc} FunctionDoc */
+/** @typedef {import('../types.js').FunctionDoc} FunctionDoc */
 
 /**
  * Validate an unknown value as a stamped function doc, or throw.

package/authoring/doctypes/function/type.ts

@@ -14,7 +14,7 @@ import type {
   AuthoredDocGraphFields,
   HookParamDoc,
   UsageDoc,
-} from '../base/type';
+} from '../base/type.js';
 
 /**
  * A documented return. Hooks list named return fields (`name` set); CLI/API
@@ -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/hook.doc.mjs

@@ -200,6 +200,10 @@ export const docs = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: 'When it loads, a hook doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+    },
     {
       type: 'prose',
       text: "A hook's discriminant is `type: 'function'`: HookDoc and FunctionDoc share the generalized function kind. HookDoc is the hook-flavored view: named `returns` fields and a required `usage` block.",

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

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').HookDoc} HookDoc */
+/** @typedef {import('../types.js').HookDoc} HookDoc */
 /**
  * Validate an unknown value as a stamped function/hook doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {HookDoc}
  */
 export function parseHook(input: unknown, label?: string): HookDoc;
-export type HookDoc = import("../types").HookDoc;
+export type HookDoc = import("../types.js").HookDoc;

package/authoring/doctypes/hook/parse.mjs

@@ -8,7 +8,7 @@
 import {FunctionDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').HookDoc} HookDoc */
+/** @typedef {import('../types.js').HookDoc} HookDoc */
 
 /**
  * Validate an unknown value as a stamped function/hook doc, or throw.

package/authoring/doctypes/hook/type.ts

@@ -12,7 +12,7 @@ import type {
   HookReturnDoc,
   RegistryDocIdentity,
   UsageDoc,
-} from '../base/type';
+} from '../base/type.js';
 
 /**
  * Documentation for a standalone hook's .doc.mjs file.
@@ -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/legacy.d.mts

@@ -1,9 +1,9 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
-/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
 /**
  * Validate an unknown value as a legacy (unstamped) doc, or throw.
  *
@@ -12,6 +12,6 @@
  * @returns {ComponentDoc | HookDoc | ReferenceDoc}
  */
 export function parseLegacyDoc(input: unknown, label?: string): ComponentDoc | HookDoc | ReferenceDoc;
-export type ComponentDoc = import("./types").ComponentDoc;
-export type HookDoc = import("./types").HookDoc;
-export type ReferenceDoc = import("./types").ReferenceDoc;
+export type ComponentDoc = import("./types.js").ComponentDoc;
+export type HookDoc = import("./types.js").HookDoc;
+export type ReferenceDoc = import("./types.js").ReferenceDoc;

package/authoring/doctypes/legacy.mjs

@@ -10,9 +10,9 @@
 import {LegacyDocSchema} from './_schema.mjs';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
-/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
 
 /**
  * Validate an unknown value as a legacy (unstamped) doc, or throw.

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

@@ -0,0 +1,233 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every authored doc kind has a compile-time lock between its load check
+ * and its published type: the `_*DriftLock` typedefs in `_schema.mjs` and
+ * `template/parse.mjs`, which the strict typecheck evaluates. A lock names each
+ * place the loader is deliberately looser than the type. These tests pin that
+ * looser behavior and the published unknown-field policy, so tightening a load
+ * check is a reviewed change rather than a silent one.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {describe, expect, it} from 'vitest';
+import {parseDoc} from './parse.mjs';
+import {AuthoredDocKindSchema} from './_schema.mjs';
+import {doc as graphFieldsDoc} from './base/graph-fields.doc.mjs';
+import {problemsInTopic} from '../../foundation/discovery/docs-discovery.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const KINDS = AuthoredDocKindSchema.options;
+
+/** The lock that pins each kind's load check to its published type. */
+const LOCKS = {
+  component: '_ComponentDocDriftLock',
+  function: '_FunctionDocDriftLock',
+  generic: '_ReferenceDocDriftLock',
+  page: '_PageTemplateDocDriftLock',
+  block: '_BlockTemplateDocDriftLock',
+  schema: '_SchemaDocDriftLock',
+  command: '_CommandDocDriftLock',
+  enum: '_EnumDocDriftLock',
+  namespace: '_NamespaceDocDriftLock',
+};
+
+/** One valid example doc per kind, from the typed examples. */
+const EXAMPLES = Object.fromEntries(
+  await Promise.all(
+    KINDS.map(async kind => {
+      const file = {generic: 'reference', function: 'function'}[kind] ?? kind;
+      const url = pathToFileURL(
+        path.join(HERE, '../../test/authoring-types', `${file}.doc.mjs`),
+      );
+      return [kind, (await import(url.href)).docs];
+    }),
+  ),
+);
+
+describe('load check vs published type', () => {
+  it('locks every doc kind', () => {
+    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());
+    const locks = [
+      ...Object.values(LOCKS),
+      '_AuthoredDocKindDriftLock',
+      '_HookDocIsFunctionDocLock',
+      '_ThemeDocDriftLock',
+    ];
+    for (const lock of locks) {
+      expect(source, `${lock} is missing`).toMatch(
+        new RegExp(`\\}\\s*${lock}\\b`),
+      );
+    }
+  });
+
+  it('dispatches every doc kind and refuses any other', () => {
+    for (const kind of KINDS) {
+      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,
+    );
+  });
+});
+
+describe('where loading is deliberately looser than the type', () => {
+  it('a stamped component needs no displayName; usage, theming and examples are unchecked', () => {
+    expect(() =>
+      parseDoc(
+        {
+          type: 'component',
+          name: 'Badge',
+          category: 'badges',
+          props: [],
+          usage: 'free text',
+          theming: 5,
+          examples: [{title: 'Basic'}],
+        },
+        'Badge.doc.mjs',
+      ),
+    ).not.toThrow();
+  });
+
+  it('each entry of a stamped group doc needs a name, and nothing more', () => {
+    const group = (/** @type {unknown[]} */ components) => ({
+      type: 'component',
+      name: 'Tabs',
+      components,
+    });
+    expect(() =>
+      parseDoc(
+        group([{name: 'Tab'}, {name: 'TabPanel', description: 'x'}]),
+        'Tabs.doc.mjs',
+      ),
+    ).not.toThrow();
+    for (const bad of [null, 5, 'Tab', {}, {name: ''}, {displayName: 'Tab'}]) {
+      expect(() => parseDoc(group([bad]), 'Tabs.doc.mjs')).toThrow(
+        /components\.0/,
+      );
+    }
+  });
+
+  it('a stamped function needs no displayName; usage is unchecked', () => {
+    expect(() =>
+      parseDoc(
+        {type: 'function', name: 'useX', params: [], returns: [], usage: 5},
+        'useX.doc.mjs',
+      ),
+    ).not.toThrow();
+  });
+
+  it('a stamped generic doc loads without title, description or sections, but is no topic', () => {
+    const doc = parseDoc({type: 'generic', name: 'notes'}, 'notes.doc.mjs');
+    expect(doc.title).toBe('notes');
+    expect(problemsInTopic(doc)).toEqual([
+      'description: expected a non-empty string',
+      'sections: expected at least one section',
+    ]);
+  });
+
+  it('a template needs no displayName or aspectRatio and may use its own category', () => {
+    expect(() =>
+      parseDoc(
+        {type: 'block', name: 'widget-demo', category: 'components/Widget'},
+        'widget-demo.doc.mjs',
+      ),
+    ).not.toThrow();
+    expect(() =>
+      parseDoc(
+        {type: 'page', name: 'widget-page', category: 'Widgets'},
+        'widget-page.doc.mjs',
+      ),
+    ).not.toThrow();
+  });
+
+  it('schema, command and enum docs load only as their type allows', () => {
+    const {fields, ...schemaDoc} = EXAMPLES.schema;
+    const {summary, ...commandDoc} = EXAMPLES.command;
+    const {members, ...enumDoc} = EXAMPLES.enum;
+    expect(() => parseDoc(schemaDoc, 's.doc.mjs')).toThrow(/fields/);
+    expect(() => parseDoc(commandDoc, 'c.doc.mjs')).toThrow(/summary/);
+    expect(() => parseDoc(enumDoc, 'e.doc.mjs')).toThrow(/members/);
+  });
+});
+
+describe('unknown fields', () => {
+  const keeps = KINDS.filter(kind => {
+    try {
+      parseDoc({...EXAMPLES[kind], notAField: true}, `${kind}.doc.mjs`);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+
+  it('match the published policy', () => {
+    const policy = graphFieldsDoc.notes
+      .map(note => ('text' in note ? note.text : ''))
+      .find(text => text.startsWith('Unknown fields'));
+    expect(policy, 'graph-fields.doc.mjs states the policy').toBeDefined();
+    const [kept, refused] = /** @type {string} */ (policy).split(
+      ' docs accept',
+    );
+    const named = (/** @type {string} */ text) =>
+      [...text.matchAll(/`([a-z]+)`/g)].map(match => match[1]).sort();
+    expect(named(kept)).toEqual([...keeps].sort());
+    expect(named(refused).filter(kind => KINDS.includes(kind))).toEqual(
+      KINDS.filter(kind => !keeps.includes(kind)).sort(),
+    );
+  });
+
+  it("are refused inside a section's reference block, which a section takes", () => {
+    const [section] = EXAMPLES.generic.sections;
+    const reference = {
+      type: 'reference',
+      target: '@astryxdesign/cli:schema:integration',
+      projection: {fields: ['docs']},
+      presentation: 'compact',
+    };
+    /** @param {object} block */
+    const withBlock = block =>
+      parseDoc(
+        {...EXAMPLES.generic, sections: [{...section, content: [block]}]},
+        'r.doc.mjs',
+      );
+    expect(() => withBlock(reference)).not.toThrow();
+    expect(() => withBlock({...reference, notAField: true})).toThrow();
+    expect(() =>
+      withBlock({...reference, projection: {fields: ['docs'], rows: []}}),
+    ).toThrow();
+    // Workflow and collection blocks belong to a namespace doc.
+    expect(() =>
+      withBlock({type: 'collection', source: {slot: 'guides'}}),
+    ).toThrow();
+  });
+
+  it('are refused inside sections and content blocks', () => {
+    const [section] = EXAMPLES.generic.sections;
+    expect(() =>
+      parseDoc(
+        {...EXAMPLES.generic, sections: [{...section, notAField: true}]},
+        'r.doc.mjs',
+      ),
+    ).toThrow();
+    expect(() =>
+      parseDoc(
+        {
+          ...EXAMPLES.generic,
+          sections: [
+            {
+              ...section,
+              content: [{type: 'prose', text: 'x', notAField: true}],
+            },
+          ],
+        },
+        'r.doc.mjs',
+      ),
+    ).toThrow();
+  });
+});

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

@@ -12,7 +12,7 @@ export const doc = {
   displayName: 'NamespaceDoc',
   namespace: 'authoring',
   description:
-    'Declares named navigation slots and renderer-neutral layout blocks for already-discovered docs. It never scans folders or copies child documents.',
+    "Declares one level of the docs tree: named slots, and adoption rules for already-discovered docs. It never scans folders, lists its children, or copies child documents: a child names its parent with `placement`, or a namespace adopts a discovery group. `astryx docs <route>` lists each slot's children one level down. The CLI keeps its namespace docs in its docs tree directory; an integration ships its own in its docs directory, and they appear in `astryx docs` beside the CLI's.",
   appliesTo: '<namespace>.doc.mjs',
   fields: [
     {
@@ -44,13 +44,13 @@ export const doc = {
       name: 'placement',
       type: 'DocPlacement',
       description:
-        'Optional canonical parent request: {parent, slot?, order?}. Invalid explicit placement fails compilation instead of falling back.',
+        'Optional canonical parent: {parent, slot?, order?}. `parent` names a namespace of the same package as `namespace:<name>`. An invalid placement withdraws the namespace with a diagnostic; it never falls back.',
     },
     {
       name: 'aliases',
       type: 'string[]',
       description:
-        'Prior names or routes that must keep resolving to this doc.',
+        'Prior names or routes the docs tree will keep resolving to this doc. Not read yet.',
     },
     {
       name: 'audience',
@@ -78,9 +78,9 @@ export const doc = {
     },
     {
       name: 'blocks',
-      type: 'ReferenceContentBlock[]',
+      type: '(ReferenceContentBlock | GraphContentBlock)[]',
       description:
-        'Ordered layout content. V1 adds only workflow, collection, and reference to the existing prose, heading, code, table, list, and token-ref blocks.',
+        'Ordered layout content for the namespace page. Graph-only workflow, collection, and reference blocks are available here without widening the stable ReferenceContentBlock union used by existing topic renderers. Not rendered yet: `astryx docs <route>` lists every slot and its children in order.',
     },
   ],
   examples: [
@@ -103,14 +103,14 @@ export const docs = {
     source: {group: 'cli-commands', kinds: ['command']},
     into: 'reference',
   }],
-  blocks: [
-    {type: 'collection', source: {slot: 'guides'}, presentation: 'cards'},
-    {type: 'collection', source: {slot: 'reference'}, presentation: 'compact'},
-  ],
 };`,
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: "The docs tree reads namespace docs from the CLI and from every configured integration. An integration's namespace doc is a top-level level of the tree, and its guides name it with `placement`; a doc can be placed only in a namespace of its own package. When two packages claim one route, the CLI's own docs win, then integrations in configured order, and `astryx doctor` names the loser.",
+    },
     {
       type: 'prose',
       text: 'Child docs request one canonical home with placement. Collections store and render stable references to those docs; they never create a second identity or parent.',

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

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('../types').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('../types.js').NamespaceDoc} NamespaceDoc */
 /**
  * Validate an unknown value as a NamespaceDoc, or throw a readable error.
  * @param {unknown} input
@@ -9,4 +9,4 @@
  * @returns {NamespaceDoc}
  */
 export function parseNamespace(input: unknown, label?: string): NamespaceDoc;
-export type NamespaceDoc = import("../types").NamespaceDoc;
+export type NamespaceDoc = import("../types.js").NamespaceDoc;

package/authoring/doctypes/namespace/parse.mjs

@@ -8,7 +8,7 @@
 import {NamespaceDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('../types.js').NamespaceDoc} NamespaceDoc */
 
 /**
  * Validate an unknown value as a NamespaceDoc, or throw a readable error.

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

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

package/authoring/doctypes/namespace/type.ts

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