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

package/src/codemods/transforms/v0.1.8/rename-avatar-size-scale.mjs

@@ -0,0 +1,234 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename Avatar named sizes to Icon's abbreviated scale
+ * @see https://github.com/facebook/astryx/issues/2672
+ *
+ * As of v0.1.8, Avatar and AvatarGroup use the same abbreviated size scale as
+ * Icon (`xsm`/`sm`/`md`/`lg`/`xl`) instead of full words. Pixel values are
+ * unchanged — only the names move:
+ *
+ *   tiny (20px)   → xsm
+ *   xsmall (24px) → sm
+ *   small (36px)  → md   ← also the new default (was `small`)
+ *   medium (48px) → lg
+ *   large (128px) → xl
+ *
+ * The default size shifts from `small` to `md`, but that is the SAME 36px, so
+ * call sites that relied on the default need no change.
+ *
+ * ## Precision
+ *
+ * `small`, `medium`, and `large` are common English words that appear as
+ * unrelated string/type literals (priorities, statuses, breakpoints, …). To
+ * avoid corrupting those, the three AMBIGUOUS names are renamed ONLY in a
+ * precise context: a `size` JSX attribute on a component that resolves to an
+ * Avatar/AvatarGroup import (alias-aware).
+ *
+ * `tiny` and `xsmall` are unique to Avatar's scale, so they are additionally
+ * renamed in context-blind positions (object properties keyed `size`/`*Size`,
+ * Storybook `options` arrays, and size-typed union literals) within files that
+ * import Avatar/AvatarGroup.
+ */
+
+export const meta = {
+  title: 'Rename Avatar named sizes tiny/xsmall/small/medium/large → xsm/sm/md/lg/xl',
+  description:
+    'Avatar and AvatarGroup adopt Icon\'s abbreviated size scale ' +
+    '(xsm/sm/md/lg/xl). Pixel values are unchanged; the default moves from ' +
+    '`small` to `md` (both 36px). The ambiguous names small/medium/large are ' +
+    'only renamed on Avatar/AvatarGroup `size` JSX attributes; the unique ' +
+    'names tiny/xsmall are also renamed in size-keyed props, Storybook ' +
+    'options, and union types in files importing Avatar/AvatarGroup.',
+  pr: '#2672',
+};
+
+/** Import sources that provide the Astryx Avatar/AvatarGroup components. */
+const IMPORT_SOURCES = new Set([
+  '@astryxdesign/core',
+  '@astryxdesign/core/Avatar',
+  '@astryxdesign/core/AvatarGroup',
+  '@xds/core',
+  '@xds/core/Avatar',
+  '@xds/core/AvatarGroup',
+]);
+
+/** Component names whose `size` prop is renamed. */
+const TARGET_IMPORTED_NAMES = new Set(['Avatar', 'AvatarGroup']);
+
+/** Old → new size-name mapping. */
+const RENAMES = new Map([
+  ['tiny', 'xsm'],
+  ['xsmall', 'sm'],
+  ['small', 'md'],
+  ['medium', 'lg'],
+  ['large', 'xl'],
+]);
+
+/**
+ * Ambiguous names — common words that must ONLY be renamed in a precise
+ * context. `tiny`/`xsmall` are omitted because they are unique to Avatar's
+ * scale; their presence in a collection proves it is an Avatar size enum.
+ */
+const AMBIGUOUS = new Set(['small', 'medium', 'large']);
+
+/** Names that appear only in Avatar's scale — safe signals of Avatar sizing. */
+const UNIQUE = new Set(['tiny', 'xsmall']);
+
+/**
+ * Rename a string-literal node if its value is an old size name.
+ * Unwraps `'small' as const`. In non-precise contexts, ambiguous names are
+ * skipped. Returns true when a rename occurred.
+ */
+function renameValue(node, {precise = false} = {}) {
+  if (!node) return false;
+  const target = node.type === 'TSAsExpression' ? node.expression : node;
+  const isString =
+    target.type === 'StringLiteral' || target.type === 'Literal';
+  if (!isString || typeof target.value !== 'string') return false;
+  const replacement = RENAMES.get(target.value);
+  if (!replacement) return false;
+  if (!precise && AMBIGUOUS.has(target.value)) return false;
+  target.value = replacement;
+  if (target.raw) target.raw = undefined;
+  return true;
+}
+
+/** Extract a plain string value from a literal-ish node, or null. */
+function literalString(node) {
+  const target = node?.type === 'TSAsExpression' ? node.expression : node;
+  if (
+    target &&
+    (target.type === 'StringLiteral' || target.type === 'Literal') &&
+    typeof target.value === 'string'
+  ) {
+    return target.value;
+  }
+  return null;
+}
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  // Track alias-aware local names for the target components.
+  const targetLocals = new Set();
+  root.find(j.ImportDeclaration).forEach((path) => {
+    if (!IMPORT_SOURCES.has(path.node.source.value)) return;
+    for (const spec of path.node.specifiers ?? []) {
+      if (
+        spec.type === 'ImportSpecifier' &&
+        TARGET_IMPORTED_NAMES.has(spec.imported.name)
+      ) {
+        targetLocals.add(spec.local.name);
+      }
+    }
+  });
+
+  if (targetLocals.size === 0) return undefined;
+
+  function renameArrayElements(node) {
+    let arr = node;
+    if (arr.type === 'TSAsExpression') arr = arr.expression;
+    if (arr.type !== 'ArrayExpression') return;
+    // If the array contains a name unique to Avatar's scale (tiny/xsmall), the
+    // whole collection is unambiguously the Avatar size enum, so it is safe to
+    // rename the ambiguous members too. Otherwise stay conservative.
+    const precise = arr.elements.some((el) => UNIQUE.has(literalString(el)));
+    for (const el of arr.elements) {
+      if (renameValue(el, {precise})) hasChanges = true;
+    }
+  }
+
+  // 1. `size` JSX attributes on target components — PRECISE (component known),
+  //    so all five names, including the ambiguous ones, are renamed here.
+  root.find(j.JSXOpeningElement).forEach((path) => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!componentName || !targetLocals.has(componentName)) return;
+
+    for (const attr of path.node.attributes) {
+      if (attr.type !== 'JSXAttribute' || attr.name?.name !== 'size') continue;
+      const value = attr.value;
+
+      // size="small"
+      if (renameValue(value, {precise: true})) {
+        hasChanges = true;
+        continue;
+      }
+      if (
+        value &&
+        value.type === 'JSXExpressionContainer' &&
+        value.expression
+      ) {
+        // size={'small'}
+        if (renameValue(value.expression, {precise: true})) {
+          hasChanges = true;
+          continue;
+        }
+        // size={cond ? 'small' : 'large'}
+        if (value.expression.type === 'ConditionalExpression') {
+          if (renameValue(value.expression.consequent, {precise: true}))
+            hasChanges = true;
+          if (renameValue(value.expression.alternate, {precise: true}))
+            hasChanges = true;
+        }
+      }
+    }
+  });
+
+  // 2. Object properties keyed `size` (or `*Size`) + Storybook `options`
+  //    arrays — NON-PRECISE (the component isn't known here), so only the
+  //    unique names tiny/xsmall are renamed.
+  const PropertyType = j.ObjectProperty ?? j.Property;
+  root.find(PropertyType).forEach((path) => {
+    const key = path.node.key;
+    const keyName =
+      key.type === 'Identifier'
+        ? key.name
+        : key.type === 'StringLiteral' || key.type === 'Literal'
+          ? key.value
+          : null;
+    if (typeof keyName !== 'string') return;
+
+    const lower = keyName.toLowerCase();
+    if (lower !== 'size' && !lower.endsWith('size')) return;
+
+    const value = path.node.value;
+    // size: 'tiny'
+    if (renameValue(value)) {
+      hasChanges = true;
+      return;
+    }
+    // size: { control: 'select', options: ['tiny', ...] }
+    if (value.type === 'ObjectExpression') {
+      const optionsProp = value.properties.find(
+        (p) => p.key && (p.key.name === 'options' || p.key.value === 'options'),
+      );
+      if (optionsProp) renameArrayElements(optionsProp.value);
+    }
+    // size: ['tiny', 'xsmall', ...]
+    renameArrayElements(value);
+  });
+
+  // 3. Union-type literals — NON-PRECISE, so only the unique names tiny/xsmall
+  //    are renamed. This avoids corrupting unrelated unions that happen to use
+  //    common words like 'medium' (e.g. a priority or breakpoint type) in a
+  //    file that also imports Avatar.
+  root.find(j.TSLiteralType).forEach((path) => {
+    if (renameValue(path.node.literal)) hasChanges = true;
+  });
+
+  // 4. Standalone array literals whose members are exactly the Avatar size
+  //    scale (identified by the presence of a unique name like tiny/xsmall) —
+  //    e.g. `(['tiny', 'xsmall', 'small', 'medium', 'large'] as const).map(...)`
+  //    used to render every size. The unique name proves the whole array is the
+  //    Avatar enum, so its ambiguous members can be renamed safely.
+  root.find(j.ArrayExpression).forEach((path) => {
+    renameArrayElements(path.node);
+  });
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/src/commands/agent-docs.mjs

@@ -104,6 +104,78 @@ export function isAstryxInitialized(targetDir = process.cwd()) {
   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};
+}
+
 /**
  * Resolve which file(s) to write for a given agent tool preset.
  * Searches for existing files first, falls back to default creation path.

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

@@ -16,6 +16,8 @@ import {
   removeXdsBlock,
   discoverAgentDocs,
   resolveAgentPaths,
+  parseBlockVersion,
+  inspectAgentDocs,
 } from './agent-docs.mjs';
 
 let tmpDir;
@@ -609,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/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
@@ -46,7 +49,7 @@ import {
   selectIntegrationCodemods,
 } from '../codemods/integration-discovery.mjs';
 import {runIntegrationCodemods} from '../codemods/integration-runner.mjs';
-import {installAgentDocs, discoverAgentDocs} from './agent-docs.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';
@@ -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).
  */
@@ -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.');
@@ -409,6 +523,7 @@ 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);
@@ -420,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);
@@ -502,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.');
@@ -513,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;
@@ -535,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
@@ -607,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 \`${getCliInvocation()} 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;