rea-agents 2.1.0 → 2.2.0

package/README.md

@@ -36,17 +36,18 @@ Reverse engineering normally makes the operator choose a tool, learn its API, mo
 
 ## Just ask your agent
 
-Install the REA skill:
+Run setup once. Agent integration installs an aligned MCP registration and the
+bundled routing skill together:
 
 ```bash
-npx skills add morluto/rea
+npx rea-agents setup
 ```
 
 Then ask:
 
 ```text
-Use REA to understand how search works in the Notes app, show me the
-evidence, and build a similar feature for my project.
+Understand how search works in the Notes app, show me the evidence, and build a
+similar feature for my project.
 ```
 
 Notes is only an example. Name any app you want to understand, or ask the agent to start with an overview.
@@ -97,9 +98,9 @@ shows its complete plan and asks before applying it. Setup does not update
 Homebrew, Node.js, or npm. `npx rea-agents setup` opens with the work it
 enables: investigate local apps from an agent, recover evidence through a
 deep-analysis provider, and reuse REA's guided workflow. It summarizes the
-detected agents, then asks which independent capabilities to set up: coding-agent
-access through MCP, the shared investigation skill, and—when needed—the Hopper
-provider. Nothing is preselected. Choosing MCP access opens a second empty
+detected agents, then asks which capabilities to set up: agent integration
+(MCP plus the matching guided workflow) and—when needed—the Hopper provider.
+Nothing is preselected. Choosing agent integration opens a second empty
 checklist for the specific detected agents that should receive a registration.
 
 REA keeps the journey inline so its history remains in the terminal. Selecting
@@ -131,10 +132,12 @@ Pass installer options after `bash -s --`, for example `--dry-run`, `--no-setup`
 ### With an agent — recommended
 
 ```bash
-npx skills add morluto/rea
+npx rea-agents setup
 ```
 
-Ask your agent to set up REA. It will check your supported host, explain anything it needs to install, ask for approval, and guide you through system prompts. After setup, restart the agent if it asks you to load the full REA toolset.
+Choose Agent Integration in the reviewed setup plan. REA installs the pinned MCP
+registration and its matching routing skill as one transaction. After setup,
+restart the configured agent so it loads the aligned integration.
 
 Review the setup plan, approve it if appropriate, then describe the app or feature you want to understand. Hopper can run in its free demo mode; if it shows a first-run prompt, choose the demo or enter an existing license.
 
@@ -456,17 +459,28 @@ Setup detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf,
 
 ### Manual MCP configuration
 
+<!-- x-release-please-start-version -->
+
 ```json
 {
   "mcpServers": {
     "rea": {
       "command": "npx",
-      "args": ["-y", "rea-agents@latest", "mcp"]
+      "args": ["-y", "rea-agents@2.2.0", "mcp"]
     }
   }
 }
 ```
 
+<!-- x-release-please-end -->
+
+Persistent registrations should use one exact package version. `rea setup`
+maintains that pin, upgrades the bundled skill at the same time, and gives Codex
+a 30-second startup allowance for a cold package-runner start. An interactive
+`rea upgrade` opens the updated setup plan after installing the new executable;
+structured or non-interactive upgrades tell you to run that sync explicitly.
+Restart clients whose approved registration changed.
+
 MCP clients that support prompts can also discover six ordered investigation
 workflows through `prompts/list`. Their optional identifier arguments use the
 current session for bounded `completion/complete` suggestions; see
@@ -693,6 +707,11 @@ Any agent that can run a local MCP server can use the manual configuration. Setu
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, architecture, tests, and release instructions. Generated API documentation is available under [`docs/api`](docs/api/index.html).
 
