@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/{src → cli}/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,23 +40,23 @@ 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 {ensureJscodeshift} from '../codemods/ensure-jscodeshift.mjs';
-import {getTransformsBetween, latestVersion} from '../codemods/registry.mjs';
-import {runCodemods} from '../codemods/runner.mjs';
+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';
 import {
   discoverIntegrationCodemods,
   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 {isValidSemver, semverGte} from '../utils/semver.mjs';
-import {jsonOut, jsonError} from '../lib/json.mjs';
-import {Project} from '../lib/project.mjs';
-import {loadIntegrations} from '../lib/integrations.mjs';
-import {warnOnIntegrationIssues} from '../lib/integration-warnings.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+} from '../../codemods/integration-discovery.mjs';
+import {runIntegrationCodemods} from '../../codemods/integration-runner.mjs';
+import {installAgentDocs, inspectAgentDocs} from '../../lib/agent-docs/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';
+import {loadIntegrations} from '../../lib/integrations.mjs';
+import {warnOnIntegrationIssues} from '../../lib/integration-warnings.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -79,8 +82,18 @@ function detectInstalledTargetVersion() {
   return null;
 }
 
+/**
+ * @param {(string | null | undefined | false)[] | undefined} files
+ * @returns {string[]}
+ */
 function uniqueFiles(files) {
-  return [...new Set((files ?? []).filter(Boolean))];
+  return [
+    ...new Set(
+      (files ?? []).filter(
+        /** @returns {f is string} */ f => Boolean(f),
+      ),
+    ),
+  ];
 }
 
 /**
@@ -92,7 +105,7 @@ function uniqueFiles(files) {
  * In apply mode the commands run in order via execFile; a nonzero exit (or a
  * buildCommand throw) fails the upgrade.
  *
- * @param {import('../types/config').PostCodemodHook[]} hooks
+ * @param {import('../../types/config').PostCodemodHook[]} hooks
  * @param {{packageDir: string, files: string[], apply: boolean}} context
  * @param {boolean} silent
  */
@@ -123,20 +136,140 @@ async function runPostCodemodHooks(hooks, context, silent) {
       continue;
     }
 
-    await execFileAsync(cmd.command, cmd.args ?? [], {
-      cwd: cmd.options?.cwd ?? packageDir,
-      timeout: cmd.options?.timeout ?? 300_000,
-      stdio: 'pipe',
-      encoding: 'utf-8',
-      ...cmd.options,
-      env: {...process.env, ...(cmd.options?.env ?? {})},
-    });
+    await execFileAsync(
+      cmd.command,
+      cmd.args ?? [],
+      /** @type {import('node:child_process').ExecFileOptions & {encoding: 'utf-8'}} */ ({
+        cwd: cmd.options?.cwd ?? packageDir,
+        timeout: cmd.options?.timeout ?? 300_000,
+        stdio: 'pipe',
+        encoding: 'utf-8',
+        ...cmd.options,
+        env: {...process.env, ...(cmd.options?.env ?? {})},
+      }),
+    );
     log.success(`Post-codemod hook ${label} completed.`);
   }
 }
 
