nx 23.0.0-beta.20 → 23.0.0-beta.22

package/dist/src/adapter/compat.d.ts

@@ -1,2 +1,2 @@
 export declare const allowedProjectExtensions: readonly ["tags", "implicitDependencies", "configFilePath", "$schema", "generators", "namedInputs", "name", "files", "root", "sourceRoot", "projectType", "release", "includedScripts", "metadata", "owners", "nxCloudImplicitDependencies"];
-export declare const allowedWorkspaceExtensions: readonly ["$schema", "implicitDependencies", "affected", "defaultBase", "tasksRunnerOptions", "workspaceLayout", "plugins", "targetDefaults", "files", "generators", "namedInputs", "extends", "cli", "pluginsConfig", "defaultProject", "installation", "release", "nxCloudAccessToken", "nxCloudId", "nxCloudUrl", "nxCloudEncryptionKey", "parallel", "cacheDirectory", "useDaemonProcess", "useInferencePlugins", "neverConnectToCloud", "analytics", "sync", "useLegacyCache", "maxCacheSize", "tui", "owners"];
+export declare const allowedWorkspaceExtensions: readonly ["$schema", "implicitDependencies", "affected", "defaultBase", "tasksRunnerOptions", "workspaceLayout", "plugins", "targetDefaults", "files", "generators", "namedInputs", "extends", "cli", "pluginsConfig", "defaultProject", "installation", "release", "nxCloudAccessToken", "nxCloudId", "nxCloudUrl", "nxCloudEncryptionKey", "parallel", "cacheDirectory", "useDaemonProcess", "useInferencePlugins", "neverConnectToCloud", "analytics", "sync", "migrate", "useLegacyCache", "maxCacheSize", "tui", "owners"];

package/dist/src/adapter/compat.js

@@ -66,6 +66,7 @@ exports.allowedWorkspaceExtensions = [
     'neverConnectToCloud',
     'analytics',
     'sync',
+    'migrate',
     'useLegacyCache',
     'maxCacheSize',
     'tui',

package/dist/src/command-line/examples.js

@@ -356,19 +356,19 @@ exports.examples = {
             description: 'Prints the specified + inferred configuration for `my-app:build`',
         },
         {
-            command: 'show target my-app:build inputs',
+            command: 'show target inputs my-app:build',
             description: 'Prints the resolved inputs for `my-app:build`',
         },
         {
-            command: 'show target my-app:build inputs --check packages/my-app/index.html',
+            command: 'show target inputs my-app:build --check packages/my-app/index.html',
             description: 'Checks if `packages/my-app/index.html` is an input for `my-app:build`',
         },
         {
-            command: 'show target my-app:build outputs',
+            command: 'show target outputs my-app:build',
             description: 'Prints the outputs detected on disk for `my-app:build`',
         },
         {
-            command: 'show target my-app:build outputs --check packages/my-app/dist/index.html',
+            command: 'show target outputs my-app:build --check packages/my-app/dist/index.html',
             description: 'Checks if `packages/my-app/dist/index.html` is an output for `my-app:build`',
         },
     ],

package/dist/src/command-line/migrate/agentic/prompts/generic-validation.d.ts

