@astryxdesign/cli 0.1.7-canary.fb9c68c → 0.1.7

package/docs/working-with-ai.doc.mjs

@@ -34,7 +34,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/cli and run `npx @astryxdesign/cli init --features agents` to set up your Astryx context. Read the generated file.',
+          code: 'Install @astryxdesign/cli and run `npx astryx init --features agents` to set up your Astryx context. Read the generated file.',
         },
         {
           type: 'prose',
@@ -48,9 +48,9 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Manual options',
-          code: `npx @astryxdesign/cli init --features agents --agent claude    # CLAUDE.md
-npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules
-npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)`,
+          code: `npx astryx init --features agents --agent claude    # CLAUDE.md
+npx astryx init --features agents --agent cursor    # .cursorrules
+npx astryx init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)`,
         },
       ],
     },
@@ -65,9 +65,9 @@ npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copi
           type: 'list',
           style: 'ordered',
           items: [
-            '`astryx template --list`: find a related page pattern to use as reference',
-            '`astryx template <name> --skeleton`: study the layout structure',
-            '`astryx component <Name>`: read props and examples for every component used',
+            '`npx astryx template --list`: find a related page pattern to use as reference',
+            '`npx astryx template <name> --skeleton`: study the layout structure',
+            '`npx astryx component <Name>`: read props and examples for every component used',
           ],
         },
         {
@@ -88,7 +88,7 @@ npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copi
           lang: 'bash',
           label: 'Install as a Cursor user rule',
           code: `mkdir -p ~/.cursor/rules
-npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
+npx astryx init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
         },
       ],
     },
@@ -109,12 +109,12 @@ npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/x
 2. How do you make an Dialog non-dismissible?
 3. What prop does Selector use for its items?
 
-If you don't know all three, run \`npx @astryxdesign/cli init --features agents\` to generate agent docs, then read the generated file.`,
+If you don't know all three, run \`npx astryx init --features agents\` to generate agent docs, then read the generated file.`,
         },
       ],
     },
     {
-      title: 'The astryx Pattern',
+      title: 'The npx astryx Pattern',
       content: [
         {
           type: 'prose',
@@ -130,16 +130,16 @@ If you don't know all three, run \`npx @astryxdesign/cli init --features agents\
         },
         {
           type: 'prose',
-          text: 'With this alias, agents use `astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
+          text: 'With this alias, agents use `npx astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Reliable CLI invocation',
-          code: `astryx component --list
-astryx component Dialog --dense
-astryx docs styling --dense
-astryx docs tokens --dense`,
+          code: `npx astryx component --list
+npx astryx component Dialog --dense
+npx astryx docs styling --dense
+npx astryx docs tokens --dense`,
         },
       ],
     },
@@ -154,9 +154,9 @@ astryx docs tokens --dense`,
           type: 'code',
           lang: 'bash',
           label: 'Dense output for pasting into AI conversations',
-          code: `astryx component Dialog --dense
-astryx docs styling --dense
-astryx docs tokens --dense`,
+          code: `npx astryx component Dialog --dense
+npx astryx docs styling --dense
+npx astryx docs tokens --dense`,
         },
       ],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.7-canary.fb9c68c",
+  "version": "0.1.7",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -67,22 +67,22 @@
   "files": [
     "bin",
     "src",
-    "scripts/postinstall.mjs",
     "templates",
     "docs",
     "CHANGELOG.md"
   ],
   "dependencies": {
+    "@clack/prompts": "^1.7.0",
     "commander": "^12.1.0",
     "jiti": "^2.7.0",
     "jscodeshift": "^17.3.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.7-canary.fb9c68c",
-    "@astryxdesign/core": "0.1.7-canary.fb9c68c",
-    "@astryxdesign/lab": "0.1.7-canary.fb9c68c",
-    "@astryxdesign/theme-neutral": "0.1.7-canary.fb9c68c",
+    "@astryxdesign/charts": "*",
+    "@astryxdesign/core": "*",
+    "@astryxdesign/lab": "*",
+    "@astryxdesign/theme-neutral": "*",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -100,15 +100,14 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.7-canary.fb9c68c",
-    "@astryxdesign/core": "0.1.7-canary.fb9c68c",
-    "@astryxdesign/lab": "0.1.7-canary.fb9c68c",
-    "@astryxdesign/theme-neutral": "0.1.7-canary.fb9c68c",
+    "@astryxdesign/charts": "*",
+    "@astryxdesign/core": "*",
+    "@astryxdesign/lab": "*",
+    "@astryxdesign/theme-neutral": "*",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",
-    "postinstall": "node scripts/postinstall.mjs",
     "typecheck:template-docs": "tsc --project tsconfig.template-docs.json",
     "typecheck:json-api": "tsc --project tsconfig.json-api.json && tsc --project tsconfig.api-contract.json"
   }

package/src/api/doctor.mjs

@@ -26,7 +26,7 @@ import {createRequire} from 'node:module';
 
 import {MIN_NODE_VERSION, isNodeVersionSupported} from '../lib/node-version.mjs';
 import {CLI_ROOT, findCoreDir} from '../utils/paths.mjs';
-import {detectPackageManager, getCliInvocation} from '../utils/package-manager.mjs';
+import {detectPackageManager} from '../utils/package-manager.mjs';
 import {findConfigPath, Project} from '../lib/project.mjs';
 import {semverCompare} from '../utils/semver.mjs';
 
@@ -343,7 +343,7 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'info',
       message: 'No agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.',
-      fix: `Generate agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      fix: 'Generate agent docs with `astryx init --features agents`.',
     };
   }
 
