Authoring Reference

The astryx.integration.* manifest that sits beside an integration package's package.json. It can preserve a stable provider identity across a package rename, and points the CLI at the package's components, templates, codemods, doc topics, source themes, managed agent guidance, and issue tracker. Every field is optional.

Applies to: astryx.integration.{ts,mjs,js}

js
export default {
  components: './src/components',
  templates: './src/templates',
  codemods: './codemods',
  docs: './docs',
  themes: './themes',
  agentDocs: {
    append: ['Run acme verify before finishing.'],
  },
  issuesUrl: 'https://github.com/acme/widgets/issues',
};

The provider name defaults to the package name in package.json. During a rename, set providerId to the old package name so the IDs of what the package already contributed stay the same. The package version always comes from package.json.

agentDocs.append may contain at most eight lines. Each line is a trimmed, non-blank string of at most 240 Unicode code points with no line separators, control characters, NUL, or Astryx/XDS managed-marker text. The configured project may contain at most 32 integration lines total.

A themes root is forward-compatible but version-gated: a CLI released before this field ignores it with a warning and continues loading every contribution kind it understands. That older CLI cannot list or add the contributed themes.

Validate the manifest with astryx doctor integration validate. At the load boundary, a known field of the wrong type is an error, issuesUrl must be a valid URL, and unknown fields become warnings so an older CLI can still load the fields it understands. Before publishing, also run templates, components, and docs under the same doctor integration group. Those leaves compare authored identities with Core and explain whether an overlap is intentional or needs a rename.

The optional astryx.config.* file at your project root. Declares which integrations to load, where to route issue links, post-codemod hooks, local debug-log and gap-report handlers, and experimental layout components. All optional; {} is valid.

Applies to: astryx.config.{ts,mjs,js}

js
export default {
  integrations: ['@acme/astryx-widgets'],
};

js
export default {
  debug: event => appendFileSync("runs.ndjson", JSON.stringify(event) + "\n"),
};

The config is validated at load with a strict schema: unknown keys are errors, so a typo fails fast rather than being silently ignored.

One recorded CLI run: what a debug handler receives, whether it is set in astryx.config or exported by an integration manifest. There is exactly one event per run, and every field is present by the time a handler sees it.

Applies to: The argument of a debug handler

js
import {appendFileSync} from 'node:fs';
​
export default {
  debug: event => {
    if (event.outcome !== 'ok') {
      appendFileSync('failed-runs.ndjson', JSON.stringify(event) + '\n');
    }
  },
};

The shape only grows: fields are added, never removed or given a new meaning. When a meaning must change, schemaVersion gets a new value. In version 3, a null output.resultKind means the run never reached an answer, so do not count it together with a version 1 or 2 null.

The handler runs synchronously as the process exits, so a promise it returns is never awaited. It gets a copy of the event, and anything it throws is ignored.

Import DebugEventOutput, DebugEventEnv, DebugEventProject, and DebugEventError from @astryxdesign/cli/authoring for the fields of output, env, project, and error.

A handler for astryx gap-report: a plain object with an audience and a handle function. Set it as gapReport in astryx.config, or export it as gapReport from an integration manifest. Every handler runs: the project handler first, then each integration handler in config order.

Applies to: gapReport in astryx.config.*, or the gapReport named export of astryx.integration.*

js
export default {
  gapReport: {
    audience: 'internal',
    async handle(report, {signal}) {
      const url = await fileIssue(report, {signal});
      return {status: 'filed', url};
    },
  },
};

The receipt is strict: an unknown field, a URL that is not http or https, or a filed or routed_only receipt with neither url nor message is invalid.

A source for astryx discover: an async function that returns a catalog of packages a project could add, their versions, and what each version adds. Set it as discover in astryx.config, or export it as discover from an integration manifest. Discover calls every source, the project one first, and one that throws, runs past 30 seconds, or returns an invalid catalog never hides the others; discover then uses the last good answer it saved for that source. Discover only reads: it prints the command that adds a package and never runs it.

