@astryxdesign/cli 0.1.0 → 0.1.1-canary.a514b99

package/src/commands/agent-docs.test.mjs

@@ -6,6 +6,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import {
   generateCompressedIndex,
+  detectStylingSystem,
   getXdsVersion,
   installAgentDocs,
   injectAgentsMd,
@@ -20,7 +21,7 @@ import {
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-agent-docs-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-test-'));
 });
 
 afterEach(() => {
@@ -32,38 +33,93 @@ describe('generateCompressedIndex', () => {
   it('includes the version number', () => {
     const result = generateCompressedIndex('1.2.3');
     expect(result).toContain('Astryx v1.2.3');
-    expect(result).toContain('<!-- XDS:START -->');
-    expect(result).toContain('<!-- XDS:END -->');
+    expect(result).toContain('<!-- ASTRYX:START -->');
+    expect(result).toContain('<!-- ASTRYX:END -->');
   });
 
   it('includes theme nudge rule', () => {
     const result = generateCompressedIndex('1.0.0');
     expect(result).toMatch(/astryx theme/);
-    expect(result).toMatch(/never override --astryx-color/);
+    expect(result).toMatch(/never override --color-/);
+  });
+
+  it('defaults to the CSS-variable styling path (no compiler)', () => {
+    const result = generateCompressedIndex('1.0.0');
+    expect(result).toMatch(/style\/className with tokens/);
+    expect(result).toMatch(/var\(--color-\*/);
+    // Must NOT push xstyle when no StyleX compiler is present.
+    expect(result).not.toMatch(/xstyle prop/);
+  });
+
+  it('recommends xstyle when StyleX is configured', () => {
+    const result = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});
+    expect(result).toMatch(/xstyle prop \/ StyleX tokens/);
+  });
+
+  it('recommends Tailwind utilities when Tailwind is configured', () => {
+    const result = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});
+    expect(result).toMatch(/Tailwind utilities backed by tokens/);
+    expect(result).toMatch(/tailwind-theme\.css/);
   });
 
   it('includes upgrade command and migration rule', () => {
     const result = generateCompressedIndex('1.0.0');
-    expect(result).toContain('astryx upgrade');
-    expect(result).toContain('astryx upgrade --apply');
-    expect(result).toMatch(/always run .+ astryx upgrade --apply/);
+    expect(result).toContain('upgrade --apply');
+    expect(result).toMatch(/after any @astryxdesign\/core bump/);
   });
 
-  it('uses custom runPrefix when provided', () => {
+  it('states the runPrefix once in the CLI header', () => {
     const result = generateCompressedIndex('1.0.0', {runPrefix: 'yarn'});
-    expect(result).toContain('yarn astryx component <Name>');
-    expect(result).toContain('yarn astryx upgrade --apply');
-    expect(result).toContain('after @astryxdesign/core bump, always run yarn astryx upgrade --apply');
+    expect(result).toContain('yarn astryx <cmd>');
     expect(result).not.toContain('npx astryx');
   });
 
   it('uses pnpm exec prefix', () => {
     const result = generateCompressedIndex('1.0.0', {runPrefix: 'pnpm exec'});
-    expect(result).toContain('pnpm exec astryx component <Name>');
+    expect(result).toContain('pnpm exec astryx <cmd>');
     expect(result).not.toContain('npx astryx');
   });
 });
 
+describe('detectStylingSystem', () => {
+  function writePkg(deps) {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'x', devDependencies: deps}),
+    );
+  }
+
+  it('defaults to css when no package.json', () => {
+    expect(detectStylingSystem(tmpDir)).toBe('css');
+  });
+
+  it('returns css for a plain project', () => {
+    writePkg({react: '19.0.0', vite: '6.0.0'});
+    expect(detectStylingSystem(tmpDir)).toBe('css');
+  });
+
+  it('detects stylex when the compiler plugin is present', () => {
+    writePkg({'@stylexjs/babel-plugin': '0.0.1'});
+    expect(detectStylingSystem(tmpDir)).toBe('stylex');
+  });
+
+  it('detects tailwind when tailwindcss is present', () => {
+    writePkg({tailwindcss: '4.0.0'});
+    expect(detectStylingSystem(tmpDir)).toBe('tailwind');
+  });
+
+  it('does NOT treat the StyleX runtime alone as a compiler', () => {
+    // Only the runtime, no compiler plugin → must stay on the safe css path.
+    writePkg({'@stylexjs/stylex': '0.0.1'});
+    expect(detectStylingSystem(tmpDir)).toBe('css');
+  });
+
+  it('prefers stylex over tailwind when both are configured', () => {
+    writePkg({'@stylexjs/babel-plugin': '0.0.1', tailwindcss: '4.0.0'});
+    expect(detectStylingSystem(tmpDir)).toBe('stylex');
+  });
+});
+
 describe('getXdsVersion', () => {
   it('reads version from core package.json', () => {
     const coreDir = path.join(tmpDir, 'core');
@@ -82,19 +138,19 @@ describe('injectXdsBlock', () => {
     const filePath = path.join(tmpDir, 'test.md');
     fs.writeFileSync(filePath, '# Existing content\n');
 
-    const result = injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->');
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->');
 
     expect(result).toBe(true);
     const content = fs.readFileSync(filePath, 'utf-8');
     expect(content).toContain('# Existing content');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
   });
 
   it('replaces existing markers', () => {
     const filePath = path.join(tmpDir, 'test.md');
     fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');
 
-    injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->');
+    injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->');
 
     const content = fs.readFileSync(filePath, 'utf-8');
     expect(content).toContain('new');
@@ -106,7 +162,7 @@ describe('injectXdsBlock', () => {
   it('returns false and does not create file when createIfMissing is false', () => {
     const filePath = path.join(tmpDir, 'nonexistent.md');
 
-    const result = injectXdsBlock(filePath, '<!-- XDS:START -->\ncontent\n<!-- XDS:END -->');
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\ncontent\n<!-- ASTRYX:END -->');
 
     expect(result).toBe(false);
     expect(fs.existsSync(filePath)).toBe(false);
@@ -116,11 +172,11 @@ describe('injectXdsBlock', () => {
     const filePath = path.join(tmpDir, 'test.md');
     fs.writeFileSync(filePath, '# Existing content\n\nNo XDS markers here.\n');
 
-    const result = injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->', {onlyReplace: true});
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->', {onlyReplace: true});
 
     expect(result).toBe(false);
     const content = fs.readFileSync(filePath, 'utf-8');
-    expect(content).not.toContain('<!-- XDS:START -->');
+    expect(content).not.toContain('<!-- ASTRYX:START -->');
     expect(content).toBe('# Existing content\n\nNo XDS markers here.\n');
   });
 
@@ -128,7 +184,7 @@ describe('injectXdsBlock', () => {
     const filePath = path.join(tmpDir, 'test.md');
     fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');
 
-    const result = injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->', {onlyReplace: true});
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->', {onlyReplace: true});
 
     expect(result).toBe(true);
     const content = fs.readFileSync(filePath, 'utf-8');
@@ -139,7 +195,7 @@ describe('injectXdsBlock', () => {
   it('creates file when createIfMissing is true', () => {
     const filePath = path.join(tmpDir, 'new.md');
 
-    const result = injectXdsBlock(filePath, '<!-- XDS:START -->\ncontent\n<!-- XDS:END -->', {
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\ncontent\n<!-- ASTRYX:END -->', {
       createIfMissing: true,
       header: '# Header',
     });
@@ -147,7 +203,7 @@ describe('injectXdsBlock', () => {
     expect(result).toBe(true);
     const content = fs.readFileSync(filePath, 'utf-8');
     expect(content).toContain('# Header');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
   });
 });
 
@@ -157,9 +213,9 @@ describe('injectAgentsMd', () => {
 
     const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
     expect(content).toContain('# AGENTS.md');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
     expect(content).toContain('Astryx v1.0.0');
-    expect(content).toContain('<!-- XDS:END -->');
+    expect(content).toContain('<!-- ASTRYX:END -->');
   });
 
   it('updates existing AGENTS.md by replacing XDS markers', () => {
@@ -195,7 +251,7 @@ Existing agent docs.
 
     const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
     expect(content).toContain('Existing agent docs.');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
     expect(content).toContain('Astryx v1.0.0');
   });
 });
@@ -210,7 +266,7 @@ describe('injectClaudeMd', () => {
     const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
     expect(content).toContain('# Claude Config');
     expect(content).toContain('Existing rules.');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
     expect(content).toContain('Astryx v1.0.0');
   });
 
@@ -322,7 +378,7 @@ describe('installAgentDocs', () => {
     expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(true);
     expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
     const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
   });
 
   it('injects into CLAUDE.md at root when it exists', () => {
@@ -334,7 +390,7 @@ describe('installAgentDocs', () => {
     expect(written).toEqual(['CLAUDE.md']);
     expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
     const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
-    expect(claudeContent).toContain('<!-- XDS:START -->');
+    expect(claudeContent).toContain('<!-- ASTRYX:START -->');
     expect(claudeContent).toContain('Project rules.');
   });
 
@@ -349,8 +405,8 @@ describe('installAgentDocs', () => {
     expect(written).toContain('CLAUDE.md');
     const agentsContent = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
     const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
-    expect(agentsContent).toContain('<!-- XDS:START -->');
-    expect(claudeContent).toContain('<!-- XDS:START -->');
+    expect(agentsContent).toContain('<!-- ASTRYX:START -->');
+    expect(claudeContent).toContain('<!-- ASTRYX:START -->');
   });
 
   it('updates existing .claude/CLAUDE.md', () => {
@@ -363,7 +419,7 @@ describe('installAgentDocs', () => {
     expect(written).toEqual(['.claude/CLAUDE.md']);
     const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');
     expect(content).toContain('Existing content.');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
   });
 
   it('respects --agent claude preset: finds existing CLAUDE.md', () => {
@@ -410,7 +466,7 @@ describe('installAgentDocs', () => {
 
     expect(written).toEqual([]);
     const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
-    expect(content).not.toContain('<!-- XDS:START -->');
+    expect(content).not.toContain('<!-- ASTRYX:START -->');
     expect(content).toBe('# Claude\n\nProject rules only.\n');
   });
 

package/src/commands/build-theme.import-path.test.mjs

@@ -70,7 +70,7 @@ beforeAll(() => {
 
 let tmpDir;
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-build-theme-import-path-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-import-path-'));
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});

package/src/commands/build-theme.path-safety.test.mjs

@@ -54,7 +54,7 @@ function writeTheme(dir, name) {
 
 let tmpDir;
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-build-theme-paths-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-paths-'));
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});

package/src/commands/build-theme.prose.test.mjs

@@ -82,7 +82,7 @@ beforeAll(() => {
 
 let tmpDir;
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-build-theme-prose-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-prose-'));
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});

package/src/commands/build.mjs

@@ -0,0 +1,196 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build command — the page-building assistant.
+ *
+ * Two modes:
+ *   astryx build                  → the PLAYBOOK: how to build a page with Astryx
+ *   astryx build "<what>"         → a COMPOSITION KIT for what you're building:
+ *                                   the closest page template (scaffold or layout
+ *                                   reference), the blocks that cover parts, and
+ *                                   the components to fill gaps, plus a one-line
+ *                                   "Compose:" suggestion.
+ *
+ * `build` is the opinionated "assemble a page" verb. For a neutral lookup across
+ * the whole CLI, use `astryx search <query>` instead.
+ */
+
+import {getRunPrefix} from '../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {search as searchApi} from '../api/search.mjs';
+
+/** A page scoring at/above this is confident enough to call a direct match. */
+const PAGE_DIRECT = 95;
+/** Below this a page is too weak to even offer as a layout reference. */
+const PAGE_FLOOR = 50;
+/** Below this a block/domain-component match is incidental noise, not surfaced. */
+const DOMAIN_FLOOR = 55;
+
+/**
+ * Always-surfaced primitives. Every page needs a shell + layout/typography/
+ * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
+ * so search alone never returns them. We list them unconditionally so an agent
+ * composing from scratch has the whole kit (esp. off-template).
+ */
+const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
+const FOUNDATION = [
+  'VStack', 'HStack', 'Grid', 'StackItem', 'Card', 'Section',
+  'Text', 'Heading', 'Button', 'Icon', 'Badge', 'Divider',
+];
+const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
+
+/** Print the build playbook (shown when `build` is run with no query). */
+function printPlaybook(run) {
+  const lines = [
+    '',
+    'How to build a page with Astryx',
+    '',
+    "1. Find a starting point for what you're building:",
+    `     ${run} astryx build "<what you're building>"`,
+    '   → returns the closest [page] template, the [block]s that cover parts,',
+    '     and the [component]s to fill the gaps, with a "Compose:" suggestion.',
+    '',
+    '2. If a [page] template matches → scaffold it and adapt:',
+    `     ${run} astryx template <name> [path]`,
+    '',
+    '3. If nothing matches exactly → compose:',
+    `     ${run} astryx template <name> --skeleton   # study a close page's layout`,
+    `     ${run} astryx template <BlockName>         # drop in each block from the kit`,
+    `     ${run} astryx component <Name>             # fill remaining gaps (read props)`,
+    '',
+    '4. Rules (keep it on-system):',
+    '   - No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
+    '   - No style={{}} — use component props; design tokens via `astryx docs tokens`.',
+    '   - Wrap the app in <Theme theme={...}> and import core reset.css + astryx.css.',
+    '',
+    `Tip: \`${run} astryx build "<idea>"\` is the fastest way in. For a neutral`,
+    `lookup of any component/doc/template, use \`${run} astryx search <query>\`.`,
+    '',
+  ];
+  for (const l of lines) humanLog(l);
+}
+
+export function registerBuild(program) {
+  program
+    .command('build [query]')
+    .description('Build a page: composition kit for an idea, or the workflow playbook (no args)')
+    .option('--type <domain>', 'Filter the kit to one domain (component|hook|template)')
+    .option('--limit <n>', 'Max candidates to draw from (default 60)')
+    .option('--detail', 'Verbose output (include import paths and match reason)')
+    .action(async (query, options) => {
+      const run = getRunPrefix();
+      const json = program.opts().json || false;
+
+      // No query → print the playbook (the "how to build" skill).
+      if (!query || !String(query).trim()) {
+        if (json) return jsonOut('build.help', {playbook: true});
+        printPlaybook(run);
+        return;
+      }
+
+      // Default to a deep pool so each role section has candidates after grouping.
+      let limit = 60;
+      if (options.limit != null) {
+        const parsed = Number.parseInt(options.limit, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+          cliError(`Invalid --limit value "${options.limit}". Must be a positive integer.`);
+          return;
+        }
+        limit = parsed;
+      }
+
+      let result;
+      try {
+        result = await searchApi(query, {cwd: process.cwd(), type: options.type, limit});
+      } catch (e) {
+        cliError(e.message, {suggestions: e.suggestions});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      const {query: q, results} = result.data;
+
+      if (results.length === 0) {
+        humanLog('');
+        humanLog(`No matches for "${q}".`);
+        humanLog(`Try a broader term, or browse: ${run} astryx component --list`);
+        humanLog('');
+        return;
+      }
+
+      // ── Group results by role (the build kit) ──────────────────────
+      const pages = results
+        .filter(r => r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR)
+        .slice(0, 3);
+      const blocks = results
+        .filter(r => r.domain === 'template' && r.kind === 'block' && r.score >= DOMAIN_FLOOR)
+        .slice(0, 5);
+      // Idea-specific atoms = matched components/hooks MINUS the always-on kit.
+      const domain = results
+        .filter(r => (r.domain === 'component' || r.domain === 'hook') && r.score >= DOMAIN_FLOOR && !ALWAYS.has(r.name))
+        .slice(0, 6);
+      const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;
+
+      const printItem = (r, label) => {
+        const display = r.domain === 'template' && r.displayName ? r.displayName : r.name;
+        humanLog('');
+        humanLog(`  [${label}] ${display}`);
+        if (r.description) humanLog(`          ${r.description}`);
+        humanLog(`          → ${run} ${r.command}`);
+        if (options.detail) {
+          if (r.import) humanLog(`          import: ${r.import}`);
+          humanLog(`          match: ${r.reason} (score ${r.score})`);
+        }
+      };
+
+      humanLog('');
+      humanLog(`Building "${q}":`);
+
+      // START — the single recommended path.
+      humanLog('');
+      if (directMatch) {
+        humanLog(`START → Scaffold the \`${pages[0].name}\` page template, then adapt: ${run} astryx template ${pages[0].name} ./src/App.tsx`);
+      } else if (pages.length) {
+        humanLog(`START → No exact page template. Use \`${pages[0].name}\` as a layout reference (${run} astryx template ${pages[0].name} --skeleton) and compose the pieces below.`);
+      } else {
+        humanLog(`START → No page template fits. Frame with AppShell and compose the blocks + components below.`);
+      }
+
+      // PAGE
+      if (pages.length) {
+        humanLog('');
+        humanLog(directMatch ? 'PAGE TEMPLATE — direct match:' : 'CLOSEST PAGE TEMPLATES — layout reference:');
+        pages.forEach(p => printItem(p, directMatch ? 'page' : 'closest'));
+      }
+
+      // FRAME — always (the page shell).
+      humanLog('');
+      humanLog(`FRAME — page shell (always): ${FRAME.join(', ')}`);
+      humanLog(`          full-page → AppShell; or Layout + SideNav/TopNav. ${run} astryx component AppShell`);
+
+      // BLOCKS — idea-specific composed patterns.
+      if (blocks.length) {
+        humanLog('');
+        humanLog('BLOCKS — drop-in patterns that cover parts of it:');
+        blocks.forEach(b => printItem(b, 'block'));
+      }
+
+      // DOMAIN COMPONENTS — idea-specific atoms.
+      if (domain.length) {
+        humanLog('');
+        humanLog('DOMAIN COMPONENTS — specific to this idea:');
+        domain.forEach(c => printItem(c, c.domain === 'hook' ? 'hook' : 'component'));
+      }
+
+      // FOUNDATION — always (layout/typography/actions).
+      humanLog('');
+      humanLog(`FOUNDATION — always available (layout/text/actions): ${FOUNDATION.join(' ')}`);
+
+      // SETUP — so it renders / stays on-system.
+      humanLog('');
+      humanLog('SETUP — import "@astryxdesign/core/reset.css" + "astryx.css". No <div>/style for layout — use Stack/Grid + tokens.');
+      humanLog('');
+    });
+}

package/src/commands/component-package.test.mjs

@@ -65,7 +65,7 @@ export const docs = {
 }
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-pkg-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-pkg-test-'));
   createFixture();
 });
 

package/src/commands/component.test.mjs

@@ -18,7 +18,7 @@ import {
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-component-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-component-test-'));
 });
 
 afterEach(() => {

package/src/commands/docs.test.mjs

@@ -10,7 +10,7 @@ import {registerDocs} from './docs.mjs';
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-docs-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-docs-test-'));
   vi.spyOn(console, 'log').mockImplementation(() => {});
   vi.spyOn(console, 'error').mockImplementation(() => {});
 });

package/src/commands/doctor.test.mjs

@@ -26,7 +26,7 @@ let logCalls;
 let exitCode;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-doctor-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-doctor-test-'));
   logCalls = [];
   exitCode = undefined;
   vi.spyOn(console, 'log').mockImplementation((...args) => {

package/src/commands/external-showcase.test.mjs

@@ -78,7 +78,7 @@ export const doc = {
 }
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-showcase-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-showcase-test-'));
   createFixture();
 });
 

package/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;
     }
 
@@ -248,7 +256,7 @@ export function registerInit(program) {
       humanLog('    2. Optionally add a theme:');
       humanLog("       import { neutralTheme } from '@astryxdesign/theme-neutral'");
       humanLog('       <Theme theme={neutralTheme}>...</Theme>');
-      humanLog(`    3. ${run} xds --help for all commands`);
+      humanLog(`    3. ${run} astryx --help for all commands`);
       humanLog('');
     });
 }

package/src/commands/interactive-guard.test.mjs

@@ -35,7 +35,7 @@ function runCli(args) {
 }
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-interactive-guard-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
 });
 
 afterEach(() => {

package/src/commands/json-contract.test.mjs

@@ -53,7 +53,7 @@ function parseJson(stdout) {
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-json-contract-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-json-contract-'));
 });
 
 afterEach(() => {
@@ -177,9 +177,16 @@ describe('--json contract: supported commands emit valid envelopes', () => {
   });
 
   it('astryx upgrade --json (already up to date) emits upgrade.status', () => {
-    // Force a no-op range: from > to.
+    // Force a no-op range: from > installed target.
+    const coreDir = path.join(tmpDir, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(coreDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(coreDir, 'package.json'),
+      JSON.stringify({name: '@astryxdesign/core', version: '0.0.1'}, null, 2),
+    );
+
     const {status, stdout} = runCli(
-      ['upgrade', '--json', '--from', '99.0.0', '--to', '0.0.1'],
+      ['upgrade', '--json', '--from', '99.0.0'],
       {cwd: tmpDir},
     );
     expect(status).toBe(0);

package/src/commands/swizzle-gap-safety.test.mjs

@@ -36,7 +36,7 @@ let markerFile;
 let baseEnv;
 
 beforeAll(() => {
-  shimDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-gh-shim-'));
+  shimDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gh-shim-'));
   markerFile = path.join(shimDir, 'gh-issue-create-was-called.marker');
 
   // Sabotaged `gh` shim. Records ONLY `gh issue create` invocations to the

package/src/commands/swizzle.path-safety.test.mjs

@@ -58,7 +58,7 @@ function runCli(args, cwd) {
 
 let tmpDir;
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-swizzle-paths-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-swizzle-paths-'));
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});

package/src/commands/template.path-safety.test.mjs

@@ -17,7 +17,7 @@ let tmpDir;
 let templateApi;
 
 beforeEach(async () => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-template-paths-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-paths-'));
   templateApi = (await import('../api/template.mjs')).template;
 });
 afterEach(() => {

package/src/commands/template.test.mjs

@@ -12,7 +12,7 @@ import * as os from 'node:os';
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-template-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-test-'));
 });
 
 afterEach(() => {