An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): build-first agent docs + restructured init output (#3098)
Joeyf891eff6ef31
diff --git a/.changeset/cli-build-first-docs.md b/.changeset/cli-build-first-docs.mdnew file mode 100644index 0000000000..e0b169e06c--- /dev/null+++ b/.changeset/cli-build-first-docs.md@@ -0,0 +1,12 @@+---+'@astryxdesign/cli': patch+---++[feat] Make generated agent docs build-first and restructure `init` output.++The generated `CLAUDE.md` now leads with the `build` workflow (search reframed as+a neutral universal find), and includes a required-CSS setup note+(`reset.css` + `astryx.css`) so components never render unstyled. `init` now+points agents at `astryx build`/`astryx search` instead of dumping page-template+names.+@joeyfarinadiff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjsindex a97cd22881..3ea352ee82 100644--- a/packages/cli/src/commands/agent-docs.mjs+++ b/packages/cli/src/commands/agent-docs.mjs@@ -121,14 +121,29 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPrelines.push(`Astryx v${version} — ${componentCount} components`);lines.push('');- // Behavioral workflow — templates first, then component lookup+ // One-time project setup — components ship precompiled CSS that MUST be+ // imported, or everything renders unstyled. Stated as text (the CLI does not+ // edit your files). The Theme provider is OPTIONAL (a default theme ships in+ // astryx.css); only the CSS imports are required.+ lines.push('SETUP (required, once) — in your app entry (e.g. main.tsx):');+ lines.push(' import "@astryxdesign/core/reset.css";');+ lines.push(' import "@astryxdesign/core/astryx.css";');+ lines.push('Without these CSS imports, components render completely unstyled.');+ lines.push(`Optional: apply a specific theme with <Theme> — see \`${run} docs theme\`.`);+ lines.push('');++ // Behavioral workflow — `build` is the front door for making pages: it returns+ // a composition kit, and `build` with no args prints the full how-to playbook.lines.push('Before writing any UI code:');- lines.push(`1. \`${run} template --list\` — find a related page pattern`);- lines.push(`2. \`${run} template <name> --skeleton\` — study layout structure (gap, padding, nesting)`);- lines.push(`3. \`${run} component <Name>\` — read props + examples for EVERY component you use`);+ lines.push(+ `1. \`${run} build "<what you're building>"\` — START HERE. Returns a composition kit: the closest [page] recipe (scaffold it, or use as a layout reference), the [block]s that cover parts, and the [component]s to fill gaps. (Run \`${run} build\` with no args for the full how-to-build playbook.)`,+ );+ lines.push(`2. \`${run} template <name> --skeleton\` — scaffold a matched [page], or study its layout (gap, padding, nesting)`);+ lines.push(`3. \`${run} template <BlockName>\` — drop in each [block] the kit surfaced (ready-made multi-component patterns) instead of hand-building`);+ lines.push(`4. \`${run} component <Name>\` — read props + examples for EVERY component you use`);lines.push('');- lines.push('Templates are reference code — read them for composition patterns, not just scaffolding.');- lines.push('Full pages → dashboard (uses AppShell). Forms → contact-form. Tables → data-table. Settings → settings-sidebar.');+ lines.push('Templates and blocks are reference code — read them for composition patterns, not just scaffolding.');+ lines.push(`(\`${run} search <query>\` is a neutral find across components/hooks/docs/templates when you just need to look something up.)`);lines.push('');// Rules — inline, compact, prevents the top error categories@@ -141,6 +156,8 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPrelines.push('');// CLI quick reference+ lines.push(`${run} build "<idea>" START HERE for pages — kit: closest page + blocks + components (\`build\` = how-to playbook)`);+ lines.push(`${run} search "<query>" find anything: components, hooks, docs, templates, blocks`);lines.push(`${run} component --list ${componentCount} components by category`);lines.push(`${run} component <Name> props, types, examples`);diff --git a/packages/cli/src/commands/init.mjs b/packages/cli/src/commands/init.mjsindex a58df0ad2c..f2afa0e96a 100644--- a/packages/cli/src/commands/init.mjs+++ b/packages/cli/src/commands/init.mjs@@ -100,7 +100,15 @@ async function runTemplate(targetDir, {interactive = true, templateName} = {}) {if (!interactive) {if (!templateName) {- humanLog(`✓ Available templates: ${templates.join(', ')}. Use ${run} astryx template <name> [path].`);+ // Point agents at the build workflow rather than dumping page-template+ // names — `build` surfaces pages AND blocks AND components for an idea,+ // and `build` with no args is the full how-to-build playbook.+ humanLog('✓ To build UI, use these commands:');+ humanLog('');+ humanLog(` ${run} astryx build "<what you're building>" build a page — kit: closest template + blocks + components`);+ humanLog(` ${run} astryx build the how-to-build workflow (read this first)`);+ humanLog(` ${run} astryx search <query> find anything — components, docs, templates, blocks`);+ humanLog('');return;}