Applies to: discover in astryx.config.*, or the discover named export of astryx.integration.*

js
export default {
  async discover({signal, package: name, version}) {
    const res = await fetch(catalogUrl(name, version), {signal});
    return res.json();
  },
};

A codemod module the CLI runs during astryx upgrade. Default-export a plain object with a type discriminant: 'code' rewrites source files, 'config' rewrites the astryx.config.* file. There is no factory to call.

Applies to: the codemods/ dir of an integration

js
export default {
  type: 'code',
  title: 'Rename Button prop kind to variant',
  fileExtensions: ['.tsx', '.ts'],
  transform(file, api) {
    const j = api.jscodeshift;
    const root = j(file.source);
    // ...rewrite the AST...
    return root.toSource();
  },
};

js
export default {
  type: 'config',
  title: 'Move issuesUrl into astryx.config',
  transform(file, api) {
    // Rewrite the astryx.config.* source; return null to skip.
    return null;
  },
};

The config-codemod variant (type: 'config') carries the same fields as a code codemod except fileExtensions: it always targets the astryx.config.* file rather than a set of source files.

Authors write a plain object and default-export it with the type discriminant; there is no factory. The CLI validates it at the load boundary via parseCodemod with a strict schema, and isOptional defaults to false.

Separates stable provider/artifact identity from package instances and runtime lifecycle state. Provider identity names integration manifests and settles provider conflicts. Docs-tree nodes are identified by doc identity; the tree covers the CLI's own docs. Artifact, instance, and compiler-input identities are defined for every provider-owned artifact; no command reads them.

Applies to: Integration manifests, provider conflicts, and docs-tree node ids.

Provider package renames require an explicit mapping: a ProviderInstance may retain its stable providerId while packageName changes. Silent identity changes are not inferred.

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.

Applies to: Every supported .doc.mjs object

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.

The doc-type for a component directory's {Name}.doc.mjs. A discriminated union of SingleComponentDoc (props on the doc), MultiComponentDoc (a components array), and SubComponentDoc (a subComponentOf pointer). All three share the ComponentBaseDoc fields below; the variant is chosen by which of props / components / subComponentOf you set.

Applies to: {Name}.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
  name: 'Switch',
  displayName: 'Switch',
  category: 'Form Controls',
  keywords: ['toggle', 'switch', 'on off'],
  usage: {
    description:
      'A Switch toggles a single setting on or off. Use it for instant, binary preferences that apply immediately without a submit step.',
    bestPractices: [
      {guidance: true, description: 'Apply the change immediately when toggled.'},
      {guidance: false, description: 'Use a Switch for actions that need confirmation; prefer a Checkbox in a form.'},
    ],
  },
  props: [
    {name: 'isSelected', type: 'boolean', description: 'Whether the switch is on.', required: true},
    {name: 'onChange', type: '(isSelected: boolean) => void', description: 'Called when the user toggles the switch.'},
    {name: 'isDisabled', type: 'boolean', description: 'Prevents interaction and dims the control.', default: 'false'},
  ],
};

js
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
  name: 'Table',
  displayName: 'Table',
  category: 'Table & List',
  usage: {description: 'Displays rows and columns of data. Compose the sub-components to build headers, rows, and cells.'},
  components: [
    {name: 'Table', displayName: 'Table', description: 'The table container.', props: []},
    {name: 'TableRow', displayName: 'Table Row', description: 'A row within the table body.', props: [
      {name: 'isSelected', type: 'boolean', description: 'Highlights the row as selected.'},
    ]},
    {name: 'useTableSelection', displayName: 'useTableSelection', description: 'Manages row selection state.',
      params: [{name: 'rows', type: 'T[]', description: 'The rows to track.', required: true}],
      returns: [{name: 'selectedIds', type: 'Set<string>', description: 'Currently selected row ids.'}]},
  ],
};

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.

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).

