@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

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:
+    "Placement, compatibility aliases, and audience: fields every authored doc kind declares for the docs tree. The docs tree reads `placement` for every guide, the CLI's and each integration's; aliases and audience are not built yet. 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:
+        'Prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Not read yet: a topic that sets it fails to load.',
+    },
+    {
+      name: 'audience',
+      type: "'public' | 'internal'",
+      description:
+        "Which docs bundle includes this doc ('public' when omitted). Not read yet: 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,47 @@
  * @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;
+  /** Prior routes or names the docs tree will keep resolving. Not read yet. */
+  aliases?: string[];
+  /** Docs bundle audience; omit for public docs. Not read 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',
@@ -150,7 +151,7 @@ export const doc = {
       name: 'subcommands',
       type: 'string[]',
       description:
-        'Subcommand names (for command groups like `theme` / `layout`).',
+        'Subcommand names (for command groups like `theme`).',
     },
     {
       name: 'examples',

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[];
@@ -74,13 +75,13 @@ export interface CommandDoc {
   args?: CommandArgDoc[];
   /** Flags/options. */
   options?: CommandOptionDoc[];
-  /** Subcommand names (for command groups like `theme` / `layout`). */
+  /** Subcommand names (for command groups like `theme`). */
   subcommands?: string[];
   /** Terminal examples. */
   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

@@ -56,7 +56,7 @@ export const doc = {
       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 +124,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 +241,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
@@ -49,7 +50,7 @@ export interface ComponentBaseDoc {
   import?: 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 +146,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.