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

package/authoring/doctypes/base/graph-fields.doc.d.mts

@@ -0,0 +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.
+
+/**
+ * @file SchemaDoc for graph metadata shared by every authored doc kind.
+ * @position packages/cli/authoring/doctypes/base — doc-type documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

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

@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for graph metadata shared by every authored doc kind.
+ * @position packages/cli/authoring/doctypes/base — doc-type documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'authored-doc-graph-fields',
+  displayName: 'Authored doc graph fields',
+  namespace: 'authoring',
+  description:
+    "Fields every authored doc kind can declare for the docs tree: `placement`, plus two reserved fields, `aliases` and `audience`. The docs tree reads `placement` for every guide, the CLI's and each integration's. Nothing reads `aliases` or `audience` today: a reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
+  appliesTo: 'Every supported .doc.mjs object',
+  fields: [
+    {
+      name: 'placement',
+      type: 'DocPlacement',
+      description:
+        "Names the doc's one parent in the docs tree: a namespace of the same package, one of its slots, and an order. Read for every guide, the CLI's and each integration's: a guide with `placement` gets a route in the tree instead of a flat topic name, and cannot also `replaces` or `extends` a topic. In the CLI's own topic directory a topic that sets it fails to load: the CLI keeps its guides in its docs tree directory. Commands, API functions, schemas, and enums do not set it: the tree adopts each by its `namespace`.",
+      fields: [
+        {
+          name: 'placement.parent',
+          type: 'string',
+          description:
+            'The parent namespace: `namespace:<name>` in the same package.',
+          required: true,
+        },
+        {
+          name: 'placement.slot',
+          type: 'string',
+          description:
+            "A slot the parent namespace declares; it must accept this doc's kind. Optional when the parent has one slot.",
+        },
+        {
+          name: 'placement.order',
+          type: 'number',
+          description: 'Integer sibling order within the slot.',
+        },
+      ],
+    },
+    {
+      name: 'aliases',
+      type: 'string[]',
+      description:
+        'Reserved: prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Nothing reads it today, and a topic that sets it fails to load.',
+    },
+    {
+      name: 'audience',
+      type: "'public' | 'internal'",
+      description:
+        "Reserved: which docs bundle includes this doc ('public' when omitted). Nothing reads it today, and a topic that sets it fails to load.",
+      default: "'public'",
+    },
+  ],
+  notes: [
+    {
+      type: 'prose',
+      text: 'Unknown fields: `component`, `function`, `generic`, `schema`, `command` and `enum` docs accept a field they do not know, and nothing reads it, so a doc written for a newer CLI still loads here. `page`, `block` and `namespace` docs refuse one, as do `theme` descriptors. Sections and content blocks refuse one in every doc.',
+    },
+  ],
+};

package/authoring/doctypes/base/type.ts

@@ -4,6 +4,49 @@
  * @file Shared leaf primitives used across the doc types.
  */
 
+/** Every authored documentation kind accepted by `parseDoc`. */
+export type AuthoredDocKind =
+  | 'component'
+  | 'function'
+  | 'generic'
+  | 'page'
+  | 'block'
+  | 'schema'
+  | 'command'
+  | 'enum'
+  | 'namespace';
+
+/** Visibility of an authored doc in a compiled audience-specific bundle. */
+export type DocAudience = 'public' | 'internal';
+
+/**
+ * Optional canonical placement request. The compiler resolves `parent` as a
+ * stable doc reference. `slot` selects one parent-owned slot, and `order`
+ * provides deterministic sibling ordering inside that slot.
+ */
+export interface DocPlacement {
+  parent: string;
+  slot?: string;
+  order?: number;
+}
+
+/**
+ * Tree metadata shared by every authored doc kind. The docs tree reads
+ * `placement` for every guide, the CLI's and each integration's
+ * (spec:AST-046); nothing reads `aliases` or `audience` yet. A reference topic
+ * outside the docs tree that sets one fails to load.
+ */
+export interface AuthoredDocGraphFields {
+  /** The doc's one parent in the docs tree: a namespace of its own package. */
+  placement?: DocPlacement;
+  /** Reserved: prior routes or names the docs tree will keep resolving.
+   *  Nothing reads it yet. */
+  aliases?: string[];
+  /** Reserved: docs bundle audience; omit for public docs. Nothing reads it
+   *  yet. */
+  audience?: DocAudience;
+}
+
 /**
  * Stable public identity for generated registry resources.
  *

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

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

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

package/authoring/doctypes/command/parse.mjs

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

package/authoring/doctypes/command/type.ts

@@ -9,7 +9,8 @@
  * `--help`. Colocated at `clients/cli/commands/<name>.doc.mjs`.
  */
 
