Template doc overview

Understand what the template doc controls, keep it accurate as the UI changes, and check how Astryx lists the template.

Understand the two files

Every template has a source file and a doc file. For acme-dashboard, the source is templates/acme-dashboard.tsx and the doc is templates/acme-dashboard.doc.mjs. Both begin with acme-dashboard, which is how Astryx knows they belong together.

File	What it controls
`templates/acme-dashboard.tsx`	The UI source that an app copies and then owns.
`templates/acme-dashboard.doc.mjs`	How Astryx names, describes, categorizes, previews, and resolves the template before it is copied.

The integration manifest points Astryx to the templates directory; it does not list each template. Change the source and doc together whenever the purpose, preview, readiness, or replacement behavior changes. No automated check can tell whether the doc still describes the rendered UI.

Document the shared fields

These fields apply to every page and block. The page, block, and replacement guides add the fields unique to each.

Field	Type	Required	Description
type	'page' \| 'block'	yes	Discriminant selecting the variant: 'page' for a full page template, 'block' for an editable composition that may be standalone or component-owned.
name	string	yes	Stable identifier for block templates; change `displayName`, not `name`, to edit their visible label. For page templates it is a human-readable label, while the existing template-directory/CLI slug owns the default registry path.
displayName	string	yes	Human-readable label for the gallery/CLI. Spaces out block names that mirror a PascalCase component ('`ChatMessageMetadata`' → 'Chat Message Metadata').
description	string	no	One-sentence description of what the template provides.
isReady	boolean	no	Whether the template is ready for use. false shows as '(WIP)' in the gallery and CLI.

From TemplateDoc: astryx docs authoring template-doc

Set type to the kind you chose in astryx docs cli/integrations/building-blocks/templates/start-a-template. It decides which other fields the doc accepts.
The file name sets the template id (astryx docs cli/integrations/building-blocks/templates/start-a-template). Labels live in the doc: the terminal list prints name, and JSON listings print displayName. Changing either never changes the id.
Write the description for someone choosing between templates. The Doc metadata category in astryx docs cli/integrations/building-blocks/templates/write-good-templates/template-grading-rubric defines what a complete description covers.
Add isReady: false as soon as you generate the doc, because a doc without isReady is listed as ready. Keep it until the template passes astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app and the quality review.

Check how Astryx lists it

Read the package-scoped template list after every doc change. Confirm the id, visible name, description, type, readiness, and package.

bash
npx astryx --json template --list --package @acme/astryx-templates

Relevant list result

json
{
  "id": "acme-dashboard",
  "name": "acme-dashboard",
  "displayName": "Acme Dashboard",
  "description": "An analytics dashboard for reviewing account health and recent trends.",
  "type": "page",
  "package": "@acme/astryx-templates",
  "isReady": false
}