feat(cli): onboard agents into the build-first workflow (init + agent docs)

.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.
+@joeyfarina

packages/cli/src/commands/agent-docs.mjs

@@ -121,14 +121,29 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
   lines.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 = getRunPre
   lines.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`);
 

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;
     }