@astryxdesign/cli 0.1.7-canary.cc83e7a → 0.1.7-canary.d91c851

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';
@@ -31,6 +31,9 @@ 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 -->';
@@ -45,20 +48,132 @@ const LEGACY_MARKER_END = '<!-- XDS:END -->';
  */
 const AGENT_PRESETS = {
   claude: [CLAUDE_MD, CLAUDE_DIR_MD],
-  cursor: ['.cursorrules', AGENTS_MD],
+  cursor: [CURSOR_RULES, AGENTS_MD],
   codex: [AGENTS_MD],
-  hermes: ['.hermes.md', 'HERMES.md', AGENTS_MD],
+  hermes: [HERMES_DOT_MD, HERMES_MD, AGENTS_MD],
 };
 
 /**
- * Find all existing agent doc files in a directory.
- * Searches all known locations (AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, .cursorrules).
+ * 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).
  * @param {string} targetDir
  * @returns {string[]} Relative paths of existing agent doc files
  */
 export function discoverAgentDocs(targetDir) {
-  const allPaths = [AGENTS_MD, CLAUDE_MD, CLAUDE_DIR_MD, '.cursorrules'];
-  return allPaths.filter(p => fs.existsSync(path.join(targetDir, p)));
+  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;
+}
+
+/**
+ * Parse the Astryx version a managed block was generated for, from its header
+ * line ("Astryx v1.2.3 · N components"). Returns null when the block predates
+ * the versioned header (e.g. a legacy XDS block) or has no header at all.
+ *
+ * @param {string} content File contents, or just the block text.
+ * @returns {string|null}
+ */
+export function parseBlockVersion(content) {
+  const match = /Astryx v(\d+\.\d+\.\d+[^\s·]*)/.exec(content ?? '');
+  return match ? match[1] : null;
+}
+
+/**
+ * Read-only staleness assessment of the managed agent-docs block(s) against the
+ * installed core version. This is the detection half of the `astryx upgrade`
+ * agent-docs refresh: it never writes, so `upgrade` can run it on EVERY path —
+ * including the up-to-date / no-codemods short-circuits — and decide whether to
+ * rewrite a stale block, nudge an uninitialized repo, or stay silent.
+ *
+ * A managed block is:
+ * - `stale`   — it carries a legacy XDS marker, has no parseable version, or
+ *               records a version other than the installed one.
+ * - `current` — every managed block already matches the installed version.
+ * And the project is `missing` when no managed block exists anywhere (the repo
+ * has agent-doc files without our markers, or none at all — i.e. never `init`ed).
+ *
+ * @param {string} targetDir
+ * @param {string} [installedVersion] Defaults to the installed core version.
+ * @returns {{
+ *   installedVersion: string,
+ *   status: 'missing' | 'stale' | 'current',
+ *   files: Array<{path: string, blockVersion: string|null, legacy: boolean, stale: boolean}>,
+ *   staleFiles: string[],
+ *   blockVersions: string[],
+ * }}
+ */
+export function inspectAgentDocs(targetDir, installedVersion) {
+  const version = installedVersion ?? getXdsVersion(findCoreDir(targetDir));
+  const files = [];
+
+  for (const rel of discoverAgentDocs(targetDir)) {
+    let content;
+    try {
+      content = fs.readFileSync(path.join(targetDir, rel), 'utf-8');
+    } catch {
+      continue; // Unreadable — treat as absent.
+    }
+    const hasNew = content.includes(MARKER_START);
+    const hasLegacy = content.includes(LEGACY_MARKER_START);
+    if (!hasNew && !hasLegacy) continue; // Not a block we manage.
+
+    const legacy = !hasNew && hasLegacy;
+    const blockVersion = parseBlockVersion(content);
+    const stale = legacy || blockVersion == null || blockVersion !== version;
+    files.push({path: rel, blockVersion, legacy, stale});
+  }
+
+  const staleEntries = files.filter(f => f.stale);
+  const staleFiles = staleEntries.map(f => f.path);
+  const blockVersions = [
+    ...new Set(staleEntries.map(f => f.blockVersion).filter(Boolean)),
+  ];
+
+  let status;
+  if (files.length === 0) status = 'missing';
+  else if (staleFiles.length > 0) status = 'stale';
+  else status = 'current';
+
+  return {installedVersion: version, status, files, staleFiles, blockVersions};
 }
 
 /**
@@ -144,8 +259,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 +507,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 +525,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 +653,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

@@ -16,6 +16,8 @@ import {
   removeXdsBlock,
   discoverAgentDocs,
   resolveAgentPaths,
+  parseBlockVersion,
+  inspectAgentDocs,
 } from './agent-docs.mjs';
 
 let tmpDir;
@@ -88,17 +90,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', () => {
@@ -602,3 +611,87 @@ describe('resolveAgentPaths', () => {
     expect(result).toEqual({inject: [], create: ['.claude/CLAUDE.md']});
   });
 });
+
+describe('parseBlockVersion', () => {
+  it('reads the version from the header of a generated block', () => {
+    expect(parseBlockVersion(generateCompressedIndex('1.2.3'))).toBe('1.2.3');
+  });
+
+  it('reads prerelease versions', () => {
+    expect(parseBlockVersion('Astryx v1.2.3-beta.4 · 10 components')).toBe(
+      '1.2.3-beta.4',
+    );
+  });
+
+  it('returns null when no versioned header is present', () => {
+    expect(parseBlockVersion('<!-- XDS:START -->\nold\n<!-- XDS:END -->')).toBeNull();
+    expect(parseBlockVersion('')).toBeNull();
+    expect(parseBlockVersion(undefined)).toBeNull();
+  });
+});
+
+describe('inspectAgentDocs', () => {
+  function writeBlock(rel, version) {
+    const filePath = path.join(tmpDir, rel);
+    fs.mkdirSync(path.dirname(filePath), {recursive: true});
+    fs.writeFileSync(filePath, `# Doc\n\n${generateCompressedIndex(version)}\n`);
+  }
+
+  it('reports missing when no agent docs exist at all', () => {
+    const res = inspectAgentDocs(tmpDir, '1.0.0');
+    expect(res.status).toBe('missing');
+    expect(res.files).toEqual([]);
+    expect(res.staleFiles).toEqual([]);
+  });
+
+  it('reports missing when agent files exist but carry no Astryx marker', () => {
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nHand-written notes.\n');
+    expect(inspectAgentDocs(tmpDir, '1.0.0').status).toBe('missing');
+  });
+
+  it('reports current when the only block matches the installed version', () => {
+    writeBlock('AGENTS.md', '1.0.0');
+    const res = inspectAgentDocs(tmpDir, '1.0.0');
+    expect(res.status).toBe('current');
+    expect(res.staleFiles).toEqual([]);
+    expect(res.blockVersions).toEqual([]);
+  });
+
+  it('reports stale (with the old version) when the block is behind', () => {
+    writeBlock('AGENTS.md', '1.0.0');
+    const res = inspectAgentDocs(tmpDir, '2.0.0');
+    expect(res.status).toBe('stale');
+    expect(res.staleFiles).toEqual(['AGENTS.md']);
+    expect(res.blockVersions).toEqual(['1.0.0']);
+    expect(res.installedVersion).toBe('2.0.0');
+  });
+
+  it('treats a legacy XDS block as stale even with no parseable version', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'CLAUDE.md'),
+      '# Claude\n\n<!-- XDS:START -->\nlegacy index\n<!-- XDS:END -->\n',
+    );
+    const res = inspectAgentDocs(tmpDir, '1.0.0');
+    expect(res.status).toBe('stale');
+    expect(res.files[0].legacy).toBe(true);
+    expect(res.blockVersions).toEqual([]);
+  });
+
+  it('is stale if ANY marked file is behind (mixed current + stale)', () => {
+    writeBlock('AGENTS.md', '2.0.0');
+    writeBlock('CLAUDE.md', '1.0.0');
+    const res = inspectAgentDocs(tmpDir, '2.0.0');
+    expect(res.status).toBe('stale');
+    expect(res.staleFiles).toEqual(['CLAUDE.md']);
+  });
+
+  it('defaults the installed version to the core package when omitted', () => {
+    const coreDir = path.join(tmpDir, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(coreDir, {recursive: true});
+    fs.writeFileSync(path.join(coreDir, 'package.json'), JSON.stringify({version: '3.0.0'}));
+    writeBlock('AGENTS.md', '3.0.0');
+    const res = inspectAgentDocs(tmpDir);
+    expect(res.installedVersion).toBe('3.0.0');
+    expect(res.status).toBe('current');
+  });
+});

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) {

package/src/commands/cli-postinstall.test.mjs

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guardrail tests for the @astryxdesign/cli postinstall nudge (layer 2).
+ *
+ * Tests the pure decision matrix (shouldNudge) — nudges for a real dependency
+ * install when not set up; stays quiet in the monorepo/source, during npx's
+ * transient fetch (path _npx or npm_command=exec), and once set up.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {shouldNudge} from '../../scripts/postinstall.mjs';
+
+const DEP = '/proj/node_modules/@astryxdesign/cli/scripts/postinstall.mjs'; // real dep install
+const NPX = '/Users/x/.npm/_npx/a1b2/node_modules/@astryxdesign/cli/scripts/postinstall.mjs';
+const REPO = '/repo/packages/cli/scripts/postinstall.mjs'; // monorepo/source
+
+describe('cli postinstall — shouldNudge', () => {
+  it('nudges for a real dependency install when not set up', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: false})).toBe(true);
+  });
+
+  it('quiet in the monorepo/source (not under node_modules)', () => {
+    expect(shouldNudge({scriptPath: REPO, npmCommand: 'install', isSetUp: false})).toBe(false);
+  });
+
+  it('quiet during npx transient install (path contains _npx)', () => {
+    expect(shouldNudge({scriptPath: NPX, npmCommand: 'install', isSetUp: false})).toBe(false);
+  });
+
+  it('quiet during npx (npm_command=exec) — avoids double-nudge before init', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'exec', isSetUp: false})).toBe(false);
+  });
+
+  it('quiet once the project is already set up', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: true})).toBe(false);
+  });
+
+  it('quiet with no script path (defensive)', () => {
+    expect(shouldNudge({})).toBe(false);
+  });
+});

package/src/commands/component/index.mjs

@@ -18,7 +18,7 @@ import {
   formatBriefAll,
 } from '../../lib/component-format.mjs';
 import {resolveTheme} from '../../lib/resolve-theme.mjs';
-import {getRunPrefix} from '../../utils/package-manager.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
 import {jsonOut, humanLog} from '../../lib/json.mjs';
 import {cliError} from '../../lib/cli-error.mjs';
 import {ERROR_CODES} from '../../lib/error-codes.mjs';
@@ -39,7 +39,7 @@ export function registerComponent(program) {
     .option('--blocks', 'List example blocks: showcase, examples, and related')
     .option('--package <name>', 'Scope lookup to an external package (e.g. @acme/xds-widgets)')
     .action(async (name, options) => {
-      const run = getRunPrefix();
+      const run = getCliInvocation();
       const zh = program.opts().zh || false;
       const dense = program.opts().dense || false;
       const lang = program.opts().lang || null;
@@ -142,7 +142,7 @@ export function registerComponent(program) {
             }
             humanLog('');
             humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
-            humanLog(`Usage: ${run} astryx component <name>`);
+            humanLog(`Usage: ${run} component <name>`);
             humanLog('');
           }
           break;
@@ -165,7 +165,7 @@ export function registerComponent(program) {
             humanLog('');
           }
           humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
-          humanLog(`Usage: ${run} astryx component <name>`);
+          humanLog(`Usage: ${run} component <name>`);
           humanLog('');
           break;
         }

package/src/commands/discover.mjs

@@ -14,6 +14,7 @@ import {formatFull, formatBrief, formatCompact} from '../lib/component-format.mj
 import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {discover as discoverApi} from '../api/discover.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
 
 export function registerDiscover(program) {
   program
@@ -25,6 +26,7 @@ export function registerDiscover(program) {
       const json = program.opts().json || false;
       const lang = program.opts().lang || null;
       const zh = program.opts().zh || false;
+      const run = getCliInvocation();
 
       let result;
       try {
@@ -80,9 +82,9 @@ export function registerDiscover(program) {
               humanLog('');
             }
             humanLog('Usage:');
-            humanLog('  astryx discover <package>            Browse a package');
-            humanLog('  astryx discover <package>/Component  View component docs');
-            humanLog('  astryx discover <search>             Search all packages');
+            humanLog(`  ${run} discover <package>            Browse a package`);
+            humanLog(`  ${run} discover <package>/Component  View component docs`);
+            humanLog(`  ${run} discover <search>             Search all packages`);
             humanLog('');
           }
           break;
@@ -99,7 +101,7 @@ export function registerDiscover(program) {
           humanLog('');
           for (const comp of result.data.components) humanLog('  ' + comp);
           humanLog('');
-          humanLog('Usage: astryx discover ' + result.data.name + '/<ComponentName>');
+          humanLog(`Usage: ${run} discover ` + result.data.name + '/<ComponentName>');
           humanLog('');
           break;
         }
@@ -122,7 +124,7 @@ export function registerDiscover(program) {
           humanLog('Found ' + result.data.matches.length + ' matches for "' + result.data.query + '":');
           humanLog('');
           for (const m of result.data.matches) {
-            humanLog('  astryx discover ' + m.package + '/' + m.component);
+            humanLog(`  ${run} discover ` + m.package + '/' + m.component);
           }
           humanLog('');
           break;