@@ -6,6 +6,11 @@ export interface GenericValidationPromptContext {
     description?: string;
     /** Absolute path the agent must write its handoff file to. */
     handoffFileAbsolutePath: string;
+    /**
+     * Path to the migration's documentation file, if any - workspace-relative,
+     * or absolute when it resolves outside the workspace.
+     */
+    documentationPath?: string;
     /** Context captured from the deterministic generator phase. */
     impl: {
         /** Raw output from the generator (devkit logger + console). */

package/dist/src/command-line/migrate/agentic/prompts/generic-validation.js

@@ -27,16 +27,9 @@ exports.GENERIC_VALIDATION_FILE_LIST_CAP = 50;
 function buildGenericValidationUserPrompt(ctx) {
     const lines = [
         `You are validating the output of an Nx migration's deterministic generator phase. The generator has already run; inspect what it produced, verify the workspace is in a consistent state for what this migration intended to accomplish, apply any minor in-scope fixes the generator should have produced cleanly, and report findings.`,
-        ``,
-        `<migration>`,
-        `package: ${(0, shared_rendering_1.escapeXmlBody)(ctx.package)}`,
-        `version: ${(0, shared_rendering_1.escapeXmlBody)(ctx.version)}`,
-        `name: ${(0, shared_rendering_1.escapeXmlBody)(ctx.name)}`,
+        ...(0, shared_rendering_1.renderMigrationBlock)(ctx),
     ];
-    if (ctx.description) {
-        lines.push(...(0, shared_rendering_1.renderKeyMultilineValue)('description', (0, shared_rendering_1.escapeXmlBody)(ctx.description)));
-    }
-    lines.push(`</migration>`);
+    lines.push(...(0, shared_rendering_1.renderMigrationDocumentationBlock)(ctx.documentationPath));
     const logs = (0, shared_rendering_1.escapeXmlBody)((0, shared_rendering_1.stripAnsi)(ctx.impl.logs ?? '').trim());
     lines.push(...(0, shared_rendering_1.renderGeneratorOutputBlock)(logs));
     if (!ctx.impl.hasDiffContext && ctx.impl.changes.length > 0) {
@@ -44,12 +37,12 @@ function buildGenericValidationUserPrompt(ctx) {
     }
     const agentContext = (0, shared_rendering_1.filterNonEmptyStrings)(ctx.impl.agentContext ?? []);
     if (agentContext.length > 0) {
-        lines.push(``, `<advisory_context note="hints emitted by the generator; treat as supplementary context, not separate tasks">`, ...agentContext.map((entry) => (0, shared_rendering_1.renderListItem)((0, shared_rendering_1.escapeXmlBody)(entry))), `</advisory_context>`);
+        lines.push(...(0, shared_rendering_1.renderAdvisoryContext)('hints emitted by the generator; treat as supplementary context, not separate tasks', agentContext));
     }
     const firstStep = ctx.impl.hasDiffContext
         ? `1. Inspect this migration's changes. ${(0, shared_rendering_1.renderGitInspectInstruction)()} Resolve each affected path to its owning Nx project via \`nx show project <name>\` (or by reading the project's \`project.json\` / \`package.json\`) to discover which targets each project actually defines — do not assume \`typecheck\` / \`test\` / \`lint\` exist. If no typecheck-equivalent exists, \`build\` is an acceptable substitute.`
         : `1. Resolve each path in <files_changed> to its owning Nx project. Use \`nx show project <name>\` (or read the project's \`project.json\` / \`package.json\`) to discover which targets each project actually defines — do not assume \`typecheck\` / \`test\` / \`lint\` exist. If no typecheck-equivalent exists, \`build\` is an acceptable substitute.`;
-    lines.push(``, `<validation_instructions>`, firstStep, `2. Pick the smallest relevant subset of available targets to verify the change. Prefer \`nx affected -t <target>\` (or \`nx run <project>:<target>\` for a single project). When many small projects are affected, you may use \`nx run-many -t <target> -p <project1>,<project2>\` with the project list derived from the changed files. Unscoped \`nx run-many\` (no \`-p\`) is forbidden.`, `3. If a verification surfaces an issue the migration should have produced cleanly (e.g. a missing import, a type annotation the generator's template missed), you may apply a minor in-scope fix. The boundary is "what this migration intended to accomplish" — do not refactor, do not modify functionality unrelated to the migration, do not extend the migration's scope, do not touch code the migration was not concerned with. If you are unsure whether a fix is in scope, report it in \`summary\` instead of applying.`, `4. Apply every fix you can within scope, then write your handoff. On \`status: "success"\`, summarize what you verified and any fixes you applied. On \`status: "failed"\`, enumerate the unresolved findings in \`summary\` so the user can address them; no commit will be created from a failed run, so the generator's changes and your partial fixes will sit uncommitted in the working tree for the user to review.`, `</validation_instructions>`, ``, `Once you finish, write your handoff JSON to:`, `<handoff_path>`, (0, shared_rendering_1.escapeXmlBody)(ctx.handoffFileAbsolutePath), `</handoff_path>`);
+    lines.push(``, `<validation_instructions>`, firstStep, `2. Pick the smallest relevant subset of available targets to verify the change. Prefer \`nx affected -t <target>\` (or \`nx run <project>:<target>\` for a single project). When many small projects are affected, you may use \`nx run-many -t <target> -p <project1>,<project2>\` with the project list derived from the changed files. Unscoped \`nx run-many\` (no \`-p\`) is forbidden.`, `3. If a verification surfaces an issue the migration should have produced cleanly (e.g. a missing import, a type annotation the generator's template missed), you may apply a minor in-scope fix. The boundary is "what this migration intended to accomplish" — do not refactor, do not modify functionality unrelated to the migration, do not extend the migration's scope, do not touch code the migration was not concerned with. If you are unsure whether a fix is in scope, report it in \`summary\` instead of applying.`, `4. Apply every fix you can within scope, then write your handoff. On \`status: "success"\`, summarize what you verified and any fixes you applied. On \`status: "failed"\`, enumerate the unresolved findings in \`summary\` so the user can address them; no commit will be created from a failed run, so the generator's changes and your partial fixes will sit uncommitted in the working tree for the user to review.`, `</validation_instructions>`, ``, `Once you finish, write your handoff JSON to:`, ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath));
     return lines.join('\n');
 }
 function renderFileListBody(changes) {

package/dist/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.d.ts

@@ -8,6 +8,11 @@ export interface HybridPromptMigrationContext {
     promptPath: string;
     /** Absolute path the agent must write its handoff file to. */
     handoffFileAbsolutePath: string;
+    /**
+     * Path to the migration's documentation file, if any - workspace-relative,
+     * or absolute when it resolves outside the workspace.
+     */
+    documentationPath?: string;
     /** Context captured from the deterministic generator phase. */
     impl?: {
         /** Raw output from the generator (devkit logger + console). */

package/dist/src/command-line/migrate/agentic/prompts/hybrid-prompt-migration.js

@@ -18,16 +18,9 @@ const shared_rendering_1 = require("./shared-rendering");
 function buildHybridPromptUserPrompt(ctx) {
     const lines = [
         `Complete the AI-driven step that follows the generator phase of a two-phase Nx migration. The deterministic generator phase has already run; the sections below summarize what it did. The step may apply additional changes, verify the generator's output, or both — follow the instructions file.`,
-        ``,
-        `<migration>`,
-        `package: ${(0, shared_rendering_1.escapeXmlBody)(ctx.package)}`,
-        `version: ${(0, shared_rendering_1.escapeXmlBody)(ctx.version)}`,
-        `name: ${(0, shared_rendering_1.escapeXmlBody)(ctx.name)}`,
+        ...(0, shared_rendering_1.renderMigrationBlock)(ctx),
     ];
-    if (ctx.description) {
-        lines.push(...(0, shared_rendering_1.renderKeyMultilineValue)('description', (0, shared_rendering_1.escapeXmlBody)(ctx.description)));
-    }
-    lines.push(`</migration>`);
+    lines.push(...(0, shared_rendering_1.renderMigrationDocumentationBlock)(ctx.documentationPath));
     const logs = (0, shared_rendering_1.escapeXmlBody)((0, shared_rendering_1.stripAnsi)(ctx.impl?.logs ?? '').trim());
     const agentContext = (0, shared_rendering_1.filterNonEmptyStrings)(ctx.impl?.agentContext ?? []);
     const hasDiffContext = !!ctx.impl?.hasDiffContext;
@@ -45,9 +38,9 @@ function buildHybridPromptUserPrompt(ctx) {
         }
     }
     if (agentContext.length > 0) {
-        lines.push(``, `<advisory_context note="hints from the generator phase; consult while following the instructions, not as separate tasks">`, ...agentContext.map((entry) => (0, shared_rendering_1.renderListItem)((0, shared_rendering_1.escapeXmlBody)(entry))), `</advisory_context>`);
+        lines.push(...(0, shared_rendering_1.renderAdvisoryContext)('hints from the generator phase; consult while following the instructions, not as separate tasks', agentContext));
     }
-    lines.push(``, `<instructions_file>${(0, shared_rendering_1.escapeXmlBody)(ctx.promptPath)}</instructions_file>`, ``, `<precedence>If anything in the sections above conflicts with the instructions file, the instructions file wins.</precedence>`, ``, `Open the instructions file (path is workspace-relative), follow its instructions step by step using the sections above as context, then write your handoff JSON to:`, `<handoff_path>`, (0, shared_rendering_1.escapeXmlBody)(ctx.handoffFileAbsolutePath), `</handoff_path>`);
+    lines.push(``, `<instructions_file>${(0, shared_rendering_1.escapeXmlBody)(ctx.promptPath)}</instructions_file>`, ``, `<precedence>If anything in the sections above conflicts with the instructions file, the instructions file wins.</precedence>`, ``, `Open the instructions file (path is workspace-relative), follow its instructions step by step using the sections above as context, then write your handoff JSON to:`, ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath));
     return lines.join('\n');
 }
 function renderFileList(changes) {

package/dist/src/command-line/migrate/agentic/prompts/prompt-migration.d.ts

@@ -7,6 +7,11 @@ export interface PromptMigrationContext {
     promptPath: string;
     /** Absolute path the agent must write its handoff file to. */
     handoffFileAbsolutePath: string;
+    /**
+     * Path to the migration's documentation file, if any - workspace-relative,
+     * or absolute when it resolves outside the workspace.
+     */
+    documentationPath?: string;
 }
 /**
  * Builds the first user-facing message for a prompt-migration step.

package/dist/src/command-line/migrate/agentic/prompts/prompt-migration.js

@@ -15,15 +15,13 @@ const shared_rendering_1 = require("./shared-rendering");
 function buildPromptMigrationUserPrompt(ctx) {
     const lines = [
         `Apply one prompt-based migration to this Nx workspace.`,
+        ...(0, shared_rendering_1.renderMigrationBlock)(ctx),
+        ...(0, shared_rendering_1.renderMigrationDocumentationBlock)(ctx.documentationPath),
         ``,
-        `<migration>`,
-        `package: ${(0, shared_rendering_1.escapeXmlBody)(ctx.package)}`,
-        `version: ${(0, shared_rendering_1.escapeXmlBody)(ctx.version)}`,
-        `name: ${(0, shared_rendering_1.escapeXmlBody)(ctx.name)}`,
+        `<instructions_file>${(0, shared_rendering_1.escapeXmlBody)(ctx.promptPath)}</instructions_file>`,
+        ``,
+        `Open the instructions file (path is workspace-relative), follow its instructions step by step, then write your handoff JSON to:`,
+        ...(0, shared_rendering_1.renderHandoffPathFooter)(ctx.handoffFileAbsolutePath),
     ];
-    if (ctx.description) {
-        lines.push(...(0, shared_rendering_1.renderKeyMultilineValue)('description', (0, shared_rendering_1.escapeXmlBody)(ctx.description)));
-    }
-    lines.push(`</migration>`, ``, `<instructions_file>${(0, shared_rendering_1.escapeXmlBody)(ctx.promptPath)}</instructions_file>`, ``, `Open the instructions file (path is workspace-relative), follow its instructions step by step, then write your handoff JSON to:`, `<handoff_path>`, (0, shared_rendering_1.escapeXmlBody)(ctx.handoffFileAbsolutePath), `</handoff_path>`);
     return lines.join('\n');
 }

package/dist/src/command-line/migrate/agentic/prompts/shared-rendering.d.ts

@@ -7,3 +7,13 @@ export declare function filterNonEmptyStrings(entries: unknown[]): string[];
 export declare function escapeXmlBody(value: string): string;
 export declare function renderGitInspectInstruction(): string;
 export declare function renderGeneratorOutputBlock(logs: string): string[];
+export interface MigrationBlockContext {
+    package: string;
+    name: string;
+    version: string;
+    description?: string;
+}
+export declare function renderMigrationBlock(ctx: MigrationBlockContext): string[];
+export declare function renderHandoffPathFooter(handoffFileAbsolutePath: string): string[];
+export declare function renderAdvisoryContext(note: string, entries: string[]): string[];
+export declare function renderMigrationDocumentationBlock(documentationPath: string | undefined): string[];

package/dist/src/command-line/migrate/agentic/prompts/shared-rendering.js

@@ -8,6 +8,10 @@ exports.filterNonEmptyStrings = filterNonEmptyStrings;
 exports.escapeXmlBody = escapeXmlBody;
 exports.renderGitInspectInstruction = renderGitInspectInstruction;
 exports.renderGeneratorOutputBlock = renderGeneratorOutputBlock;
+exports.renderMigrationBlock = renderMigrationBlock;
+exports.renderHandoffPathFooter = renderHandoffPathFooter;
+exports.renderAdvisoryContext = renderAdvisoryContext;
+exports.renderMigrationDocumentationBlock = renderMigrationDocumentationBlock;
 function renderFileEntry(change) {
     return `[${change.type}] ${change.path}`;
 }
@@ -85,3 +89,57 @@ function renderGeneratorOutputBlock(logs) {
         `</generator_output>`,
     ];
 }
+// Identical `<migration>` block used by prompt-migration, hybrid, and
+// generic-validation builders. Leading blank included so callers can spread
+// directly after a lead sentence. Centralized so the schema and the
+// `escapeXmlBody` contract on values stay in lock-step.
+function renderMigrationBlock(ctx) {
+    const lines = [
+        ``,
+        `<migration>`,
+        `package: ${escapeXmlBody(ctx.package)}`,
+        `version: ${escapeXmlBody(ctx.version)}`,
+        `name: ${escapeXmlBody(ctx.name)}`,
+    ];
+    if (ctx.description) {
+        lines.push(...renderKeyMultilineValue('description', escapeXmlBody(ctx.description)));
+    }
+    lines.push(`</migration>`);
+    return lines;
+}
+// `<handoff_path>` footer that follows the "write your handoff JSON to:"
+// sentence. No leading blank — the block is part of that sentence's structure,
+// not a separate section.
+function renderHandoffPathFooter(handoffFileAbsolutePath) {
+    return [
+        `<handoff_path>`,
+        escapeXmlBody(handoffFileAbsolutePath),
+        `</handoff_path>`,
+    ];
+}
+// Advisory hints from the generator phase. The `note` attribute varies between
+// callers (hybrid vs generic-validation lead-in differs), so it's parameterized
+// rather than hardcoded. Entries are escaped here so callers can pass raw
+// strings.
+function renderAdvisoryContext(note, entries) {
+    return [
+        ``,
+        `<advisory_context note="${note}">`,
+        ...entries.map((entry) => renderListItem(escapeXmlBody(entry))),
+        `</advisory_context>`,
+    ];
+}
+// Points the agent at the migration's documentation file (reference, not
+// instructions). Returns `[]` when there's no doc so callers can spread without
+// guarding; the path is escaped like other user-authored values interpolated
+// into the prompt.
+function renderMigrationDocumentationBlock(documentationPath) {
+    if (!documentationPath)
+        return [];
+    return [
+        ``,
+        `<migration_documentation note="reference: documents what this migration does; read this file if you need more context on its intent, not as instructions">`,
+        escapeXmlBody(documentationPath),
+        `</migration_documentation>`,
+    ];
+}

package/dist/src/command-line/migrate/agentic/run-step.d.ts

@@ -31,6 +31,13 @@ export interface RunAgenticPromptStepInput {
         description?: string;
         prompt?: string;
     };
+    /**
+     * Path to the migration's documentation file, resolved by the orchestrator -
+     * workspace-relative, or absolute when the file resolves outside the
+     * workspace. Omitted when the migration declares no `documentation` or it
+     * can't be resolved.
+     */
+    documentationPath?: string;
     agentic: EnabledResolvedAgentic;
     runDir: string;
     installDepsIfChanged: () => Promise<void>;

package/dist/src/command-line/migrate/agentic/run-step.js

@@ -27,7 +27,7 @@ const runner_1 = require("./runner");
  * the file free of cross-imports with the orchestrator.
  */
 async function runAgenticPromptStep(input) {
-    const { root, migration, agentic, runDir, installDepsIfChanged, implContext, mode = 'author', } = input;
+    const { root, migration, agentic, runDir, installDepsIfChanged, implContext, documentationPath, mode = 'author', } = input;
     const handoffFilePath = (0, handoff_1.stepHandoffPath)(runDir, migration);
     // The system prompt tells the agent the parent dir exists, so the agent
     // doesn't defensively `mkdir -p` (which triggers a workspace-permission
@@ -52,6 +52,7 @@ async function runAgenticPromptStep(input) {
             version: migration.version,
             description: migration.description,
             handoffFileAbsolutePath: handoffFilePath,
+            documentationPath,
             impl: implContext,
         });
     }
@@ -63,6 +64,7 @@ async function runAgenticPromptStep(input) {
             description: migration.description,
             promptPath: migration.prompt,
             handoffFileAbsolutePath: handoffFilePath,
+            documentationPath,
         };
         userPrompt = implContext
             ? (0, hybrid_prompt_migration_1.buildHybridPromptUserPrompt)({ ...promptCtx, impl: implContext })

package/dist/src/command-line/migrate/agentic/runner.js

@@ -27,6 +27,9 @@ async function runAgentic(args) {
         windowsHide: true,
     });
     let child;
+    // Local alias so `@nx/workspace-require-windows-hide` recognizes the
+    // options arg as a tracked Identifier rather than giving up on a
+    // member-expression skip — keeps the lint rule strict on other call sites.
     const spawnOptions = adapted.options;
     try {
         child = (0, child_process_1.spawn)(adapted.binary, adapted.args, spawnOptions);

package/dist/src/command-line/migrate/agentic/select.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAgentic = resolveAgentic;
+const fs_1 = require("fs");
+const jsonc_parser_1 = require("jsonc-parser");
+const path_1 = require("path");
 const output_1 = require("../../../utils/output");
+const workspace_root_1 = require("../../../utils/workspace-root");
 const safe_prompt_1 = require("../safe-prompt");
 const detect_installed_1 = require("./detect-installed");
 const inception_1 = require("./inception");
@@ -32,20 +36,35 @@ async function resolveAgentic(input) {
         return { kind: 'disabled' };
     }
     const detected = await (0, detect_installed_1.detectInstalledAgents)(definitions_1.AGENT_DEFINITIONS);
-    const { enabled, explicitId } = await resolveFlag(input, isInteractive, detected);
+    const { enabled, explicitId, persist } = await resolveFlag(input, isInteractive, detected);
     if (!enabled) {
+        if (persist === false) {
+            persistAgenticChoice(false);
+        }
         return { kind: 'disabled' };
     }
     const selected = await selectAgent(detected, explicitId, isInteractive);
+    if (persist === true) {
+        persistAgenticChoice(true);
+    }
+    else if (persist === 'pin') {
+        persistAgenticChoice(selected.id);
+    }
     return { kind: 'enabled', selectedAgent: selected };
 }
 async function resolveFlag(input, isInteractive, detected) {
     if (input.agentic === true) {
-        requireInteractiveOrAbort(isInteractive);
+        if (!isInteractive) {
+            warnAgenticInteractiveOnly();
+            return { enabled: false };
+        }
         return { enabled: true };
     }
     if (typeof input.agentic === 'string') {
-        requireInteractiveOrAbort(isInteractive);
+        if (!isInteractive) {
+            warnAgenticInteractiveOnly();
+            return { enabled: false };
+        }
         return { enabled: true, explicitId: input.agentic };
     }
     // undefined — fire the up-front prompt only when we have a TTY, something
@@ -61,7 +80,7 @@ async function resolveFlag(input, isInteractive, detected) {
     if (detected.length === 0) {
         return { enabled: false };
     }
-    return { enabled: await firePromptForAgentic(input.migrations) };
+    return firePromptForAgentic(input.migrations, detected);
 }
 function requireInteractiveOrAbort(isInteractive) {
     if (isInteractive)
@@ -74,29 +93,102 @@ function requireInteractiveOrAbort(isInteractive) {
     });
     throw new Error('Agentic flow requires an interactive terminal.');
 }
-async function firePromptForAgentic(migrations) {
-    // The "Yes"/"No" hints below assume at least one prompt-bearing migration is
-    // queued. If we later extend the prompt to fire for generator-only runs
-    // (validation-only), the hints need to branch.
+function warnAgenticInteractiveOnly() {
+    output_1.output.warn({
+        title: 'Skipping the agentic flow: it is interactive-only in this release and this is a non-interactive terminal.',
+        bodyLines: [
+            'Continuing the migration without the agentic flow. Re-run in an interactive terminal to use it.',
+        ],
+    });
+}
+async function firePromptForAgentic(migrations, detected) {
+    // The apply hint assumes at least one prompt-bearing migration is queued. If
+    // we later extend the prompt to fire for generator-only runs (validation-
+    // only), the hint needs to branch.
     const promptCount = migrations.filter((m) => !!m.prompt).length;
-    const yesHint = `Apply ${promptCount} prompt migration${promptCount === 1 ? '' : 's'} and validate generator output with an AI agent`;
-    const noHint = `Skip prompts and run generators without AI validation`;
+    const applyHint = `Apply ${promptCount} prompt migration${promptCount === 1 ? '' : 's'} and validate generator output with an AI agent`;
+    const skipHint = `Skip prompts and run generators without AI validation`;
+    const rememberHint = `Saved to nx.json so Nx won't ask again`;
+    // The pin-vs-flexible distinction only matters when more than one agent is
+    // installed. With a single agent, "always" simply persists `true` and the
+    // pin option is dropped.
+    const multipleAgents = detected.length > 1;
+    const choices = [
+        { name: 'yes-once', message: 'Yes, just this time', hint: applyHint },
+        {
+            name: 'yes-flex',
+            message: multipleAgents
+                ? "Yes, always (I'll pick the agent each run)"
+                : 'Yes, always',
+            hint: rememberHint,
+        },
+        ...(multipleAgents
+            ? [
+                {
+                    name: 'yes-pin',
+                    message: 'Yes, always with the same agent',
+                    hint: rememberHint,
+                },
+            ]
+            : []),
+        { name: 'no-once', message: 'No, just this time', hint: skipHint },
+        { name: 'no-never', message: 'No, never', hint: rememberHint },
+    ];
     // Blank line keeps the prompt from gluing to the previous `npm install`
     // output or any earlier orchestrator line.
     console.log();
     // `as any` because enquirer's TS types lag the runtime (per-choice `hint`
-    // and `value` are supported but not in the .d.ts).
+    // is supported but not in the .d.ts).
     const response = await (0, safe_prompt_1.migratePrompt)({
-        name: 'enable',
-        type: 'autocomplete',
+        name: 'choice',
+        type: 'select',
         message: 'Enable the agentic flow?',
-        choices: [
-            { name: 'yes', message: 'Yes', hint: yesHint },
-            { name: 'no', message: 'No', hint: noHint },
-        ],
+        choices,
         initial: 0,
     });
-    return response.enable === 'yes';
+    switch (response.choice) {
+        case 'yes-once':
+            return { enabled: true };
+        case 'yes-flex':
+            return { enabled: true, persist: true };
+        case 'yes-pin':
+            return { enabled: true, persist: 'pin' };
+        case 'no-never':
+            return { enabled: false, persist: false };
+        case 'no-once':
+        default:
+            return { enabled: false };
+    }
+}
+// Persists the user's agentic choice to `nx.json` so the up-front prompt is
+// skipped on future runs. Edits the raw file in place via jsonc-parser, so it
+// touches only the `migrate.agentic` key and preserves comments, formatting,
+// and any `extends` preset (the prompt fires mid-migration, so a silent
+// reformat would be surprising). Never throws - a failed write only costs the
+// user the prompt again next time.
+function persistAgenticChoice(value) {
+    const nxJsonPath = (0, path_1.join)(workspace_root_1.workspaceRoot, 'nx.json');
+    if (!(0, fs_1.existsSync)(nxJsonPath)) {
+        output_1.output.warn({
+            title: `Could not save your agentic choice: no nx.json found at the workspace root.`,
+        });
+        return;
+    }
+    try {
+        const content = (0, fs_1.readFileSync)(nxJsonPath, 'utf-8');
+        const edits = (0, jsonc_parser_1.modify)(content, ['migrate', 'agentic'], value, {
+            formattingOptions: { insertSpaces: true, tabSize: 2 },
+        });
+        (0, fs_1.writeFileSync)(nxJsonPath, (0, jsonc_parser_1.applyEdits)(content, edits));
+        output_1.output.log({
+            title: `Saved your choice to nx.json (migrate.agentic = ${JSON.stringify(value)}). Nx won't ask again.`,
+        });
+    }
+    catch (e) {
+        output_1.output.warn({
+            title: `Could not save your agentic choice to nx.json: ${e instanceof Error ? e.message : String(e)}`,
+        });
+    }
 }
 async function selectAgent(detected, explicitId, isInteractive) {
     if (explicitId) {
@@ -104,22 +196,18 @@ async function selectAgent(detected, explicitId, isInteractive) {
         if (match) {
             return match;
         }
-        if (detected.length === 0) {
-            output_1.output.error({
-                title: `The agent "${explicitId}" was requested via --agentic but no supported AI agent is installed on this machine.`,
-                bodyLines: INSTALL_SUPPORTED_AGENTS_HINT,
+        // The requested agent isn't installed. Rather than aborting the migration,
+        // warn and fall through to resolve from the agents that ARE installed
+        // (pick when 2+, auto-select the only one, error only when none exist).
+        if (detected.length > 0) {
+            output_1.output.warn({
+                title: `The requested agent "${explicitId}" is not installed; using the installed agent(s) instead.`,
+                bodyLines: [
+                    'Currently installed agents:',
+                    ...detected.map((d) => `  - ${d.displayName} (${d.id})`),
+                ],
             });
-            throw new Error(`The requested agent "${explicitId}" is not installed.`);
         }
-        output_1.output.error({
-            title: `The agent "${explicitId}" was requested via --agentic but is not installed.`,
-            bodyLines: [
-                'Install the requested agent and re-run, or pass --agentic without an explicit agent to choose from installed ones.',
-                'Currently installed agents:',
-                ...detected.map((d) => `  - ${d.displayName} (${d.id})`),
-            ],
-        });
-        throw new Error(`The requested agent "${explicitId}" is not installed.`);
     }
     if (detected.length === 0) {
         output_1.output.error({

package/dist/src/command-line/migrate/command-object.d.ts

@@ -1,4 +1,46 @@
 import { CommandModule } from 'yargs';
+import type { AgenticArg } from './agentic/select';
 export declare const yargsMigrateCommand: CommandModule;
 export declare const yargsInternalMigrateCommand: CommandModule;
 export declare const DEFAULT_MIGRATION_COMMIT_PREFIX = "chore: [nx migration] ";
+/** Allowed values for `--mode` / `migrate.mode`. */
+export declare const MIGRATE_MODES: readonly ["first-party", "third-party", "all"];
+export type MigrateMode = (typeof MIGRATE_MODES)[number];
+/** Allowed values for `--multi-major-mode` / `migrate.multiMajorMode`. */
+export declare const MULTI_MAJOR_MODES: readonly ["direct", "gradual"];
+export type MultiMajorMode = (typeof MULTI_MAJOR_MODES)[number];
+/**
+ * The `nx migrate` args bag. Types the keys the nx.json overlay and the
+ * commit-prefix invariant read/write; the index signature keeps the rest of
+ * the yargs args flowing through untouched.
+ */
+export interface MigrateArgs {
+    packageAndVersion?: string;
+    runMigrations?: string;
+    mode?: MigrateMode;
+    /**
+     * nx.json `migrate.mode` default. Consumed by `resolveMode` only when the
+     * target is Nx itself; kept separate from `mode` so it is never mistaken for
+     * an explicit `--mode` (which would hard-fail for non-Nx targets).
+     */
+    modeFromConfig?: MigrateMode;
+    multiMajorMode?: MultiMajorMode;
+    createCommits?: boolean;
+    commitPrefix?: string;
+    agentic?: AgenticArg;
+    validate?: boolean;
+    [key: string]: any;
+}
+/**
+ * Whether a custom commit prefix would be silently ignored: commits aren't
+ * enabled and the agentic flow can't enable them either. Shared by the yargs
+ * `.check()` (CLI args) and the nx.json overlay (merged args) so the rule lives
+ * in one place. `agentic` may flip commits on by default, so a configured
+ * agentic value (other than `false`, and not paired with `--no-create-commits`)
+ * keeps the prefix in play.
+ */
+export declare function customCommitPrefixHasNoEffect(args: {
+    createCommits: boolean | undefined;
+    commitPrefix: string | undefined;
+    agentic: unknown;
+}): boolean;