+/**
+ * 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;
+}
+
+/**
+ * A single core transform entry as produced by the registry manifests. The
+ * registry's declared return type omits the optional `optional` flag and the
+ * `pr`/`codemodType` meta fields that the transform modules actually carry;
+ * this local shape captures what the upgrade command reads. Remove once
+ * codemods/registry.mjs declares these fields on its return type.
+ * @typedef {object} CoreTransformEntry
+ * @property {string} name
+ * @property {import('../../types/codemod').CodemodTransform} transform
+ * @property {{title: string, description?: string, pr?: string, codemodType?: string}} meta
+ * @property {boolean} [optional]
+ */
+
+/**
+ * A version-scoped group of core transforms from the registry.
+ * @typedef {{version: string, transforms: CoreTransformEntry[]}} CoreVersionManifest
+ */
+
 /**
  * Register the `upgrade` command (codemod-driven version migration).
+ * @param {import('commander').Command} program
  */
 export function registerUpgrade(program) {
   program
@@ -160,6 +293,10 @@ export function registerUpgrade(program) {
     .option(
       '--integration <package-or-file>',
       'Explicit integration package name or integration file path (repeatable)',
+      /**
+       * @param {string} value
+       * @param {string[]} previous
+       */
       (value, previous) => [...(previous ?? []), value],
       [],
     )
@@ -170,13 +307,27 @@ export function registerUpgrade(program) {
       false,
     )
     .option('--list', 'List available codemods', false)
-    .action(async options => {
+    .action(
+      /**
+       * @param {{
+       *   list?: boolean,
+       *   from?: string,
+       *   apply: boolean,
+       *   force?: boolean,
+       *   codemod?: string,
+       *   skipCodemod?: string[],
+       *   integration?: string[],
+       *   path: string,
+       *   installDeps?: boolean,
+       * }} options
+       */
+      async options => {
       const json = program.opts().json || false;
       if (!json) p.intro('Upgrade');
 
       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);
@@ -201,7 +352,9 @@ export function registerUpgrade(program) {
         // over every version and re-walked getTransformsBetween('0.0.0', v),
         // so each codemod was printed once per release that included it
         // (31 unique × 9 ≈ 201 lines on the current registry).
-        const manifests = await getTransformsBetween('0.0.0', latestVersion);
+        const manifests = /** @type {CoreVersionManifest[]} */ (
+          await getTransformsBetween('0.0.0', latestVersion)
+        );
         for (const {version, transforms} of manifests) {
           for (const {name, meta, optional} of transforms) {
             codemods.push({
@@ -233,11 +386,12 @@ export function registerUpgrade(program) {
         return;
       }
 
-      const currentVersion = options.from;
+      // Guarded above: reaching here means --from passed isValidSemver, so it's a string.
+      const currentVersion = /** @type {string} */ (options.from);
       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 +408,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 +442,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.');
@@ -286,9 +454,9 @@ export function registerUpgrade(program) {
       // Resolve CORE transforms from the registry. These do not need the loaded
       // config. Integration codemods are discovered later, AFTER the config
       // loads successfully (they require a valid config to resolve).
-      const versionManifests = [
+      const versionManifests = /** @type {CoreVersionManifest[]} */ ([
         ...(await getTransformsBetween(currentVersion, targetVersion)),
-      ];
+      ]);
 
       // Does the selected core set include >=1 CONFIG codemod? A config codemod
       // is the established convention `meta.codemodType === 'config'` (see
@@ -356,6 +524,15 @@ export function registerUpgrade(program) {
         skipCodemods,
         silent: json,
       });
+      // runCodemods returns either a success accounting or a
+      // {ok: false, reason} sentinel (e.g. source_path_missing). Narrow to the
+      // success shape so downstream property reads type-check; the sentinel
+      // branch collapses to null and the `?? 0`/`?? []` fallbacks below treat
+      // it as "no files changed", matching the existing runtime behavior.
+      const coreResult =
+        codemodResult && 'totalFilesChanged' in codemodResult
+          ? codemodResult
+          : null;
 
       // STEP 4 — Load the consumer's config (STRICT validation; unchanged). On
       // --apply this now sees the repaired config the core codemod just wrote.
@@ -363,8 +540,11 @@ export function registerUpgrade(program) {
       // here. Wrap in a graceful dry-run catch (see below).
       // Assigned inside the try below; every catch branch returns, so these
       // are always set before any later read.
+      /** @type {Array<import('../../lib/integrations.mjs').LoadedIntegration>} */
       let integrations;
+      /** @type {import('../../types/config').PostCodemodHook[]} */
       let postCodemodHooks;
+      /** @type {Array<{version: string, codemods: import('../../types/codemod').CodemodEntry[]}>} */
       let integrationVersionGroups;
       try {
         const project = await Project.load(process.cwd());
@@ -375,6 +555,7 @@ export function registerUpgrade(program) {
         ]);
         integrations = await loadIntegrations(integrationSpecs);
       } catch (err) {
+        const configErr = /** @type {Error} */ (err);
         // GRACEFUL DRY-RUN CATCH. A config that fails strict validation is the
         // EXPECTED, fixable case ONLY when we are in dry-run AND a pending core
         // config codemod just PREVIEWED a change to the config — i.e. the very
@@ -385,11 +566,14 @@ export function registerUpgrade(program) {
         // gate and aborts below — preserving the strictness contract.) This is
         // the reason this PR reorders the pipeline.
         const codemodWouldFixConfig =
-          hasCoreConfigCodemod && (codemodResult?.totalFilesChanged ?? 0) > 0;
+          hasCoreConfigCodemod && (coreResult?.totalFilesChanged ?? 0) > 0;
         if (!options.apply && codemodWouldFixConfig) {
           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 ' +
@@ -401,15 +585,16 @@ export function registerUpgrade(program) {
               status: 'config_fixable',
               from: currentVersion,
               to: targetVersion,
-              configError: err.message,
+              configError: configErr.message,
               configCodemods: coreConfigCodemodNames,
               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,14 +602,15 @@ 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,
+            configErr.message,
+            /** @type {import('../../types/base').Suggestion[]} */ (/** @type {unknown} */ ({agentDocs})),
             ERROR_CODES.ERR_INVALID_ARGUMENT,
           );
-        p.log.error(err.message);
+        p.log.error(configErr.message);
         p.outro('Aborted');
         process.exitCode = 1;
         return;
@@ -455,12 +641,21 @@ export function registerUpgrade(program) {
       // hard-failing the upgrade. An EXECUTION-time failure (a transform
       // throwing) is handled later by the codemod-error gate, which still
       // aborts the upgrade.
+      /** @type {Map<string, Array<import('../../types/codemod').CodemodEntry>>} */
       const integrationCodemodsByVersion = new Map();
       for (const integration of integrations) {
         if (!integration?.codemods) continue;
         try {
           const byVersion = await discoverIntegrationCodemods([integration]);
-          for (const [version, list] of byVersion) {
+          for (const [version, rawList] of byVersion) {
+            // discoverIntegrationCodemods declares `codemod: object` (loose); the
+            // runtime entries carry the full CodemodEntry.codemod shape. Narrow
+            // to the map's element type. Report: integration-discovery.mjs's
+            // @returns should declare CodemodEntry instead of the loose object.
+            const list =
+              /** @type {Array<import('../../types/codemod').CodemodEntry>} */ (
+                /** @type {unknown} */ (rawList)
+              );
             const existing = integrationCodemodsByVersion.get(version);
             if (existing) existing.push(...list);
             else integrationCodemodsByVersion.set(version, [...list]);
@@ -470,11 +665,14 @@ export function registerUpgrade(program) {
           // above surfaces the underlying issue. Best-effort, non-blocking.
         }
       }
-      integrationVersionGroups = selectIntegrationCodemods(
-        integrationCodemodsByVersion,
-        currentVersion,
-        targetVersion,
-      );
+      integrationVersionGroups =
+        /** @type {Array<{version: string, codemods: import('../../types/codemod').CodemodEntry[]}>} */ (
+          selectIntegrationCodemods(
+            integrationCodemodsByVersion,
+            currentVersion,
+            targetVersion,
+          )
+        );
       const hasIntegrationCodemods = integrationVersionGroups.some(
         g => g.codemods.length > 0,
       );
@@ -499,6 +697,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 +709,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, /** @type {import('../../types/base').Suggestion[]} */ (/** @type {unknown} */ ({agentDocs})), ERROR_CODES.ERR_UNKNOWN_CODEMOD);
         p.log.error(msg);
         p.outro('Aborted');
         process.exitCode = 1;
@@ -527,12 +726,35 @@ export function registerUpgrade(program) {
         }
       }
 
+      /**
+       * Terminal upgrade receipt. NOTE: the shape emitted here (with
+       * `integrations`, `filesChanged`, `transformsApplied`, `errors`) is what
+       * the command has always produced and what upgrade.test/config-ordering
+       * assert on; it does NOT match `UpgradeRunResponse.data` in
+       * types/upgrade.d.ts (which declares a stale `depsUpdated` field and omits
+       * these). The jsonOut call below is cast to bridge that drift. See the
+       * report: types/upgrade.d.ts needs reconciling with the real envelope.
+       * @type {{
+       *   from: string,
+       *   to: string,
+       *   codemods: number,
+       *   integrations: string[],
+       *   agentDocsRefreshed: boolean,
+       *   agentDocs: import('../../types/upgrade').AgentDocsSummary,
+       *   filesChanged?: number,
+       *   transformsApplied?: number,
+       *   errors?: Array<{file: string, codemod: string, error: string}>,
+       * }}
+       */
       const receipt = {
         from: currentVersion,
         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
@@ -556,17 +778,17 @@ export function registerUpgrade(program) {
       // Merge core + integration codemod results into a single accounting so
       // hooks, receipts, and error gating see both.
       const mergedFilesChanged =
-        (codemodResult?.totalFilesChanged ?? 0) +
+        (coreResult?.totalFilesChanged ?? 0) +
         (integrationResult?.totalFilesChanged ?? 0);
       const mergedTransformsApplied =
-        (codemodResult?.totalTransformsApplied ?? 0) +
+        (coreResult?.totalTransformsApplied ?? 0) +
         (integrationResult?.totalTransformsApplied ?? 0);
       const mergedWrittenFiles = [
-        ...(codemodResult?.writtenFiles ?? []),
+        ...(coreResult?.writtenFiles ?? []),
         ...(integrationResult?.writtenFiles ?? []),
       ];
       const mergedErrors = [
-        ...(codemodResult?.errors ?? []),
+        ...(coreResult?.errors ?? []),
         ...(integrationResult?.errors ?? []),
       ];
 
@@ -591,39 +813,23 @@ export function registerUpgrade(program) {
             json,
           );
         } catch (err) {
+          const hookErr = /** @type {Error} */ (err);
           if (json)
             return jsonError(
-              `Post-codemod hook failed: ${err.message}`,
-              {receipt},
+              `Post-codemod hook failed: ${hookErr.message}`,
+              /** @type {import('../../types/base').Suggestion[]} */ (/** @type {unknown} */ ({receipt})),
               ERROR_CODES.ERR_CODEMOD_FAILED,
             );
-          p.log.error(`Post-codemod hook failed: ${err.message}`);
+          p.log.error(`Post-codemod hook failed: ${hookErr.message}`);
           p.outro('Upgrade failed');
           process.exitCode = 1;
           return;
         }
       }
 
-      // 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;
@@ -632,7 +838,7 @@ export function registerUpgrade(program) {
       if (receipt.errors?.length > 0) {
         const msg = `Upgrade completed with ${receipt.errors.length} codemod error${receipt.errors.length === 1 ? '' : 's'}.`;
         if (json) {
-          return jsonError(msg, {receipt}, ERROR_CODES.ERR_CODEMOD_FAILED);
+          return jsonError(msg, /** @type {import('../../types/base').Suggestion[]} */ (/** @type {unknown} */ ({receipt})), ERROR_CODES.ERR_CODEMOD_FAILED);
         }
         p.outro('Upgrade failed');
         process.exitCode = 1;
@@ -640,7 +846,15 @@ export function registerUpgrade(program) {
       }
 
       if (json) {
-        return jsonOut('upgrade.run', receipt);
+        // The emitted receipt intentionally differs from UpgradeRunResponse.data
+        // (see the typedef note above and the report): cast to the declared
+        // envelope shape until types/upgrade.d.ts is reconciled.
+        return jsonOut(
+          'upgrade.run',
+          /** @type {import('../../types/upgrade').UpgradeRunResponse['data']} */ (
+            /** @type {unknown} */ (receipt)
+          ),
+        );
       }
       p.outro(options.apply ? 'Upgrade complete' : 'Dry run complete');
     });