@@ -365,7 +365,7 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'warn',
       message: `Agent docs present (${present.join(', ')}) but no Astryx section markers found.`,
-      fix: `Add the Astryx section to your agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      fix: 'Add the Astryx section to your agent docs with `astryx init --features agents`.',
     };
   }
 

package/src/codemods/ensure-jscodeshift.mjs

@@ -3,15 +3,16 @@
 /**
  * @file Lazy jscodeshift installer
  *
- * Checks if jscodeshift is available and installs it on-demand.
+ * Checks if jscodeshift is available and offers to install it on-demand.
  * Keeps the CLI lean — jscodeshift is only needed for codemods.
  *
- * Non-interactive by default (no prompts): pass `installDeps: true` to
- * auto-install, otherwise the command fails fast with a helpful error.
+ * In non-interactive environments (CI, LLM agents), the interactive prompt
+ * is skipped. Pass `installDeps: true` to auto-install without prompting,
+ * or the command will fail with a helpful error message.
  */
 
 import {execSync} from 'node:child_process';
-import * as p from '../lib/term-log.mjs';
+import * as p from '@clack/prompts';
 import {detectPackageManager} from '../utils/package-manager.mjs';
 
 /**
@@ -29,17 +30,32 @@ export async function ensureJscodeshift({installDeps = false, silent = false} =
   } catch {
     log.warn('jscodeshift is required for codemods but not installed.');
 
+    const isInteractive = process.stdout.isTTY && !process.env.CI;
+
     if (installDeps) {
-      // Explicit opt-in — install without prompting.
+      // Explicit opt-in — install without prompting
       return installJscodeshift(silent);
     }
 
-    // Non-interactive by default: fail fast with a helpful message instead of
-    // prompting (the CLI never blocks on a TTY).
-    log.error(
-      'Cannot run codemods without jscodeshift. Use --install-deps to auto-install.',
-    );
-    return false;
+    if (!isInteractive || silent) {
+      // Non-interactive environment (or --json) — fail fast with a helpful message
+      log.error(
+        'Cannot run codemods without jscodeshift. ' +
+          'Use --install-deps to auto-install in non-interactive environments.',
+      );
+      return false;
+    }
+
+    // Interactive TTY — prompt as before
+    const shouldInstall = await p.confirm({
+      message: 'Install jscodeshift now?',
+      initialValue: true,
+    });
+    if (p.isCancel(shouldInstall) || !shouldInstall) {
+      p.log.error('Cannot run codemods without jscodeshift.');
+      return false;
+    }
+    return installJscodeshift(silent);
   }
 }
 

package/src/codemods/run-codemod.mjs

@@ -29,7 +29,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as p from '../lib/term-log.mjs';
+import * as p from '@clack/prompts';
 import {findConfigPath} from '../lib/project.mjs';
 import {fixDirectiveCorruption, validateOutput} from './runner.mjs';
 

package/src/codemods/runner.mjs

@@ -10,7 +10,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as p from '../lib/term-log.mjs';
+import * as p from '@clack/prompts';
 import {humanLog} from '../lib/json.mjs';
 import {runConfigCodemod} from './run-codemod.mjs';
 
@@ -184,7 +184,7 @@ export async function runCodemods(
   versionManifests,
   {apply, path: srcPath, codemod, skipCodemods, silent = false},
 ) {
-  // No-op stub object so silent mode skips log output entirely without
+  // No-op stub object so silent mode skips clack stdout entirely without
   // littering the body with `if (!silent)` guards.
   const log = silent
     ? {step() {}, info() {}, success() {}, warn() {}, error() {}, message() {}}

package/src/commands/agent-docs.mjs

@@ -22,7 +22,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';
 import {assertWithin, PathSafetyError} from '../utils/path-safety.mjs';
-import {getCliInvocation} from '../utils/package-manager.mjs';
+import {getRunPrefix} from '../utils/package-manager.mjs';
 import {discoverComponents} from '../lib/component-discovery.mjs';
 import {humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
@@ -31,9 +31,6 @@ import {ERROR_CODES} from '../lib/error-codes.mjs';
 const AGENTS_MD = 'AGENTS.md';
 const CLAUDE_MD = 'CLAUDE.md';
 const CLAUDE_DIR_MD = '.claude/CLAUDE.md'; // cross-platform literal
-const CURSOR_RULES = '.cursorrules';
-const HERMES_DOT_MD = '.hermes.md';
-const HERMES_MD = 'HERMES.md';
 
 
 const MARKER_START = '<!-- ASTRYX:START -->';
@@ -48,60 +45,20 @@ const LEGACY_MARKER_END = '<!-- XDS:END -->';
  */
 const AGENT_PRESETS = {
   claude: [CLAUDE_MD, CLAUDE_DIR_MD],
-  cursor: [CURSOR_RULES, AGENTS_MD],
+  cursor: ['.cursorrules', AGENTS_MD],
   codex: [AGENTS_MD],
-  hermes: [HERMES_DOT_MD, HERMES_MD, AGENTS_MD],
+  hermes: ['.hermes.md', 'HERMES.md', AGENTS_MD],
 };
 
 /**
- * The canonical set of EVERY location an --agent preset (or the default) can
- * write the Astryx block. SINGLE SOURCE OF TRUTH: discovery, removal, and the
- * `isAstryxInitialized` predicate all derive from this list, so "where init
- * writes" and "where we look" can never drift. (Explicit --agent-docs-path
- * targets are user-chosen and not enumerable here.)
- */
-const AGENT_DOC_PATHS = [
-  AGENTS_MD, // Codex / ChatGPT / generic
-  CLAUDE_MD, // Claude Code (root)
-  CLAUDE_DIR_MD, // Claude Code (.claude/CLAUDE.md)
-  CURSOR_RULES, // Cursor
-  HERMES_DOT_MD, // Hermes
-  HERMES_MD, // Hermes
-];
-
-/**
- * Find all existing agent doc files in a directory, across EVERY location any
- * preset can write (see {@link AGENT_DOC_PATHS}: AGENTS.md, CLAUDE.md,
- * .claude/CLAUDE.md, .cursorrules, .hermes.md, HERMES.md).
+ * Find all existing agent doc files in a directory.
+ * Searches all known locations (AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, .cursorrules).
  * @param {string} targetDir
  * @returns {string[]} Relative paths of existing agent doc files
  */
 export function discoverAgentDocs(targetDir) {
-  return AGENT_DOC_PATHS.filter(p => fs.existsSync(path.join(targetDir, p)));
-}
-
-/**
- * Single source of truth for "is Astryx set up in this project?" — true when any
- * agent-doc file already carries the Astryx marker, i.e. `init` / `agent-docs`
- * has run. Reused by the init & upgrade commands, the per-command setup nudge
- * (enforcement layer 3), and the cli postinstall nudge (layer 2). Core's
- * postinstall (separate package, layer 1) mirrors the same marker contract.
- *
- * @param {string} [targetDir=process.cwd()]
- * @returns {boolean}
- */
-export function isAstryxInitialized(targetDir = process.cwd()) {
-  for (const rel of discoverAgentDocs(targetDir)) {
-    try {
-      const content = fs.readFileSync(path.join(targetDir, rel), 'utf-8');
-      if (content.includes(MARKER_START) || content.includes(LEGACY_MARKER_START)) {
-        return true;
-      }
-    } catch {
-      // Unreadable file — ignore and keep checking the others.
-    }
-  }
-  return false;
+  const allPaths = [AGENTS_MD, CLAUDE_MD, CLAUDE_DIR_MD, '.cursorrules'];
+  return allPaths.filter(p => fs.existsSync(path.join(targetDir, p)));
 }
 
 /**
@@ -187,8 +144,8 @@ export function detectStylingSystem(targetDir) {
  * configured (see {@link detectStylingSystem}) so the agent never reaches for a
  * styling path that isn't compiled here.
  */
-export function generateCompressedIndex(version, {coreDir, invocation = getCliInvocation(), stylingSystem = 'css'} = {}) {
-  const run = invocation;
+export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPrefix(), stylingSystem = 'css'} = {}) {
+  const run = `${runPrefix} astryx`;
   const lines = [MARKER_START];
 
   // Component count from live discovery
@@ -435,7 +392,7 @@ export function removeAgentDocs(targetDir) {
 
 /**
  * Programmatic entry point for installing agent docs.
- * Used by the init command, upgrade command, and agent-docs command.
+ * Used by the init wizard, upgrade command, and agent-docs command.
  *
  * Strategy (when no agent/paths specified):
  * - Discover all existing agent doc files and update them
@@ -453,9 +410,9 @@ export function removeAgentDocs(targetDir) {
 export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onlyReplace = false} = {}) {
   const coreDir = findCoreDir(targetDir);
   const version = getXdsVersion(coreDir);
-  const invocation = getCliInvocation(targetDir);
+  const runPrefix = getRunPrefix(targetDir);
   const stylingSystem = detectStylingSystem(targetDir);
-  const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, invocation, stylingSystem});
+  const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, runPrefix, stylingSystem});
   const written = [];
 
   // Explicit paths override everything
@@ -581,7 +538,8 @@ export function registerAgentDocs(program) {
         throw err;
       }
 
-      const run = getCliInvocation(targetDir);
+      const runPrefix = getRunPrefix(targetDir);
+      const run = `${runPrefix} astryx`;
 
       for (const t of targets) {
         humanLog(`✓ ${t}`);

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

@@ -88,24 +88,17 @@ describe('generateCompressedIndex', () => {
     expect(result).toMatch(/after any @astryxdesign\/core bump/);
   });
 
-  it('states the invocation once in the CLI header (yarn)', () => {
-    const result = generateCompressedIndex('1.0.0', {invocation: 'yarn astryx'});
+  it('states the runPrefix once in the CLI header', () => {
+    const result = generateCompressedIndex('1.0.0', {runPrefix: 'yarn'});
     expect(result).toContain('yarn astryx <cmd>');
     expect(result).not.toContain('npx astryx');
   });
 
-  it('uses the pnpm exec invocation', () => {
-    const result = generateCompressedIndex('1.0.0', {invocation: 'pnpm exec astryx'});
+  it('uses pnpm exec prefix', () => {
+    const result = generateCompressedIndex('1.0.0', {runPrefix: 'pnpm exec'});
     expect(result).toContain('pnpm exec astryx <cmd>');
     expect(result).not.toContain('npx astryx');
   });
-
-  it('uses the scoped package for one-off (uninstalled) runs so agents never hit the bare name', () => {
-    const result = generateCompressedIndex('1.0.0', {invocation: 'npx @astryxdesign/cli'});
-    expect(result).toContain('npx @astryxdesign/cli <cmd>');
-    // The header defines the mapping; the bare "run every command as `npx astryx`" footgun must be absent.
-    expect(result).not.toContain('npx astryx <cmd>');
-  });
 });
 
 describe('detectStylingSystem', () => {

package/src/commands/build-theme.mjs

@@ -8,8 +8,8 @@
  * - An updated JS module that references the built className
  *
  * Usage:
- *   astryx theme build ./src/themes/ocean.ts
- *   astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css
+ *   npx astryx theme build ./src/themes/ocean.ts
+ *   npx astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css
  */
 
 import * as fs from 'node:fs';
@@ -17,15 +17,16 @@ import * as path from 'node:path';
 import {pathToFileURL, fileURLToPath} from 'node:url';
 import {spawn} from 'node:child_process';
 import {createJiti} from 'jiti';
-import {getCliInvocation} from '../utils/package-manager.mjs';
+import {getRunPrefix} from '../utils/package-manager.mjs';
 import {
   sanitizeName,
   PathSafetyError,
+  isNonInteractive,
 } from '../utils/path-safety.mjs';
 import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {themeAdd} from '../api/theme-add.mjs';
+import {themeAdd, listThemes} from '../api/theme-add.mjs';
 
 // Import shared theme processing from core. `astryx theme build` MUST produce the
 // exact same CSS as the `<Theme>` runtime, so it has exactly one generation
@@ -499,7 +500,7 @@ function generateBuiltModule(themeDef, iconInfo) {
     .join('\n');
 
   return `${iconImport}/**
- * ${themeDef.name} theme — built by \`${getCliInvocation()} theme build\`
+ * ${themeDef.name} theme — built by \`${getRunPrefix()} astryx theme build\`
  * Import the CSS file alongside this module:
  *
  *   import { ${toIdentifier(themeDef.name)}Theme } from './${themeDef.name}';
@@ -1129,7 +1130,7 @@ Or with a <link> tag:
         if (t.description) humanLog(`    ${t.description}`);
       }
       humanLog('\nUsage:');
-      humanLog(`  ${getCliInvocation()} theme add <slug> [target-path]   Scaffold a theme file you own\n`);
+      humanLog('  astryx theme add <slug> [target-path]   Scaffold a theme file you own\n');
     });
 
   theme
@@ -1140,9 +1141,32 @@ Or with a <link> tag:
     .action(async (slug, targetPath, options) => {
       const json = program.opts().json || false;
 
-      // The CLI is non-interactive: never prompt to confirm an overwrite.
-      // Existing files require an explicit --overwrite; otherwise themeAdd's
-      // ERR_FILE_EXISTS guard rejects the write.
+      // Only prompt with a real TTY on stdin — a piped/redirected stdin would
+      // make clack hang. Non-interactive callers fall through to the API's
+      // ERR_FILE_EXISTS guard.
+      const interactive =
+        !json && !isNonInteractive({json}) && Boolean(process.stdin.isTTY);
+      if (slug && !options.list && !options.overwrite && interactive) {
+        const collision = await detectThemeCollision(slug, targetPath);
+        if (collision) {
+          const rel = path.relative(process.cwd(), collision) || collision;
+          const p = await import('@clack/prompts');
+          const confirmed = await p.confirm({
+            message: `Overwrite existing file ${rel}?`,
+            initialValue: false,
+          });
+          if (p.isCancel(confirmed)) {
+            p.cancel('Cancelled.');
+            return;
+          }
+          if (!confirmed) {
+            humanLog('Aborted. Re-run with --overwrite to replace the file.');
+            return;
+          }
+          options.overwrite = true;
+        }
+      }
+
       let result;
       try {
         result = await themeAdd(slug, {
@@ -1167,7 +1191,7 @@ Or with a <link> tag:
           if (t.description) humanLog(`    ${t.description}`);
         }
         humanLog('\nUsage:');
-        humanLog(`  ${getCliInvocation()} theme add <slug> [target-path]   Scaffold a theme file you own\n`);
+        humanLog('  astryx theme add <slug> [target-path]   Scaffold a theme file you own\n');
         return;
       }
 
@@ -1195,3 +1219,40 @@ This is your copy of the ${displayName} theme — edit ${entry} to make it your
     });
 }
 
+/**
+ * First existing file that scaffolding <slug> into <targetPath> would clobber,
+ * or null. Used to prompt before invoking the API; the API re-validates and
+ * owns any authoritative error.
+ *
+ * @param {string} slug
+ * @param {string} [targetPath]
+ * @returns {Promise<string|null>}
+ */
+async function detectThemeCollision(slug, targetPath) {
+  let themes;
+  try {
+    themes = listThemes();
+  } catch {
+    return null;
+  }
+  const match = themes.find(t => t.slug.toLowerCase() === slug.toLowerCase());
+  if (!match) return null;
+
+  const rawTarget = targetPath || path.join('src', 'themes', match.slug);
+  let resolvedDir;
+  try {
+    // Fail soft (null) on traversal; the API surfaces the real error.
+    const {assertWithin} = await import('../utils/path-safety.mjs');
+    resolvedDir = assertWithin(rawTarget, process.cwd(), {
+      label: 'theme target path',
+    });
+  } catch {
+    return null;
+  }
+
+  for (const name of match.files) {
+    const dest = path.join(resolvedDir, name);
+    if (fs.existsSync(dest)) return dest;
+  }
+  return null;
+}

