@astryxdesign/cli 0.1.7 → 0.1.8-canary.0c4d8d7

package/src/commands/template.mjs

@@ -6,25 +6,16 @@
 
 import * as path from 'node:path';
 import * as fs from 'node:fs';
-import * as p from '@clack/prompts';
-import {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 {template as templateApi} from '../api/template.mjs';
 import {Project} from '../lib/project.mjs';
 import {warnOnIntegrationIssues} from '../lib/integration-warnings.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
 
 export {discoverTemplates, listTemplates} from '../api/template.mjs';
 
-function isCancel(value) {
-  if (p.isCancel(value)) {
-    p.cancel('Cancelled.');
-    process.exit(0);
-  }
-  return value;
-}
-
 export function registerTemplate(program) {
   program
     .command('template [name] [path]')
@@ -36,6 +27,7 @@ export function registerTemplate(program) {
     .option('-f, --overwrite', 'Overwrite existing files without prompting')
     .action(async (name, targetPath, options) => {
       const json = program.opts().json || false;
+      const run = getCliInvocation();
 
       // Non-blocking nudge: if any configured integration has validation
       // issues, print one compact line to stderr pointing at
@@ -59,23 +51,11 @@ export function registerTemplate(program) {
         const collision = await detectTemplateCollision(name, targetPath);
         if (collision && !options.overwrite) {
           const rel = path.relative(process.cwd(), collision) || collision;
-          if (json || isNonInteractive({json})) {
-            const msg =
-              `Refusing to overwrite existing file ${rel}. ` +
-              `Re-run with --overwrite (or -f) to replace it.`;
-            cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
-            return;
-          }
-          const confirmed = isCancel(
-            await p.confirm({
-              message: `Overwrite existing file ${rel}?`,
-              initialValue: false,
-            }),
-          );
-          if (!confirmed) {
-            humanLog('Aborted. Re-run with --overwrite to replace the file.');
-            return;
-          }
+          const msg =
+            `Refusing to overwrite existing file ${rel}. ` +
+            `Re-run with --overwrite (or -f) to replace it.`;
+          cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
+          return;
         }
       }
 
@@ -120,10 +100,10 @@ export function registerTemplate(program) {
             for (const t of blocks) renderEntry(t);
           }
           humanLog('\nUsage:');
-          humanLog('  astryx template <id> [target-path]     Scaffold page or block');
-          humanLog('  astryx template <id> --skeleton        Layout reference');
-          humanLog('  astryx template --list --type block    List only blocks');
-          humanLog('  astryx template --list --package <pkg> List from one package\n');
+          humanLog(`  ${run} template <id> [target-path]     Scaffold page or block`);
+          humanLog(`  ${run} template <id> --skeleton        Layout reference`);
+          humanLog(`  ${run} template --list --type block    List only blocks`);
+          humanLog(`  ${run} template --list --package <pkg> List from one package\n`);
           break;
         }
 

package/src/commands/upgrade.mjs

@@ -11,8 +11,11 @@
  *
  * Pipeline (--apply):
  *   1. Read installed @astryxdesign/core (or legacy @xds/core) version
- *   2. Run codemods for --from → installed version
- *   3. Refresh agent docs (AGENTS.md / CLAUDE.md) if present
+ *   2. Refresh the managed agent-docs block (AGENTS.md / CLAUDE.md) to the
+ *      installed version — runs on EVERY path (including the up-to-date /
+ *      no-codemods short-circuits), because the block documents the installed
+ *      library, not the codemod outcome. Dry-run reports without writing.
+ *   3. Run codemods for --from → installed version
  *
  * Options:
  *   --from <version>       Previous version before the dependency upgrade
@@ -37,7 +40,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {execFile} from 'node:child_process';
 import {promisify} from 'node:util';
-import * as p from '@clack/prompts';
+import * as p from '../lib/term-log.mjs';
 import {ensureJscodeshift} from '../codemods/ensure-jscodeshift.mjs';
 import {getTransformsBetween, latestVersion} from '../codemods/registry.mjs';
 import {runCodemods} from '../codemods/runner.mjs';
@@ -46,8 +49,8 @@ import {
   selectIntegrationCodemods,
 } from '../codemods/integration-discovery.mjs';
 import {runIntegrationCodemods} from '../codemods/integration-runner.mjs';
-import {installAgentDocs, discoverAgentDocs} from './agent-docs.mjs';
-import {getRunPrefix} from '../utils/package-manager.mjs';
+import {installAgentDocs, inspectAgentDocs} from './agent-docs.mjs';
+import {getCliInvocation, formatCliCommand} from '../utils/package-manager.mjs';
 import {isValidSemver, semverGte} from '../utils/semver.mjs';
 import {jsonOut, jsonError} from '../lib/json.mjs';
 import {Project} from '../lib/project.mjs';
@@ -135,6 +138,103 @@ async function runPostCodemodHooks(hooks, context, silent) {
   }
 }
 
+/**
+ * Refresh (or, in dry-run, report) the managed agent-docs block after a version
+ * bump. The block (`<!-- ASTRYX:START --> … <!-- ASTRYX:END -->`) documents the
+ * INSTALLED library — its version, component index, and agent rules — so it must
+ * be re-synced on EVERY upgrade path, including the up-to-date / no-codemods
+ * short-circuits where no source file changes. That was the gap in #4168: an
+ * agent reading a stale index queries missing components and follows superseded
+ * rules. Three cases, one detection pass:
+ *
+ * - `stale`   — a managed block records an older version (or a legacy XDS
+ *               marker). `--apply` rewrites it; dry-run reports the pending
+ *               refresh as a loud next step and writes nothing.
+ * - `missing` — core is installed but no managed block exists anywhere (the repo
+ *               never ran `init`, or its agent docs were never marked). We never
+ *               silently create docs mid-upgrade; we nudge to run `init`.
+ * - `current` — every block already matches the installed version: stay silent.
+ *
+ * @param {{cwd: string, installedVersion: string, apply: boolean, json: boolean}} ctx
+ * @returns {import('../types/upgrade').AgentDocsSummary}
+ */
+export function refreshAgentDocs({cwd, installedVersion, apply, json}) {
+  const inspection = inspectAgentDocs(cwd, installedVersion);
+  /** @type {import('../types/upgrade').AgentDocsSummary} */
+  const summary = {
+    status: inspection.status,
+    installedVersion,
+    fromVersions: inspection.blockVersions,
+    files: [],
+    refreshed: false,
+    action: 'none',
+  };
+
+  // Never initialized — don't silently create docs during an upgrade; nudge.
+  if (inspection.status === 'missing') {
+    summary.action = 'nudge-init';
+    if (!json) {
+      p.log.warn(
+        `No Astryx agent-docs block found — AI agents have no component index. Run \`${formatCliCommand('astryx init --features agents')}\` to install it.`,
+      );
+    }
+    return summary;
+  }
+
+  if (inspection.status === 'current') return summary;
+
+  // Stale.
+  summary.files = inspection.staleFiles;
+  const fromLabel = summary.fromVersions.length
+    ? `v${summary.fromVersions.join(', v')}`
+    : 'an unknown version';
+
+  if (!apply) {
+    // Dry-run: report the pending change, never write.
+    summary.action = 'would-refresh';
+    if (!json) {
+      p.log.warn(
+        `Agent docs are stale: block is at ${fromLabel}, installed is v${installedVersion}. Re-run with --apply to refresh (${summary.files.join(', ')}).`,
+      );
+    }
+    return summary;
+  }
+
+  // Apply: rewrite only files that already carry a marker (onlyReplace).
+  try {
+    const written = installAgentDocs(cwd, {onlyReplace: true});
+    summary.refreshed = written.length > 0;
+    summary.files = written;
+    if (summary.refreshed) {
+      summary.action = 'refreshed';
+      if (!json) {
+        p.log.success(
+          `Agent docs refreshed → v${installedVersion} (from ${fromLabel}): ${written.join(', ')}`,
+        );
+      }
+    } else {
+      // We detected a stale marked block but rewrote nothing, and
+      // installAgentDocs did not throw — the block markers are malformed (e.g. a
+      // START with no matching END, so the writer can't safely splice it). Don't
+      // fail silently: the block is exactly the artifact agents rely on.
+      summary.action = 'error';
+      if (!json) {
+        p.log.warn(
+          `Agent docs look stale but couldn't be refreshed — the <!-- ASTRYX:START -->/<!-- ASTRYX:END --> markers may be malformed. Run \`${formatCliCommand('astryx init --features agents')}\` to reinstall the block.`,
+        );
+      }
+    }
+  } catch {
+    summary.action = 'error';
+    if (!json) {
+      p.log.warn(
+        `Could not refresh agent docs. Run \`${formatCliCommand('astryx init --features agents')}\` to update them manually.`,
+      );
+    }
+  }
+  return summary;
+}
+
 /**
  * Register the `upgrade` command (codemod-driven version migration).
  */
@@ -176,7 +276,7 @@ export function registerUpgrade(program) {
 
       if (!options.list && !options.from) {
         const msg =
-          'Missing required --from. Install the target version first, then run `astryx upgrade --from <old-version>`.';
+          `Missing required --from. Install the target version first, then run \`${getCliInvocation()} upgrade --from <old-version>\`.`;
         if (json)
           return jsonError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);
         p.log.error(msg);
@@ -237,7 +337,7 @@ export function registerUpgrade(program) {
       const installed = detectInstalledTargetVersion();
       if (!installed) {
         const msg =
-          'Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun `astryx upgrade --from <old-version>`.';
+          `Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun \`${getCliInvocation()} upgrade --from <old-version>\`.`;
         if (json)
           return jsonError(msg, undefined, ERROR_CODES.ERR_VERSION_DETECT);
         p.log.error(msg);
@@ -254,6 +354,19 @@ export function registerUpgrade(program) {
         );
       }
 
+      // Sync the managed agent-docs block to the installed version FIRST. It
+      // documents the installed library (version + component index + rules),
+      // independent of any source codemods, so it must be refreshed on every
+      // path below — including the up-to-date / no-codemods short-circuits that
+      // return before codemods ever run (issue #4168). Dry-run reports without
+      // writing. Folded into every terminal payload as `agentDocs`.
+      const agentDocs = refreshAgentDocs({
+        cwd: process.cwd(),
+        installedVersion: targetVersion,
+        apply: options.apply,
+        json,
+      });
+
       // ───────────────────────────────────────────────────────────────────
       // PIPELINE ORDERING
       //
@@ -275,6 +388,7 @@ export function registerUpgrade(program) {
             status: 'up_to_date',
             from: currentVersion,
             to: targetVersion,
+            agentDocs,
           });
         }
         p.log.success('Already up to date — no codemods to run.');
@@ -390,6 +504,9 @@ export function registerUpgrade(program) {
           const codemodFlags = coreConfigCodemodNames
             .map(name => `--codemod ${name}`)
             .join(' ');
+          // Canonical (bare) form — this is a structured, machine-executable
+          // field in the --json envelope. The human print below is made
+          // install-aware via formatCliCommand.
           const suggestedCommand = `astryx upgrade --from ${currentVersion} ${codemodFlags} --apply`;
           const guidance =
             'Your astryx.config currently fails strict validation, but a pending ' +
@@ -406,10 +523,11 @@ export function registerUpgrade(program) {
               suggestedCommand,
               message: guidance,
               note: 'Integrations are skipped in this preview; they will be processed on the --apply run.',
+              agentDocs,
             });
           }
           p.log.warn(guidance);
-          p.log.info(`  ${suggestedCommand}`);
+          p.log.info(`  ${formatCliCommand(suggestedCommand)}`);
           p.log.info(
             'Integrations are skipped in this preview; they will be processed on the --apply run.',
           );
@@ -417,11 +535,12 @@ export function registerUpgrade(program) {
           return;
         }
         // Genuine config error (apply mode, OR dry-run with no pending core
-        // config codemod that would fix it): abort as before.
+        // config codemod that would fix it): abort as before. The agent-docs
+        // refresh already ran (it's independent of config), so surface it.
         if (json)
           return jsonError(
             err.message,
-            undefined,
+            {agentDocs},
             ERROR_CODES.ERR_INVALID_ARGUMENT,
           );
         p.log.error(err.message);
@@ -499,6 +618,7 @@ export function registerUpgrade(program) {
             status: 'no_codemods',
             from: currentVersion,
             to: targetVersion,
+            agentDocs,
           });
         }
         p.log.success('No codemods available for this version range.');
