@astryxdesign/cli 0.1.6-canary.ff5dfca → 0.1.7-canary.04cd8f7

package/docs/theme.doc.mjs

@@ -148,7 +148,7 @@ function App() {
           type: 'code',
           lang: 'bash',
           label: 'Scaffold with CLI',
-          code: 'npx astryx theme',
+          code: 'astryx theme',
         },
       ],
     },
@@ -287,7 +287,7 @@ const brandTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'Run `npx astryx component <Name>` to see a component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
+          text: 'Run `astryx component <Name>` to see a component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
         },
         {
           type: 'list',
@@ -361,13 +361,13 @@ const brandTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: '`npx astryx theme build` compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint.',
+          text: '`astryx theme build` compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Build a theme',
-          code: 'npx astryx theme build ./src/themes/ocean.ts',
+          code: 'astryx theme build ./src/themes/ocean.ts',
         },
         {
           type: 'prose',
@@ -432,7 +432,7 @@ import './themes/ocean.css';
             [
               'Import (custom theme)',
               'defineTheme() directly',
-              "Built .js + .css from `npx astryx theme build`",
+              "Built .js + .css from `astryx theme build`",
             ],
             [
               'How it works',
@@ -462,7 +462,7 @@ import './themes/ocean.css';
           items: [
             'Use the /built subpath + theme.css for production SSR apps.',
             'Use runtime themes during development for fast iteration.',
-            'Run `npx astryx theme build` for custom themes to get the built artifacts.',
+            'Run `astryx theme build` for custom themes to get the built artifacts.',
           ],
         },
         {
@@ -610,7 +610,7 @@ function ChartConfig() {
         },
         {
           type: 'prose',
-          text: 'See `npx astryx docs styling-libraries` for styling-library interop and `npx astryx docs tokens` for the full token reference.',
+          text: 'See `astryx docs styling-libraries` for styling-library interop and `astryx docs tokens` for the full token reference.',
         },
       ],
     },

package/docs/theme.doc.zh.mjs

@@ -10,7 +10,7 @@ export const docsZh = {
     { section: 'Theme Props', title: 'Theme 属性', content: [null] },
     { section: 'Creating a Custom Theme', title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导（推荐）或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },
     { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },
-    { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'npx astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js（__built:true）+ .d.ts。' }, null, null, null, null] },
+    { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js（__built:true）+ .d.ts。' }, null, null, null, null] },
     { section: 'Runtime vs Built Themes', title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时：useInsertionEffect 在客户端注入样式。构建：静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },
     { section: 'Light/Dark Mode', title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'（默认）跟随系统偏好。" }, null, null] },
     { section: 'Nesting Themes', title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },

package/docs/tokens.doc.mjs

@@ -1068,7 +1068,7 @@ export const docs = {
         },
         {
           "type": "prose",
-          "text": "See `npx astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `npx astryx docs theme` for overriding tokens with defineTheme."
+          "text": "See `astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `astryx docs theme` for overriding tokens with defineTheme."
         }
       ]
     }

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 astryx init --features agents` to set up your Astryx context. Read the generated file.',
+          code: 'Install @astryxdesign/cli and run `npx @astryxdesign/cli 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 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.)`,
+          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.)`,
         },
       ],
     },
@@ -65,9 +65,9 @@ npx astryx init --features agents --agent codex     # AGENTS.md (Copilot, Codex,
           type: 'list',
           style: 'ordered',
           items: [
-            '`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',
+            '`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',
           ],
         },
         {
@@ -88,7 +88,7 @@ npx astryx init --features agents --agent codex     # AGENTS.md (Copilot, Codex,
           lang: 'bash',
           label: 'Install as a Cursor user rule',
           code: `mkdir -p ~/.cursor/rules
-npx astryx init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
+npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
         },
       ],
     },
@@ -109,12 +109,12 @@ npx astryx init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
 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 astryx init --features agents\` to generate agent docs, then read the generated file.`,
+If you don't know all three, run \`npx @astryxdesign/cli init --features agents\` to generate agent docs, then read the generated file.`,
         },
       ],
     },
     {
-      title: 'The npx astryx Pattern',
+      title: 'The astryx Pattern',
       content: [
         {
           type: 'prose',
@@ -130,16 +130,16 @@ If you don't know all three, run \`npx astryx init --features agents\` to genera
         },
         {
           type: 'prose',
-          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.',
+          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.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Reliable CLI invocation',
-          code: `npx astryx component --list
-npx astryx component Dialog --dense
-npx astryx docs styling --dense
-npx astryx docs tokens --dense`,
+          code: `astryx component --list
+astryx component Dialog --dense
+astryx docs styling --dense
+astryx docs tokens --dense`,
         },
       ],
     },