package/src/commands/build.mjs

@@ -15,7 +15,7 @@
  * the whole CLI, use `astryx search <query>` instead.
  */
 
-import {getCliInvocation, formatCliCommand} from '../utils/package-manager.mjs';
+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';
@@ -47,25 +47,25 @@ function printPlaybook(run) {
     'How to build a page with Astryx',
     '',
     "1. Find a starting point for what you're building:",
-    `     ${run} build "<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} template <name> [path]`,
+    `     ${run} astryx template <name> [path]`,
     '',
     '3. If nothing matches exactly → compose:',
-    `     ${run} template <name> --skeleton   # study a close page's layout`,
-    `     ${run} template <BlockName>         # drop in each block from the kit`,
-    `     ${run} component <Name>             # fill remaining gaps (read props)`,
+    `     ${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 \`${run} docs tokens\`.`,
+    '   - 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} build "<idea>"\` is the fastest way in. For a neutral`,
-    `lookup of any component/doc/template, use \`${run} search <query>\`.`,
+    `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);
@@ -79,7 +79,7 @@ export function registerBuild(program) {
     .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 = getCliInvocation();
+      const run = getRunPrefix();
       const json = program.opts().json || false;
 
       // No query → print the playbook (the "how to build" skill).
@@ -115,7 +115,7 @@ export function registerBuild(program) {
       if (results.length === 0) {
         humanLog('');
         humanLog(`No matches for "${q}".`);
-        humanLog(`Try a broader term, or browse: ${run} component --list`);
+        humanLog(`Try a broader term, or browse: ${run} astryx component --list`);
         humanLog('');
         return;
       }
@@ -138,7 +138,7 @@ export function registerBuild(program) {
         humanLog('');
         humanLog(`  [${label}] ${display}`);
         if (r.description) humanLog(`          ${r.description}`);
-        humanLog(`          → ${formatCliCommand(r.command)}`);
+        humanLog(`          → ${run} ${r.command}`);
         if (options.detail) {
           if (r.import) humanLog(`          import: ${r.import}`);
           humanLog(`          match: ${r.reason} (score ${r.score})`);
@@ -151,9 +151,9 @@ export function registerBuild(program) {
       // START — the single recommended path.
       humanLog('');
       if (directMatch) {
-        humanLog(`START → Scaffold the \`${pages[0].name}\` page template, then adapt: ${run} template ${pages[0].name} ./src/App.tsx`);
+        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} template ${pages[0].name} --skeleton) and compose the pieces below.`);
+        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.`);
       }
@@ -168,7 +168,7 @@ export function registerBuild(program) {
       // FRAME — always (the page shell).
       humanLog('');
       humanLog(`FRAME — page shell (always): ${FRAME.join(', ')}`);
-      humanLog(`          full-page → AppShell; or Layout + SideNav/TopNav. ${run} component AppShell`);
+      humanLog(`          full-page → AppShell; or Layout + SideNav/TopNav. ${run} astryx component AppShell`);
 
       // BLOCKS — idea-specific composed patterns.
       if (blocks.length) {