@@ -510,7 +630,7 @@ export function registerUpgrade(program) {
       if (totalTransforms === 0 && totalOptional === 0) {
         const msg = `Codemod "${options.codemod}" not found. Use --list to see available codemods.`;
         if (json)
-          return jsonError(msg, undefined, ERROR_CODES.ERR_UNKNOWN_CODEMOD);
+          return jsonError(msg, {agentDocs}, ERROR_CODES.ERR_UNKNOWN_CODEMOD);
         p.log.error(msg);
         p.outro('Aborted');
         process.exitCode = 1;
@@ -532,7 +652,10 @@ export function registerUpgrade(program) {
         to: targetVersion,
         codemods: totalTransforms,
         integrations: integrations.map(i => i.name ?? i.__spec),
-        agentDocsRefreshed: false,
+        // Refreshed up front (before the gates above), so the receipt just
+        // reports what happened. `agentDocsRefreshed` kept for back-compat.
+        agentDocsRefreshed: agentDocs.refreshed,
+        agentDocs,
       };
 
       // Run file-based integration codemods alongside the core registry
@@ -604,26 +727,9 @@ export function registerUpgrade(program) {
         }
       }
 
-      // Refresh agent docs if any exist (AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, etc.)
-      // Always update after --apply; also update during dry-run if files exist,
-      // since the index reflects the installed CLI version, not the codemods.
-      const existingDocs = discoverAgentDocs(process.cwd());
-      if (existingDocs.length > 0) {
-        try {
-          // onlyReplace: only update files that already have Astryx markers.
-          // Don't inject into files that never had Astryx content.
-          const written = installAgentDocs(process.cwd(), {onlyReplace: true});
-          receipt.agentDocsRefreshed = written.length > 0;
-          if (!json && written.length > 0)
-            p.log.success(`Agent docs updated: ${written.join(', ')}`);
-        } catch {
-          if (!json) {
-            p.log.warn(
-              `Could not update agent docs. Run \`${getRunPrefix()} astryx init --features agents\` to update manually.`,
-            );
-          }
-        }
-      }
+      // NOTE: the managed agent-docs block was already refreshed up front (see
+      // refreshAgentDocs after installed-version detection), so it stays in sync
+      // even on the short-circuit paths that return before this point.
 
       receipt.filesChanged = mergedFilesChanged;
       receipt.transformsApplied = mergedTransformsApplied;

package/src/commands/upgrade.test.mjs

@@ -6,6 +6,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import {Command} from 'commander';
 import {registerUpgrade} from './upgrade.mjs';
+import {generateCompressedIndex} from './agent-docs.mjs';
 
 let tmpDir;
 let originalCwd;
@@ -24,7 +25,7 @@ beforeEach(() => {
     logCalls.push(args.join(' '));
   });
   vi.spyOn(console, 'error').mockImplementation(() => {});
-  // @clack/prompts writes directly to process.stdout — capture that too.
+  // Some human logs are written straight to process.stdout — capture that too.
   vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
     stdoutCalls.push(typeof chunk === 'string' ? chunk : chunk.toString());
     return true;
@@ -158,3 +159,156 @@ describe('upgrade --list dedup', () => {
     expect(names.length).toBe(unique.size);
   });
 });