-import type {ReferenceContentBlock} from '../reference/type';
+import type {AuthoredDocGraphFields} from '../base/type.js';
+import type {ReferenceContentBlock} from '../reference/type.js';
 
 /** A positional argument. `param` links it to a FunctionDoc param for its description. */
 export interface CommandArgDoc {
@@ -53,7 +54,7 @@ export interface CommandExampleDoc {
  *   /\*\* @type {import('@astryxdesign/cli/authoring').CommandDoc} \*\/
  *   export const doc = { type: 'command', name: 'search', fn: 'search', ... };
  */
-export interface CommandDoc {
+export interface CommandDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant. */
   type?: 'command';
   /** Command path, e.g. 'search' | 'theme build'. */
@@ -64,7 +65,7 @@ export interface CommandDoc {
   summary: string;
   /** Longer help body / when-to-use. */
   description?: string;
-  /** Docs namespace path. Defaults to 'cli' when applied by the docs index. */
+  /** The group that reads this doc. The CLI's commands use 'cli/commands', which the docs tree adopts: each is the leaf `cli/commands/<name>`. Every command doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads. */
   namespace?: string;
   /** Alternate slugs that also resolve to this doc. */
   aliases?: string[];
@@ -80,7 +81,7 @@ export interface CommandDoc {
   examples?: CommandExampleDoc[];
   /** Documented exit codes. */
   exitCodes?: {code: number; when: string}[];
-  /** Related command names. */
+  /** Related command names; the CLI links each to its doc. */
   related?: string[];
   /** Freeform prose/notes. */
   notes?: ReferenceContentBlock[];

package/authoring/doctypes/component/component.doc.mjs

@@ -52,11 +52,17 @@ export const doc = {
       description:
         'Exact public package specifier consumers use to import an integration-owned component. The packed-package gate resolves this specifier and verifies it exports the component name.',
     },
+    {
+      name: 'replaces',
+      type: 'string',
+      description:
+        "Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, lists, search, swizzle, and issue routing. The Core original stays reachable with `--package @astryxdesign/core`. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.",
+    },
     {
       name: 'keywords',
       type: 'string[]',
       description:
-        'Search keywords for CLI discovery: synonyms and related UI concepts from other design systems (MUI, Chakra, Radix, shadcn). Lowercase. Used by `astryx component <term>` fuzzy matching.',
+        'Search keywords for CLI discovery: synonyms and related UI concepts from other design systems (MUI, Chakra, Radix, and others). Lowercase. Used by `astryx component <term>` fuzzy matching.',
     },
     {
       name: 'hiddenComponents',
@@ -124,8 +130,7 @@ export const doc = {
       name: 'usage',
       type: 'UsageDoc',
       description:
-        'Component usage documentation: concise summary, best practices, component-specific accessibility requirements, and optional visual anatomy. (Optional on SubComponentDoc, where the sub-component description is used instead.)',
-      required: true,
+        'Component usage documentation: concise summary, best practices, component-specific accessibility requirements, and optional visual anatomy. Required on a component doc; optional on a sub-component doc (`subComponentOf`), which uses its description instead.',
       fields: [
         {
           name: 'usage.description',
@@ -242,6 +247,10 @@ export const docs = {
     },
   ],
   notes: [
+    {
+      type: 'prose',
+      text: "When it loads, a stamped component doc is checked as loosely as an unstamped one, so adding `type: 'component'` to an existing doc never breaks it: `displayName` may be missing, `category` may be any string, and `usage`, `theming`, `playground` and `examples` are not checked. Each entry in a group doc's `components` must have a `name`. Write to the type anyway; it is the contract.",
+    },
     {
       type: 'prose',
       text: 'ComponentDoc is a discriminated union of three shapes that all extend ComponentBaseDoc. Pick the variant by which key you set: `props` (single), `components` (multi), or `subComponentOf` (sub).',

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

package/authoring/doctypes/component/parse.mjs

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

package/authoring/doctypes/component/type.ts

@@ -5,6 +5,7 @@
  */
 
 import type {
+  AuthoredDocGraphFields,
   ComponentAccessibilityRequirement,
   ComponentAnatomyElement,
   ComponentBestPractice,
@@ -18,13 +19,13 @@ import type {
   HookReturnDoc,
   RegistryDocIdentity,
   UsageDoc,
-} from '../base/type';
+} from '../base/type.js';
 
 /**
  * Shared fields between single-component and multi-component docs.
  * Do not use this interface directly — use `ComponentDoc` (the union type).
  */
-export interface ComponentBaseDoc {
+export interface ComponentBaseDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant for the stamped default-export format
    *  (`export default { type: 'component', ... }`). Optional: legacy
    *  `export const docs = {...}` docs omit it, and `parseDoc` falls back to
@@ -47,9 +48,17 @@ export interface ComponentBaseDoc {
   displayName: string;
   /** Exact consumer import specifier for integration-owned components. */
   import?: string;
+  /** Integration components only: the exact `name` of the Core ComponentDoc
+   *  this component takes over for unqualified lookup, so every app that loads
+   *  the integration gets this component from component detail, lists, search,
+   *  swizzle, and issue routing. The Core original stays reachable with
+   *  `--package @astryxdesign/core`. Set it only to intentionally own a Core
+   *  identity; give an alternative or variant its own name instead. Older CLIs
+   *  that do not read `replaces` keep the component under its own name. */
+  replaces?: string;
   /** Search keywords for CLI discovery. Terms a developer might type when
    *  looking for this component: synonyms, related UI concepts, and common
-   *  names from other design systems (MUI, Chakra, Radix, shadcn).
+   *  names from other design systems (MUI, Chakra, Radix, and others).
    *  Lowercase only. Used by `astryx component <term>` for fuzzy matching.
    *  e.g. `['accordion', 'expand', 'toggle', 'disclosure']` for Collapsible */
   keywords?: string[];
@@ -145,10 +154,10 @@ export interface ComponentBaseDoc {
 /**
  * The documentation type for a component directory's {Name}.doc.mjs file.
  *
- * Every .doc.mjs must export a single `docs` constant of this type:
+ * Every new .doc.mjs default-exports a stamped object of this type:
  *
  *   /\*\* \@type \{import('@astryxdesign/cli/authoring').ComponentDoc\} *\/
- *   export const docs = \{ ... \};
+ *   export default \{ type: 'component', ... \};
  *
  * Use SingleComponentDoc (with `props`) for single-component directories.
  * Use MultiComponentDoc (with `components`) for multi-component directories.

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

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

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

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

package/authoring/doctypes/enum/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,6 +5,8 @@
  * discriminants). Colocated next to the source of truth it documents.
  */
 
+import type {AuthoredDocGraphFields} from '../base/type.js';
+
 /** One member of an enumerated vocabulary. */
 export interface EnumMemberDoc {
   /** The literal value, e.g. 'ERR_UNKNOWN_TOPIC' | 'component.list'. */
@@ -21,7 +23,7 @@ export interface EnumMemberDoc {
  *   /\*\* @type {import('@astryxdesign/cli/authoring').EnumDoc} \*\/
  *   export const doc = { type: 'enum', name: 'error-codes', ... };
  */
-export interface EnumDoc {
+export interface EnumDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant. */
   type?: 'enum';
   /** URL-safe identifier, used as the docs slug within its namespace. */
@@ -30,7 +32,7 @@ export interface EnumDoc {
   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

@@ -10,7 +10,11 @@
  * here — the function does not know it has a CLI.
  */
 
-import type {HookParamDoc, UsageDoc} from '../base/type';
+import type {
+  AuthoredDocGraphFields,
+  HookParamDoc,
+  UsageDoc,
+} from '../base/type.js';
 
 /**
  * A documented return. Hooks list named return fields (`name` set); CLI/API
@@ -45,7 +49,7 @@ export interface FunctionExampleDoc {
  *   /\*\* @type {import('@astryxdesign/cli/authoring').FunctionDoc} \*\/
  *   export const doc = { type: 'function', kind: 'api', name: 'search', ... };
  */
-export interface FunctionDoc {
+export interface FunctionDoc extends AuthoredDocGraphFields {
   /** Doc-kind discriminant (shared with hooks). */
   type?: 'function';
   /** Export name, e.g. 'search' | 'useMediaQuery'. */
@@ -58,7 +62,7 @@ export interface FunctionDoc {
   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[];
@@ -80,7 +84,8 @@ export interface FunctionDoc {
   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.