• SingleComponentDoc: one primary component; put props directly on the doc via props. Use for Switch, Badge, Spinner, TextInput.
• MultiComponentDoc: a directory exporting several components/hooks; list them in components (inline ComponentEntry or name-only ComponentRef). Use for Table, Dialog, TabList.
• SubComponentDoc: a single sub-component in its own {Name}.doc.mjs inside the parent directory; set subComponentOf to the parent name. It inherits family fields and may omit usage.

js
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
  name: 'ChatComposer',
  displayName: 'Chat Composer',
  subComponentOf: 'Chat',
  description: 'The message input row within a Chat, with an editor and send affordance.',
  props: [
    {name: 'onSend', type: '(text: string) => void', description: 'Called when the user submits a message.', required: true},
  ],
};

The stamped format is export default { type: 'component', ... }; legacy docs use export const docs = {...} and omit type (the parser shape-sniffs). A hook that is part of a component API is documented as a ComponentEntry in a MultiComponentDoc components array (with params/returns), not as a standalone HookDoc.

The doc-type for a standalone React hook (e.g. useMediaQuery, useFocusTrap, useOverflow) that gets its own .doc.mjs. Hooks that are part of a component API (e.g. useImperativeDialog) belong in that component's MultiComponentDoc components array instead. HookDoc is the hook-flavored view of the shared type: 'function' kind.

Applies to: {useX}.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
export const docs = {
  type: 'function',
  name: 'useMediaQuery',
  displayName: 'useMediaQuery',
  importPath: '@astryxdesign/core/hooks',
  params: [
    {name: 'query', type: 'string', description: 'A CSS media query, e.g. "(min-width: 768px)".', required: true},
  ],
  returns: [
    {name: 'matches', type: 'boolean', description: 'Whether the query currently matches.'},
  ],
  usage: {
    description:
      'Subscribes to a CSS media query and re-renders when it changes. Use for responsive behavior that CSS alone cannot express, such as swapping components by breakpoint.',
  },
  relatedHooks: ['useIsMobile'],
};

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.

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.

Only standalone hooks get their own file. A hook that is part of a component API is documented as an entry in that component's MultiComponentDoc components array (with params/returns), so it renders under the component.

The generalized type: 'function' doc-type covering both React hooks and CLI/API functions. A hook (HookDoc) is the hook-flavored view of this same kind; FunctionDoc adds the fields an API function needs (a {type, data} return envelope, thrown error codes, the wrapping CLI command). The CLI binding itself lives in a separate CommandDoc.

Applies to: api/<name>/<name>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
export const doc = {
  type: 'function',
  kind: 'api',
  name: 'search',
  displayName: 'search()',
  namespace: 'cli/api',
  importPath: '@astryxdesign/cli/api',
  summary: 'Find components, hooks, docs, and templates by term.',
  signature: 'search(query, options?): Promise<SearchResponse>',
  params: [
    {name: 'query', type: 'string', description: 'The search term.', required: true},
    {name: 'options.type', type: "'component' | 'hook' | 'doc' | 'template'", description: 'Restrict results to one domain.'},
  ],
  returns: [
    {type: 'search', description: 'Envelope with the query and ranked results[].'},
  ],
  throws: [
    {code: 'ERR_INVALID_ARGUMENT', when: 'query is empty.'},
  ],
  examples: [
    {label: 'Basic', code: "await search('button')", result: "{ type: 'search', data: { results: [...] } }"},
  ],
  command: 'search',
};

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.

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.

The two flavors differ in returns: a hook lists named fields (name set), while an API function lists {type, data} envelope entries whose type is the response discriminant and whose name is omitted. throws (keyed to ERROR_CODES) applies to API functions.

The function does not know it has a CLI. The terminal binding (args, flags, exit codes) lives in a separate CommandDoc that references this function via fn; here you only note the wrapping command name via command.