+
+// Issue #4168 — `upgrade` must refresh the managed agent-docs block after a
+// version bump, on EVERY path (the block documents the installed library, not
+// the codemod outcome), and must NOT write during a dry run.
+describe('upgrade agent-docs refresh (#4168)', () => {
+  /** Write an agent-doc file with a managed block generated for `version`. */
+  function writeAgentBlock(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('refreshes a stale block with --apply, even when there are no codemods (up-to-date path)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+
+    // --from == installed → up-to-date short-circuit: no codemods run, yet the
+    // stale block must still be brought current. This is the exact gap in #4168.
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.type).toBe('upgrade.status');
+    expect(result.data.status).toBe('up_to_date');
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('refreshed');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    expect(result.data.agentDocs.fromVersions).toEqual(['0.0.1']);
+    expect(result.data.agentDocs.files).toContain('AGENTS.md');
+
+    const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toMatch(/Astryx v0\.0\.15 ·/);
+    expect(content).not.toMatch(/Astryx v0\.0\.1 ·/);
+  });
+
+  it('reports a stale block on a dry run WITHOUT writing', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+    const before = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15']); // no --apply
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('would-refresh');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // The file must be untouched by a dry run.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(before);
+  });
+
+  it('refreshes a stale block on the no-codemods path (--apply)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.11'); // (0.0.10, 0.0.11] has no registered codemods
+    writeSourceFile();
+    writeAgentBlock('CLAUDE.md', '0.0.1');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.10', '--apply', '--path', 'src']);
+
+    expect(result.type).toBe('upgrade.status');
+    expect(result.data.status).toBe('no_codemods');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    expect(fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8')).toMatch(/Astryx v0\.0\.11 ·/);
+  });
+
+  it('nudges to run init when core is installed but no managed block exists', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    // No agent-doc files at all.
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('missing');
+    expect(result.data.agentDocs.action).toBe('nudge-init');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // Must NOT silently create docs during an upgrade.
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+  });
+
+  it('treats an agent file without our markers as "never initialized" (missing)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nHand-written, no astryx block.\n');
+    const before = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('missing');
+    expect(result.data.agentDocs.action).toBe('nudge-init');
+    // An unmarked file is left exactly as-is.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(before);
+  });
+
+  it('does not silently no-op a stale block with malformed markers (START without END)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    // A corrupted block: START + version header but no matching END marker, so
+    // the writer can't safely splice it. This must not crash, corrupt the file,
+    // or falsely claim success — it should surface an error and nudge re-init.
+    const corrupted =
+      '# A\n\n<!-- ASTRYX:START -->\nAstryx v0.0.1 · 9 components\nguidance, but no end marker\n';
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), corrupted);
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.action).toBe('error');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+    // File left byte-for-byte intact — never corrupted.
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe(corrupted);
+  });
+
+  it('stays silent when the block already matches the installed version', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.15');
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('current');
+    expect(result.data.agentDocs.action).toBe('none');
+    expect(result.data.agentDocs.refreshed).toBe(false);
+  });
+
+  it('migrates a legacy XDS block to the current Astryx block (--apply)', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    fs.writeFileSync(
+      path.join(tmpDir, 'CLAUDE.md'),
+      '# Claude\n\n<!-- XDS:START -->\nlegacy index\n<!-- XDS:END -->\n\nMore rules.\n',
+    );
+
+    const result = await runJson(['--json', 'upgrade', '--from', '0.0.15', '--apply']);
+
+    expect(result.data.agentDocs.status).toBe('stale');
+    expect(result.data.agentDocs.refreshed).toBe(true);
+    const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+    expect(content).toMatch(/Astryx v0\.0\.15 ·/);
+    expect(content).not.toContain('legacy index');
+    expect(content).toContain('More rules.');
+  });
+
+  it('surfaces agentDocs in the human output on the up-to-date path', async () => {
+    writePkg();
+    writeInstalledCore('0.0.15');
+    writeAgentBlock('AGENTS.md', '0.0.1');
+
+    const program = createProgram();
+    await program.parseAsync(['node', 'astryx', 'upgrade', '--from', '0.0.15', '--apply']);
+    const output = stdoutCalls.join('') + logCalls.join('\n');
+    expect(output).toMatch(/Agent docs refreshed/i);
+  });
+});