@@ -154,9 +154,9 @@ npx astryx docs tokens --dense`,
           type: 'code',
           lang: 'bash',
           label: 'Dense output for pasting into AI conversations',
-          code: `npx astryx component Dialog --dense
-npx astryx docs styling --dense
-npx astryx docs tokens --dense`,
+          code: `astryx component Dialog --dense
+astryx docs styling --dense
+astryx docs tokens --dense`,
         },
       ],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.6-canary.ff5dfca",
+  "version": "0.1.7-canary.04cd8f7",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -72,17 +72,16 @@
     "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.6-canary.ff5dfca",
-    "@astryxdesign/core": "0.1.6-canary.ff5dfca",
-    "@astryxdesign/lab": "0.1.6-canary.ff5dfca",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.ff5dfca",
+    "@astryxdesign/charts": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/core": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/lab": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/theme-neutral": "0.1.7-canary.04cd8f7",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -100,10 +99,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.ff5dfca",
-    "@astryxdesign/core": "0.1.6-canary.ff5dfca",
-    "@astryxdesign/lab": "0.1.6-canary.ff5dfca",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.ff5dfca",
+    "@astryxdesign/charts": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/core": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/lab": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/theme-neutral": "0.1.7-canary.04cd8f7",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

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} from '../utils/package-manager.mjs';
+import {detectPackageManager, getCliInvocation} 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 `astryx init --features agents`.',
+      fix: `Generate agent docs with \`${getCliInvocation(ctx.cwd)} 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 `astryx init --features agents`.',
+      fix: `Add the Astryx section to your agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
     };
   }
 

package/src/codemods/ensure-jscodeshift.mjs

@@ -3,16 +3,15 @@
 /**
  * @file Lazy jscodeshift installer
  *
- * Checks if jscodeshift is available and offers to install it on-demand.
+ * Checks if jscodeshift is available and installs it on-demand.
  * Keeps the CLI lean — jscodeshift is only needed for codemods.
  *
- * 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.
+ * Non-interactive by default (no prompts): pass `installDeps: true` to
+ * auto-install, otherwise the command fails fast with a helpful error.
  */
 
 import {execSync} from 'node:child_process';
-import * as p from '@clack/prompts';
+import * as p from '../lib/term-log.mjs';
 import {detectPackageManager} from '../utils/package-manager.mjs';
 
 /**
@@ -30,32 +29,17 @@ 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);
     }
 
-    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);
+    // 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;
   }
 }
 

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 '@clack/prompts';
+import * as p from '../lib/term-log.mjs';
 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 '@clack/prompts';
+import * as p from '../lib/term-log.mjs';
 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 clack stdout entirely without
+  // No-op stub object so silent mode skips log output 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 {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} 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';
@@ -144,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, runPrefix = getRunPrefix(), stylingSystem = 'css'} = {}) {
-  const run = `${runPrefix} astryx`;
+export function generateCompressedIndex(version, {coreDir, invocation = getCliInvocation(), stylingSystem = 'css'} = {}) {
+  const run = invocation;
   const lines = [MARKER_START];
 
   // Component count from live discovery
@@ -392,7 +392,7 @@ export function removeAgentDocs(targetDir) {
 
 /**
  * Programmatic entry point for installing agent docs.
- * Used by the init wizard, upgrade command, and agent-docs command.
+ * Used by the init command, upgrade command, and agent-docs command.
  *
  * Strategy (when no agent/paths specified):
  * - Discover all existing agent doc files and update them
@@ -410,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 runPrefix = getRunPrefix(targetDir);
+  const invocation = getCliInvocation(targetDir);
   const stylingSystem = detectStylingSystem(targetDir);
-  const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, runPrefix, stylingSystem});
+  const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, invocation, stylingSystem});
   const written = [];
 
   // Explicit paths override everything
@@ -538,8 +538,7 @@ export function registerAgentDocs(program) {
         throw err;
       }
 
-      const runPrefix = getRunPrefix(targetDir);
-      const run = `${runPrefix} astryx`;
+      const run = getCliInvocation(targetDir);
 
       for (const t of targets) {
         humanLog(`✓ ${t}`);

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

@@ -88,17 +88,24 @@ describe('generateCompressedIndex', () => {
     expect(result).toMatch(/after any @astryxdesign\/core bump/);
   });
 
-  it('states the runPrefix once in the CLI header', () => {
-    const result = generateCompressedIndex('1.0.0', {runPrefix: 'yarn'});
+  it('states the invocation once in the CLI header (yarn)', () => {
+    const result = generateCompressedIndex('1.0.0', {invocation: 'yarn astryx'});
     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'});
+  it('uses the pnpm exec invocation', () => {
+    const result = generateCompressedIndex('1.0.0', {invocation: 'pnpm exec astryx'});
     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:
- *   npx astryx theme build ./src/themes/ocean.ts
- *   npx astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css
+ *   astryx theme build ./src/themes/ocean.ts
+ *   astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css
  */
 
 import * as fs from 'node:fs';