The doc-type for a CLI command: the terminal binding of an operation. A command is not its own behavior; it is a FunctionDoc exposed on the CLI, referenced via fn, carrying only CLI-surface facts (args, flags, subcommands, examples, exit codes). A defineCommand converter turns it into Commander config + --help.

Applies to: clients/cli/commands/<name>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
export const doc = {
  type: 'command',
  name: 'search',
  displayName: 'astryx search',
  summary: 'Find components, hooks, docs, and templates.',
  namespace: 'cli',
  fn: 'search',
  args: [{name: 'query', param: 'query', required: true}],
  options: [
    {flag: '--type <domain>', param: 'options.type', choices: ['component', 'hook', 'doc', 'template']},
    {flag: '--json', cliOnly: true, description: 'Emit the typed JSON envelope.'},
  ],
  examples: [{label: 'Terminal', cli: 'astryx search button --json'}],
  exitCodes: [{code: 1, when: 'The --type value is not a known domain.'}],
  related: ['discover'],
};

A command carries only CLI-surface facts. Behavior, parameters, returns, and thrown errors live in the FunctionDoc it points at via fn; the function does not know it has a CLI.

Bind an arg/option to a function param via param so it inherits that param's description. Use cliOnly: true for flags with no function param (e.g. --json); those must supply their own description.

The doc-type for a closed vocabulary: a fixed set of literal values such as error codes or response-type discriminants. Colocated as a .doc.mjs next to the source of truth it documents.

Applies to: <enum>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').EnumDoc} */
export const doc = {
  type: 'enum',
  name: 'error-codes',
  displayName: 'Error Codes',
  namespace: 'cli',
  description: 'Stable error codes thrown by the CLI/API and surfaced in the JSON envelope.',
  members: [
    {value: 'ERR_UNKNOWN_TOPIC', description: 'The requested docs topic does not exist.'},
    {value: 'ERR_INVALID_ARGUMENT', description: 'A required argument was missing or malformed.'},
    {value: 'ERR_LEGACY', description: 'Old alias.', deprecated: 'Use ERR_INVALID_ARGUMENT.'},
  ],
};

An enum doc is the human-readable mirror of a closed vocabulary defined elsewhere in source (e.g. an ERROR_CODES map or a response-type union). Keep the members in sync with that source of truth.

Mark a value with deprecated (a migration hint) rather than deleting it, so old codes stay documented while readers are pointed at the replacement.

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.

Applies to: <namespace>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
export const docs = {
  type: 'namespace',
  name: 'cli',
  title: 'Astryx CLI',
  summary: 'Commands, APIs, and integration authoring.',
  slots: {
    guides: {title: 'Guides', accepts: {kinds: ['namespace', 'generic']}},
    reference: {
      title: 'Reference',
      accepts: {kinds: ['namespace', 'command']},
    },
  },
  adopts: [{
    source: {group: 'cli-commands', kinds: ['command']},
    into: 'reference',
  }],
};

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.

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.

The doc-type for a reference/topic doc: tokens, principles, theming, patterns, accessibility, migration guides. Unlike ComponentDoc it is not tied to a component: drop a .doc.mjs in the docs directory and it shows up in astryx docs. Content is built from ordered sections of mixed content blocks.

Applies to: assets/docs/<topic>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
export const docs = {
  type: 'generic',
  name: 'spacing',
  title: 'Spacing',
  description: 'Spacing tokens for gap, margin, and padding.',
  category: 'foundations',
  tokenCategory: 'spacing',
  sections: [
    {
      title: 'Spacing Tokens',
      content: [
        {type: 'prose', text: 'Use spacing tokens instead of raw pixel values so layouts stay on the 4px grid.'},
        {type: 'table', headers: ['Token', 'Value'], rows: [['--spacing-4', '16px']]},
      ],
      previewType: 'spacing-bar',
    },
  ],
};

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.

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.

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.

js
{
  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']},
    },
  ],
}