+`npm run verify:agent` runs brandless native, JavaScript-application, managed,
+and browser prompts through a real local Codex CLI. Its JSON report measures
+natural MCP use, first-tool routing, repeated calls, actual Codex token usage,
+completion quality, and explicit treatment of authority and unknowns.
+
 ## Project links
 
 [npm](https://www.npmjs.com/package/rea-agents) · [Issues](https://github.com/morluto/rea/issues) · [Security](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Hopper](https://www.hopperapp.com/) · [Ghidra](https://github.com/NationalSecurityAgency/ghidra)

package/dist/application/AndroidApplicationService.js

@@ -0,0 +1,17 @@
+import { androidApplicationProjectionInputSchema, projectAndroidApplication, } from "../domain/androidApplication.js";
+import { ANDROID_APPLICATION_PROVIDER } from "./InvestigationProviders.js";
+import { projectInventoryEvidence } from "./InventoryProjectionEvidence.js";
+const OPERATION = "project_android_application_graph";
+/** Project authenticated APK inventory Evidence into Android application Evidence. */
+export const projectAndroidApplicationEvidence = (rawInput) => {
+    return projectInventoryEvidence({
+        rawInput,
+        schema: androidApplicationProjectionInputSchema,
+        project: projectAndroidApplication,
+        operation: OPERATION,
+        predicateType: "rea.android-application-graph/v1",
+        provider: ANDROID_APPLICATION_PROVIDER,
+        subjectFormat: () => "apk",
+        protocolError: "Android application projection produced an invalid result",
+    });
+};

package/dist/application/AppleApplicationService.js

@@ -0,0 +1,17 @@
+import { appleApplicationProjectionInputSchema, projectAppleApplication, } from "../domain/appleApplication.js";
+import { APPLE_APPLICATION_PROVIDER } from "./InvestigationProviders.js";
+import { projectInventoryEvidence } from "./InventoryProjectionEvidence.js";
+const OPERATION = "project_apple_application_graph";
+/** Project authenticated IPA inventory Evidence into Apple application evidence. */
+export const projectAppleApplicationEvidence = (rawInput) => {
+    return projectInventoryEvidence({
+        rawInput,
+        schema: appleApplicationProjectionInputSchema,
+        project: projectAppleApplication,
+        operation: OPERATION,
+        predicateType: "rea.apple-application-graph/v1",
+        provider: APPLE_APPLICATION_PROVIDER,
+        subjectFormat: () => "ipa",
+        protocolError: "Apple application projection produced an invalid result",
+    });
+};

package/dist/application/ClientRegistrationStatus.js

@@ -6,7 +6,11 @@ import { PRODUCT_IDENTITY } from "../identity.js";
 import { supportedClients } from "./SupportedClients.js";
 const objectSchema = z.record(z.string(), z.unknown());
 const registrationSchema = z
-    .object({ command: z.string().min(1), args: z.array(z.string()).default([]) })
+    .object({
+    command: z.string().min(1),
+    args: z.array(z.string()).default([]),
+    startup_timeout_sec: z.number().positive().optional(),
+})
     .passthrough();
 /** Inspect supported client registrations without reading their environment. */
 export const readClientRegistrationStatuses = async (home, currentCommandPath = resolve(process.argv[1] ?? "unknown")) => {
@@ -25,7 +29,7 @@ export const readClientRegistrationStatuses = async (home, currentCommandPath =
             }
             const registration = registrationSchema.parse(raw);
             const command = [registration.command, ...registration.args];
-            statuses.push(status(client.name, client.configPath, command, registrationAligned(command, currentCommandPath)
+            statuses.push(status(client.name, client.configPath, command, registrationAligned(registration, client.name, currentCommandPath)
                 ? "aligned"
                 : "stale"));
         }
@@ -35,11 +39,14 @@ export const readClientRegistrationStatuses = async (home, currentCommandPath =
     }
     return statuses.sort((left, right) => left.client.localeCompare(right.client));
 };
-const registrationAligned = (command, currentCommandPath) => {
+const registrationAligned = (registration, client, currentCommandPath) => {
+    const command = [registration.command, ...registration.args];
+    if (client === "codex" && registration.startup_timeout_sec !== 30)
+        return false;
     if (command.length === 4 &&
         command[0] === "npx" &&
         command[1] === "-y" &&
-        command[2] === PRODUCT_IDENTITY.packageSpecifier &&
+        command[2] === PRODUCT_IDENTITY.registrationPackageSpecifier &&
         command[3] === "mcp")
         return true;
     return (command.length === 2 &&

package/dist/application/InventoryProjectionEvidence.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js";
+import { createEvidence, } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+/** Parse one inventory projection and wrap its deterministic result in Evidence v2. */
+export const projectInventoryEvidence = (options) => {
+    const parsed = options.schema.safeParse(options.rawInput);
+    if (!parsed.success)
+        return err(new AnalysisInputError(options.operation, { cause: parsed.error }));
+    try {
+        const result = options.project(parsed.data);
+        const first = parsed.data.inventory_evidence[0];
+        return ok(createEvidence(first?.subject === null || first?.subject === undefined
+            ? undefined
+            : {
+                path: first.subject.local_path,
+                sha256: result.root_sha256,
+                format: options.subjectFormat(first),
+            }, options.provider, {
+            predicateType: options.predicateType,
+            operation: options.operation,
+            parameters: {
+                inventory_evidence_ids: [...result.source_evidence_ids],
+                limits: jsonValueSchema.parse(parsed.data.limits),
+            },
+            result: jsonValueSchema.parse(result),
+            rawResult: null,
+            confidence: "inferred",
+            authority: "analyst-inference",
+            environment: null,
+            limitations: result.limitations,
+            evidenceLinks: result.source_evidence_ids,
+        }));
+    }
+    catch (cause) {
+        return err(cause instanceof TypeError || cause instanceof z.ZodError
+            ? new AnalysisInputError(options.operation, { cause })
+            : new AnalysisProtocolError(options.protocolError, { cause }));
+    }
+};

package/dist/application/InvestigationProviders.js

@@ -27,6 +27,18 @@ export const MANAGED_WORKFLOW_PROVIDER = {
     name: "REA managed-code workflows",
     version: "1",
 };
+/** Provider identity for deterministic Apple application projections. */
+export const APPLE_APPLICATION_PROVIDER = {
+    id: "rea-apple-application",
+    name: "REA Apple application workflows",
+    version: "1",
+};
+/** Provider identity for deterministic Android application projections. */
+export const ANDROID_APPLICATION_PROVIDER = {
+    id: "rea-android-application",
+    name: "REA Android application workflows",
+    version: "1",
+};
 /** Provider identity for deterministic static JavaScript application analysis. */
 export const JAVASCRIPT_APPLICATION_PROVIDER = {
     id: "rea-javascript-application",

package/dist/application/ProcessPairedExperiment.js

@@ -0,0 +1,72 @@
+import { processCaptureCancelled, } from "./ProcessCaptureError.js";
+import { captureProcessScenario } from "./ProcessHarness.js";
+import { compareProcessCaptures } from "../domain/processComparison.js";
+import { PROCESS_COMPARISON_DIMENSIONS } from "../domain/processComparison.js";
+import { analyzeProcessRepeatability, bindProcessScenario, } from "../domain/processPairedExperiment.js";
+import { err, ok } from "../domain/result.js";
+const productionCapturePort = {
+    capture: captureProcessScenario,
+};
+const captureRepeats = async (input) => {
+    const captures = [];
+    for (let index = 0; index < input.repeatCount; index += 1) {
+        if (input.signal?.aborted === true)
+            return err(processCaptureCancelled());
+        const capture = await input.port.capture(input.scenario, input.policy, input.signal);
+        if (!capture.ok)
+            return err(capture.error);
+        captures.push(capture.value);
+    }
+    return ok(captures);
+};
+/** Execute repeatability-first authority/candidate captures under one contract. */
+export const runPairedProcessExperiment = async (experiment, policy, options = {}) => {
+    const port = options.capturePort ?? productionCapturePort;
+    const authorityScenario = bindProcessScenario(experiment.shared_scenario, experiment.authority);
+    const candidateScenario = bindProcessScenario(experiment.shared_scenario, experiment.candidate);
+    const authorityRuns = await captureRepeats({
+        scenario: authorityScenario,
+        repeatCount: experiment.repeat_count,
+        policy,
+        port,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    if (!authorityRuns.ok)
+        return authorityRuns;
+    const candidateRuns = await captureRepeats({
+        scenario: candidateScenario,
+        repeatCount: experiment.repeat_count,
+        policy,
+        port,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    if (!candidateRuns.ok)
+        return candidateRuns;
+    const authorityRepeatability = analyzeProcessRepeatability(authorityRuns.value, experiment.required_dimensions);
+    const candidateRepeatability = analyzeProcessRepeatability(candidateRuns.value, experiment.required_dimensions);
+    const stable = authorityRepeatability.stable && candidateRepeatability.stable;
+    const allDimensionsRequired = PROCESS_COMPARISON_DIMENSIONS.every((dimension) => experiment.required_dimensions.includes(dimension));
+    const authorityLatest = authorityRuns.value.at(-1);
+    const candidateLatest = candidateRuns.value.at(-1);
+    const crossSide = stable &&
+        allDimensionsRequired &&
+        authorityLatest !== undefined &&
+        candidateLatest !== undefined
+        ? compareProcessCaptures(authorityLatest, candidateLatest, {
+            maxCaptureAgeMs: experiment.freshness_policy.max_capture_age_ms,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        })
+        : null;
+    return ok({
+        authority_runs: authorityRuns.value,
+        candidate_runs: candidateRuns.value,
+        authority_repeatability: authorityRepeatability,
+        candidate_repeatability: candidateRepeatability,
+        cross_side: crossSide,
+        cross_side_blocked_reason: crossSide !== null
+            ? null
+            : !allDimensionsRequired
+                ? "Cross-side comparison is blocked until every returned dimension is required and repeatable."
+                : "Cross-side comparison is blocked because a required same-side dimension is unstable.",
+    });
+};

package/dist/application/Setup.js

@@ -15,7 +15,7 @@ export { configureJsonClient, configureTomlClient };
 import { setupInstallFailure, } from "./SetupInstallFailure.js";
 export { canonicalSkillNeedsInstall, installCanonicalSkill };
 const registrationCommand = () => process.env.npm_command === "exec"
-    ? ["npx", "-y", PRODUCT_IDENTITY.packageSpecifier, "mcp"]
+    ? PRODUCT_IDENTITY.mcpCommand.split(" ")
     : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
 /** Discover, approve, and apply setup actions idempotently. */
 export const runSetup = async (options, host = systemSetupHost(), confirm) => {
@@ -47,7 +47,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             plannedActions,
             appliedActions,
             clients,
-            doctor: await host.doctor(),
+            doctor: discovery.initialDoctor,
             remediation: "Review the setup plan, then rerun interactively or with --yes.",
         };
     let detectedClients = selection.detectedClients;
@@ -110,7 +110,7 @@ const resolveSetupSelection = async (options, discovery, confirm) => {
             installSkill = plannedActions.some(({ kind }) => kind === "install_skill");
             detectedClients = detectedClients.filter((client) => selected.has(`configure_client:${client.name}`));
             interactiveApproval = decision.approved;
-            approved = decision.approved || plannedActions.length === 0;
+            approved = decision.approved;
         }
     }
     return {

package/dist/application/SetupClientConfiguration.js

@@ -9,9 +9,10 @@ import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
 const defaultCommand = () => [
     "npx",
     "-y",
-    PRODUCT_IDENTITY.packageSpecifier,
+    PRODUCT_IDENTITY.registrationPackageSpecifier,
     "mcp",
 ];
+const CODEX_STARTUP_TIMEOUT_SECONDS = 30;
 /** Back up, atomically update, and semantically read back one JSON MCP configuration. */
 export const configureJsonClient = async (client, environment = {}, command = defaultCommand()) => {
     const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
@@ -34,7 +35,7 @@ export const configureJsonClient = async (client, environment = {}, command = de
     catch {
         return { status: "failed", reason: "readback" };
     }
-    const desired = clientConfigurationDesired(normalizeProviderEnvironment(environment), command);
+    const desired = clientConfigurationDesired(client, normalizeProviderEnvironment(environment), command);
     if (sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
         return { status: "unchanged" };
     let backupPath;
@@ -95,7 +96,7 @@ export const configureTomlClient = async (client, environment = {}, command = de
     catch {
         return { status: "failed", reason: "readback" };
     }
-    const desired = clientConfigurationDesired(normalizeProviderEnvironment(environment), command);
+    const desired = clientConfigurationDesired(client, normalizeProviderEnvironment(environment), command);
     if (sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
         return { status: "unchanged" };
     const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
@@ -127,7 +128,7 @@ export const configureTomlClient = async (client, environment = {}, command = de
 };
 /** Determine whether an existing client configuration matches the desired registration. */
 export const clientConfigurationAligned = async (client, providerEnvironment, command) => {
-    const desired = clientConfigurationDesired(providerEnvironment, command);
+    const desired = clientConfigurationDesired(client, providerEnvironment, command);
     try {
         const original = await readFile(client.configPath, "utf8");
         const document = client.format === "toml"
@@ -162,7 +163,7 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
             remediation: "The configuration file could not be read. Check its permissions before rerunning setup.",
         };
     }
-    const desired = clientConfigurationDesired(providerEnvironment, command);
+    const desired = clientConfigurationDesired(client, providerEnvironment, command);
     try {
         const document = client.format === "toml"
             ? objectSchema.parse(parseToml(original))
@@ -207,11 +208,14 @@ const restoreConfig = async (path, original) => {
         // The backup remains available for the remediation reported by setup.
     }
 };
-const clientConfigurationDesired = (providerEnvironment, command) => {
+const clientConfigurationDesired = (client, providerEnvironment, command) => {
     const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
     return {
         command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
         args: command.slice(1),
+        ...(client.name === "codex"
+            ? { startup_timeout_sec: CODEX_STARTUP_TIMEOUT_SECONDS }
+            : {}),
         ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
     };
 };

package/dist/application/SetupPlan.js

@@ -48,8 +48,8 @@ const setupPlan = (input) => [
                 id: "install_skill",
                 kind: "install_skill",
                 label: "REA reverse-engineering skill",
-                target: join(homedir(), ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md"),
-                detail: "Install or update the bundled REA reverse-engineering skill.",
+                target: join(homedir(), ".agents/skills", PRODUCT_IDENTITY.skillName),
+                detail: "Install or update the bundled REA reverse-engineering skill and on-demand references.",
                 external: false,
                 operation: "install",
             },
@@ -112,6 +112,7 @@ export const discoverSetupActions = async (input) => {
         : []);
     const linuxDistribution = host.platform === "linux" ? await host.linuxDistribution() : undefined;
     return {
+        initialDoctor,
         installHopper,
         installSkill,
         detectedClients: clientPlans.map(({ client }) => client),

package/dist/application/SetupSkill.js

@@ -2,7 +2,15 @@ import { mkdir, readFile, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { PRODUCT_IDENTITY } from "../identity.js";
-const skillDestination = (home, name) => join(home, ".agents/skills", name, "SKILL.md");
+const SKILL_FILES = [
+    "SKILL.md",
+    "references/native-and-artifacts.md",
+    "references/javascript-applications.md",
+    "references/runtime-observation.md",
+    "references/evidence-workflows.md",
+    "references/controlled-replay.md",
+];
+const skillRoot = (home) => join(home, ".agents/skills", PRODUCT_IDENTITY.skillName);
 const readOptionalText = async (path) => {
     try {
         return await readFile(path, "utf8");
@@ -13,62 +21,58 @@ const readOptionalText = async (path) => {
         throw cause;
     }
 };
-const canonicalSkillFiles = async (home) => ({
-    destination: skillDestination(home, PRODUCT_IDENTITY.skillName),
-    content: await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`, import.meta.url), "utf8"),
-});
-/** Report whether setup would change the managed REA skill. */
+const canonicalSkillFiles = async (home) => Promise.all(SKILL_FILES.map(async (relativePath) => {
+    const destination = join(skillRoot(home), relativePath);
+    return {
+        destination,
+        content: await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/${relativePath}`, import.meta.url), "utf8"),
+        original: await readOptionalText(destination),
+    };
+}));
+/** Report whether setup would change any file in the managed REA skill bundle. */
 export const canonicalSkillNeedsInstall = async (home) => {
     try {
-        const { content, destination } = await canonicalSkillFiles(home);
-        return (await readOptionalText(destination)) !== content;
+        return (await canonicalSkillFiles(home)).some(({ content, original }) => original !== content);
     }
     catch {
         return true;
     }
 };
-/** Transactionally install or upgrade the versioned canonical REA skill. */
+const writeText = (path, content) => writeFileAtomic(path, content, { encoding: "utf8", mode: 0o600 });
+const restoreSkillFiles = async (changed) => {
+    for (const { destination, original } of [...changed].reverse()) {
+        if (original === undefined)
+            await rm(destination, { force: true });
+        else
+            await writeText(destination, original);
+    }
+};
+/** Transactionally install or upgrade the canonical REA skill and references. */
 export const installCanonicalSkill = async (home) => {
-    let destination = skillDestination(home, PRODUCT_IDENTITY.skillName);
-    let backup = `${destination}.rea.backup`;
-    let original;
-    let canonicalChanged = false;
+    let changed = [];
     try {
         const canonical = await canonicalSkillFiles(home);
-        destination = canonical.destination;
-        backup = `${destination}.rea.backup`;
-        const { content } = canonical;
-        original = await readOptionalText(destination);
-        if (original === content)
+        changed = canonical.filter(({ content, original }) => original !== content);
+        if (changed.length === 0)
             return "unchanged";
-        await mkdir(dirname(destination), { recursive: true });
-        if (original !== undefined && original !== content)
-            await writeFileAtomic(backup, original, {
-                encoding: "utf8",
-                mode: 0o600,
-            });
-        canonicalChanged = original !== content;
-        if (canonicalChanged)
-            await writeFileAtomic(destination, content, {
-                encoding: "utf8",
-                mode: 0o600,
-            });
-        if ((await readFile(destination, "utf8")) !== content)
-            throw new Error("skill readback mismatch");
+        for (const { destination, original } of changed) {
+            await mkdir(dirname(destination), { recursive: true });
+            if (original !== undefined)
+                await writeText(`${destination}.rea.backup`, original);
+        }
+        for (const { destination, content } of changed)
+            await writeText(destination, content);
+        for (const { destination, content } of changed)
+            if ((await readFile(destination, "utf8")) !== content)
+                throw new Error(`skill readback mismatch: ${destination}`);
         return "installed";
     }
     catch {
         try {
-            if (canonicalChanged && original === undefined)
-                await rm(destination, { force: true });
-            else if (canonicalChanged && original !== undefined)
-                await writeFileAtomic(destination, original, {
-                    encoding: "utf8",
-                    mode: 0o600,
-                });
+            await restoreSkillFiles(changed);
         }
         catch {
-            // The canonical backup remains beside the skill for operator recovery.
+            // Per-file backups remain beside changed files for operator recovery.
         }
         return "failed";
     }

package/dist/application/Uninstall.js

@@ -128,7 +128,13 @@ const isOwnedRegistration = (value) => {
         args[0] === "mcp") ||
         (command === "npx" &&
             (JSON.stringify(args) ===
-                JSON.stringify(["-y", PRODUCT_IDENTITY.packageSpecifier, "mcp"]) ||
+                JSON.stringify([
+                    "-y",
+                    PRODUCT_IDENTITY.registrationPackageSpecifier,
+                    "mcp",
+                ]) ||
+                JSON.stringify(args) ===
+                    JSON.stringify(["-y", PRODUCT_IDENTITY.packageSpecifier, "mcp"]) ||
                 JSON.stringify(args) ===
                     JSON.stringify(["-y", PRODUCT_IDENTITY.packageName, "mcp"]))));
 };

package/dist/application/Upgrade.js

@@ -9,6 +9,7 @@ import { PRODUCT_IDENTITY } from "../identity.js";
 const execFileAsync = promisify(execFile);
 const registryResponseSchema = z.object({ version: z.string().min(1) });
 const UPGRADE_COMMAND = "npm install --global rea-agents@latest";
+const CLI_SCRIPT_PATH = fileURLToPath(new URL("../../scripts/rea.mjs", import.meta.url));
 /** Check the npm registry and update the same global REA installation. */
 export const runUpgrade = async (currentVersion, host = systemUpgradeHost(), output = "human") => {
     const latestVersion = await host.latestVersion();
@@ -46,6 +47,12 @@ export const runUpgrade = async (currentVersion, host = systemUpgradeHost(), out
             reason: "install",
             remediation: `REA could not update through npm. Check npm registry access and global install permissions, then run: ${UPGRADE_COMMAND}`,
         };
+    const integrationSyncResult = await host.syncAgentIntegration(output);
+    const integrationSync = integrationSyncResult === undefined
+        ? "deferred"
+        : integrationSyncResult
+            ? "setup_invoked"
+            : "failed";
     return {
         status: "upgraded",
         previousVersion: currentVersion,
@@ -53,8 +60,11 @@ export const runUpgrade = async (currentVersion, host = systemUpgradeHost(), out
         versionCheck: "available",
         installMethod: "npm",
         command: UPGRADE_COMMAND,
+        integrationSync,
         clientRestartRequired: true,
-        remediation: "Rerun rea setup to refresh registrations and the skill, then restart clients that may retain an older MCP server.",
+        remediation: integrationSync === "setup_invoked"
+            ? "The updated setup journey was opened to align registrations and the skill. Restart clients whose approved registration changed."
+            : "Run rea setup --all-detected to align registrations and the skill, then restart clients that may retain an older MCP server.",
     };
 };
 /** Create the npm registry and subprocess effects for a production upgrade. */
@@ -79,6 +89,11 @@ export const systemUpgradeHost = () => ({
         prefix,
         `${PRODUCT_IDENTITY.packageName}@latest`,
     ], output),
+    syncAgentIntegration: (output) => output === "structured" ||
+        process.stdin.isTTY !== true ||
+        process.stderr.isTTY !== true
+        ? Promise.resolve(undefined)
+        : runCommand(process.execPath, [CLI_SCRIPT_PATH, "setup", "--all-detected"], "human"),
 });
 const systemNpmInstallationHost = {
     canonicalPath: realpath,

package/dist/cli/setupCommands.js

@@ -39,7 +39,7 @@ export const registerSetupCommands = (cli, logger) => {
             skill: z
                 .boolean()
                 .optional()
-                .describe("Install or skip the bundled REA skill"),
+                .describe("Override the bundled skill included with agent integrations"),
             dryRun: z
                 .boolean()
                 .default(false)
@@ -84,7 +84,8 @@ const runSetupCommand = async (input) => {
         process.stderr.isTTY === true;
     const hasExplicitScope = setupHasExplicitScope(options);
     if (options.yes && !hasExplicitScope)
-        process.stderr.write("!  Implicit `rea setup --yes` scope is deprecated; use `--all-detected --skill` to retain it.\n");
+        process.stderr.write("!  Implicit `rea setup --yes` scope is deprecated; use `--all-detected` to retain it.\n");
+    const agentIntegrationSelected = options.allDetected || options.client.length > 0;
     const result = await runSetup({
         approved: options.yes && !options.dryRun,
         installHopper: options.installHopper,
@@ -93,7 +94,11 @@ const runSetupCommand = async (input) => {
         ...(!hasExplicitScope || options.allDetected
             ? {}
             : { clientIds: options.client }),
-        ...(!hasExplicitScope ? {} : { installSkill: options.skill ?? false }),
+        ...(!hasExplicitScope
+            ? {}
+            : {
+                installSkill: options.skill ?? agentIntegrationSelected,
+            }),
         ...(interactive ? { onProgress: renderSetupProgress } : {}),
     }, systemSetupHost(createSystemDoctorHost()), interactive
         ? (actions) => confirmInteractiveSetup(actions, options.accessible)