@@ -17,16 +17,15 @@ import * as path from 'node:path';
 import {pathToFileURL, fileURLToPath} from 'node:url';
 import {spawn} from 'node:child_process';
 import {createJiti} from 'jiti';
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation} 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, listThemes} from '../api/theme-add.mjs';
+import {themeAdd} 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
@@ -500,7 +499,7 @@ function generateBuiltModule(themeDef, iconInfo) {
     .join('\n');
 
   return `${iconImport}/**
- * ${themeDef.name} theme — built by \`${getRunPrefix()} astryx theme build\`
+ * ${themeDef.name} theme — built by \`${getCliInvocation()} theme build\`
  * Import the CSS file alongside this module:
  *
  *   import { ${toIdentifier(themeDef.name)}Theme } from './${themeDef.name}';
@@ -1130,7 +1129,7 @@ Or with a <link> tag:
         if (t.description) humanLog(`    ${t.description}`);
       }
       humanLog('\nUsage:');
-      humanLog('  astryx theme add <slug> [target-path]   Scaffold a theme file you own\n');
+      humanLog(`  ${getCliInvocation()} theme add <slug> [target-path]   Scaffold a theme file you own\n`);
     });
 
   theme
@@ -1141,32 +1140,9 @@ Or with a <link> tag:
     .action(async (slug, targetPath, options) => {
       const json = program.opts().json || false;
 
-      // 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;
-        }
-      }
-
+      // 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.
       let result;
       try {
         result = await themeAdd(slug, {
@@ -1191,7 +1167,7 @@ Or with a <link> tag:
           if (t.description) humanLog(`    ${t.description}`);
         }
         humanLog('\nUsage:');
-        humanLog('  astryx theme add <slug> [target-path]   Scaffold a theme file you own\n');
+        humanLog(`  ${getCliInvocation()} theme add <slug> [target-path]   Scaffold a theme file you own\n`);
         return;
       }
 
@@ -1219,40 +1195,3 @@ 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 {getRunPrefix} from '../utils/package-manager.mjs';
+import {getCliInvocation, formatCliCommand} 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} astryx build "<what you're building>"`,
+    `     ${run} 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]`,
+    `     ${run} 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)`,
+    `     ${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)`,
     '',
     '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`.',
+    `   - No style={{}} — use component props; design tokens via \`${run} 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>\`.`,
+    `Tip: \`${run} build "<idea>"\` is the fastest way in. For a neutral`,
+    `lookup of any component/doc/template, use \`${run} 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 = getRunPrefix();
+      const run = getCliInvocation();
       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} astryx component --list`);
+        humanLog(`Try a broader term, or browse: ${run} component --list`);
         humanLog('');
         return;
       }
@@ -138,7 +138,7 @@ export function registerBuild(program) {
         humanLog('');
         humanLog(`  [${label}] ${display}`);
         if (r.description) humanLog(`          ${r.description}`);
-        humanLog(`          → ${run} ${r.command}`);
+        humanLog(`          → ${formatCliCommand(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} astryx template ${pages[0].name} ./src/App.tsx`);
+        humanLog(`START → Scaffold the \`${pages[0].name}\` page template, then adapt: ${run} 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.`);
+        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.`);
       } 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} astryx component AppShell`);
+      humanLog(`          full-page → AppShell; or Layout + SideNav/TopNav. ${run} component AppShell`);
 
       // BLOCKS — idea-specific composed patterns.
       if (blocks.length) {