@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/authoring/doctypes/namespace/type.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Namespace doc types. A namespace owns navigation slots and a
+ * renderer-neutral layout over already-discovered docs. It never scans files
+ * or copies child documents.
+ */
+
+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';
+
+/** Constraints declared by the namespace that owns a slot. */
+export interface NamespaceSlotAcceptance {
+  /** Authored doc kinds accepted by this slot. */
+  kinds: AuthoredDocKind[];
+  /** Omit for the namespace provider; `configured` admits provider appearances. */
+  providers?: NamespaceProviderScope;
+}
+
+/** One named placement and collection target owned by a NamespaceDoc. */
+export interface NamespaceSlot {
+  /** Human-readable heading for children in this slot. */
+  title: string;
+  /** Which docs may be placed or shown in this slot. */
+  accepts: NamespaceSlotAcceptance;
+}
+
+/** One logical source group that a namespace may adopt. */
+export interface NamespaceAdoptionSource {
+  /** Provider-local discovery group, such as `cli-commands`. */
+  group: string;
+  /** Optional subset of authored kinds from the group. */
+  kinds?: AuthoredDocKind[];
+}
+
+/**
+ * Assigns otherwise-unplaced docs from one provider-local source group to a
+ * child namespace. Discovery defines groups; this rule never scans a folder.
+ */
+export interface NamespaceAdoptionRule {
+  source: NamespaceAdoptionSource;
+  /** Slot owned by this namespace that becomes the canonical destination. */
+  into: string;
+  /** Generate one child namespace per authored kind. */
+  groupBy?: 'kind';
+}
+
+/**
+ * An authored documentation namespace. Its ordered blocks control layout while
+ * slots and adoption rules describe where already-discovered docs may appear.
+ */
+export interface NamespaceDoc extends AuthoredDocGraphFields {
+  type: 'namespace';
+  /** Stable provider-local name. Navigation changes do not change this value. */
+  name: string;
+  /** Human-readable page title. */
+  title: string;
+  /** One-line summary shown in listings and search results. */
+  summary: string;
+  /** Search terms that are not already present in the title or summary. */
+  keywords?: string[];
+  /** Named child-placement and collection targets. */
+  slots: Record<string, NamespaceSlot>;
+  /** Optional source-adoption rules for otherwise-unplaced docs. */
+  adopts?: NamespaceAdoptionRule[];
+  /** Ordered renderer-neutral content and collection blocks. */
+  blocks?: (ReferenceContentBlock | GraphContentBlock)[];
+}

package/authoring/doctypes/parse.d.mts

@@ -1,14 +1,16 @@
 // @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').FunctionDoc} FunctionDoc */
-/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
-/** @typedef {import('./types').TemplateDoc} TemplateDoc */
-/** @typedef {import('./types').SchemaDoc} SchemaDoc */
-/** @typedef {import('./types').CommandDoc} CommandDoc */
-/** @typedef {import('./types').EnumDoc} EnumDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').FunctionDoc} FunctionDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('./types.js').TemplateDoc} TemplateDoc */
+/** @typedef {import('./types.js').SchemaDoc} SchemaDoc */
+/** @typedef {import('./types.js').CommandDoc} CommandDoc */
+/** @typedef {import('./types.js').EnumDoc} EnumDoc */
+/** @typedef {import('./types.js').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./types.js').ThemeDoc} ThemeDoc */
 /**
  * Validate an unknown loaded doc value into its typed shape, or throw.
  * Dispatches on the stamped `type`; unstamped docs fall back to
@@ -17,14 +19,16 @@
  *
  * @param {unknown} input
  * @param {string} [label]
- * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc}
+ * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc | ThemeDoc}
  */
-export function parseDoc(input: unknown, label?: string): ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc;
-export type ComponentDoc = import("./types").ComponentDoc;
-export type HookDoc = import("./types").HookDoc;
-export type FunctionDoc = import("./types").FunctionDoc;
-export type ReferenceDoc = import("./types").ReferenceDoc;
-export type TemplateDoc = import("./types").TemplateDoc;
-export type SchemaDoc = import("./types").SchemaDoc;
-export type CommandDoc = import("./types").CommandDoc;
-export type EnumDoc = import("./types").EnumDoc;
+export function parseDoc(input: unknown, label?: string): ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc | ThemeDoc;
+export type ComponentDoc = import("./types.js").ComponentDoc;
+export type HookDoc = import("./types.js").HookDoc;
+export type FunctionDoc = import("./types.js").FunctionDoc;
+export type ReferenceDoc = import("./types.js").ReferenceDoc;
+export type TemplateDoc = import("./types.js").TemplateDoc;
+export type SchemaDoc = import("./types.js").SchemaDoc;
+export type CommandDoc = import("./types.js").CommandDoc;
+export type EnumDoc = import("./types.js").EnumDoc;
+export type NamespaceDoc = import("./types.js").NamespaceDoc;
+export type ThemeDoc = import("./types.js").ThemeDoc;