package/src/index.mjs

@@ -12,13 +12,14 @@ import {fileURLToPath} from 'node:url';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {checkForUpdate} from './utils/update-check.mjs';
-import {getRunPrefix} from './utils/package-manager.mjs';
+import {getCliInvocation} from './utils/package-manager.mjs';
 import {API_VERSION, setJsonMode} from './lib/json.mjs';
 import {buildManifest} from './lib/manifest.mjs';
 import {cliError} from './lib/cli-error.mjs';
 import {ERROR_CODES} from './lib/error-codes.mjs';
 import {levenshteinDistance} from './lib/string-utils.mjs';
 import {installJsonShim} from './lib/json-shim.mjs';
+import {isAstryxInitialized} from './commands/agent-docs.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -174,7 +175,7 @@ function fullCommandName(actionCommand) {
  *
  * If --json is set on a command that is not on the JSON_SUPPORTED allowlist,
  * emit a structured error envelope and exit 1 — without running the command's
- * action (so no filesystem mutations, no clack prompts, no spawned processes).
+ * action (so no filesystem mutations, no interactive prompts, no spawned processes).
  *
  * This is the single source of truth for "command does not support --json".
  * Individual commands should NOT re-check this; they may assume that if their
@@ -237,6 +238,40 @@ program.hook('postAction', (thisCommand, actionCommand) => {
   }
 });
 
