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

package/assets/docs/tree/extend-or-replace.doc.mjs

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/docs/extend-or-replace`: take over an
+ * existing topic with `replaces`, merge sections into one with `extends`, and
+ * check overlaps with Core topics.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'extend-or-replace',
+  placement: {parent: 'namespace:docs', slot: 'guides', order: 40},
+  title: 'Extend or replace a topic',
+  category: 'guide',
+  description: 'Take over a topic, or merge sections into it.',
+  sections: [
+    {
+      id: 'replace-a-topic',
+      title: 'Replace a topic',
+      content: [
+        {
+          type: 'prose',
+          text: "Set `replaces` to take over an existing topic, such as Core's `getting-started`. Readers who open the old name get your topic.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx integration add doc acme-getting-started --replaces getting-started\n# The old name now opens your topic\nnpx astryx docs getting-started',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'docs/acme-getting-started.doc.mjs',
+          code: "export default {\n  type: 'generic',\n  name: 'acme-getting-started',\n  replaces: 'getting-started',\n  title: 'Acme getting started',\n  description: 'Install Acme widgets and render your first carousel.',\n  sections: [/* ... */],\n};",
+        },
+        {
+          type: 'prose',
+          text: 'The docs list shows your topic in place of the old one. Because your topic has its own `name`, the old name keeps resolving to it, so links and agents that learned the old name still land on your topic.',
+        },
+      ],
+    },
+    {
+      id: 'extend-a-topic',
+      title: 'Extend a topic',
+      content: [
+        {
+          type: 'prose',
+          text: 'Set `extends` to merge sections into an existing topic instead of owning it. A section with the same key replaces the base section, and a new section is added at the end.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx integration add doc acme-theming --extends theme\nnpx astryx docs theme --index',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'docs/acme-theming.doc.mjs',
+          code: "export default {\n  type: 'generic',\n  name: 'acme-theming',\n  extends: 'theme',\n  title: 'Acme theming',\n  description: 'Theme an app that uses Acme widgets.',\n  sections: [\n    {id: 'quick-start', title: 'Quick Start', content: [/* replaces the base section */]},\n    {id: 'use-the-ocean-theme', title: 'Use the ocean theme', content: [/* added at the end */]},\n  ],\n};",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "A section's key is its `id`, or a key made from its title. Read the base topic's keys with `--index`.",
+            "The topic keeps the base's title and description, and readers open it by the base's name.",
+            'Replace the `Overview` placeholder that `integration add` writes, or it is added to the base topic.',
+            "Extend a topic to correct or add to it. A copy made with `replaces` stops getting the owner's fixes.",
+          ],
+        },
+      ],
+    },
+    {
+      id: 'check-overlaps-with-core-topics',
+      title: 'Check overlaps with Core topics',
+      content: [
+        {
+          type: 'prose',
+          text: "A topic sets `replaces` or `extends`, never both, and a placed guide sets neither. A topic that uses a Core topic's name with neither is an accidental conflict: apps keep reading the Core topic.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx doctor integration docs',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'severity:     [info]\ntopic:        acme-getting-started\nrelationship: replaces\ncoreTopic:    getting-started\nmessage:      Intentional override: "acme-getting-started" replaces the Core topic "getting-started".\n\nseverity:     [fail]\ntopic:        tokens\nrelationship: accidental\ncoreTopic:    tokens\nmessage:      Accidental conflict: "tokens" is already a Core topic. Rename it, declare replaces: \'tokens\' to take it over, or declare extends: \'tokens\' to merge sections.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'An intentional overlap prints as `[info]`. An accidental one fails with exit code 1.',
+            'A topic that sets both fails as `invalid_doc`, and so does a placed guide that sets either one.',
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/fonts-and-assets.doc.mjs

@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/fonts-and-assets`:
+ * name a theme's fonts, and have the app load them (Astryx never loads a font).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'fonts-and-assets',
+  placement: {parent: 'namespace:themes', slot: 'guides', order: 35},
+  title: 'Fonts',
+  category: 'guide',
+  description:
+    'Name your theme\'s fonts in its tokens, then have the app load them — Astryx never loads a font file.',
+  sections: [
+    {
+      id: 'name-the-font',
+      title: 'Name the font',
+      content: [
+        {
+          type: 'prose',
+          text: 'A theme names its typefaces in `typography`: `body`, `heading`, and `code`, each with a `family` and `fallbacks`. These set the `--font-family-*` tokens every component reads. Always give real `fallbacks` so text stays readable before the font loads, or if it never does. `heading` inherits `family` and `fallbacks` from `body` when you omit them.',
+        },
+        {
+          type: 'code',
+          lang: 'ts',
+          code: `// themes/ocean/oceanTheme.ts
+export const oceanTheme = defineTheme({
+  name: 'ocean',
+  typography: {
+    body: {family: 'Acme Sans', fallbacks: 'system-ui, sans-serif'},
+    code: {family: 'Acme Mono', fallbacks: 'ui-monospace, monospace'},
+  },
+  // ...your tokens
+});`,
+        },
+        {
+          type: 'prose',
+          text: 'The full type scale and font roles are in {@link generic:theme}.',
+        },
+      ],
+    },
+    {
+      id: 'load-the-font-in-the-app',
+      title: 'Load the font in the app',
+      content: [
+        {
+          type: 'prose',
+          text: 'Naming a family does not load it — Astryx never downloads a font file. The app that uses your theme loads the font itself, so your job is to tell your users which families and weights to load, in your theme\'s docs ({@link generic:document-the-theme}). An app loads a font one of two ways:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Link a hosted stylesheet in the app\'s `<head>` — for example a Google Fonts `<link>` covering every weight the UI uses.',
+            'Self-host: serve the font files and add an `@font-face` for each weight and style to the app\'s global CSS.',
+          ],
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          code: `/* In the app's global CSS, when self-hosting */
+@font-face {
+  font-family: 'Acme Sans';
+  src: url('/fonts/acme-sans.woff2') format('woff2');
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153;
+}`,
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Load every weight and style the theme uses. Do not let the browser synthesize bold or italic — include the italic face, with the same `unicode-range`s as the roman.',
+            'Set a `unicode-range` per face so the browser downloads only the subsets it needs.',
+            'Use `font-display: swap` unless a measured need justifies another value.',
+            'Serve WOFF2; add another format only when a target browser needs it.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'verify-in-an-app',
+      title: 'Verify in an app',
+      content: [
+        {
+          type: 'prose',
+          text: 'Before publishing, install the package in a clean app, apply the theme, load the fonts, and open it in a browser. The source and the applied result are not the same thing until you look.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Text renders in the named families at every weight and style — the italic face resolves, not a synthesized slant.',
+            'Every font request succeeds; nothing silently falls back to a system font.',
+            'Color pairs still meet contrast in both light and dark mode.',
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/generate-a-palette.doc.mjs

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/generate-a-palette`:
+ * turn a few seed colors into a full light and dark color palette.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'generate-a-palette',
+  placement: {parent: 'namespace:themes', slot: 'guides', order: 20},
+  title: 'Generate a palette',
+  category: 'guide',
+  description:
+    'Turn a few seed colors into full light and dark color ramps, saved in the theme folder.',
+  sections: [
+    {
+      id: 'generate-a-palette',
+      title: 'Generate a palette',
+      content: [
+        {
+          type: 'prose',
+          text: 'A theme needs dozens of related colors — shades of each brand color for backgrounds, borders, text, and states, in both light and dark mode. A palette is that full set of shades. Rather than hand-pick every one, you name a few seed colors and generate the rest, so the shades stay consistent and keep enough contrast to read.',
+        },
+        {
+          type: 'prose',
+          text: 'You write a short config naming each color family and its seed, then run `theme palette generate`. It expands each seed into a full light and dark ramp — the scale of shades — and writes the result into the theme folder, where your theme tokens point at it (see {@link generic:define-the-theme}). Keep the config and the generated palette together in that folder.',
+        },
+        {
+          type: 'prose',
+          text: 'The smallest config is one color family: an `id` to name it and a `seed` color to grow it from. Save it as `themes/ocean/palette.config.json`:',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          code: '{"families": [{"id": "ocean", "seed": "#0074e2"}]}',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `# Print the palette without writing files
+npx astryx theme palette generate themes/ocean/palette.config.json
+# Write the palette and its receipt
+npx astryx theme palette generate themes/ocean/palette.config.json \\
+  --out themes/ocean/tokens/ocean.palette.ts`,
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: `[ok] Wrote themes/ocean/tokens/ocean.palette.ts
+
+[ok] Wrote themes/ocean/tokens/ocean.palette.receipt.json`,
+        },
+        {
+          type: 'prose',
+          text: 'The command writes two files. `ocean.palette.ts` is the palette your theme tokens will read: it exports `black`, `white`, and `palette` — a ramp of 21 shades (stops `0` to `100`) for both `light` and `dark`. The `.receipt.json` beside it records the exact seeds and settings, so you can regenerate the same palette later. A second run leaves both files alone unless you pass `--overwrite`.',
+        },
+        {
+          type: 'prose',
+          text: 'Add `--preview <file>.html` to also get a web page showing every shade, so you can eyeball the palette in a browser. Write it outside `themes/` so it does not ship in your package. The full list of config fields and options is in {@link command:theme palette generate}.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/grade-template-with-agent.doc.mjs

@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/templates/grade-template-with-agent`:
+ * give an agent the canonical rubric and require a reproducible template grade.
+ */
+
+import {TEMPLATE_RUBRIC} from './template-grading-rubric.doc.mjs';
+
+const scorecardRows = TEMPLATE_RUBRIC.categories
+  .map(({title, max}) => `| ${title} | X | ${max} | |`)
+  .join('\n');
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'grade-template-with-agent',
+  placement: {parent: 'namespace:write-good-templates', slot: 'guides', order: 20},
+  title: 'Grade and improve with an agent',
+  category: 'guide',
+  description:
+    'Give an agent the rubric and evidence it needs to find problems, produce a reproducible scorecard, and improve the template.',
+  sections: [
+    {
+      id: 'give-the-agent-the-rubric',
+      title: 'Give the agent the rubric',
+      content: [
+        {
+          type: 'prose',
+          text: `Grade one exact package revision against template rubric ${TEMPLATE_RUBRIC.version}. Give the agent the template id, the package name, and a clean app that can install the packed package, then use this prompt. Replace every angle-bracket value. The first pass is read-only so the original score and findings stay visible.`,
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          label: 'Agent grading prompt',
+          code: `Grade integration template <id> from <package> at <revision>.
+
+Before scoring:
+1. Read \`npx astryx docs cli/integrations/building-blocks/templates/write-good-templates --full\`.
+2. Read \`npx astryx docs cli/integrations/building-blocks/templates/write-good-templates/template-grading-rubric --full\` and every guide it links.
+3. Inspect the template source, its matching .doc.mjs file, package.json exports and files, and astryx.integration.mjs.
+4. Run \`npx astryx integration verify\` in the package.
+5. Follow \`npx astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app --full\`: install the packed package in the clean app, copy the template, build the app, and render the behavior matrix.
+
+Score all seven rubric categories. Cite file and line evidence for every deduction. Do not award points for a state you did not inspect. If browser or build evidence is unavailable, say so and mark the template not publishable.
+
+Return the rubric version, package revision, numeric score, letter grade, category scorecard, publishable yes/no verdict, detailed findings, and the top three fixes. Treat 100 as the target. Name every remaining deduction and say whether it is an intentional tradeoff or still needs work. Do not edit files during this first pass.`,
+        },
+      ],
+    },
+    {
+      id: 'require-a-scorecard',
+      title: 'Require a scorecard',
+      content: [
+        {
+          type: 'code',
+          lang: 'markdown',
+          code: `# Template grade: <id>
+
+**Rubric:** ${TEMPLATE_RUBRIC.version}
+**Package revision:** <revision>
+**Type:** page | block
+**Grade:** <letter> (<score>/100)
+**Publishable:** yes | no
+
+| Category | Points | Max | Evidence |
+| --- | ---: | ---: | --- |
+${scorecardRows}
+| **Total** | **X** | **100** | |
+
+## Detailed findings
+- <file:line, rubric rule, observed problem, and deduction>
+
+## Publication blockers
+- <failed pack, copy, build, asset, browser, theme, responsive, or input check>
+
+## Top three fixes
+1. <highest-value fix>
+2. <second fix>
+3. <third fix>`,
+        },
+        {
+          type: 'prose',
+          text: `The category scores must add exactly to the total, and the grade comes from the published bands. The verdict is \`yes\` only when the score is ${TEMPLATE_RUBRIC.minimumScore} or higher and every package, copy, build, asset, and rendered-app check passes.`,
+        },
+      ],
+    },
+    {
+      id: 'improve-and-regrade',
+      title: 'Improve and regrade',
+      content: [
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Fix publication blockers first.',
+            'Fix every reasonable deduction without hiding it behind helper components or package CSS.',
+            'Pack again, copy into a fresh app, and have the agent repeat the full grade. Keep the earlier scorecard so the improvement is visible.',
+            'Stop only when no reasonable fix remains, and record every intentional tradeoff that still costs points.',
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/help.doc.mjs

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @file astryx docs cli/integrations/help — find a CLI message and its fix. */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'help',
+  placement: {parent: 'namespace:integrations', slot: 'guides', order: 40},
+  title: 'Help',
+  summary: 'Find a CLI message and how to fix it.',
+  keywords: ['help', 'troubleshooting', 'error'],
+  slots: {
+    guides: {title: 'Help', accepts: {kinds: ['generic']}},
+  },
+};

package/assets/docs/tree/integrations.doc.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @file astryx docs cli/integrations — build an integration package. */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'integrations',
+  placement: {parent: 'namespace:cli', slot: 'guides', order: 10},
+  title: 'Build an integration',
+  summary:
+    'Build an npm package that adds components, templates, themes, docs, and codemods to Astryx apps.',
+  keywords: [
+    'integration',
+    'integration package',
+    'make an integration',
+    'publish an integration',
+    'integration authoring',
+  ],
+  slots: {
+    guides: {
+      title: 'Build an integration',
+      accepts: {kinds: ['generic', 'namespace']},
+    },
+  },
+  blocks: [
+    {
+      type: 'prose',
+      text: 'An integration is a way to share things with Astryx users: a package you own and maintain, built on a framework Astryx gives you. Publish one, many, or any mix, and people install it in one step. It works with the Astryx CLI alongside Core. See each kind under {@link namespace:building-blocks}.',
+    },
+    {
+      type: 'prose',
+      text: 'For example, ship a carousel as an integration. Any app that installs it can find it with `npx astryx search carousel`, and the CLI uses it like any Astryx Core component.',
+    },
+    {
+      type: 'prose',
+      text: 'An integration can also replace a built-in template or doc. To start, install `@astryxdesign/cli` and open {@link generic:quick-start}.',
+    },
+  ],
+};

package/assets/docs/tree/links.doc.mjs

@@ -0,0 +1,98 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/docs/links`: link one doc to another by
+ * identity, link the CLI's docs, and fix a link that names no doc.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'links',
+  placement: {parent: 'namespace:docs', slot: 'guides', order: 30},
+  title: 'Links',
+  category: 'guide',
+  description:
+    'Link one doc to another so the link keeps working when the doc moves.',
+  sections: [
+    {
+      id: 'link-another-doc',
+      title: 'Link another doc',
+      content: [
+        {
+          type: 'prose',
+          text: 'Write `{@link [provider:]kind:name}` in prose, list items, and table cells to link another doc. The CLI prints the command that opens it, so the link keeps working when the doc moves.',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "{type: 'prose', text: 'Before you ship, read {@link generic:deploying}.'},\n{type: 'list', style: 'unordered', items: ['All guides: {@link namespace:acme}.']},\n{type: 'table', headers: ['Task', 'Guide'], rows: [['Ship', '{@link generic:deploying}']]},",
+        },
+        {
+          type: 'prose',
+          text: 'Each link reads as a command. This link, {@link generic:extend-or-replace}, opens the next guide.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'The kind is `generic` for a topic or guide, `namespace` for a docs section, and `command` or `function` for a CLI command or API function.',
+            'A link to a component or a template does not resolve. Write its name in backticks instead, such as `AcmeCarousel`.',
+            'Inside backticks or a code block, link syntax prints as written.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'link-another-packages-docs',
+      title: "Link another package's docs",
+      content: [
+        {
+          type: 'prose',
+          text: "A link without a provider resolves against your own package. To link the CLI's docs, or another package's, start the target with that package's name, such as `@astryxdesign/cli:`.",
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "// Resolves: the CLI's doctor command\n{type: 'prose', text: 'Check the app with {@link @astryxdesign/cli:command:doctor}.'},\n// Does not resolve: looks for a doctor command in your package\n{type: 'prose', text: 'Check the app with {@link command:doctor}.'},",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Name a CLI command the way you type it, spaces included, such as `@astryxdesign/cli:command:doctor integration docs`.',
+            "In a topic that `extends` another package's topic, your sections still resolve against your package, so a link to the base topic's docs needs its provider.",
+          ],
+        },
+      ],
+    },
+    {
+      id: 'fix-a-link-that-names-no-doc',
+      title: 'Fix a link that names no doc',
+      content: [
+        {
+          type: 'prose',
+          text: 'A link that names no doc prints as written, and `doctor integration docs` warns. The warning names a search that finds the right target.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx doctor integration docs',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'severity: [warn]\ncode:     invalid_doc_graph\nmessage:  acme/deploying § check-before-you-ship: "command:doctor" names no doc. Find it with `astryx search doctor --type doc`, then name it as `[<provider>:]<kind>:<name>`.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'The warning keeps exit code 0, so read the report before you ship; see {@link generic:check-your-docs}.',
+            'A stable CLI before 0.7.0 does not read links: it prints each one as written. See {@link generic:versioning}.',
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/package-and-test.doc.mjs

@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/package-and-test`:
+ * expose a template from its package and prove the copied result in an app.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'package-and-test',
+  placement: {
+    parent: 'namespace:build-the-template',
+    slot: 'guides',
+    order: 30,
+  },
+  title: 'Package and test',
+  summary:
+    'Publish a package that works the first time: include everything the template needs, check the package before you publish, and try the template in a real app.',
+  keywords: [
+    'template export',
+    'package template',
+    'integration verify',
+    'test template',
+  ],
+  slots: {
+    guides: {
+      title: 'Guides',
+      accepts: {kinds: ['generic']},
+    },
+  },
+};

package/assets/docs/tree/page-template.doc.mjs

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/document-the-template/page-template`:
+ * the page-only fields that help people find a page.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'page-template',
+  placement: {
+    parent: 'namespace:document-the-template',
+    slot: 'guides',
+    order: 20,
+  },
+  title: 'Page template',
+  category: 'guide',
+  description:
+    'Help people find a page: give it a category for `astryx search` and template listings, and flag a sparse starting shell as a scaffold.',
+  sections: [
+    {
+      id: 'start-from-the-generated-page-doc',
+      title: 'Start from the generated page doc',
+      content: [
+        {
+          type: 'prose',
+          text: '`integration add template` writes a page doc by default. Replace its sample description, then add the page-only fields below.',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'templates/acme-dashboard.doc.mjs',
+          code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+  type: 'page',
+  name: 'acme-dashboard',
+  displayName: 'Acme Analytics Dashboard',
+  description:
+    'A filterable account-health dashboard with headline metrics, trends, and a recent-activity table. Dashboard, reporting, analytics, or status overview.',
+  category: 'Dashboard - Analytics',
+  isReady: false,
+};`,
+        },
+      ],
+    },
+    {
+      id: 'help-people-find-the-page',
+      title: 'Help people find the page',
+      content: [
+        {
+          type: 'reference',
+          target: 'schema:template-doc',
+          projection: {
+            fields: ['category', 'scaffold'],
+          },
+          presentation: 'full',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Set `category` to the most specific supported `{Group} - {Variant}` value. Its words become search terms for `astryx search`, and it appears in the JSON template list.',
+            'Set `scaffold: true` only for a deliberately sparse starting shell. The JSON template list reports it, so tools and galleries can tell a scaffold from a finished page.',
+            "Fields that only Astryx's own gallery reads, such as `isHiddenFromOverview`, have no effect on integration templates.",
+          ],
+        },
+      ],
+    },
+  ],
+};