package/authoring/doctypes/parse.mjs

@@ -4,8 +4,8 @@
  * @file The doc load boundary. `parseDoc` validates an unknown loaded doc value
  * into its typed shape (or throws a readable error), dispatching on the stamped
  * `type` and falling back to legacy shape-sniffing for unstamped docs. Its
- * acceptance set matches the old permissive `ComponentDocSchema` exactly, so
- * every existing `.doc.*` keeps loading unchanged.
+ * acceptance set preserves the old permissive `ComponentDocSchema` while new
+ * stamped kinds, including `theme`, use their sealed parser.
  */
 
 import {parseComponent} from './component/parse.mjs';
@@ -15,16 +15,20 @@ import {parseTemplate} from './template/parse.mjs';
 import {parseSchema} from './schema/parse.mjs';
 import {parseCommand} from './command/parse.mjs';
 import {parseEnum} from './enum/parse.mjs';
+import {parseNamespace} from './namespace/parse.mjs';
+import {parseTheme} from './theme/parse.mjs';
 import {parseLegacyDoc} from './legacy.mjs';
 
-/** @typedef {import('./types').ComponentDoc} ComponentDoc */
-/** @typedef {import('./types').HookDoc} HookDoc */
-/** @typedef {import('./types').FunctionDoc} FunctionDoc */
-/** @typedef {import('./types').ReferenceDoc} ReferenceDoc */
-/** @typedef {import('./types').TemplateDoc} TemplateDoc */
-/** @typedef {import('./types').SchemaDoc} SchemaDoc */
-/** @typedef {import('./types').CommandDoc} CommandDoc */
-/** @typedef {import('./types').EnumDoc} EnumDoc */
+/** @typedef {import('./types.js').ComponentDoc} ComponentDoc */
+/** @typedef {import('./types.js').HookDoc} HookDoc */
+/** @typedef {import('./types.js').FunctionDoc} FunctionDoc */
+/** @typedef {import('./types.js').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('./types.js').TemplateDoc} TemplateDoc */
+/** @typedef {import('./types.js').SchemaDoc} SchemaDoc */
+/** @typedef {import('./types.js').CommandDoc} CommandDoc */
+/** @typedef {import('./types.js').EnumDoc} EnumDoc */
+/** @typedef {import('./types.js').NamespaceDoc} NamespaceDoc */
+/** @typedef {import('./types.js').ThemeDoc} ThemeDoc */
 
 /**
  * Validate an unknown loaded doc value into its typed shape, or throw.
@@ -34,7 +38,7 @@ import {parseLegacyDoc} from './legacy.mjs';
  *
  * @param {unknown} input
  * @param {string} [label]
- * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc}
+ * @returns {ComponentDoc | HookDoc | FunctionDoc | ReferenceDoc | TemplateDoc | SchemaDoc | CommandDoc | EnumDoc | NamespaceDoc | ThemeDoc}
  */
 export function parseDoc(input, label = 'doc') {
   const type =
@@ -58,7 +62,14 @@ export function parseDoc(input, label = 'doc') {
       return parseCommand(input, label);
     case 'enum':
       return parseEnum(input, label);
+    case 'namespace':
+      return parseNamespace(input, label);
+    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);
   }
 }

package/authoring/doctypes/parse.test.mjs

@@ -25,8 +25,18 @@ const goodComponent = {
   displayName: 'Widget',
   description: 'A small widget.',
   props: [
-    {name: 'label', type: 'string', description: 'Visible label.', required: true},
-    {name: 'size', type: "'sm' | 'md'", description: 'Control size.', default: "'md'"},
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Visible label.',
+      required: true,
+    },
+    {
+      name: 'size',
+      type: "'sm' | 'md'",
+      description: 'Control size.',
+      default: "'md'",
+    },
   ],
 };
 