+/**
+ * Enforcement layer 3 — setup nudge. If this project hasn't run `astryx init`
+ * yet (no Astryx marker in any agent-doc file — see isAstryxInitialized), remind
+ * the user/agent that setup is missing.
+ *
+ * Uses `preAction` (not postAction) so it fires for EVERY valid command — even
+ * ones whose action errors or calls process.exit (postAction is skipped then).
+ *
+ * Suppressed in --json: that is machine output with a strict clean stdout+stderr
+ * contract (json-shim.test: "error envelopes have empty stderr"), and --json
+ * consumers parse stdout, not stderr — a stderr nudge would not reach them anyway.
+ * The core/cli postinstall layers already nudge at install time regardless of
+ * --json; a machine-readable nudge could later be an envelope field. Also skipped
+ * for the installer commands themselves and outside a project (no package.json).
+ */
+const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
+program.hook('preAction', (thisCommand, actionCommand) => {
+  try {
+    if (program.opts().json) return; // machine mode — keep --json output clean
+    if (SETUP_NUDGE_EXEMPT.has(actionCommand.name())) return;
+    const cwd = process.cwd();
+    if (!fs.existsSync(path.join(cwd, 'package.json'))) return; // not a project
+    if (isAstryxInitialized(cwd)) return; // already set up — stay quiet
+    // Same wording as the core/cli postinstall nudges. #4151's getCliInvocation()
+    // renders the correct form for THIS project — scoped `npx @astryxdesign/cli`
+    // one-off, or `<pm> astryx` when installed — never the bare `npx astryx` footgun.
+    console.error(
+      `\nNext step: run \`${getCliInvocation(cwd)} init\` to finish setup and install the Astryx agent prompt.`,
+    );
+  } catch {
+    // Never let the nudge break a command.
+  }
+});
+
 /**
  * Command registry — each command is lazy-loaded so a broken command
  * doesn't take down the entire CLI.
@@ -305,15 +340,14 @@ program
       console.log(`  ${c.name}${tag}`);
       if (c.description) console.log(`    ${c.description}`);
     }
-    console.log(`\nRun \`astryx manifest --json\` for the full structured manifest.\n`);
+    console.log(`\nRun \`${getCliInvocation()} manifest --json\` for the full structured manifest.\n`);
   });
 
 // Hidden command used by package.json postinstall scripts
 program
   .command('postinstall', {hidden: true})
   .action(() => {
-    const run = getRunPrefix();
-    const r = `${run} xds`;
+    const r = getCliInvocation();
     const pad = (s, len) => s + ' '.repeat(Math.max(0, len - s.length));
     const W = 49; // inner width of the box
     const line = (s) => `  │ ${pad(s, W)}│`;
@@ -323,7 +357,7 @@ ${line('')}
 ${line('  Design system installed!')}
 ${line('')}
 ${line('  Get started:')}
-${line(`    ${r} init          Interactive setup`)}
+${line(`    ${r} init          Setup + AI agent docs`)}
 ${line(`    ${r} --help        See all commands`)}
 ${line('')}
 ${line('  Or run directly:')}

package/src/lib/cli-error.mjs

@@ -55,8 +55,8 @@ import {ERROR_CODES} from './error-codes.mjs';
 
 /**
  * Suggestion object — matches the shape used by API errors and the JSON
- * envelope's `suggestions` field.
- * @typedef {{name: string, reason?: string}} Suggestion
+ * envelope's `suggestions` field. Canonical definition lives in types/base.
+ * @typedef {import('../types/base').Suggestion} Suggestion
  */
 
 /**

package/src/lib/component-format.mjs

@@ -6,6 +6,7 @@
 
 import {discoverComponents, findComponentReadme, resolveImportPath} from './component-discovery.mjs';
 import {loadDocs} from './component-loader.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
 
 /**
  * Derive the `defineTheme` component-override key from a theming target.
@@ -81,7 +82,7 @@ function formatSubComponent(comp) {
   if (table) {
     out.push(table + '\n');
   } else {
-    out.push(`See \`astryx component ${comp.name}\` for props and usage.\n`);
+    out.push(`See \`${getCliInvocation()} component ${comp.name}\` for props and usage.\n`);
   }
   return out;
 }

package/src/lib/json-shim.mjs

@@ -102,7 +102,7 @@ export function buildHelpEnvelope(cmd) {
  * for both success and error).
  *
  * @param {string} message
- * @param {Array<{name: string, reason: string}>} [suggestions]
+ * @param {import('../types/base').Suggestion[]} [suggestions]
  * @param {string} [code] - Stable machine-readable error code (error-codes.mjs).
  */
 function emitJsonError(message, suggestions, code) {