ts
type ReferenceContentBlock =
  | { type: 'prose'; text: string }
  | { type: 'heading'; level: 3 | 4 | 5 | 6; text: string }
  | { 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 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;

A token-ref block (e.g. {type: 'token-ref', topic: 'tokens', section: 'Color Tokens'}) references a token table in another topic; the CLI resolves and inlines it at read time so the docsite can render live theme values.

A section may set previewType to render a visual preview column for token tables: one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.

The doc-type for documenting an authored/received OBJECT shape (astryx.config, a codemod payload, the doc-types themselves). Colocated as a .doc.mjs next to the schema it describes. Fields nest recursively, so a whole shape is one tree.

Applies to: <schema>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
export const doc = {
  type: 'schema',
  name: 'integration',
  displayName: 'Astryx Integration',
  namespace: 'cli',
  description: 'The astryx.integration.* manifest that registers the components a package provides.',
  appliesTo: 'astryx.integration.{ts,mjs,js}',
  fields: [
    {name: 'name', type: 'string', description: 'Package name.', required: true},
    {
      name: 'components',
      type: '{ dir: string }',
      description: 'Where component sources live.',
      fields: [
        {name: 'components.dir', type: 'string', description: 'Glob root for Acme*.tsx files.', required: true},
      ],
    },
  ],
};

SchemaFieldDoc is recursive: an object-typed field lists its members in its own fields, so an entire nested shape (including paths like hooks.postCodemod or experimental.xle.components) is documented as one tree.

Name nested fields with a dotted path from the root (e.g. hooks.postCodemod) so readers can see where each field sits in the shape.

The doc-type for template metadata. A discriminated union of PageTemplateDoc (type: 'page') for full page templates and BlockTemplateDoc (type: 'block') for editable compositions. A block can stand alone or use exampleFor to attach to one component; isShowcase requires that component ownership.

Applies to: <Name>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
export default {
  type: 'page',
  name: 'Dashboard',
  displayName: 'Dashboard',
  description: 'An analytics dashboard with KPI cards and charts.',
  category: 'Dashboard - Analytics',
  isReady: true,
};

js
/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
export default {
  type: 'block',
  name: 'ButtonGroupExample',
  displayName: 'Button Group Example',
  description: 'A row of related buttons showing primary and secondary actions.',
  exampleFor: 'Button',
  aspectRatio: 16 / 9,
  componentsUsed: ['Button', 'HStack'],
  isShowcase: true,
};

When it loads, a template may leave out displayName and aspectRatio and use its own category, as integration templates already published do; a block with no aspectRatio previews at 1. Write to the type anyway; it is the contract.

TemplateDoc is a discriminated union keyed by type. Set type: 'page' for a full page template. Set type: 'block' for an editable composition; add exampleFor only when one component owns the example.

• PageTemplateDoc (type: 'page'): a full page template; name doubles as its display value.
• BlockTemplateDoc (type: 'block'): an editable composition. exampleFor is optional component ownership; omit it for a standalone block. isShowcase requires exampleFor.

category uses the shared TemplateCategory taxonomy: 'Group - Variant' strings (e.g. 'Table - Bulk Actions'). Not every value maps to an existing template; unused values are reserved so authors get autocomplete for the full taxonomy.

The strongly typed descriptor for one integration or CLI-bundled source theme.

Applies to: <theme-source-stem>.doc.mjs

js
/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
export default {
  type: 'theme',
  name: 'ocean',
  displayName: 'Ocean',
  description: 'Cool blue surfaces with crisp contrast.',
  maintained: true,
};

ThemeDoc is static metadata. Default-export one object with literal string and boolean fields; discovery validates it without executing the descriptor or theme source.

The descriptor and source share one stem. For oceanTheme.doc.mjs, discovery requires exactly one oceanTheme source module and a named oceanTheme runtime export.

The parent theme directory, including this descriptor, is the complete copy and pack boundary. Nested source, palettes, assets, and receipts need no second file list.