@@ -35,7 +45,9 @@ const goodFunction = {
   name: 'useThing',
   displayName: 'useThing',
   description: 'A thing hook.',
-  params: [{name: 'input', type: 'string', description: 'The input.', required: true}],
+  params: [
+    {name: 'input', type: 'string', description: 'The input.', required: true},
+  ],
   returns: [{name: 'value', type: 'string', description: 'The result.'}],
 };
 
@@ -43,7 +55,11 @@ const goodGeneric = {
   type: 'generic',
   name: 'Theming',
   displayName: 'Theming',
+  title: 'Theming',
   description: 'How theming works.',
+  sections: [
+    {title: 'Overview', content: [{type: 'prose', text: 'Use a theme.'}]},
+  ],
 };
 
 /** Run parseDoc and return the thrown message (asserting it throws). */
@@ -101,6 +117,34 @@ describe('per-kind parsers (stamped format)', () => {
     expect(() => parseReference(goodGeneric)).not.toThrow();
   });
 
+  it('normalizes a migrated minimal generic doc to the public shape', () => {
+    expect(
+      parseReference({
+        type: 'generic',
+        name: 'Theming',
+        description: 'How theming works.',
+      }),
+    ).toMatchObject({
+      type: 'generic',
+      name: 'Theming',
+      title: 'Theming',
+      description: 'How theming works.',
+      sections: [],
+    });
+  });
+
+  it('rejects duplicate stable section IDs', () => {
+    expect(() =>
+      parseReference({
+        ...goodGeneric,
+        sections: [
+          {id: 'start', title: 'Start', content: []},
+          {id: 'start', title: 'Renamed start', content: []},
+        ],
+      }),
+    ).toThrow(/sections\.1\.id.*duplicate section id/u);
+  });
+
   it('keeps nested rich blobs loose (usage/theming/playground passthrough)', () => {
     expect(() =>
       parseComponent({
@@ -123,6 +167,16 @@ describe('per-kind parsers (stamped format)', () => {
     expect(parsed.parent).toBe('WidgetGroup');
     expect(parsed.relatedDocs).toEqual(['Gauge', 'useThing']);
   });
+
+  it('validates graph metadata on unstamped legacy docs', () => {
+    expect(() =>
+      parseDoc({name: 'Widget', props: [], placement: {parent: ''}}),
+    ).toThrow(/placement\.parent/u);
+    expect(() => parseDoc({name: 'Widget', props: [], aliases: [1]})).toThrow();
+    expect(() =>
+      parseDoc({name: 'Widget', props: [], audience: 'secret'}),
+    ).toThrow();
+  });
 });
 
 describe('parseDoc (load boundary, both formats)', () => {
@@ -175,6 +229,24 @@ describe('parseDoc (load boundary, both formats)', () => {
     expect(() => parseDoc(hook)).not.toThrow();
   });
 
+  it('accepts and validates the OLD loose reference-topic shape', () => {
+    const reference = {
+      name: 'theming',
+      title: 'Theming',
+      description: 'How theming works.',
+      sections: [
+        {id: 'start', title: 'Start', content: [{type: 'prose', text: 'Go.'}]},
+      ],
+    };
+    expect(parseDoc(reference)).toEqual(reference);
+    expect(() =>
+      parseDoc({
+        ...reference,
+        sections: [{title: 'Start', content: [{type: 'prose'}]}],
+      }),
+    ).toThrow();
+  });
+
   it('accepts BOTH parent and legacy subComponentOf', () => {
     const withParent = {name: 'A', parent: 'B', props: []};
     const withSubComponentOf = {
@@ -289,7 +361,9 @@ describe('loadComponentDoc (end-to-end load boundary)', () => {
         "  type: 'generic',",
         "  name: 'Theming',",
         "  displayName: 'Theming',",
+        "  title: 'Theming',",
         "  description: 'How theming works.',",
+        "  sections: [{title: 'Overview', content: [{type: 'prose', text: 'Use a theme.'}]}],",
         '};',
       ].join('\n'),
     );

package/authoring/doctypes/reference/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').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('../types.js').ReferenceDoc} ReferenceDoc */
 /**
  * Validate an unknown value as a stamped reference/topic doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {ReferenceDoc}
  */
 export function parseReference(input: unknown, label?: string): ReferenceDoc;
-export type ReferenceDoc = import("../types").ReferenceDoc;
+export type ReferenceDoc = import("../types.js").ReferenceDoc;

package/authoring/doctypes/reference/parse.mjs

@@ -9,7 +9,7 @@
 import {GenericDocKindSchema} from '../_schema.mjs';
 import {formatZodError} from '../../_shared/errors.mjs';
 
-/** @typedef {import('../types').ReferenceDoc} ReferenceDoc */
+/** @typedef {import('../types.js').ReferenceDoc} ReferenceDoc */
 
 /**
  * Validate an unknown value as a stamped reference/topic doc, or throw.
@@ -23,8 +23,11 @@ export function parseReference(input, label = 'reference doc') {
   if (!result.success) {
     throw new Error(formatZodError(label, result.error));
   }
-  // The schema is permissive (it also accepts legacy generic docs), so it is
-  // deliberately looser than the rich public type; cast through unknown at this
-  // validated boundary.
-  return /** @type {ReferenceDoc} */ (/** @type {unknown} */ (result.data));
+  const doc = result.data;
+  return /** @type {ReferenceDoc} */ ({
+    ...doc,
+    title: doc.title ?? doc.displayName ?? doc.name,
+    description: doc.description ?? '',
+    sections: doc.sections ?? [],
+  });
 }

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

@@ -51,18 +51,25 @@ export const doc = {
       type: 'string',
       description: "Navigation category: 'guide' or 'foundations'.",
     },
+    {
+      name: 'keywords',
+      type: 'string[]',
+      description:
+        "Words a reader may search for that the title and sections do not use: a synonym, a task, or another library's name for the same thing. `astryx search` matches each as a keyword of the whole topic, so an exact one ranks the topic like its own title does.",
+      example: "['dark mode', 'color scheme']",
+    },
     {
       name: 'replaces',
       type: 'string',
       description:
-        "Name of an existing topic this doc takes the place of. Authored by an integration that serves its own guide instead of the built-in one: on a doc of the same name it swaps the content, and on a doc of another name it also leaves the old name as an alias so `astryx docs <old>` still resolves. Exclusive with `extends`.",
+        'Name of an existing topic this doc takes the place of. Authored by an integration that serves its own guide instead of the built-in one: on a doc of the same name it swaps the content, and on a doc of another name it also leaves the old name as an alias so `astryx docs <old>` still resolves. Exclusive with `extends`.',
       example: "'getting-started'",
     },
     {
       name: 'extends',
       type: 'string',
       description:
-        'Name of an existing topic this doc merges onto, section by section: a section whose title matches one in the base replaces it, a section the base does not have is appended. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.',
+        "Name of an existing topic this doc merges onto, section by section: a section whose title matches one in the base replaces it, a section the base does not have is appended. The topic keeps the base's title and description. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.",
       example: "'theme'",
     },
     {
@@ -72,6 +79,12 @@ export const doc = {
         'Ordered sections that make up the doc. Each becomes an h2 in full output and can be retrieved via `astryx docs <topic> <section>`.',
       required: true,
       fields: [
+        {
+          name: 'sections[].id',
+          type: 'string',
+          description:
+            'Stable section anchor. New docs should set this instead of relying on a mutable title.',
+        },
         {
           name: 'sections[].title',
           type: 'string',
@@ -87,9 +100,9 @@ export const doc = {
         },
         {
           name: 'sections[].content',
-          type: 'ReferenceContentBlock[]',
+          type: '(ReferenceContentBlock | ReferenceDocBlock)[]',
           description:
-            'Ordered content blocks. Mix prose, code, tables, and lists freely.',
+            "Ordered content blocks: prose, heading, code, table, list, token-ref, and reference. A `reference` block (`{type: 'reference', target, projection?, presentation?}`) includes another doc from its canonical source instead of a copy: a schema, command, function, or enum doc as `astryx docs` prints it, then the command that opens it. `projection.fields` keeps only those fields of a schema; `presentation` is `full` (the default), `compact` (no code blocks), or `summary` (only the doc's title, summary, and command). Any other doc shows as a summary. Graph-only workflow and collection blocks are available through GraphContentBlock on NamespaceDoc, without widening the stable ReferenceContentBlock union. Inside text, `{@link <target>}` links another doc by identity (`[<provider>:]<kind>:<name>`): the CLI prints the command that opens it, and `astryx doctor` warns on one that names no doc.",
           required: true,
         },
         {
@@ -134,7 +147,31 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. New block types can be added without breaking existing docs. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
+      text: 'A stamped generic doc without `title`, `description` or `sections` still loads, as older codemod output does; its title falls back to `displayName` or `name`. Without a description and sections it is not a usable topic, and `astryx doctor` reports it.',
+    },
+    {
+      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, plus the reference block (ReferenceDocBlock). A read inlines a reference block the way it inlines a token-ref, so `astryx docs`, in text and in `--json`, returns only the stable block kinds. Docs-graph-only workflow and collection 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. Inside text, `{@link <target>}` links another doc by identity (`[<provider>:]<kind>:<name>`): the CLI prints the command that opens it, and `astryx doctor` warns on one that names no doc.',
+    },
+    {
+      type: 'prose',
+      text: "A reference block includes content, where a link only points at it: `astryx doctor integration docs` fails when its target names no doc, when `projection.fields` names a field the schema does not have, or when the doc cannot take the projection or presentation it sets, and a read marks the missing content. A target without a provider names a doc of the package that wrote it, so an integration names the CLI's docs with the CLI's provider, as in `@astryxdesign/cli:schema:integration`.",
+    },
+    {
+      type: 'code',
+      lang: 'js',
+      label: 'A section that includes two fields of the integration manifest',
+      code: `{
+  title: 'Point the manifest at your folders',
+  content: [
+    {type: 'prose', text: 'Add these fields to astryx.integration.mjs.'},
+    {
+      type: 'reference',
+      target: '@astryxdesign/cli:schema:integration',
+      projection: {fields: ['components', 'docs']},
+    },
+  ],
+}`,
     },
     {
       type: 'code',
@@ -146,7 +183,19 @@ export const docs = {
   | { type: 'code'; lang: string; code: string; label?: string }
   | { type: 'table'; headers: string[]; rows: string[][] }
   | { type: 'list'; style: 'ordered' | 'unordered' | 'do' | 'dont'; items: string[] }
-  | { type: 'token-ref'; topic: string; section: string };`,
+  | { type: 'token-ref'; topic: string; section: string };
+
+type ReferenceDocBlock = {
+  type: 'reference';
+  target: string;
+  projection?: { fields?: string[]; sections?: string[] };
+  presentation?: 'summary' | 'compact' | 'full';
+};
+
+type GraphContentBlock =
+  | { type: 'workflow'; title?: string; steps: WorkflowStep[] }
+  | { type: 'collection'; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
+  | ReferenceDocBlock;`,
     },
     {
       type: 'prose',

package/authoring/doctypes/reference/type.ts

@@ -4,10 +4,66 @@
  * @file Reference/topic doc types.
  */
 
+import type {AuthoredDocGraphFields} from '../base/type.js';
+
+/** One step in a renderer-neutral workflow. */
+export interface WorkflowStep {
+  title: string;
+  description?: string;
+  /** Stable doc references that supply detail for this step. */
+  references?: string[];
+}
+
+/** Ordered procedural guidance. */
+export interface WorkflowDocBlock {
+  type: 'workflow';
+  title?: string;
+  steps: WorkflowStep[];
+}
+
+/** A generated view over docs placed in one namespace slot. */
+export interface CollectionDocBlock {
+  type: 'collection';
+  title?: string;
+  source: {slot: string};
+  presentation?: 'list' | 'cards' | 'compact';
+  whenEmpty?: 'show' | 'omit';
+}
+
+/**
+ * A bounded projection of one canonical doc. In a namespace doc's `blocks` it
+ * is layout the docs tree renders later. In a topic section, a read includes
+ * the doc it names in place of the block: a schema, command, function, or
+ * enum doc as `astryx docs` prints it (`projection.fields` keeps only those
+ * fields of a schema), then the command that opens that doc. Any other doc
+ * shows its title and summary.
+ */
+export interface ReferenceDocBlock {
+  type: 'reference';
+  /** The doc it names, by identity: `[<provider>:]<kind>:<name>`. */
+  target: string;
+  projection?: {
+    fields?: string[];
+    sections?: string[];
+  };
+  /** `summary`: only the doc's title, summary, and the command that opens it.
+   *  `compact`: the included doc without its code blocks. `full`, the default:
+   *  the included doc. */
+  presentation?: 'summary' | 'compact' | 'full';
+}
+
+/** Graph-only content blocks, for a namespace doc's `blocks`. These are
+ * additive and do not widen the stable {@link ReferenceContentBlock} union
+ * consumed by existing exhaustive renderers. A topic section accepts the
+ * `reference` block too, and a read inlines it as stable blocks. */
+export type GraphContentBlock =
+  WorkflowDocBlock | CollectionDocBlock | ReferenceDocBlock;
+
 /**
  * A content block within a reference doc section.
- * Ordered array of these makes up a section's content.
- * New block types can be added without breaking existing docs.
+ * 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.
  *
  * @example
  * ```
@@ -17,9 +73,12 @@
  * { 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: 'prose', text: 'Check it with {@link command:doctor}.' }
  * ```
  */
 export type ReferenceContentBlock =
+  /** Text. `{@link [<provider>:]<kind>:<name>}` inside it links another doc
+   *  by identity; `astryx docs` prints the command that opens that doc. */
   | {type: 'prose'; text: string}
   | {type: 'heading'; level: 3 | 4 | 5 | 6; text: string}
   | {type: 'code'; lang: string; code: string; label?: string}
@@ -49,12 +108,12 @@ export type ReferenceContentBlock =
  * they aren't tied to a specific component — just drop a .doc.mjs file
  * in the docs/ directory and it shows up in `astryx docs`.
  *
- * Every reference .doc.mjs must export a single `docs` constant:
+ * Every new reference .doc.mjs default-exports a stamped object:
  *
  *   /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} *\/
- *   export const docs = { ... };
+ *   export default { type: 'generic', ... };
  */
-export interface ReferenceDoc {
+export interface ReferenceDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant for the stamped default-export format
    *  (`export default { type: 'generic', ... }`). Optional: legacy
    *  `export const docs = {...}` docs omit it. The value stays `'generic'`
@@ -68,6 +127,11 @@ export interface ReferenceDoc {
   description: string;
   /** Navigation category: 'guide' or 'foundations'. */
   category?: string;
+  /** Words a reader may search for that the title and sections do not use:
+   *  a synonym, a task ("dark mode"), or another library's name for the same
+   *  thing. `astryx search` matches each as a keyword of the whole topic, so
+   *  an exact one ranks the topic like its own title does. */
+  keywords?: string[];
   /** Name of an existing topic this doc takes the place of. Authored by an
    *  integration whose guide should be served instead of the built-in one —
    *  `replaces: 'getting-started'` on a doc named `getting-started` swaps the
@@ -95,13 +159,17 @@ export interface ReferenceDoc {
  * and can be individually retrieved via `astryx docs <topic> <section>`.
  */
 export interface ReferenceSection {
+  /** Stable section anchor. New docs should set this instead of relying on title. */
+  id?: string;
   /** Section title, e.g. "Spacing Tokens", "Light/Dark Mode" */
   title: string;
   /** Navigation category ('guide' | 'foundations'). Mirrors the parent doc's
    *  category so sections can be grouped independently in the docsite nav. */
   category?: string;
-  /** Ordered content blocks. Mix prose, code, tables, and lists freely. */
-  content: ReferenceContentBlock[];
+  /** Ordered content blocks. Mix prose, code, tables, and lists freely. A
+   *  `reference` block includes another doc from its canonical source, so a
+   *  guide never copies a schema's fields or a command's options. */
+  content: (ReferenceContentBlock | ReferenceDocBlock)[];
   /** Preview type for token tables in this section. When set, the docsite
    *  renders a visual preview column using the token's computed CSS value
    *  from the current theme. Omit for non-token sections. */

package/authoring/doctypes/schema/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').SchemaDoc} SchemaDoc */
+/** @typedef {import('../types.js').SchemaDoc} SchemaDoc */
 /**
  * Validate an unknown value as a stamped schema doc, or throw.
  *
@@ -10,4 +10,4 @@
  * @returns {SchemaDoc}
  */
 export function parseSchema(input: unknown, label?: string): SchemaDoc;
-export type SchemaDoc = import("../types").SchemaDoc;
+export type SchemaDoc = import("../types.js").SchemaDoc;

package/authoring/doctypes/schema/parse.mjs

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

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

@@ -49,7 +49,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "Docs namespace path (e.g. 'cli' | 'authoring'). Defaults are applied by the docs index; set explicitly to place the schema.",
+        "The group that reads this doc: 'authoring' for a file an author writes (a section of {@link generic:authoring}), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',
@@ -162,7 +162,7 @@ export const doc = {
       type: '{ dir: string }',
       description: 'Where component sources live.',
       fields: [
-        {name: 'components.dir', type: 'string', description: 'Glob root for XDS*.tsx files.', required: true},
+        {name: 'components.dir', type: 'string', description: 'Glob root for Acme*.tsx files.', required: true},
       ],
     },
   ],