@prisma/cli 8.0.0-rc.10-dev.83 → 8.0.0-rc.10-dev.85

package/dist/cli.js

@@ -61,11 +61,15 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 * unified binary's name.
 */
 const CLI_NAME = "prisma";
-/** The CLI docs page (also the update-check fallback instruction URL).
-*  The old /docs/orm/tools/prisma-cli path 308-redirects to the ORM CLI
-*  reference — the wrong docs for the unified CLI — so this points at
-*  the docs root until the unified CLI has its own page. */
-const CLI_DOCS_URL = "https://www.prisma.io/docs";
+/** The unified CLI's docs section (also the update-check fallback
+*  instruction URL). */
+const CLI_DOCS_URL = "https://www.prisma.io/docs/cli";
+/**
+* Base URL for structured-error documentation links. The engine composes
+* each diagnostic's docsUrl as base + code; every code is documented at
+* this page (registry: docs/reference/error-reference.md).
+*/
+const DOCS_ERRORS_BASE_URL = "https://www.prisma.io/docs/cli/error-reference/";
 //#endregion
 //#region src/auth/client.ts
 const CLIENT_ID = "cmm3lndn701oo0uefvxzo0ivw";
@@ -2460,7 +2464,7 @@ function loginWorkspaceUnknownError() {
 		}]
 	});
 }
-function nextActionsFor$5(agentSetupTipCommand) {
+function nextActionsFor$1(agentSetupTipCommand) {
 	return [
 		{
 			kind: "run-command",
@@ -2511,7 +2515,7 @@ function presentationsFor$2(spec, result) {
 			}]
 		],
 		stdout: () => rows.map((row) => `${row.label}: ${row.value}`),
-		next: () => nextActionsFor$5(spec.agentSetupTipCommand)
+		next: () => nextActionsFor$1(spec.agentSetupTipCommand)
 	};
 }
 const authLoginCommand = defineCommand({
@@ -2966,65 +2970,6 @@ async function promptForSession(stored, select) {
 	return requireSession(stored.sessions, workspaceId);
 }
 //#endregion
-//#region src/errors.ts
-var CliError = class extends Error {
-	code;
-	domain;
-	severity;
-	summary;
-	why;
-	fix;
-	debug;
-	where;
-	meta;
-	docsUrl;
-	exitCode;
-	nextSteps;
-	nextActions;
-	humanLines;
-	constructor(options) {
-		super(options.summary);
-		this.name = "CliError";
-		this.code = options.code;
-		this.domain = options.domain;
-		this.severity = "error";
-		this.summary = options.summary;
-		this.why = options.why;
-		this.fix = options.fix;
-		this.debug = options.debug ?? null;
-		this.where = options.where ?? null;
-		this.meta = options.meta ?? {};
-		this.docsUrl = options.docsUrl ?? null;
-		this.exitCode = options.exitCode ?? 1;
-		this.nextSteps = options.nextSteps ?? [];
-		this.nextActions = options.nextActions ?? [];
-		this.humanLines = options.humanLines && options.humanLines.length > 0 ? [...options.humanLines] : null;
-	}
-};
-function usageError(summary, why, fix, nextSteps = [], domain = "cli") {
-	return new CliError({
-		code: "USAGE_ERROR",
-		domain,
-		summary,
-		why,
-		fix,
-		exitCode: 2,
-		nextSteps
-	});
-}
-function authRequiredError(nextSteps = ["prisma auth login"], options = {}) {
-	return new CliError({
-		code: "AUTH_REQUIRED",
-		domain: "auth",
-		summary: "Authentication required",
-		why: "This command needs an authenticated session.",
-		fix: "Run prisma auth login, or rerun the command in a TTY to sign in interactively.",
-		debug: options.debug,
-		exitCode: 1,
-		nextSteps
-	});
-}
-//#endregion
 //#region src/controllers/branch.ts
 function sortBranches(branches) {
 	return branches.slice().sort((left, right) => {
@@ -3067,14 +3012,17 @@ function toBranchSummary(branch) {
 }
 function branchApiError(summary, response, error) {
 	const status = response?.status ?? 0;
-	return new CliError({
-		code: error?.error?.code ?? "BRANCH_API_ERROR",
-		domain: "branch",
-		summary,
+	const apiCode = error?.error?.code;
+	return new CliStructuredError("BRANCH.API_ERROR", summary, {
 		why: error?.error?.message ?? `The Management API returned status ${status || "unknown"}.`,
-		fix: error?.error?.hint ?? "Re-run with --trace for the underlying API response details.",
-		exitCode: 1,
-		nextSteps: []
+		...status || apiCode !== void 0 ? { meta: {
+			...status ? { status } : {},
+			...apiCode !== void 0 ? { apiCode } : {}
+		} } : {},
+		nextActions: [{
+			kind: "user-choice",
+			label: error?.error?.hint ?? "Re-run with --log-level verbose for the underlying API response details."
+		}]
 	});
 }
 //#endregion
@@ -3342,54 +3290,50 @@ function createManagementProjectProvider(client) {
 		}
 	};
 }
+function userChoice$6(label) {
+	return {
+		kind: "user-choice",
+		label
+	};
+}
 function projectRenameFailedError(name, error) {
-	return new CliError({
-		code: "PROJECT_RENAME_FAILED",
-		domain: "project",
-		summary: "Project rename failed",
+	return new CliStructuredError("PROJECT.RENAME_FAILED", "Project rename failed", {
 		why: error?.error?.message ?? `The platform rejected the name "${name}".`,
-		fix: error?.error?.hint ?? "Pass a different project name and retry the rename.",
-		exitCode: 1,
-		nextSteps: []
+		nextActions: [userChoice$6(error?.error?.hint ?? "Pass a different project name and retry the rename.")]
 	});
 }
 function projectDeleteBlockedError(projectId, error) {
-	return new CliError({
-		code: "PROJECT_DELETE_BLOCKED",
-		domain: "project",
-		summary: "Project cannot be deleted yet",
+	const deleteServicesCommand = formatPrismaCliCommand([
+		"service",
+		"delete",
+		"--service",
+		"<name>"
+	]);
+	return new CliStructuredError("PROJECT.DELETE_BLOCKED", "Project cannot be deleted yet", {
 		why: error?.error?.message ?? `Project "${projectId}" still has active deployments.`,
-		fix: "Delete the project's services first, then retry the deletion.",
-		exitCode: 1,
-		nextSteps: [formatPrismaCliCommand([
-			"service",
-			"delete",
-			"--service",
-			"<name>"
-		])]
+		nextActions: [userChoice$6("Delete the project's services first, then retry the deletion."), {
+			kind: "run-command",
+			label: deleteServicesCommand,
+			command: deleteServicesCommand
+		}]
 	});
 }
 function projectTransferRejectedError(projectId, error) {
-	return new CliError({
-		code: "PROJECT_TRANSFER_REJECTED",
-		domain: "project",
-		summary: "Project transfer was rejected",
+	return new CliStructuredError("PROJECT.TRANSFER_REJECTED", "Project transfer was rejected", {
 		why: error?.error?.message ?? `The platform rejected the transfer of project "${projectId}", for example because the recipient token is invalid or expired.`,
-		fix: "Check the recipient workspace session or token and retry the transfer.",
-		exitCode: 1,
-		nextSteps: []
+		nextActions: [userChoice$6("Check the recipient workspace session or token and retry the transfer.")]
 	});
 }
 function projectApiError(summary, response, error) {
 	const status = response?.status ?? 0;
-	return new CliError({
-		code: error?.error?.code ?? "PROJECT_API_ERROR",
-		domain: "project",
-		summary,
+	const apiCode = error?.error?.code;
+	return new CliStructuredError("PROJECT.API_ERROR", summary, {
 		why: error?.error?.message ?? `The Management API returned status ${status || "unknown"}.`,
-		fix: error?.error?.hint ?? "Re-run with --trace for the underlying API response details.",
-		exitCode: 1,
-		nextSteps: []
+		...apiCode !== void 0 || status ? { meta: {
+			...status ? { status } : {},
+			...apiCode !== void 0 ? { apiCode } : {}
+		} } : {},
+		nextActions: [userChoice$6(error?.error?.hint ?? "Re-run with --log-level verbose for the underlying API response details.")]
 	});
 }
 //#endregion
@@ -3479,60 +3423,59 @@ async function inspectProjectBinding(options) {
 		});
 	});
 }
+function runCommand$5(command, reason) {
+	return {
+		kind: "run-command",
+		label: command,
+		command,
+		...reason === void 0 ? {} : { reason }
+	};
+}
+function userChoice$5(label) {
+	return {
+		kind: "user-choice",
+		label
+	};
+}
 function projectNotFoundError$1(projectRef, workspace) {
-	return projectResolutionErrorToCliError(new ProjectNotFoundError(projectRef, workspace));
+	return projectResolutionErrorToStructured(new ProjectNotFoundError(projectRef, workspace));
 }
-function projectNotFoundCliError(projectRef, workspace) {
-	return new CliError({
-		code: "PROJECT_NOT_FOUND",
-		domain: "project",
-		summary: "Project not found",
+function projectNotFoundStructuredError(projectRef, workspace) {
+	return new CliStructuredError("PROJECT.NOT_FOUND", "Project not found", {
 		why: `The project "${projectRef}" does not exist in workspace "${workspace.name}" or is not accessible.`,
-		fix: "Pass a project id or name from prisma project list.",
-		exitCode: 1,
-		nextSteps: ["prisma project list"]
+		nextActions: [userChoice$5("Pass a project id or name from prisma project list."), runCommand$5("prisma project list")]
 	});
 }
 function projectAmbiguousError(projectRef, matches) {
-	return projectResolutionErrorToCliError(new ProjectAmbiguousError(projectRef, matches));
+	return projectResolutionErrorToStructured(new ProjectAmbiguousError(projectRef, matches));
 }
-function projectAmbiguousCliError(projectRef, matches) {
+function projectAmbiguousStructuredError(projectRef, matches) {
 	const firstMatch = matches[0];
-	const nextSteps = ["prisma project list"];
-	if (firstMatch) nextSteps.push(`prisma project link ${firstMatch.id}`);
-	return new CliError({
-		code: "PROJECT_AMBIGUOUS",
-		domain: "project",
-		summary: "Project resolution is ambiguous",
+	const nextActions = [userChoice$5("Pass --project <id-or-name> to choose the project explicitly."), runCommand$5("prisma project list")];
+	if (firstMatch) nextActions.push(runCommand$5(`prisma project link ${firstMatch.id}`));
+	return new CliStructuredError("PROJECT.AMBIGUOUS", "Project resolution is ambiguous", {
 		why: projectRef ? `Multiple projects matched "${projectRef}".` : "Multiple projects matched the current directory context.",
-		fix: "Pass --project <id-or-name> to choose the project explicitly.",
 		meta: { matches: matches.map((project) => ({
 			id: project.id,
 			name: project.name
 		})) },
-		exitCode: 1,
-		nextSteps
+		nextActions
 	});
 }
-function localStateStaleCliError() {
-	return new CliError({
-		code: "LOCAL_STATE_STALE",
-		domain: "project",
-		summary: "Local project binding is stale",
+function localStateStaleStructuredError() {
+	return new CliStructuredError("PROJECT.LOCAL_STATE_STALE", "Local project binding is stale", {
 		why: `The target recorded in ${LOCAL_RESOLUTION_PIN_RELATIVE_PATH} is no longer available in the selected workspace.`,
-		fix: `Delete ${LOCAL_RESOLUTION_PIN_RELATIVE_PATH}, then choose a Project explicitly.`,
 		meta: { pinPath: LOCAL_RESOLUTION_PIN_RELATIVE_PATH },
-		exitCode: 1,
-		nextSteps: ["prisma project list", "prisma project link <id-or-name>"]
+		nextActions: [
+			userChoice$5(`Delete ${LOCAL_RESOLUTION_PIN_RELATIVE_PATH}, then choose a Project explicitly.`),
+			runCommand$5("prisma project list"),
+			runCommand$5("prisma project link <id-or-name>")
+		]
 	});
 }
-function localProjectWorkspaceMismatchCliError(options) {
-	return new CliError({
-		code: "LOCAL_PROJECT_WORKSPACE_MISMATCH",
-		domain: "project",
-		summary: "Project link uses another workspace",
+function localProjectWorkspaceMismatchStructuredError(options) {
+	return new CliStructuredError("PROJECT.LOCAL_WORKSPACE_MISMATCH", "Project link uses another workspace", {
 		why: `${LOCAL_RESOLUTION_PIN_RELATIVE_PATH} links this directory to project ${options.pinnedProjectId} in workspace ${options.pinnedWorkspaceId}, but your current CLI session is workspace "${options.activeWorkspace.name}" (${options.activeWorkspace.id}).`,
-		fix: "Switch to the linked workspace, or relink this directory to a project in the current workspace.",
 		meta: {
 			pinPath: LOCAL_RESOLUTION_PIN_RELATIVE_PATH,
 			pinnedWorkspaceId: options.pinnedWorkspaceId,
@@ -3540,27 +3483,29 @@ function localProjectWorkspaceMismatchCliError(options) {
 			activeWorkspaceId: options.activeWorkspace.id,
 			activeWorkspaceName: options.activeWorkspace.name
 		},
-		exitCode: 1,
-		nextSteps: [
-			`prisma auth workspace use ${options.pinnedWorkspaceId}`,
-			"prisma project list",
-			"prisma project link <id-or-name>"
+		nextActions: [
+			userChoice$5("Switch to the linked workspace, or relink this directory to a project in the current workspace."),
+			runCommand$5(`prisma auth workspace use ${options.pinnedWorkspaceId}`),
+			runCommand$5("prisma project list"),
+			runCommand$5("prisma project link <id-or-name>")
 		]
 	});
 }
 /**
-* Converts expected project-resolution variants to command-boundary CliErrors.
+* Converts expected project-resolution variants to the structured errors
+* a command boundary raises — the codes here are the registered PROJECT.*
+* codes, assigned at origin.
 * `LocalResolutionPinReadAbortedError` and `UnhandledException` intentionally
 * propagate as exceptions; callers such as `resolveProjectShowInRealMode`
 * throw this helper's result, so passthrough variants should keep bubbling.
 */
-function projectResolutionErrorToCliError(error) {
+function projectResolutionErrorToStructured(error) {
 	return matchError(error, {
-		ProjectNotFoundError: (error) => projectNotFoundCliError(error.projectRef, error.workspace),
-		ProjectAmbiguousError: (error) => projectAmbiguousCliError(error.projectRef, error.matches),
-		ProjectSetupRequiredError: (error) => projectSetupRequiredCliError(error),
-		LocalStateStaleError: () => localStateStaleCliError(),
-		LocalProjectWorkspaceMismatchError: (error) => localProjectWorkspaceMismatchCliError({
+		ProjectNotFoundError: (error) => projectNotFoundStructuredError(error.projectRef, error.workspace),
+		ProjectAmbiguousError: (error) => projectAmbiguousStructuredError(error.projectRef, error.matches),
+		ProjectSetupRequiredError: (error) => projectSetupRequiredStructuredError(error),
+		LocalStateStaleError: () => localStateStaleStructuredError(),
+		LocalProjectWorkspaceMismatchError: (error) => localProjectWorkspaceMismatchStructuredError({
 			pinnedWorkspaceId: error.pinnedWorkspaceId,
 			pinnedProjectId: error.pinnedProjectId,
 			activeWorkspace: error.activeWorkspace
@@ -3590,17 +3535,11 @@ async function projectSetupRequiredError(options) {
 		suggestion
 	});
 }
-function projectSetupRequiredCliError(error) {
+function projectSetupRequiredStructuredError(error) {
 	const suggestion = error.suggestion;
-	return new CliError({
-		code: "PROJECT_SETUP_REQUIRED",
-		domain: "project",
-		summary: "Choose a Project before running this command",
+	return new CliStructuredError("PROJECT.SETUP_REQUIRED", "Choose a Project before running this command", {
 		why: error.message,
-		fix: "Link the directory to an existing Project, or pass --project <id-or-name> for this command.",
 		meta: { ...suggestion },
-		exitCode: 1,
-		nextSteps: ["prisma project list", ...suggestion.recoveryCommands],
 		nextActions: buildProjectSetupNextActions({
 			commandName: error.commandName,
 			suggestedProjectName: suggestion.suggestedProjectName
@@ -3613,7 +3552,6 @@ function buildProjectSetupNextActions(options = {}) {
 	const retryCommand = options.retryCommand ?? recoveryCommands[1];
 	const actions = [{
 		kind: "user-choice",
-		journey: "project-setup",
 		label: "Ask the user whether to link an existing Project or create a new one",
 		commands: [
 			"prisma project list",
@@ -3623,7 +3561,6 @@ function buildProjectSetupNextActions(options = {}) {
 		reason: options.reason ?? "This directory is not linked to a Prisma Project. Package and directory names are suggestions only, not a safe Project selection."
 	}, {
 		kind: "run-command",
-		journey: "project-setup",
 		label: "Link the chosen Project",
 		command: linkCommand,
 		reason: "Linking writes the durable local Project binding for this directory."
@@ -3631,14 +3568,12 @@ function buildProjectSetupNextActions(options = {}) {
 	const createCommand = options.createCommand ?? (options.suggestedProjectName ? `prisma project create ${formatCommandArgument(options.suggestedProjectName)}` : void 0);
 	if (createCommand) actions.push({
 		kind: "run-command",
-		journey: "project-setup",
 		label: "Create and link a new Project",
 		command: createCommand,
 		reason: "Use this when the user wants a new Prisma Project instead of an existing one."
 	});
 	if (options.commandName) actions.push({
 		kind: "run-command",
-		journey: "recover",
 		label: "Retry with an explicit Project",
 		command: retryCommand ?? `prisma ${options.commandName} --project <id-or-name>`
 	});
@@ -3770,6 +3705,28 @@ function toProjectSummary$1(project) {
 //#region src/controllers/project.ts
 const GITHUB_INSTALL_POLL_INTERVAL_MS = 2e3;
 const GITHUB_INSTALL_POLL_TIMEOUT_MS = 12e4;
+function runCommand$4(command) {
+	return {
+		kind: "run-command",
+		label: command,
+		command
+	};
+}
+function userChoice$4(label) {
+	return {
+		kind: "user-choice",
+		label
+	};
+}
+/** A URL is not a command: putting one in `command` tells a consumer to
+*  execute it. */
+function openUrl(url) {
+	return {
+		kind: "open-url",
+		label: url,
+		url
+	};
+}
 async function readProjectListLocalBinding(cwd, projects, signal) {
 	const pinResult = await readLocalResolutionPin(cwd, signal);
 	if (pinResult.isErr()) return localPinReadErrorToInvalidLocalBinding(pinResult.error);
@@ -3790,37 +3747,31 @@ function localPinReadErrorToInvalidLocalBinding(error) {
 	});
 }
 function transferRecipientRequiredError(formatCommand) {
-	return new CliError({
-		code: "TRANSFER_RECIPIENT_REQUIRED",
-		domain: "project",
-		summary: "Transfer recipient required",
+	return new CliStructuredError("PROJECT.TRANSFER_RECIPIENT_REQUIRED", "Transfer recipient required", {
 		why: "Project transfer needs the receiving workspace.",
-		fix: "Pass --to-workspace <id-or-name> for a locally authenticated workspace, or --recipient-token <token> for a cross-account transfer.",
-		exitCode: 2,
-		nextSteps: [formatCommand([
-			"auth",
-			"workspace",
-			"list"
-		]), formatCommand([
-			"project",
-			"transfer",
-			"<project>",
-			"--to-workspace",
-			"<id-or-name>",
-			"--confirm",
-			"<project-id>"
-		])]
+		nextActions: [
+			userChoice$4("Pass --to-workspace <id-or-name> for a locally authenticated workspace, or --recipient-token <token> for a cross-account transfer."),
+			runCommand$4(formatCommand([
+				"auth",
+				"workspace",
+				"list"
+			])),
+			runCommand$4(formatCommand([
+				"project",
+				"transfer",
+				"<project>",
+				"--to-workspace",
+				"<id-or-name>",
+				"--confirm",
+				"<project-id>"
+			]))
+		]
 	});
 }
 function transferRecipientUnavailableError(formatCommand) {
-	return new CliError({
-		code: "TRANSFER_RECIPIENT_UNAVAILABLE",
-		domain: "project",
-		summary: "Local workspace sessions are unavailable",
+	return new CliStructuredError("PROJECT.TRANSFER_RECIPIENT_UNAVAILABLE", "Local workspace sessions are unavailable", {
 		why: `--to-workspace resolves locally stored OAuth sessions, but ${SERVICE_TOKEN_ENV_VAR} is set and service-token mode does not read them.`,
-		fix: "Pass --recipient-token <token> with an access token for the receiving workspace, or unset the service token.",
-		exitCode: 1,
-		nextSteps: [formatCommand([
+		nextActions: [userChoice$4("Pass --recipient-token <token> with an access token for the receiving workspace, or unset the service token."), runCommand$4(formatCommand([
 			"project",
 			"transfer",
 			"<project>",
@@ -3828,7 +3779,7 @@ function transferRecipientUnavailableError(formatCommand) {
 			"<token>",
 			"--confirm",
 			"<project-id>"
-		])]
+		]))]
 	});
 }
 async function cleanupLocalPinForProject(context, projectId, hooks) {
@@ -3966,8 +3917,8 @@ async function findRepositoryInInstallationIfAvailable(api, installationId, repo
 	}
 }
 function isUnavailableScmInstallationError(error) {
-	if (!(error instanceof CliError) || error.code !== "REPO_CONNECTION_FAILED") return false;
-	return error.meta.status === 404 || error.meta.status === 422;
+	if (!CliStructuredError.is(error) || error.code !== "GIT.REPO_CONNECTION_FAILED") return false;
+	return error.meta?.status === 404 || error.meta?.status === 422;
 }
 async function createGitHubInstallIntent(api, workspaceId, signal) {
 	const { data, error, response } = await api.POST("/v1/scm-installations/install-intents", {
@@ -4020,69 +3971,50 @@ function toRepositoryConnection(record) {
 	};
 }
 function unsupportedRepositoryProviderError() {
-	return new CliError({
-		code: "REPO_PROVIDER_UNSUPPORTED",
-		domain: "project",
-		summary: "Repository provider is not supported",
+	return new CliStructuredError("GIT.REPO_PROVIDER_UNSUPPORTED", "Repository provider is not supported", {
 		why: "Repository connection supports GitHub repository URLs only.",
-		fix: "Pass a GitHub repository URL such as git@github.com:prisma/prisma-cli.git.",
-		exitCode: 2,
-		nextSteps: ["prisma git connect git@github.com:owner/repo.git"]
+		nextActions: [userChoice$4("Pass a GitHub repository URL such as git@github.com:prisma/prisma-cli.git."), runCommand$4("prisma git connect git@github.com:owner/repo.git")]
 	});
 }
 function repoNotConnectedError() {
-	return new CliError({
-		code: "REPO_NOT_CONNECTED",
-		domain: "project",
-		summary: "No GitHub repository connected",
+	return new CliStructuredError("GIT.REPO_NOT_CONNECTED", "No GitHub repository connected", {
 		why: "The resolved project does not have an active GitHub repository connection.",
-		fix: "Run prisma git connect before disconnecting.",
-		exitCode: 1,
-		nextSteps: ["prisma git connect"]
+		nextActions: [userChoice$4("Run prisma git connect before disconnecting."), runCommand$4("prisma git connect")]
 	});
 }
-function repoInstallationRequiredError(repository, installUrl, opened) {
-	return new CliError({
-		code: "REPO_INSTALLATION_REQUIRED",
-		domain: "project",
-		summary: "GitHub App installation required",
+function repoInstallationRequiredError(repository, installUrl) {
+	return new CliStructuredError("GIT.REPO_INSTALLATION_REQUIRED", "GitHub App installation required", {
 		why: `The selected workspace does not have a GitHub App installation that can be used to link ${repository.fullName}.`,
-		fix: opened ? "Finish installing the GitHub App in the browser, then rerun prisma git connect." : "Open the GitHub App installation URL, approve access, then rerun prisma git connect.",
 		meta: {
 			repository: repository.fullName,
-			installUrl,
-			opened
+			installUrl
 		},
-		exitCode: 1,
-		nextSteps: [installUrl, `prisma git connect ${repository.url}`]
+		nextActions: [
+			userChoice$4("Finish installing the GitHub App in the browser, then rerun prisma git connect."),
+			openUrl(installUrl),
+			runCommand$4(`prisma git connect ${repository.url}`)
+		]
 	});
 }
-function repoNotAccessibleError(repository, installUrl, opened) {
-	return new CliError({
-		code: "REPO_NOT_ACCESSIBLE",
-		domain: "project",
-		summary: "GitHub repository is not accessible",
+function repoNotAccessibleError(repository, installUrl) {
+	return new CliStructuredError("GIT.REPO_NOT_ACCESSIBLE", "GitHub repository is not accessible", {
 		why: `The GitHub App installations connected to this workspace do not expose ${repository.fullName}.`,
-		fix: "Open the GitHub App installation URL, grant access to this repository, then rerun prisma git connect.",
 		meta: {
 			repository: repository.fullName,
-			installUrl,
-			opened
+			installUrl
 		},
-		exitCode: 1,
-		nextSteps: [installUrl, `prisma git connect ${repository.url}`]
+		nextActions: [
+			userChoice$4("Open the GitHub App installation URL, grant access to this repository, then rerun prisma git connect."),
+			openUrl(installUrl),
+			runCommand$4(`prisma git connect ${repository.url}`)
+		]
 	});
 }
 function repoAlreadyConnectedError(repositoryFullName) {
-	return new CliError({
-		code: "REPO_ALREADY_CONNECTED",
-		domain: "project",
-		summary: "Project already has a GitHub repository connected",
+	return new CliStructuredError("GIT.REPO_ALREADY_CONNECTED", "Project already has a GitHub repository connected", {
 		why: `The resolved project is already connected to ${repositoryFullName}.`,
-		fix: "Disconnect the existing repository before connecting a different one.",
 		meta: { repository: repositoryFullName },
-		exitCode: 1,
-		nextSteps: ["prisma git disconnect"]
+		nextActions: [userChoice$4("Disconnect the existing repository before connecting a different one."), runCommand$4("prisma git disconnect")]
 	});
 }
 function repositoryFullNamesMatch(left, right) {
@@ -4093,26 +4025,22 @@ function repoConnectionApiError(summary, response, error) {
 	const apiCode = error?.error?.code;
 	const apiMessage = error?.error?.message;
 	const apiHint = error?.error?.hint;
-	if (status === 401 || status === 403) return authRequiredError(["prisma auth login"]);
-	return new CliError({
-		code: "REPO_CONNECTION_FAILED",
-		domain: "project",
-		summary,
-		why: apiMessage ?? `The Management API returned status ${status || "unknown"}.`,
-		fix: apiHint ?? repoConnectionFixForStatus(status),
+	const unauthorized = status === 401 || status === 403;
+	return new CliStructuredError("GIT.REPO_CONNECTION_FAILED", summary, {
+		why: apiMessage ?? (unauthorized ? `The Management API rejected the request as unauthorized (HTTP ${status}).` : `The Management API returned status ${status || "unknown"}.`),
 		meta: {
 			status,
 			...apiCode ? { apiCode } : {}
 		},
-		exitCode: 1,
-		nextSteps: ["prisma project show"]
+		nextActions: [userChoice$4(apiHint ?? repoConnectionFixForStatus(status)), runCommand$4(unauthorized ? "prisma auth login" : "prisma project show")]
 	});
 }
 function repoConnectionFixForStatus(status) {
+	if (status === 401 || status === 403) return "Sign in again with prisma auth login, then rerun the command.";
 	if (status === 404) return "Install the GitHub App for this workspace, then rerun prisma git connect.";
 	if (status === 409) return "This project or repository is already linked. Disconnect the old link first, then try again.";
 	if (status === 422) return "Make sure the GitHub App installation has access to this repository.";
-	return "Re-run with --trace for the underlying API response details.";
+	return "Re-run with --log-level verbose for the underlying API response details.";
 }
 //#endregion
 //#region src/lib/project/setup.ts
@@ -4126,7 +4054,7 @@ function resolveProjectForSetup(projectRef, projects, workspace) {
 	if (match !== void 0) return match;
 	throw projectNotFoundError$1(projectRef, workspace);
 }
-function projectDirectoryBindingErrorToCliError(error) {
+function projectDirectoryBindingErrorToStructured(error) {
 	return matchError(error, {
 		LocalResolutionPinSerializationError: (error) => {
 			throw error;
@@ -4154,16 +4082,18 @@ function projectDirectoryBindingErrorToCliError(error) {
 	});
 }
 function localStateWriteFailedError(error, options) {
-	return new CliError({
-		code: "LOCAL_STATE_WRITE_FAILED",
-		domain: "project",
-		summary: "Could not save local Project binding",
+	return new CliStructuredError("PROJECT.LOCAL_STATE_WRITE_FAILED", "Could not save local Project binding", {
 		why: options.why,
-		fix: "Check that this directory is writable and that .prisma/local.json and .gitignore are not blocked by directories or permissions, then retry.",
-		debug: formatDebugDetails(error.cause),
 		meta: options.meta,
-		exitCode: 1,
-		nextSteps: ["prisma project link <id-or-name>"]
+		cause: error.cause,
+		nextActions: [{
+			kind: "user-choice",
+			label: "Check that this directory is writable and that .prisma/local.json and .gitignore are not blocked by directories or permissions, then retry."
+		}, {
+			kind: "run-command",
+			label: "prisma project link <id-or-name>",
+			command: "prisma project link <id-or-name>"
+		}]
 	});
 }
 function toProjectSummary(project) {
@@ -4175,29 +4105,35 @@ function toProjectSummary(project) {
 	};
 }
 function projectSetupNameRequiredError(command) {
-	return usageError("Project create requires a name", "The project name must be a non-empty value.", "Pass a Project name explicitly.", [`prisma ${command} my-app`], "project");
+	const example = `prisma ${command} my-app`;
+	return new CliStructuredError("PROJECT.USAGE_ERROR", "Project create requires a name", {
+		why: "The project name must be a non-empty value.",
+		nextActions: [{
+			kind: "user-choice",
+			label: "Pass a Project name explicitly."
+		}, {
+			kind: "run-command",
+			label: example,
+			command: example
+		}]
+	});
 }
 function projectCreateFailedError(error, projectName, workspace, options) {
 	const status = extractHttpStatus(error);
-	if (status === 401 || status === 403) return new CliError({
-		code: "PROJECT_CREATE_FAILED",
-		domain: "project",
-		summary: `Could not create Project "${projectName}"`,
-		why: `The platform rejected the Project create in workspace "${workspace.name}" (HTTP ${status}).`,
-		fix: options.permissionFix,
-		debug: formatDebugDetails(error),
-		exitCode: 1,
-		nextSteps: options.nextSteps
-	});
-	return new CliError({
-		code: "PROJECT_CREATE_FAILED",
-		domain: "project",
-		summary: `Could not create Project "${projectName}"`,
-		why: error instanceof Error ? error.message : String(error),
-		fix: options.fallbackFix,
-		debug: formatDebugDetails(error),
-		exitCode: 1,
-		nextSteps: options.nextSteps
+	const permissionRejection = status === 401 || status === 403;
+	const message = error instanceof Error ? error.message : String(error);
+	const nextActions = [{
+		kind: "user-choice",
+		label: permissionRejection ? options.permissionFix : options.fallbackFix
+	}, ...options.nextSteps.map((step) => ({
+		kind: "run-command",
+		label: step,
+		command: step
+	}))];
+	return new CliStructuredError("PROJECT.CREATE_FAILED", `Could not create Project "${projectName}"`, {
+		why: permissionRejection ? `The platform rejected the Project create in workspace "${workspace.name}" (HTTP ${status}).` : message,
+		cause: error,
+		nextActions
 	});
 }
 const HTTP_STATUS_IN_MESSAGE = /\(HTTP (\d{3})\)/;
@@ -4212,10 +4148,6 @@ function extractHttpStatus(error) {
 	}
 	return null;
 }
-function formatDebugDetails(error) {
-	if (error instanceof Error) return error.stack ?? error.message;
-	return typeof error === "string" ? error : null;
-}
 //#endregion
 //#region src/commands/project/context.ts
 /**
@@ -4265,7 +4197,7 @@ async function resolvePinnedProject(ctx, workspace, explicitProject, commandName
 		listProjects: () => listWorkspaceProjects$1(ctx),
 		commandName
 	});
-	if (target.isErr()) throw projectResolutionErrorToCliError(target.error);
+	if (target.isErr()) throw projectResolutionErrorToStructured(target.error);
 	return target.value;
 }
 /** Writes `.prisma/local.json` for this directory and keeps it out of
@@ -4275,9 +4207,9 @@ async function bindDirectoryToProject(ctx, workspace, project, action) {
 		workspaceId: workspace.id,
 		projectId: project.id
 	}, ctx.signal);
-	if (written.isErr()) throw projectDirectoryBindingErrorToCliError(written.error);
+	if (written.isErr()) throw projectDirectoryBindingErrorToStructured(written.error);
 	const ignored = await ensureLocalResolutionPinGitignore(ctx.cwd, ctx.signal);
-	if (ignored.isErr()) throw projectDirectoryBindingErrorToCliError(ignored.error);
+	if (ignored.isErr()) throw projectDirectoryBindingErrorToStructured(ignored.error);
 	return {
 		workspace,
 		project,
@@ -4313,129 +4245,6 @@ async function resolveActiveWorkspace(ctx) {
 	};
 }
 //#endregion
-//#region src/commands/project/errors.ts
-const PROJECT_CODE_MAP = {
-	USAGE_ERROR: "PROJECT.USAGE_ERROR",
-	PROJECT_NOT_FOUND: "PROJECT.NOT_FOUND",
-	PROJECT_AMBIGUOUS: "PROJECT.AMBIGUOUS",
-	PROJECT_SETUP_REQUIRED: "PROJECT.SETUP_REQUIRED",
-	LOCAL_STATE_STALE: "PROJECT.LOCAL_STATE_STALE",
-	LOCAL_PROJECT_WORKSPACE_MISMATCH: "PROJECT.LOCAL_WORKSPACE_MISMATCH",
-	LOCAL_STATE_WRITE_FAILED: "PROJECT.LOCAL_STATE_WRITE_FAILED",
-	PROJECT_CREATE_FAILED: "PROJECT.CREATE_FAILED",
-	PROJECT_RENAME_FAILED: "PROJECT.RENAME_FAILED",
-	PROJECT_DELETE_BLOCKED: "PROJECT.DELETE_BLOCKED",
-	PROJECT_TRANSFER_REJECTED: "PROJECT.TRANSFER_REJECTED",
-	TRANSFER_RECIPIENT_REQUIRED: "PROJECT.TRANSFER_RECIPIENT_REQUIRED",
-	TRANSFER_RECIPIENT_UNAVAILABLE: "PROJECT.TRANSFER_RECIPIENT_UNAVAILABLE",
-	CONFIRMATION_REQUIRED: "PROJECT.CONFIRMATION_REQUIRED",
-	PROJECT_LINK_TARGET_REQUIRED: "PROJECT.LINK_TARGET_REQUIRED",
-	ENV_VARIABLE_ALREADY_EXISTS: "PROJECT.ENV_VARIABLE_ALREADY_EXISTS",
-	ENV_VARIABLE_NOT_FOUND: "PROJECT.ENV_VARIABLE_NOT_FOUND",
-	ENV_BRANCH_NOT_FOUND: "PROJECT.ENV_BRANCH_NOT_FOUND",
-	ENV_BRANCH_SCOPE_IS_PRODUCTION: "PROJECT.ENV_BRANCH_SCOPE_IS_PRODUCTION",
-	ENV_BRANCH_CREATE_REQUIRES_DEFAULT_BRANCH: "PROJECT.ENV_BRANCH_CREATE_REQUIRES_DEFAULT_BRANCH",
-	ENV_FILE_APPLY_FAILED: "PROJECT.ENV_FILE_APPLY_FAILED",
-	ENV_API_ERROR: "PROJECT.ENV_API_ERROR",
-	PROJECT_API_ERROR: "PROJECT.API_ERROR"
-};
-const PACKAGE_RUNNER_PREFIX = /^\S+(?: -y)? @prisma\/cli@\S+ /;
-const COMMENT_PREFIX$1 = /^#\s*/;
-/** Ported command strings already name this binary; what still needs
-*  porting is the package-runner spelling the legacy formatter emitted
-*  (`npx -y @prisma/cli@next auth login`), which becomes a plain
-*  invocation. Anything else is passed through untouched. */
-function portCommandString(command) {
-	if (command.startsWith(`prisma `)) return command;
-	return command.replace(PACKAGE_RUNNER_PREFIX, `${CLI_NAME} `);
-}
-const STALE_INTERACTIVE_SIGN_IN$4 = /, or rerun the command in a TTY to sign in interactively\./g;
-const TRACE_FLAG$4 = /--trace/g;
-/** `--trace` is gone in this CLI; the log level replaces it. Interactive
-*  sign-in is gone too (R-S2b-2), so the legacy offer to rerun in a TTY
-*  describes something this CLI cannot do; `auth login` is the whole remedy. */
-function portFixText$4(fix) {
-	return fix.replace(TRACE_FLAG$4, "--log-level verbose").replace(STALE_INTERACTIVE_SIGN_IN$4, ".");
-}
-/** A `#`-comment line in the legacy nextSteps is not an action: it
-*  explains the command that follows it, so it becomes that action's
-*  `reason`. */
-function runCommandActions$1(nextSteps) {
-	const actions = [];
-	let reason;
-	for (const step of nextSteps) {
-		if (step.startsWith("#")) {
-			reason = step.replace(COMMENT_PREFIX$1, "");
-			continue;
-		}
-		const command = portCommandString(step);
-		actions.push({
-			kind: "run-command",
-			label: command,
-			command,
-			...reason === void 0 ? {} : { reason }
-		});
-		reason = void 0;
-	}
-	return actions;
-}
-function nextActionsFor$4(error) {
-	return [...error.fix ? [{
-		kind: "user-choice",
-		label: portFixText$4(error.fix)
-	}] : [], ...runCommandActions$1(error.nextSteps)];
-}
-function mapProjectOperationError(error) {
-	if (!(error instanceof CliError)) return null;
-	return new CliStructuredError(PROJECT_CODE_MAP[error.code] ?? `PROJECT.${error.code}`, error.summary, {
-		why: error.why ?? void 0,
-		meta: Object.keys(error.meta).length > 0 ? error.meta : void 0,
-		nextActions: nextActionsFor$4(error)
-	});
-}
-//#endregion
-//#region src/commands/branch/errors.ts
-const BRANCH_CODE_MAP = { BRANCH_API_ERROR: "BRANCH.API_ERROR" };
-/** The project-resolution codes `branch list` can raise; they keep the
-*  project group's dotted codes and copy. */
-const PROJECT_CODES$3 = new Set([
-	"PROJECT_NOT_FOUND",
-	"PROJECT_AMBIGUOUS",
-	"PROJECT_SETUP_REQUIRED",
-	"LOCAL_STATE_STALE",
-	"LOCAL_PROJECT_WORKSPACE_MISMATCH"
-]);
-const STALE_INTERACTIVE_SIGN_IN$3 = /, or rerun the command in a TTY to sign in interactively\./g;
-const TRACE_FLAG$3 = /--trace/g;
-/** `--trace` is gone in this CLI; the log level replaces it. Interactive
-*  sign-in is gone too (R-S2b-2), so the legacy offer to rerun in a TTY
-*  describes something this CLI cannot do; `auth login` is the whole remedy. */
-function portFixText$3(fix) {
-	return fix.replace(TRACE_FLAG$3, "--log-level verbose").replace(STALE_INTERACTIVE_SIGN_IN$3, ".");
-}
-function nextActionsFor$3(error) {
-	return [...error.fix ? [{
-		kind: "user-choice",
-		label: portFixText$3(error.fix)
-	}] : [], ...error.nextSteps.map((step) => {
-		const command = portCommandString(step);
-		return {
-			kind: "run-command",
-			label: command,
-			command
-		};
-	})];
-}
-function mapBranchOperationError(error) {
-	if (!(error instanceof CliError)) return null;
-	if (PROJECT_CODES$3.has(error.code)) return mapProjectOperationError(error);
-	return new CliStructuredError(BRANCH_CODE_MAP[error.code] ?? `BRANCH.${error.code}`, error.summary, {
-		why: error.why ?? void 0,
-		meta: Object.keys(error.meta).length > 0 ? error.meta : void 0,
-		nextActions: nextActionsFor$3(error)
-	});
-}
-//#endregion
 //#region src/commands/branch/list.ts
 /** The `branch list` command. */
 const TITLE$12 = "Listing branches for the resolved project.";
@@ -4489,20 +4298,14 @@ const branchListCommand = defineCommand({
 	}) } },
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const target = await resolvePinnedProject(ctx, await resolveActiveWorkspace(ctx), args.flags.project, "branch list");
-			const branches = await listBranches$1(ctx.api, target.project.id, ctx.signal);
-			const result = {
-				projectId: target.project.id,
-				projectName: target.project.name,
-				branches: sortBranches(branches.map(toBranchSummary))
-			};
-			return ok(ctx.present({ data: result }, listPresentations$8(result)));
-		} catch (error) {
-			const mapped = mapBranchOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const target = await resolvePinnedProject(ctx, await resolveActiveWorkspace(ctx), args.flags.project, "branch list");
+		const branches = await listBranches$1(ctx.api, target.project.id, ctx.signal);
+		const result = {
+			projectId: target.project.id,
+			projectName: target.project.name,
+			branches: sortBranches(branches.map(toBranchSummary))
+		};
+		return ok(ctx.present({ data: result }, listPresentations$8(result)));
 	}
 });
 //#endregion
@@ -4583,15 +4386,7 @@ function createManagementBucketProvider(client) {
 			const accessKeyId = raw.accessKeyId;
 			const endpoint = raw.endpoint;
 			const bucketName = raw.bucketName;
-			if (!secretAccessKey || !accessKeyId || !endpoint || !bucketName) throw new CliError({
-				code: "BUCKET_KEY_SECRET_MISSING",
-				domain: "bucket",
-				summary: "Created bucket key did not return credentials",
-				why: "Bucket key credentials are one-time-view secrets, but the Management API did not include them in this create response.",
-				fix: "Create another bucket key and store the returned credentials immediately.",
-				exitCode: 1,
-				nextSteps: [`prisma bucket key create ${options.bucketId}`]
-			});
+			if (!secretAccessKey || !accessKeyId || !endpoint || !bucketName) throw bucketKeySecretMissingError(options.bucketId);
 			return {
 				key: normalizeKey(raw),
 				secretAccessKey,
@@ -4630,21 +4425,66 @@ function normalizeKey(raw) {
 		createdAt: raw.createdAt
 	};
 }
+const VERBOSE_LOG_FIX$1 = "Re-run with --log-level verbose for the underlying API response details.";
+function userChoice$3(label) {
+	return {
+		kind: "user-choice",
+		label
+	};
+}
+function runCommand$3(command) {
+	return {
+		kind: "run-command",
+		label: command,
+		command
+	};
+}
+function bucketKeySecretMissingError(bucketId) {
+	return new CliStructuredError("BUCKET.KEY_SECRET_MISSING", "Created bucket key did not return credentials", {
+		why: "Bucket key credentials are one-time-view secrets, but the Management API did not include them in this create response.",
+		nextActions: [userChoice$3("Create another bucket key and store the returned credentials immediately."), runCommand$3(`${CLI_NAME} bucket key create ${bucketId}`)]
+	});
+}
+/** A 401 or 403 is the API refusing the caller, not a bucket problem. */
+function isRejectedCaller$1(status) {
+	return status === 401 || status === 403;
+}
+function apiErrorWhy$1(status, message) {
+	if (!isRejectedCaller$1(status)) return message ?? `The Management API returned status ${status || "unknown"}.`;
+	const rejection = `The Management API rejected the request as ${status === 401 ? "unauthorized" : "forbidden"}.`;
+	return message ? `${rejection} ${message}` : rejection;
+}
+function apiErrorMeta$1(status, apiCode) {
+	if (!status && apiCode === void 0) return;
+	return {
+		...status ? { status } : {},
+		...apiCode === void 0 ? {} : { apiCode }
+	};
+}
+function apiErrorActions$1(status, hint) {
+	if (!isRejectedCaller$1(status)) return [userChoice$3(hint ?? VERBOSE_LOG_FIX$1)];
+	return [userChoice$3(hint ?? `Sign in again with prisma auth login, then retry the command.`), runCommand$3(`${CLI_NAME} auth login`)];
+}
+/**
+* Every bucket Management API failure lands on the one registered code.
+* The response's own error code is data, not an identity: it travels in
+* `meta.apiCode` beside `meta.status` so a consumer can still branch on
+* it without the CLI minting a code it never registered.
+*/
 function bucketApiError(summary, response, error) {
 	const status = response?.status ?? 0;
-	return new CliError({
-		code: error?.error?.code ?? "BUCKET_API_ERROR",
-		domain: "bucket",
-		summary,
-		why: error?.error?.message ?? `The Management API returned status ${status || "unknown"}.`,
-		fix: error?.error?.hint ?? "Re-run with --trace for the underlying API response details.",
-		exitCode: 1,
-		nextSteps: []
+	const meta = apiErrorMeta$1(status, error?.error?.code);
+	return new CliStructuredError("BUCKET.API_ERROR", summary, {
+		why: apiErrorWhy$1(status, error?.error?.message),
+		...meta === void 0 ? {} : { meta },
+		nextActions: apiErrorActions$1(status, error?.error?.hint)
 	});
 }
 //#endregion
 //#region src/commands/bucket/context.ts
 /** Workspace, project and provider for the `bucket *` commands. */
+/** Where a caller who is missing a bucket id finds one. */
+const LIST_BUCKETS_COMMAND = `${CLI_NAME} bucket list`;
 const projectFlag$3 = flag.string({
 	brief: "Project id or name",
 	placeholder: "id-or-name"
@@ -4675,52 +4515,6 @@ function resolveBucketProviderOnly(ctx) {
 	return createManagementBucketProvider(ctx.api);
 }
 //#endregion
-//#region src/commands/bucket/errors.ts
-const BUCKET_CODE_MAP = {
-	USAGE_ERROR: "BUCKET.USAGE_ERROR",
-	BUCKET_KEY_SECRET_MISSING: "BUCKET.KEY_SECRET_MISSING",
-	BUCKET_API_ERROR: "BUCKET.API_ERROR"
-};
-/** The project-resolution codes `bucket list` and `bucket create` can
-*  raise; they keep the project group's dotted codes and copy. */
-const PROJECT_CODES$2 = new Set([
-	"PROJECT_NOT_FOUND",
-	"PROJECT_AMBIGUOUS",
-	"PROJECT_SETUP_REQUIRED",
-	"LOCAL_STATE_STALE",
-	"LOCAL_PROJECT_WORKSPACE_MISMATCH"
-]);
-const STALE_INTERACTIVE_SIGN_IN$2 = /, or rerun the command in a TTY to sign in interactively\./g;
-const TRACE_FLAG$2 = /--trace/g;
-/** `--trace` is gone in this CLI; the log level replaces it. Interactive
-*  sign-in is gone too (R-S2b-2), so the legacy offer to rerun in a TTY
-*  describes something this CLI cannot do; `auth login` is the whole remedy. */
-function portFixText$2(fix) {
-	return fix.replace(TRACE_FLAG$2, "--log-level verbose").replace(STALE_INTERACTIVE_SIGN_IN$2, ".");
-}
-function nextActionsFor$2(error) {
-	return [...error.fix ? [{
-		kind: "user-choice",
-		label: portFixText$2(error.fix)
-	}] : [], ...error.nextSteps.map((step) => {
-		const command = portCommandString(step);
-		return {
-			kind: "run-command",
-			label: command,
-			command
-		};
-	})];
-}
-function mapBucketOperationError(error) {
-	if (!(error instanceof CliError)) return null;
-	if (PROJECT_CODES$2.has(error.code)) return mapProjectOperationError(error);
-	return new CliStructuredError(BUCKET_CODE_MAP[error.code] ?? `BUCKET.${error.code}`, error.summary, {
-		why: error.why ?? void 0,
-		meta: Object.keys(error.meta).length > 0 ? error.meta : void 0,
-		nextActions: nextActionsFor$2(error)
-	});
-}
-//#endregion
 //#region src/commands/bucket/presentation.ts
 /** Legacy `formatBucketTarget`. */
 function bucketTargetLabel(projectName, branchId) {
@@ -4777,34 +4571,28 @@ const bucketCreateCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const { provider, projectId, projectName } = await resolveBucketContext(ctx, args.flags, "bucket create");
-			const bucket = await provider.createBucket({
-				projectId,
-				name: args.flags.name?.trim() || void 0,
-				branchGitName: args.flags.branch,
-				signal: ctx.signal
-			});
-			const result = {
-				projectId,
-				projectName,
-				bucket
-			};
-			return ok(ctx.present({ data: result }, {
-				human: () => [{
-					kind: "summary",
-					status: "ok",
-					text: `Created bucket "${bucket.name}" in ${bucketTargetLabel(projectName, bucket.branchId)}.`
-				}],
-				stdout: () => [],
-				json: () => result,
-				next: () => []
-			}));
-		} catch (error) {
-			const mapped = mapBucketOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const { provider, projectId, projectName } = await resolveBucketContext(ctx, args.flags, "bucket create");
+		const bucket = await provider.createBucket({
+			projectId,
+			name: args.flags.name?.trim() || void 0,
+			branchGitName: args.flags.branch,
+			signal: ctx.signal
+		});
+		const result = {
+			projectId,
+			projectName,
+			bucket
+		};
+		return ok(ctx.present({ data: result }, {
+			human: () => [{
+				kind: "summary",
+				status: "ok",
+				text: `Created bucket "${bucket.name}" in ${bucketTargetLabel(projectName, bucket.branchId)}.`
+			}],
+			stdout: () => [],
+			json: () => result,
+			next: () => []
+		}));
 	}
 });
 //#endregion
@@ -4844,18 +4632,22 @@ const bucketDeleteCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const bucketId = args.positionals.bucketId.trim();
-			if (!bucketId) throw usageError("Bucket id required", "Bucket deletion needs a bucket id.", "Pass the bucket id to delete.", [`${CLI_NAME} bucket list`], "bucket");
-			await ctx.prompt.consent(CONSENT_QUESTION$6, { token: bucketId });
-			await resolveBucketProviderOnly(ctx).deleteBucket(bucketId, { signal: ctx.signal });
-			const result = { bucket: { id: bucketId } };
-			return ok(ctx.present({ data: result }, deletePresentations$5(result)));
-		} catch (error) {
-			const mapped = mapBucketOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const bucketId = args.positionals.bucketId.trim();
+		if (!bucketId) throw new CliStructuredError("BUCKET.USAGE_ERROR", "Bucket id required", {
+			why: "Bucket deletion needs a bucket id.",
+			nextActions: [{
+				kind: "user-choice",
+				label: "Pass the bucket id to delete."
+			}, {
+				kind: "run-command",
+				label: LIST_BUCKETS_COMMAND,
+				command: LIST_BUCKETS_COMMAND
+			}]
+		});
+		await ctx.prompt.consent(CONSENT_QUESTION$6, { token: bucketId });
+		await resolveBucketProviderOnly(ctx).deleteBucket(bucketId, { signal: ctx.signal });
+		const result = { bucket: { id: bucketId } };
+		return ok(ctx.present({ data: result }, deletePresentations$5(result)));
 	}
 });
 //#endregion
@@ -4936,24 +4728,28 @@ const bucketKeyCreateCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const bucketId = args.positionals.bucketId.trim();
-			if (!bucketId) throw usageError("Bucket id required", "Bucket key creation needs a bucket id.", "Pass the bucket id.", ["prisma bucket list"], "bucket");
-			const result = {
+		const bucketId = args.positionals.bucketId.trim();
+		if (!bucketId) throw new CliStructuredError("BUCKET.USAGE_ERROR", "Bucket id required", {
+			why: "Bucket key creation needs a bucket id.",
+			nextActions: [{
+				kind: "user-choice",
+				label: "Pass the bucket id."
+			}, {
+				kind: "run-command",
+				label: LIST_BUCKETS_COMMAND,
+				command: LIST_BUCKETS_COMMAND
+			}]
+		});
+		const result = {
+			bucketId,
+			...await resolveBucketProviderOnly(ctx).createKey({
 				bucketId,
-				...await resolveBucketProviderOnly(ctx).createKey({
-					bucketId,
-					name: args.flags.name?.trim() || void 0,
-					role: resolveKeyRole(args.flags.role),
-					signal: ctx.signal
-				})
-			};
-			return ok(ctx.present({ data: result }, createPresentations$1(result)));
-		} catch (error) {
-			const mapped = mapBucketOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+				name: args.flags.name?.trim() || void 0,
+				role: resolveKeyRole(args.flags.role),
+				signal: ctx.signal
+			})
+		};
+		return ok(ctx.present({ data: result }, createPresentations$1(result)));
 	}
 });
 //#endregion
@@ -4998,18 +4794,25 @@ const bucketKeyDeleteCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const bucketId = args.positionals.bucketId.trim();
-			const keyId = args.positionals.keyId.trim();
-			if (!bucketId || !keyId) throw usageError("Bucket id and key id required", "Bucket key deletion needs both a bucket id and a key id.", "Pass the bucket id and key id.", ["prisma bucket key list <bucketId>"], "bucket");
-			await resolveBucketProviderOnly(ctx).deleteKey(bucketId, keyId, { signal: ctx.signal });
-			const result = { key: { id: keyId } };
-			return ok(ctx.present({ data: result }, deletePresentations$4(result)));
-		} catch (error) {
-			const mapped = mapBucketOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
+		const bucketId = args.positionals.bucketId.trim();
+		const keyId = args.positionals.keyId.trim();
+		if (!bucketId || !keyId) {
+			const listKeysCommand = `${CLI_NAME} bucket key list <bucketId>`;
+			throw new CliStructuredError("BUCKET.USAGE_ERROR", "Bucket id and key id required", {
+				why: "Bucket key deletion needs both a bucket id and a key id.",
+				nextActions: [{
+					kind: "user-choice",
+					label: "Pass the bucket id and key id."
+				}, {
+					kind: "run-command",
+					label: listKeysCommand,
+					command: listKeysCommand
+				}]
+			});
 		}
+		await resolveBucketProviderOnly(ctx).deleteKey(bucketId, keyId, { signal: ctx.signal });
+		const result = { key: { id: keyId } };
+		return ok(ctx.present({ data: result }, deletePresentations$4(result)));
 	}
 });
 //#endregion
@@ -5108,19 +4911,23 @@ const bucketKeyListCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const bucketId = args.positionals.bucketId.trim();
-			if (!bucketId) throw usageError("Bucket id required", "Bucket key listing needs a bucket id.", "Pass the bucket id.", ["prisma bucket list"], "bucket");
-			const result = {
-				bucketId,
-				keys: await resolveBucketProviderOnly(ctx).listKeys(bucketId, { signal: ctx.signal })
-			};
-			return ok(ctx.present({ data: result }, listPresentations$7(result)));
-		} catch (error) {
-			const mapped = mapBucketOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const bucketId = args.positionals.bucketId.trim();
+		if (!bucketId) throw new CliStructuredError("BUCKET.USAGE_ERROR", "Bucket id required", {
+			why: "Bucket key listing needs a bucket id.",
+			nextActions: [{
+				kind: "user-choice",
+				label: "Pass the bucket id."
+			}, {
+				kind: "run-command",
+				label: LIST_BUCKETS_COMMAND,
+				command: LIST_BUCKETS_COMMAND
+			}]
+		});
+		const result = {
+			bucketId,
+			keys: await resolveBucketProviderOnly(ctx).listKeys(bucketId, { signal: ctx.signal })
+		};
+		return ok(ctx.present({ data: result }, listPresentations$7(result)));
 	}
 });
 //#endregion
@@ -5183,25 +4990,19 @@ const bucketListCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const { provider, projectId, projectName } = await resolveBucketContext(ctx, args.flags, "bucket list");
-			const buckets = await provider.listBuckets({
-				projectId,
-				branchName: args.flags.branch,
-				signal: ctx.signal
-			});
-			const result = {
-				projectId,
-				projectName,
-				branchName: args.flags.branch ?? null,
-				buckets
-			};
-			return ok(ctx.present({ data: result }, listPresentations$6(result)));
-		} catch (error) {
-			const mapped = mapBucketOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const { provider, projectId, projectName } = await resolveBucketContext(ctx, args.flags, "bucket list");
+		const buckets = await provider.listBuckets({
+			projectId,
+			branchName: args.flags.branch,
+			signal: ctx.signal
+		});
+		const result = {
+			projectId,
+			projectName,
+			branchName: args.flags.branch ?? null,
+			buckets
+		};
+		return ok(ctx.present({ data: result }, listPresentations$6(result)));
 	}
 });
 //#endregion
@@ -5495,84 +5296,13 @@ async function resolveGitContext(ctx, explicitProject, commandName) {
 }
 //#endregion
 //#region src/commands/git/errors.ts
-const GIT_CODE_MAP = {
-	USAGE_ERROR: "GIT.USAGE_ERROR",
-	REPO_PROVIDER_UNSUPPORTED: "GIT.REPO_PROVIDER_UNSUPPORTED",
-	REPO_ALREADY_CONNECTED: "GIT.REPO_ALREADY_CONNECTED",
-	REPO_INSTALLATION_REQUIRED: "GIT.REPO_INSTALLATION_REQUIRED",
-	REPO_NOT_ACCESSIBLE: "GIT.REPO_NOT_ACCESSIBLE",
-	REPO_NOT_CONNECTED: "GIT.REPO_NOT_CONNECTED",
-	REPO_CONNECTION_FAILED: "GIT.REPO_CONNECTION_FAILED"
-};
-/** The project-resolution codes the git commands can raise; they keep
-*  the project group's dotted codes and copy. */
-const PROJECT_CODES$1 = new Set([
-	"PROJECT_NOT_FOUND",
-	"PROJECT_AMBIGUOUS",
-	"PROJECT_SETUP_REQUIRED",
-	"LOCAL_STATE_STALE",
-	"LOCAL_PROJECT_WORKSPACE_MISMATCH"
-]);
-const STALE_INTERACTIVE_SIGN_IN$1 = /, or rerun the command in a TTY to sign in interactively\./g;
-const TRACE_FLAG$1 = /--trace/g;
-/** `--trace` is gone in this CLI; the log level replaces it. Interactive
-*  sign-in is gone too (R-S2b-2), so the legacy offer to rerun in a TTY
-*  describes something this CLI cannot do; `auth login` is the whole remedy. */
-function portFixText$1(fix) {
-	return fix.replace(TRACE_FLAG$1, "--log-level verbose").replace(STALE_INTERACTIVE_SIGN_IN$1, ".");
-}
-/** The install-required and not-accessible errors put the raw install
-*  URL in their nextSteps beside real commands. A URL is not a command,
-*  so it becomes an `open-url` action. */
-function nextStepAction(step) {
-	if (step.startsWith("https://") || step.startsWith("http://")) return {
-		kind: "open-url",
-		label: step,
-		url: step
-	};
-	const command = portCommandString(step);
-	return {
-		kind: "run-command",
-		label: command,
-		command
-	};
-}
-function nextActionsFor$1(error) {
-	return [...error.fix ? [{
-		kind: "user-choice",
-		label: portFixText$1(error.fix)
-	}] : [], ...error.nextSteps.map(nextStepAction)];
-}
-/** The legacy errors branch their fix text on whether a browser was
-*  opened. The engine's browser wait always shows the URL, so the
-*  opened branch is the one that describes what this CLI does. */
-const BROWSER_OPENED = true;
 /**
-* The install wait's two terminal outcomes. The legacy constructors own
-* every copy string; the design drops `opened` from the meta they build
-* (`browserWait` does not report it and the URL is always shown), so
-* the structured error is assembled from their fields with the meta
-* d3 §3.8 pins.
+* The install wait's two terminal outcomes: the workspace has an
+* inspectable installation that simply does not expose the repository,
+* or it has none at all.
 */
 function installWaitFailedError(repository, installUrl, inspectableInstallationCount) {
-	const legacy = inspectableInstallationCount > 0 ? repoNotAccessibleError(repository, installUrl, BROWSER_OPENED) : repoInstallationRequiredError(repository, installUrl, BROWSER_OPENED);
-	return new CliStructuredError(GIT_CODE_MAP[legacy.code], legacy.summary, {
-		why: legacy.why ?? void 0,
-		meta: {
-			repository: repository.fullName,
-			installUrl
-		},
-		nextActions: nextActionsFor$1(legacy)
-	});
-}
-function mapGitOperationError(error) {
-	if (!(error instanceof CliError)) return null;
-	if (PROJECT_CODES$1.has(error.code)) return mapProjectOperationError(error);
-	return new CliStructuredError(GIT_CODE_MAP[error.code] ?? `GIT.${error.code}`, error.summary, {
-		why: error.why ?? void 0,
-		meta: Object.keys(error.meta).length > 0 ? error.meta : void 0,
-		nextActions: nextActionsFor$1(error)
-	});
+	return inspectableInstallationCount > 0 ? repoNotAccessibleError(repository, installUrl) : repoInstallationRequiredError(repository, installUrl);
 }
 //#endregion
 //#region src/commands/git/connect.ts
@@ -5671,43 +5401,50 @@ const gitConnectCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const { api, target } = await resolveGitContext(ctx, args.flags.project, "git connect");
-			const remoteUrl = args.positionals.gitUrl ?? await readGitOriginRemote(ctx.cwd, ctx.signal);
-			if (!remoteUrl) throw usageError("Repository connection requires a GitHub repository URL", "No git-url was provided and the local repo does not have an origin remote.", `Pass a GitHub repository URL, or add a GitHub origin remote and rerun ${CLI_NAME} git connect.`, [`${CLI_NAME} git connect git@github.com:prisma/prisma-cli.git`], "project");
-			const repository = parseGitHubRepositoryUrl(remoteUrl);
-			if (!repository) throw unsupportedRepositoryProviderError();
-			const existing = await readFirstSourceRepository(api, target.project.id, ctx.signal);
-			if (existing) {
-				const existingConnection = toRepositoryConnection(existing);
-				if (!repositoryFullNamesMatch(existingConnection.repository.fullName, repository.fullName)) throw repoAlreadyConnectedError(existingConnection.repository.fullName);
-				const idempotent = {
-					...target,
-					repositoryConnection: existingConnection
-				};
-				return ok(ctx.present({ data: idempotent }, connectPresentations(idempotent)));
-			}
-			const installed = await resolveInstalledRepository(ctx, api, target.workspace.id, repository);
-			const { data, error, response } = await api.POST("/v1/source-repositories", {
-				body: {
-					projectId: target.project.id,
-					provider: "github",
-					providerRepositoryId: installed.repository.id,
-					installationId: installed.installation.id
-				},
-				signal: ctx.signal
+		const { api, target } = await resolveGitContext(ctx, args.flags.project, "git connect");
+		const remoteUrl = args.positionals.gitUrl ?? await readGitOriginRemote(ctx.cwd, ctx.signal);
+		if (!remoteUrl) {
+			const example = `${CLI_NAME} git connect git@github.com:prisma/prisma-cli.git`;
+			throw new CliStructuredError("GIT.USAGE_ERROR", "Repository connection requires a GitHub repository URL", {
+				why: "No git-url was provided and the local repo does not have an origin remote.",
+				nextActions: [{
+					kind: "user-choice",
+					label: `Pass a GitHub repository URL, or add a GitHub origin remote and rerun ${CLI_NAME} git connect.`
+				}, {
+					kind: "run-command",
+					label: example,
+					command: example
+				}]
 			});
-			if (error || !data) throw repoConnectionApiError("Failed to connect GitHub repository", response, error);
-			const result = {
+		}
+		const repository = parseGitHubRepositoryUrl(remoteUrl);
+		if (!repository) throw unsupportedRepositoryProviderError();
+		const existing = await readFirstSourceRepository(api, target.project.id, ctx.signal);
+		if (existing) {
+			const existingConnection = toRepositoryConnection(existing);
+			if (!repositoryFullNamesMatch(existingConnection.repository.fullName, repository.fullName)) throw repoAlreadyConnectedError(existingConnection.repository.fullName);
+			const idempotent = {
 				...target,
-				repositoryConnection: toRepositoryConnection(data.data)
+				repositoryConnection: existingConnection
 			};
-			return ok(ctx.present({ data: result }, connectPresentations(result)));
-		} catch (error) {
-			const mapped = mapGitOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
+			return ok(ctx.present({ data: idempotent }, connectPresentations(idempotent)));
 		}
+		const installed = await resolveInstalledRepository(ctx, api, target.workspace.id, repository);
+		const { data, error, response } = await api.POST("/v1/source-repositories", {
+			body: {
+				projectId: target.project.id,
+				provider: "github",
+				providerRepositoryId: installed.repository.id,
+				installationId: installed.installation.id
+			},
+			signal: ctx.signal
+		});
+		if (error || !data) throw repoConnectionApiError("Failed to connect GitHub repository", response, error);
+		const result = {
+			...target,
+			repositoryConnection: toRepositoryConnection(data.data)
+		};
+		return ok(ctx.present({ data: result }, connectPresentations(result)));
 	}
 });
 //#endregion
@@ -5756,25 +5493,19 @@ const gitDisconnectCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const { api, target } = await resolveGitContext(ctx, args.flags.project, "git disconnect");
-			const existing = await readFirstSourceRepository(api, target.project.id, ctx.signal);
-			if (!existing) throw repoNotConnectedError();
-			const { error, response } = await api.DELETE("/v1/source-repositories/{id}", {
-				params: { path: { id: existing.id } },
-				signal: ctx.signal
-			});
-			if (error) throw repoConnectionApiError("Failed to disconnect GitHub repository", response, error);
-			const result = {
-				...target,
-				repositoryConnection: toRepositoryConnection(existing)
-			};
-			return ok(ctx.present({ data: result }, disconnectPresentations(result)));
-		} catch (error) {
-			const mapped = mapGitOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const { api, target } = await resolveGitContext(ctx, args.flags.project, "git disconnect");
+		const existing = await readFirstSourceRepository(api, target.project.id, ctx.signal);
+		if (!existing) throw repoNotConnectedError();
+		const { error, response } = await api.DELETE("/v1/source-repositories/{id}", {
+			params: { path: { id: existing.id } },
+			signal: ctx.signal
+		});
+		if (error) throw repoConnectionApiError("Failed to disconnect GitHub repository", response, error);
+		const result = {
+			...target,
+			repositoryConnection: toRepositoryConnection(existing)
+		};
+		return ok(ctx.present({ data: result }, disconnectPresentations(result)));
 	}
 });
 //#endregion
@@ -6581,41 +6312,51 @@ const initCommand = defineCommand({
 //#region src/controllers/database.ts
 const USAGE_DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 const USAGE_DATETIME_PATTERN = /^\d{4}-\d{2}-\d{2}T/;
-function parseUsageDate(value, flagName, dayBoundary, formatCommand) {
+const LIST_DATABASES_COMMAND = `${CLI_NAME} postgres list`;
+/** The corrected `postgres usage` form both period errors point at. */
+const USAGE_PERIOD_EXAMPLE_COMMAND = `${CLI_NAME} postgres usage <database> --from 2026-06-01 --to 2026-06-30`;
+function userChoice$2(label) {
+	return {
+		kind: "user-choice",
+		label
+	};
+}
+function runCommand$2(command) {
+	return {
+		kind: "run-command",
+		label: command,
+		command
+	};
+}
+function parseUsageDate(value, flagName, dayBoundary) {
 	if (value === void 0) return;
 	const trimmed = value.trim();
 	if (USAGE_DATE_ONLY_PATTERN.test(trimmed) && isValidCalendarDate(trimmed)) return dayBoundary === "start" ? `${trimmed}T00:00:00.000Z` : `${trimmed}T23:59:59.999Z`;
 	if (USAGE_DATETIME_PATTERN.test(trimmed) && !Number.isNaN(Date.parse(trimmed)) && isValidCalendarDate(trimmed.slice(0, 10))) return trimmed;
-	throw usageError("Invalid usage period", `${flagName} must be an ISO date such as 2026-06-01 or an ISO datetime such as 2026-06-01T12:00:00Z.`, `Pass an ISO date or datetime to ${flagName}.`, [formatCommand([
-		"database",
-		"usage",
-		"<database>",
-		"--from",
-		"2026-06-01",
-		"--to",
-		"2026-06-30"
-	])], "database");
+	throw new CliStructuredError("POSTGRES.USAGE_ERROR", "Invalid usage period", {
+		why: `${flagName} must be an ISO date such as 2026-06-01 or an ISO datetime such as 2026-06-01T12:00:00Z.`,
+		nextActions: [userChoice$2(`Pass an ISO date or datetime to ${flagName}.`), runCommand$2(USAGE_PERIOD_EXAMPLE_COMMAND)]
+	});
 }
 function isValidCalendarDate(datePart) {
 	const timestamp = Date.parse(`${datePart}T00:00:00.000Z`);
 	return !Number.isNaN(timestamp) && new Date(timestamp).toISOString().startsWith(datePart);
 }
-function parseBackupLimit(value, formatCommand) {
+function parseBackupLimit(value) {
 	if (value === void 0) return;
 	const limit = Number(value.trim());
-	if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw usageError("Invalid backup limit", "--limit must be an integer between 1 and 100.", "Pass a --limit between 1 and 100.", [formatCommand([
-		"database",
-		"backup",
-		"list",
-		"<database>",
-		"--limit",
-		"50"
-	])], "database");
+	if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new CliStructuredError("POSTGRES.USAGE_ERROR", "Invalid backup limit", {
+		why: "--limit must be an integer between 1 and 100.",
+		nextActions: [userChoice$2("Pass a --limit between 1 and 100."), runCommand$2(`${CLI_NAME} postgres backup list <database> --limit 50`)]
+	});
 	return limit;
 }
 async function resolveDatabase(provider, target, databaseRef, branchName, signal) {
 	const ref = databaseRef.trim();
-	if (!ref) throw usageError("Database id or name required", "This command needs a database id or name.", "Pass a database id or name.", ["prisma database list"], "database");
+	if (!ref) throw new CliStructuredError("POSTGRES.USAGE_ERROR", "Database id or name required", {
+		why: "This command needs a database id or name.",
+		nextActions: [userChoice$2("Pass a database id or name."), runCommand$2(LIST_DATABASES_COMMAND)]
+	});
 	const databases = await provider.listDatabases({
 		projectId: target.project.id,
 		branchName,
@@ -6634,14 +6375,9 @@ async function resolveDatabase(provider, target, databaseRef, branchName, signal
 	return ensureProjectId(shown, target.project.id);
 }
 function databaseRemovedDuringResolutionError(database, projectName) {
-	return new CliError({
-		code: "DATABASE_NOT_FOUND",
-		domain: "database",
-		summary: "Database not found",
+	return new CliStructuredError("POSTGRES.NOT_FOUND", "Database not found", {
 		why: `"${database.name}" (${database.id}) was listed for project "${projectName}", but reading it returned 404. It was most likely removed while this command was running.`,
-		fix: "Re-run the command, or list the project's databases to see what is there now.",
-		exitCode: 1,
-		nextSteps: ["prisma database list"]
+		nextActions: [userChoice$2("Re-run the command, or list the project's databases to see what is there now."), runCommand$2(LIST_DATABASES_COMMAND)]
 	});
 }
 function ensureProjectId(database, projectId) {
@@ -6662,30 +6398,20 @@ function defaultConnectionName() {
 	return `cli-${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:.TZ]/g, "").slice(0, 17)}-${randomBytes(2).toString("hex")}`;
 }
 function databaseNotFoundError(databaseRef, projectName, branchName) {
-	return new CliError({
-		code: "DATABASE_NOT_FOUND",
-		domain: "database",
-		summary: "Database not found",
+	return new CliStructuredError("POSTGRES.NOT_FOUND", "Database not found", {
 		why: `No database matched "${databaseRef}"${projectName ? ` in project "${projectName}"${branchName ? ` on branch "${branchName}"` : ""}` : ""}.`,
-		fix: "Pass a database id or name from prisma database list.",
-		exitCode: 1,
-		nextSteps: ["prisma database list"]
+		nextActions: [userChoice$2(`Pass a database id or name from ${LIST_DATABASES_COMMAND}.`), runCommand$2(LIST_DATABASES_COMMAND)]
 	});
 }
 function databaseAmbiguousError(databaseRef, matches, branchName) {
-	return new CliError({
-		code: "DATABASE_AMBIGUOUS",
-		domain: "database",
-		summary: "Database resolution is ambiguous",
+	return new CliStructuredError("POSTGRES.AMBIGUOUS", "Database resolution is ambiguous", {
 		why: branchName ? `Multiple databases matched "${databaseRef}" on branch "${branchName}".` : `Multiple databases matched "${databaseRef}".`,
-		fix: "Pass the database id, or pass --branch <git-name> to narrow the match.",
-		exitCode: 1,
-		nextSteps: ["prisma database list"],
 		meta: { matches: matches.map((database) => ({
 			id: database.id,
 			name: database.name,
 			branchName: database.branchName
-		})) }
+		})) },
+		nextActions: [userChoice$2("Pass the database id, or pass --branch <git-name> to narrow the match."), runCommand$2(LIST_DATABASES_COMMAND)]
 	});
 }
 //#endregion
@@ -6752,8 +6478,21 @@ function serializeDatabaseBackupList(result) {
 //#endregion
 //#region src/lib/database/provider.ts
 const SUBSCRIPTION_LOOKUP_TIMEOUT_MS = 3e3;
+const VERBOSE_LOG_FIX = "Re-run with --log-level verbose for the underlying API response details.";
+function userChoice$1(label) {
+	return {
+		kind: "user-choice",
+		label
+	};
+}
+function runCommand$1(command) {
+	return {
+		kind: "run-command",
+		label: command,
+		command
+	};
+}
 function createManagementDatabaseProvider(client, options) {
-	const formatCommand = options?.formatCommand ?? ((args) => formatPrismaCliCommand(args));
 	const toDatabaseApiError = (summary, response, error, signal) => databaseApiError({
 		client,
 		workspaceId: options?.workspaceId,
@@ -6873,8 +6612,8 @@ function createManagementDatabaseProvider(client, options) {
 				} },
 				signal: options.signal
 			});
-			if (result.response?.status === 409 && !isPlanLimitApiError(result.error)) throw restoreConflictError(options.targetDatabaseId, result.error, formatCommand);
-			if (result.response?.status === 404 && !isPlanLimitApiError(result.error)) throw restoreBackupNotFoundError(options, result.error, formatCommand);
+			if (result.response?.status === 409 && !isPlanLimitApiError(result.error)) throw restoreConflictError(options.targetDatabaseId, result.error);
+			if (result.response?.status === 404 && !isPlanLimitApiError(result.error)) throw restoreBackupNotFoundError(options, result.error);
 			if (result.error || !result.data) throw await toDatabaseApiError("Failed to restore database", result.response, result.error, options.signal);
 			return normalizeDatabase(result.data.data, options.projectId);
 		},
@@ -6911,14 +6650,9 @@ function normalizeConnection(connection, fallbackDatabaseId) {
 }
 function normalizeCreatedDatabase(database, fallbackProjectId) {
 	const rawConnection = database.connections?.[0];
-	if (!rawConnection) throw new CliError({
-		code: "DATABASE_CONNECTION_MISSING",
-		domain: "database",
-		summary: "Created database did not return a connection string",
+	if (!rawConnection) throw new CliStructuredError("POSTGRES.CONNECTION_MISSING", "Created database did not return a connection string", {
 		why: "The Management API created the database but did not include the one-time connection payload.",
-		fix: "Create a connection explicitly with prisma database connection create <database>.",
-		exitCode: 1,
-		nextSteps: [`prisma database connection create ${database.id}`]
+		nextActions: [userChoice$1(`Create a connection explicitly with ${CLI_NAME} postgres connection create <database>.`), runCommand$1(`${CLI_NAME} postgres connection create ${database.id}`)]
 	});
 	return {
 		database: normalizeDatabase(database, fallbackProjectId),
@@ -6927,14 +6661,9 @@ function normalizeCreatedDatabase(database, fallbackProjectId) {
 }
 function normalizeCreatedConnection(connection, fallbackDatabaseId) {
 	const connectionString = extractConnectionString(connection);
-	if (!connectionString) throw new CliError({
-		code: "DATABASE_CONNECTION_STRING_MISSING",
-		domain: "database",
-		summary: "Created connection did not return a connection string",
+	if (!connectionString) throw new CliStructuredError("POSTGRES.CONNECTION_STRING_MISSING", "Created connection did not return a connection string", {
 		why: "Database connection strings are one-time-view secrets, but the Management API did not include one in this create response.",
-		fix: "Create another database connection and store the returned URL immediately.",
-		exitCode: 1,
-		nextSteps: [`prisma database connection create ${fallbackDatabaseId}`]
+		nextActions: [userChoice$1("Create another database connection and store the returned URL immediately."), runCommand$1(`${CLI_NAME} postgres connection create ${fallbackDatabaseId}`)]
 	});
 	return {
 		connection: normalizeConnection(connection, fallbackDatabaseId),
@@ -6948,14 +6677,9 @@ function normalizeRegion(database) {
 function requireDatabaseProjectId(database, fallbackProjectId) {
 	const projectId = database.projectId ?? fallbackProjectId;
 	if (projectId) return projectId;
-	throw new CliError({
-		code: "DATABASE_API_ERROR",
-		domain: "database",
-		summary: "Database response did not include a project id",
+	throw new CliStructuredError("POSTGRES.API_ERROR", "Database response did not include a project id", {
 		why: "The Management API returned database metadata without project context.",
-		fix: "Re-run with --trace for the underlying API response details.",
-		exitCode: 1,
-		nextSteps: []
+		nextActions: [userChoice$1(VERBOSE_LOG_FIX)]
 	});
 }
 function extractConnectionString(connection) {
@@ -7000,14 +6724,9 @@ function normalizeBackupList(body) {
 }
 function normalizeRotatedConnection(connection) {
 	const connectionString = extractConnectionString(connection);
-	if (!connectionString) throw new CliError({
-		code: "DATABASE_CONNECTION_STRING_MISSING",
-		domain: "database",
-		summary: "Rotated connection did not return a connection string",
+	if (!connectionString) throw new CliStructuredError("POSTGRES.CONNECTION_STRING_MISSING", "Rotated connection did not return a connection string", {
 		why: "Rotated connection strings are one-time-view secrets, but the Management API did not include one in this rotate response.",
-		fix: "Re-run the rotation, or create a replacement connection and store the returned URL immediately.",
-		exitCode: 1,
-		nextSteps: []
+		nextActions: [userChoice$1("Re-run the rotation, or create a replacement connection and store the returned URL immediately.")]
 	});
 	const database = connection.database?.id && connection.database?.name ? {
 		id: connection.database.id,
@@ -7020,74 +6739,68 @@ function normalizeRotatedConnection(connection) {
 	};
 }
 function backupsUnsupportedError(databaseId, error) {
-	return new CliError({
-		code: "DATABASE_BACKUPS_UNSUPPORTED",
-		domain: "database",
-		summary: "Backups are not available for this database",
+	return new CliStructuredError("POSTGRES.BACKUPS_UNSUPPORTED", "Backups are not available for this database", {
 		why: error?.error?.message ?? `The platform does not manage backups for database "${databaseId}", for example because it is a remote/BYO database.`,
-		fix: "Use your own backup tooling for externally managed databases.",
-		exitCode: 1,
-		nextSteps: []
+		nextActions: [userChoice$1("Use your own backup tooling for externally managed databases.")]
 	});
 }
-function restoreBackupNotFoundError(options, error, formatCommand) {
-	const listCommand = formatCommand([
-		"database",
-		"backup",
-		"list",
-		options.sourceDatabaseId
-	]);
-	return new CliError({
-		code: "DATABASE_BACKUP_NOT_FOUND",
-		domain: "database",
-		summary: "Database backup not found",
+function restoreBackupNotFoundError(options, error) {
+	const listCommand = `${CLI_NAME} postgres backup list ${options.sourceDatabaseId}`;
+	return new CliStructuredError("POSTGRES.BACKUP_NOT_FOUND", "Database backup not found", {
 		why: error?.error?.message ?? `No backup matched "${options.backupId}" for database "${options.sourceDatabaseId}".`,
-		fix: `Pass a backup id from ${listCommand}.`,
-		exitCode: 1,
-		nextSteps: [listCommand]
+		nextActions: [userChoice$1(`Pass a backup id from ${listCommand}.`), runCommand$1(listCommand)]
 	});
 }
-function restoreConflictError(targetDatabaseId, error, formatCommand) {
-	return new CliError({
-		code: "DATABASE_RESTORE_CONFLICT",
-		domain: "database",
-		summary: "Database cannot be restored right now",
+function restoreConflictError(targetDatabaseId, error) {
+	return new CliStructuredError("POSTGRES.RESTORE_CONFLICT", "Database cannot be restored right now", {
 		why: error?.error?.message ?? `Database "${targetDatabaseId}" is provisioning or already recovering.`,
-		fix: "Wait for the database to become ready, then retry the restore.",
-		exitCode: 1,
-		nextSteps: [formatCommand([
-			"database",
-			"show",
-			targetDatabaseId
-		])]
+		nextActions: [userChoice$1("Wait for the database to become ready, then retry the restore."), runCommand$1(`${CLI_NAME} postgres show ${targetDatabaseId}`)]
 	});
 }
+/** A 401 or 403 is the API refusing the caller, not a database problem. */
+function isRejectedCaller(status) {
+	return status === 401 || status === 403;
+}
+function apiErrorWhy(status, message) {
+	if (!isRejectedCaller(status)) return message ?? `The Management API returned status ${status || "unknown"}.`;
+	const rejection = `The Management API rejected the request as ${status === 401 ? "unauthorized" : "forbidden"}.`;
+	return message ? `${rejection} ${message}` : rejection;
+}
+function apiErrorMeta(status, apiCode) {
+	if (!status && apiCode === void 0) return;
+	return {
+		...status ? { status } : {},
+		...apiCode === void 0 ? {} : { apiCode }
+	};
+}
+function apiErrorActions(status, hint) {
+	if (!isRejectedCaller(status)) return [userChoice$1(hint ?? VERBOSE_LOG_FIX)];
+	return [userChoice$1(hint ?? `Sign in again with prisma auth login, then retry the command.`), runCommand$1(`${CLI_NAME} auth login`)];
+}
+/**
+* Every database Management API failure that is not a plan limit lands
+* on the one registered code. The response's own error code is data, not
+* an identity: it travels in `meta.apiCode` beside `meta.status` so a
+* consumer can still branch on it without the CLI minting a code it
+* never registered.
+*/
 async function databaseApiError(options) {
 	if (isPlanLimitApiError(options.error)) return planLimitReachedError(options);
 	const status = options.response?.status ?? 0;
-	return new CliError({
-		code: options.error?.error?.code ?? "DATABASE_API_ERROR",
-		domain: "database",
-		summary: options.summary,
-		why: options.error?.error?.message ?? `The Management API returned status ${status || "unknown"}.`,
-		fix: options.error?.error?.hint ?? "Re-run with --trace for the underlying API response details.",
-		exitCode: 1,
-		nextSteps: []
+	const meta = apiErrorMeta(status, options.error?.error?.code);
+	return new CliStructuredError("POSTGRES.API_ERROR", options.summary, {
+		why: apiErrorWhy(status, options.error?.error?.message),
+		...meta === void 0 ? {} : { meta },
+		nextActions: apiErrorActions(status, options.error?.error?.hint)
 	});
 }
 async function planLimitReachedError(options) {
 	const subscription = options.workspaceId ? await readWorkspaceSubscription(options.client, options.workspaceId, options.signal) : null;
-	const workspaceLine = options.workspaceId ? `Workspace: ${options.workspaceId}` : "Workspace: unavailable";
 	const planName = subscription?.planName || null;
 	const usageBlocked = subscription?.usageBlocked ?? null;
 	const upgradeUrl = subscription?.upgradeUrl || null;
-	const recoveryLines = [...planName ? [`Current plan: ${planName}`] : [], upgradeUrl ? `Upgrade: ${upgradeUrl}` : "Upgrade: Open Prisma Console and upgrade the affected workspace plan."];
-	return new CliError({
-		code: "PLAN_LIMIT_REACHED",
-		domain: "database",
-		summary: "Workspace plan limit reached",
+	return new CliStructuredError("POSTGRES.PLAN_LIMIT_REACHED", "Workspace plan limit reached", {
 		why: "Database operations are blocked because this workspace has used the operations included in its plan. This is a workspace plan limit, not a Prisma outage.",
-		fix: upgradeUrl ? `Upgrade the workspace plan at ${upgradeUrl}.` : "Open Prisma Console and upgrade the affected workspace plan.",
 		meta: {
 			workspaceId: options.workspaceId ?? null,
 			blockedFeature: null,
@@ -7095,16 +6808,11 @@ async function planLimitReachedError(options) {
 			usageBlocked,
 			upgradeUrl
 		},
-		exitCode: 1,
-		nextSteps: [],
-		humanLines: [
-			"Workspace plan limit reached [PLAN_LIMIT_REACHED]",
-			"",
-			"Database operations are blocked because this workspace has used the operations included in its plan. This is a workspace plan limit, not a Prisma outage.",
-			"",
-			workspaceLine,
-			...recoveryLines
-		]
+		nextActions: [{
+			kind: "user-choice",
+			label: "Upgrade the workspace plan",
+			reason: upgradeUrl ? `Upgrade at ${upgradeUrl}${planName ? ` (current plan: ${planName})` : ""}.` : "Open Prisma Console and upgrade the affected workspace plan."
+		}]
 	});
 }
 function isPlanLimitApiError(error) {
@@ -7145,10 +6853,6 @@ const databasePositional = positional.string({
 	brief: "Database id or name",
 	placeholder: "database"
 });
-/** The legacy helpers build their nextSteps through a command
-*  formatter. This CLI phrases every command string as `${CLI_NAME} …`; the
-*  error mapper rewrites the `database` group name to `postgres`. */
-const legacyCommandFormatter = (args) => [CLI_NAME, ...args].join(" ");
 async function resolvePostgresContext(ctx, flags, commandName) {
 	const workspace = await resolveActiveWorkspace(ctx);
 	const target = await resolvePinnedProject(ctx, workspace, flags.project, commandName);
@@ -7167,99 +6871,6 @@ async function resolvePostgresProviderOnly(ctx) {
 	return createManagementDatabaseProvider(ctx.api, { ...workspaceId === void 0 ? {} : { workspaceId } });
 }
 //#endregion
-//#region src/commands/postgres/errors.ts
-const POSTGRES_CODE_MAP = {
-	USAGE_ERROR: "POSTGRES.USAGE_ERROR",
-	DATABASE_NOT_FOUND: "POSTGRES.NOT_FOUND",
-	DATABASE_AMBIGUOUS: "POSTGRES.AMBIGUOUS",
-	DATABASE_CONNECTION_MISSING: "POSTGRES.CONNECTION_MISSING",
-	DATABASE_CONNECTION_STRING_MISSING: "POSTGRES.CONNECTION_STRING_MISSING",
-	DATABASE_BACKUPS_UNSUPPORTED: "POSTGRES.BACKUPS_UNSUPPORTED",
-	DATABASE_RESTORE_CONFLICT: "POSTGRES.RESTORE_CONFLICT",
-	DATABASE_BACKUP_NOT_FOUND: "POSTGRES.BACKUP_NOT_FOUND",
-	DATABASE_API_ERROR: "POSTGRES.API_ERROR"
-};
-/** The project-resolution codes this group can raise; they keep the
-*  project group's dotted codes and copy. */
-const PROJECT_CODES = new Set([
-	"PROJECT_NOT_FOUND",
-	"PROJECT_AMBIGUOUS",
-	"PROJECT_SETUP_REQUIRED",
-	"LOCAL_STATE_STALE",
-	"LOCAL_PROJECT_WORKSPACE_MISMATCH"
-]);
-const PACKAGE_RUNNER = /[\w./@-]+(?: [\w.-]+)? @prisma\/cli@\S+ /g;
-const COMMENT_PREFIX = /^#\s*/;
-const LEGACY_GROUP = new RegExp(`${CLI_NAME} database `, "g");
-/** §0 rename: wherever a legacy command reference appears — a
-*  nextSteps string or prose inside `fix` — the package-runner prefix
-*  becomes `${CLI_NAME}` and the `database` group becomes `postgres`.
-*  The resource noun "database" in prose is left alone. */
-function portCommandReferences(text) {
-	return text.replace(PACKAGE_RUNNER, `${CLI_NAME} `).replace(LEGACY_GROUP, `${CLI_NAME} postgres `);
-}
-function portPostgresCommand(command) {
-	const named = portCommandReferences(command);
-	return named.startsWith(`prisma `) ? named : `${CLI_NAME} ${named}`;
-}
-const STALE_INTERACTIVE_SIGN_IN = /, or rerun the command in a TTY to sign in interactively\./g;
-const TRACE_FLAG = /--trace/g;
-/** `--trace` is gone in this CLI; the log level replaces it. Interactive
-*  sign-in is gone too (R-S2b-2), so the legacy offer to rerun in a TTY
-*  describes something this CLI cannot do; `auth login` is the whole remedy. */
-function portFixText(fix) {
-	return portCommandReferences(fix).replace(TRACE_FLAG, "--log-level verbose").replace(STALE_INTERACTIVE_SIGN_IN, ".");
-}
-function runCommandActions(nextSteps) {
-	const actions = [];
-	let reason;
-	for (const step of nextSteps) {
-		if (step.startsWith("#")) {
-			reason = step.replace(COMMENT_PREFIX, "");
-			continue;
-		}
-		const command = portPostgresCommand(step);
-		actions.push({
-			kind: "run-command",
-			label: command,
-			command,
-			...reason === void 0 ? {} : { reason }
-		});
-		reason = void 0;
-	}
-	return actions;
-}
-/** PR #127's plan-limit error: the legacy full-page `humanLines`
-*  rendering does not port, so the recovery guidance becomes the one
-*  nextAction beside the verbatim why and meta. */
-function planLimitError(error) {
-	const upgradeUrl = error.meta.upgradeUrl;
-	const planName = error.meta.planName;
-	const reason = typeof upgradeUrl === "string" && upgradeUrl ? `Upgrade at ${upgradeUrl}${typeof planName === "string" && planName ? ` (current plan: ${planName})` : ""}.` : "Open Prisma Console and upgrade the affected workspace plan.";
-	return new CliStructuredError("POSTGRES.PLAN_LIMIT_REACHED", error.summary, {
-		why: error.why ?? void 0,
-		meta: error.meta,
-		nextActions: [{
-			kind: "user-choice",
-			label: "Upgrade the workspace plan",
-			reason
-		}]
-	});
-}
-function mapPostgresOperationError(error) {
-	if (!(error instanceof CliError)) return null;
-	if (error.code === "PLAN_LIMIT_REACHED") return planLimitError(error);
-	if (PROJECT_CODES.has(error.code)) return mapProjectOperationError(error);
-	return new CliStructuredError(POSTGRES_CODE_MAP[error.code] ?? `POSTGRES.${error.code}`, error.summary, {
-		why: error.why ?? void 0,
-		meta: Object.keys(error.meta).length > 0 ? error.meta : void 0,
-		nextActions: [...error.fix ? [{
-			kind: "user-choice",
-			label: portFixText(error.fix)
-		}] : [], ...runCommandActions(error.nextSteps)]
-	});
-}
-//#endregion
 //#region src/commands/postgres/presentation.ts
 /** Legacy `formatDatabaseTarget`. */
 function postgresTargetLabel(projectName, branchName) {
@@ -7418,28 +7029,22 @@ const postgresBackupListCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const limit = parseBackupLimit(args.flags.limit, legacyCommandFormatter);
-			const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres backup list");
-			const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
-			const backups = await provider.listBackups(database.id, {
-				limit,
-				signal: ctx.signal
-			});
-			const result = {
-				projectId,
-				projectName,
-				database,
-				backups: backups.backups,
-				retentionDays: backups.retentionDays,
-				hasMore: backups.hasMore
-			};
-			return ok(ctx.present({ data: result }, backupListPresentations(result)));
-		} catch (error) {
-			const mapped = mapPostgresOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const limit = parseBackupLimit(args.flags.limit);
+		const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres backup list");
+		const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
+		const backups = await provider.listBackups(database.id, {
+			limit,
+			signal: ctx.signal
+		});
+		const result = {
+			projectId,
+			projectName,
+			database,
+			backups: backups.backups,
+			retentionDays: backups.retentionDays,
+			hasMore: backups.hasMore
+		};
+		return ok(ctx.present({ data: result }, backupListPresentations(result)));
 	}
 });
 //#endregion
@@ -7519,44 +7124,41 @@ const postgresBackupRestoreCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const backupId = args.flags.backup?.trim();
-			if (!backupId) throw usageError("Backup id required", "Database restore needs the backup to restore from.", `Pass --backup <backup-id> from ${legacyCommandFormatter([
-				"postgres",
-				"backup",
-				"list",
-				"<database>"
-			])}.`, [legacyCommandFormatter([
-				"postgres",
-				"backup",
-				"list",
-				"<database>"
-			])], "database");
-			const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres backup restore");
-			const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
-			const sourceDatabase = args.flags.sourceDatabase ? await resolveDatabase(provider, target, args.flags.sourceDatabase, args.flags.branch, ctx.signal) : database;
-			await ctx.prompt.consent(CONSENT_QUESTION$5, { token: database.id });
-			const result = {
-				projectId,
-				projectName,
-				database: await provider.restoreDatabase({
-					targetDatabaseId: database.id,
-					sourceDatabaseId: sourceDatabase.id,
-					backupId,
-					projectId,
-					signal: ctx.signal
-				}),
-				source: {
-					databaseId: sourceDatabase.id,
-					backupId
-				}
-			};
-			return ok(ctx.present({ data: result }, restorePresentations(result, sourceDatabase.id === database.id ? null : sourceDatabase.id, database.id)));
-		} catch (error) {
-			const mapped = mapPostgresOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
+		const backupId = args.flags.backup?.trim();
+		if (!backupId) {
+			const listCommand = `${CLI_NAME} postgres backup list <database>`;
+			throw new CliStructuredError("POSTGRES.USAGE_ERROR", "Backup id required", {
+				why: "Database restore needs the backup to restore from.",
+				nextActions: [{
+					kind: "user-choice",
+					label: `Pass --backup <backup-id> from ${listCommand}.`
+				}, {
+					kind: "run-command",
+					label: listCommand,
+					command: listCommand
+				}]
+			});
 		}
+		const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres backup restore");
+		const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
+		const sourceDatabase = args.flags.sourceDatabase ? await resolveDatabase(provider, target, args.flags.sourceDatabase, args.flags.branch, ctx.signal) : database;
+		await ctx.prompt.consent(CONSENT_QUESTION$5, { token: database.id });
+		const result = {
+			projectId,
+			projectName,
+			database: await provider.restoreDatabase({
+				targetDatabaseId: database.id,
+				sourceDatabaseId: sourceDatabase.id,
+				backupId,
+				projectId,
+				signal: ctx.signal
+			}),
+			source: {
+				databaseId: sourceDatabase.id,
+				backupId
+			}
+		};
+		return ok(ctx.present({ data: result }, restorePresentations(result, sourceDatabase.id === database.id ? null : sourceDatabase.id, database.id)));
 	}
 });
 //#endregion
@@ -7580,32 +7182,26 @@ const postgresConnectionCreateCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres connection create");
-			const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
-			const created = await provider.createConnection({
-				databaseId: database.id,
-				name: args.flags.name?.trim() || defaultConnectionName(),
-				signal: ctx.signal
-			});
-			const result = {
-				projectId,
-				projectName,
-				database,
-				connection: created.connection,
-				connectionString: created.connectionString
-			};
-			return ok(ctx.present({ data: result }, {
-				human: () => secretBlocks(`Added a connection to "${database.name}" in ${postgresTargetLabel(projectName, database.branchName)}.`, result.connectionString),
-				stdout: () => [result.connectionString],
-				json: () => result,
-				next: () => []
-			}));
-		} catch (error) {
-			const mapped = mapPostgresOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres connection create");
+		const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
+		const created = await provider.createConnection({
+			databaseId: database.id,
+			name: args.flags.name?.trim() || defaultConnectionName(),
+			signal: ctx.signal
+		});
+		const result = {
+			projectId,
+			projectName,
+			database,
+			connection: created.connection,
+			connectionString: created.connectionString
+		};
+		return ok(ctx.present({ data: result }, {
+			human: () => secretBlocks(`Added a connection to "${database.name}" in ${postgresTargetLabel(projectName, database.branchName)}.`, result.connectionString),
+			stdout: () => [result.connectionString],
+			json: () => result,
+			next: () => []
+		}));
 	}
 });
 //#endregion
@@ -7623,40 +7219,47 @@ const postgresConnectionDeleteCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const connectionId = args.positionals.connection.trim();
-			if (!connectionId) throw usageError("Connection id required", "Database connection deletion needs a connection id.", "Pass the connection id to delete.", [`${CLI_NAME} postgres connection delete <connection-id> --confirm <connection-id>`], "database");
-			await ctx.prompt.consent(CONSENT_QUESTION$4, { token: connectionId });
-			await (await resolvePostgresProviderOnly(ctx)).removeConnection(connectionId, { signal: ctx.signal });
-			const result = { connection: { id: connectionId } };
-			return ok(ctx.present({ data: result }, {
-				human: () => [
-					{
-						kind: "summary",
-						status: "ok",
-						text: "Deleting database connection."
-					},
-					{
-						kind: "fields",
-						rows: [{
-							label: "connection",
-							value: connectionId
-						}]
-					},
-					{
-						kind: "list",
-						items: ["The connection metadata was deleted. Existing one-time secrets were not shown."]
-					}
-				],
-				stdout: () => [],
-				json: () => ({ connection: result.connection }),
-				next: () => []
-			}));
-		} catch (error) {
-			const mapped = mapPostgresOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
+		const connectionId = args.positionals.connection.trim();
+		if (!connectionId) {
+			const example = `${CLI_NAME} postgres connection delete <connection-id> --confirm <connection-id>`;
+			throw new CliStructuredError("POSTGRES.USAGE_ERROR", "Connection id required", {
+				why: "Database connection deletion needs a connection id.",
+				nextActions: [{
+					kind: "user-choice",
+					label: "Pass the connection id to delete."
+				}, {
+					kind: "run-command",
+					label: example,
+					command: example
+				}]
+			});
 		}
+		await ctx.prompt.consent(CONSENT_QUESTION$4, { token: connectionId });
+		await (await resolvePostgresProviderOnly(ctx)).removeConnection(connectionId, { signal: ctx.signal });
+		const result = { connection: { id: connectionId } };
+		return ok(ctx.present({ data: result }, {
+			human: () => [
+				{
+					kind: "summary",
+					status: "ok",
+					text: "Deleting database connection."
+				},
+				{
+					kind: "fields",
+					rows: [{
+						label: "connection",
+						value: connectionId
+					}]
+				},
+				{
+					kind: "list",
+					items: ["The connection metadata was deleted. Existing one-time secrets were not shown."]
+				}
+			],
+			stdout: () => [],
+			json: () => ({ connection: result.connection }),
+			next: () => []
+		}));
 	}
 });
 //#endregion
@@ -7728,21 +7331,15 @@ const postgresConnectionListCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres connection list");
-			const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
-			const result = {
-				projectId,
-				projectName,
-				database,
-				connections: await provider.listConnections(database.id, { signal: ctx.signal })
-			};
-			return ok(ctx.present({ data: result }, listPresentations$4(result)));
-		} catch (error) {
-			const mapped = mapPostgresOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres connection list");
+		const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
+		const result = {
+			projectId,
+			projectName,
+			database,
+			connections: await provider.listConnections(database.id, { signal: ctx.signal })
+		};
+		return ok(ctx.present({ data: result }, listPresentations$4(result)));
 	}
 });
 //#endregion
@@ -7760,35 +7357,35 @@ const postgresConnectionRotateCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const connectionId = args.positionals.connection.trim();
-			if (!connectionId) throw usageError("Connection id required", "Database connection rotation needs a connection id.", "Pass the connection id to rotate.", [legacyCommandFormatter([
-				"database",
-				"connection",
-				"rotate",
-				"<connection-id>",
-				"--confirm",
-				"<connection-id>"
-			])], "database");
-			await ctx.prompt.consent(CONSENT_QUESTION$3, { token: connectionId });
-			const rotated = await (await resolvePostgresProviderOnly(ctx)).rotateConnection(connectionId, { signal: ctx.signal });
-			const result = {
-				connection: rotated.connection,
-				database: rotated.database,
-				connectionString: rotated.connectionString
-			};
-			const subject = result.database ? `"${result.database.name}"` : `connection ${result.connection.id}`;
-			return ok(ctx.present({ data: result }, {
-				human: () => secretBlocks(`Rotated credentials for ${subject}. The previous credentials no longer work.`, result.connectionString),
-				stdout: () => [result.connectionString],
-				json: () => result,
-				next: () => []
-			}));
-		} catch (error) {
-			const mapped = mapPostgresOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
+		const connectionId = args.positionals.connection.trim();
+		if (!connectionId) {
+			const example = `${CLI_NAME} postgres connection rotate <connection-id> --confirm <connection-id>`;
+			throw new CliStructuredError("POSTGRES.USAGE_ERROR", "Connection id required", {
+				why: "Database connection rotation needs a connection id.",
+				nextActions: [{
+					kind: "user-choice",
+					label: "Pass the connection id to rotate."
+				}, {
+					kind: "run-command",
+					label: example,
+					command: example
+				}]
+			});
 		}
+		await ctx.prompt.consent(CONSENT_QUESTION$3, { token: connectionId });
+		const rotated = await (await resolvePostgresProviderOnly(ctx)).rotateConnection(connectionId, { signal: ctx.signal });
+		const result = {
+			connection: rotated.connection,
+			database: rotated.database,
+			connectionString: rotated.connectionString
+		};
+		const subject = result.database ? `"${result.database.name}"` : `connection ${result.connection.id}`;
+		return ok(ctx.present({ data: result }, {
+			human: () => secretBlocks(`Rotated credentials for ${subject}. The previous credentials no longer work.`, result.connectionString),
+			stdout: () => [result.connectionString],
+			json: () => result,
+			next: () => []
+		}));
 	}
 });
 //#endregion
@@ -7815,35 +7412,42 @@ const postgresCreateCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const name = args.positionals.name.trim();
-			if (!name) throw usageError("Database name required", "Database create needs a non-empty name.", "Pass a database name.", [`${CLI_NAME} postgres create <name>`], "database");
-			const { provider, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres create");
-			const created = await provider.createDatabase({
-				projectId,
-				name,
-				branchName: args.flags.branch,
-				region: args.flags.region,
-				signal: ctx.signal
+		const name = args.positionals.name.trim();
+		if (!name) {
+			const example = `${CLI_NAME} postgres create <name>`;
+			throw new CliStructuredError("POSTGRES.USAGE_ERROR", "Database name required", {
+				why: "Database create needs a non-empty name.",
+				nextActions: [{
+					kind: "user-choice",
+					label: "Pass a database name."
+				}, {
+					kind: "run-command",
+					label: example,
+					command: example
+				}]
 			});
-			const result = {
-				projectId,
-				projectName,
-				database: ensureProjectId(created.database, projectId),
-				connection: created.connection,
-				connectionString: created.connectionString
-			};
-			return ok(ctx.present({ data: result }, {
-				human: () => secretBlocks(`Created database "${result.database.name}" in ${postgresTargetLabel(projectName, result.database.branchName)}.`, result.connectionString),
-				stdout: () => [result.connectionString],
-				json: () => result,
-				next: () => []
-			}));
-		} catch (error) {
-			const mapped = mapPostgresOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
 		}
+		const { provider, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres create");
+		const created = await provider.createDatabase({
+			projectId,
+			name,
+			branchName: args.flags.branch,
+			region: args.flags.region,
+			signal: ctx.signal
+		});
+		const result = {
+			projectId,
+			projectName,
+			database: ensureProjectId(created.database, projectId),
+			connection: created.connection,
+			connectionString: created.connectionString
+		};
+		return ok(ctx.present({ data: result }, {
+			human: () => secretBlocks(`Created database "${result.database.name}" in ${postgresTargetLabel(projectName, result.database.branchName)}.`, result.connectionString),
+			stdout: () => [result.connectionString],
+			json: () => result,
+			next: () => []
+		}));
 	}
 });
 //#endregion
@@ -7899,22 +7503,16 @@ const postgresDeleteCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres delete");
-			const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
-			await ctx.prompt.consent(CONSENT_QUESTION$2, { token: database.id });
-			await provider.removeDatabase(database.id, { signal: ctx.signal });
-			const result = {
-				projectId,
-				projectName,
-				database
-			};
-			return ok(ctx.present({ data: result }, deletePresentations$3(result)));
-		} catch (error) {
-			const mapped = mapPostgresOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres delete");
+		const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
+		await ctx.prompt.consent(CONSENT_QUESTION$2, { token: database.id });
+		await provider.removeDatabase(database.id, { signal: ctx.signal });
+		const result = {
+			projectId,
+			projectName,
+			database
+		};
+		return ok(ctx.present({ data: result }, deletePresentations$3(result)));
 	}
 });
 //#endregion
@@ -7997,25 +7595,19 @@ const postgresListCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const { provider, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres list");
-			const databases = sortDatabases(await provider.listDatabases({
-				projectId,
-				branchName: args.flags.branch,
-				signal: ctx.signal
-			}));
-			const result = {
-				projectId,
-				projectName,
-				branchName: args.flags.branch ?? null,
-				databases
-			};
-			return ok(ctx.present({ data: result }, listPresentations$3(result)));
-		} catch (error) {
-			const mapped = mapPostgresOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const { provider, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres list");
+		const databases = sortDatabases(await provider.listDatabases({
+			projectId,
+			branchName: args.flags.branch,
+			signal: ctx.signal
+		}));
+		const result = {
+			projectId,
+			projectName,
+			branchName: args.flags.branch ?? null,
+			databases
+		};
+		return ok(ctx.present({ data: result }, listPresentations$3(result)));
 	}
 });
 //#endregion
@@ -8119,21 +7711,15 @@ const postgresShowCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres show");
-			const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
-			const result = {
-				projectId,
-				projectName,
-				database,
-				connections: await provider.listConnections(database.id, { signal: ctx.signal })
-			};
-			return ok(ctx.present({ data: result }, showPresentations$2(result)));
-		} catch (error) {
-			const mapped = mapPostgresOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres show");
+		const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
+		const result = {
+			projectId,
+			projectName,
+			database,
+			connections: await provider.listConnections(database.id, { signal: ctx.signal })
+		};
+		return ok(ctx.present({ data: result }, showPresentations$2(result)));
 	}
 });
 //#endregion
@@ -8251,39 +7837,35 @@ const postgresUsageCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const from = parseUsageDate(args.flags.from, "--from", "start", legacyCommandFormatter);
-			const to = parseUsageDate(args.flags.to, "--to", "end", legacyCommandFormatter);
-			if (from && to && Date.parse(from) > Date.parse(to)) throw usageError("Invalid usage period", "--from must not be later than --to.", "Pass a --from date that is on or before the --to date.", [legacyCommandFormatter([
-				"database",
-				"usage",
-				"<database>",
-				"--from",
-				"2026-06-01",
-				"--to",
-				"2026-06-30"
-			])], "database");
-			const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres usage");
-			const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
-			const usage = await provider.getUsage(database.id, {
-				from,
-				to,
-				signal: ctx.signal
-			});
-			const result = {
-				projectId,
-				projectName,
-				database,
-				period: usage.period,
-				metrics: usage.metrics,
-				generatedAt: usage.generatedAt
-			};
-			return ok(ctx.present({ data: result }, usagePresentations(result)));
-		} catch (error) {
-			const mapped = mapPostgresOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const from = parseUsageDate(args.flags.from, "--from", "start");
+		const to = parseUsageDate(args.flags.to, "--to", "end");
+		if (from && to && Date.parse(from) > Date.parse(to)) throw new CliStructuredError("POSTGRES.USAGE_ERROR", "Invalid usage period", {
+			why: "--from must not be later than --to.",
+			nextActions: [{
+				kind: "user-choice",
+				label: "Pass a --from date that is on or before the --to date."
+			}, {
+				kind: "run-command",
+				label: USAGE_PERIOD_EXAMPLE_COMMAND,
+				command: USAGE_PERIOD_EXAMPLE_COMMAND
+			}]
+		});
+		const { provider, target, projectId, projectName } = await resolvePostgresContext(ctx, args.flags, "postgres usage");
+		const database = await resolveDatabase(provider, target, args.positionals.database, args.flags.branch, ctx.signal);
+		const usage = await provider.getUsage(database.id, {
+			from,
+			to,
+			signal: ctx.signal
+		});
+		const result = {
+			projectId,
+			projectName,
+			database,
+			period: usage.period,
+			metrics: usage.metrics,
+			generatedAt: usage.generatedAt
+		};
+		return ok(ctx.present({ data: result }, usagePresentations(result)));
 	}
 });
 //#endregion
@@ -8933,17 +8515,6 @@ function localPinDiagnostics(warnings) {
 		nextActions: []
 	}));
 }
-/** The legacy NextAction shape minus its `journey` field, which the engine
-*  protocol does not carry. */
-function toNextActions(actions) {
-	return actions.map((action) => ({
-		kind: action.kind,
-		label: action.label,
-		...action.command ? { command: portCommandString(action.command) } : {},
-		...action.commands ? { commands: action.commands.map(portCommandString) } : {},
-		...action.reason ? { reason: action.reason } : {}
-	}));
-}
 function setupPresentations(result) {
 	return {
 		stdout: () => [],
@@ -8988,38 +8559,32 @@ const projectCreateCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const workspace = await resolveActiveWorkspace(ctx);
-			if (!isValidProjectSetupName(args.positionals.name)) throw projectSetupNameRequiredError("project create");
-			const name = args.positionals.name.trim();
-			const created = await createAppProvider(ctx.api).createProject({
-				name,
-				region: args.flags.region,
-				signal: ctx.signal
-			}).catch((error) => {
-				/** A cancelled run is cancelled, not a failed creation. The
-				*  provider flattens the underlying AbortError into a plain
-				*  Error, which the engine would settle as a bug, so hand it
-				*  back its own abort reason and let it settle the run as
-				*  cancelled. */
-				if (ctx.signal.aborted) throw ctx.signal.reason;
-				throw projectCreateFailedError(error, name, workspace, {
-					nextSteps: ["prisma project list", "prisma project link <id-or-name>"],
-					permissionFix: "Grant the token permission to create Projects in this workspace, or link an existing Project.",
-					fallbackFix: "Retry the command, or choose an existing Project with prisma project link <id-or-name>."
-				});
+		const workspace = await resolveActiveWorkspace(ctx);
+		if (!isValidProjectSetupName(args.positionals.name)) throw projectSetupNameRequiredError("project create");
+		const name = args.positionals.name.trim();
+		const created = await createAppProvider(ctx.api).createProject({
+			name,
+			region: args.flags.region,
+			signal: ctx.signal
+		}).catch((error) => {
+			/** A cancelled run is cancelled, not a failed creation. The
+			*  provider flattens the underlying AbortError into a plain
+			*  Error, which the engine would settle as a bug, so hand it
+			*  back its own abort reason and let it settle the run as
+			*  cancelled. */
+			if (ctx.signal.aborted) throw ctx.signal.reason;
+			throw projectCreateFailedError(error, name, workspace, {
+				nextSteps: ["prisma project list", "prisma project link <id-or-name>"],
+				permissionFix: "Grant the token permission to create Projects in this workspace, or link an existing Project.",
+				fallbackFix: "Retry the command, or choose an existing Project with prisma project link <id-or-name>."
 			});
-			const result = await bindDirectoryToProject(ctx, workspace, {
-				id: created.id,
-				name: created.name,
-				...created.defaultRegion != null ? { defaultRegion: created.defaultRegion } : {}
-			}, "created");
-			return ok(ctx.present({ data: result }, setupPresentations(result)));
-		} catch (error) {
-			const mapped = mapProjectOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		});
+		const result = await bindDirectoryToProject(ctx, workspace, {
+			id: created.id,
+			name: created.name,
+			...created.defaultRegion != null ? { defaultRegion: created.defaultRegion } : {}
+		}, "created");
+		return ok(ctx.present({ data: result }, setupPresentations(result)));
 	}
 });
 //#endregion
@@ -9072,34 +8637,56 @@ const projectDeleteCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const workspace = await resolveActiveWorkspace(ctx);
-			const projects = await listWorkspaceProjects$1(ctx);
-			const project = toProjectSummary(resolveProjectForSetup(args.positionals.project.trim(), projects, workspace));
-			await ctx.prompt.consent(CONSENT_QUESTION$1, { token: project.id });
-			await createManagementProjectProvider(ctx.api).removeProject({
-				projectId: project.id,
-				signal: ctx.signal
-			});
-			const warnings = [];
-			const result = {
-				workspace,
-				project,
-				localPin: { cleared: await cleanupLocalPinForProject(legacyOperationContext(ctx), project.id, { onError: (message) => warnings.push(message) }) }
-			};
-			const diagnostics = localPinDiagnostics(warnings);
-			return ok(ctx.present({
-				data: result,
-				diagnostics
-			}, deletePresentations$2(result)));
-		} catch (error) {
-			const mapped = mapProjectOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const workspace = await resolveActiveWorkspace(ctx);
+		const projects = await listWorkspaceProjects$1(ctx);
+		const project = toProjectSummary(resolveProjectForSetup(args.positionals.project.trim(), projects, workspace));
+		await ctx.prompt.consent(CONSENT_QUESTION$1, { token: project.id });
+		await createManagementProjectProvider(ctx.api).removeProject({
+			projectId: project.id,
+			signal: ctx.signal
+		});
+		const warnings = [];
+		const result = {
+			workspace,
+			project,
+			localPin: { cleared: await cleanupLocalPinForProject(legacyOperationContext(ctx), project.id, { onError: (message) => warnings.push(message) }) }
+		};
+		const diagnostics = localPinDiagnostics(warnings);
+		return ok(ctx.present({
+			data: result,
+			diagnostics
+		}, deletePresentations$2(result)));
 	}
 });
 //#endregion
+//#region src/lib/app/env-errors.ts
+/**
+* The structured errors the `project env` code paths raise, with the
+* registered PROJECT.* codes assigned at origin. This is the lowest
+* layer the env commands, controllers and parsers share, so the
+* parsers can raise without depending on the controllers.
+*/
+function userChoice(label) {
+	return {
+		kind: "user-choice",
+		label
+	};
+}
+function runCommand(command, reason) {
+	return {
+		kind: "run-command",
+		label: command,
+		command,
+		...reason === void 0 ? {} : { reason }
+	};
+}
+function envUsageError(summary, why, fix, commands = []) {
+	return new CliStructuredError("PROJECT.USAGE_ERROR", summary, {
+		why,
+		nextActions: [userChoice(fix), ...commands.map((step) => runCommand(step))]
+	});
+}
+//#endregion
 //#region src/lib/app/env-config.ts
 const VALID_ROLES = new Set(["production", "preview"]);
 function positionalHint(command) {
@@ -9108,9 +8695,9 @@ function positionalHint(command) {
 	return "";
 }
 function resolveEnvScope(flags, options) {
-	if (flags.roleName && flags.branchName) throw usageError(`prisma project env ${options.command} accepts either --role or --branch`, "--role targets a project-level config map; --branch targets a preview branch override.", "Pass exactly one scope flag.", [`prisma project env ${options.command} ${positionalHint(options.command)}--role preview`, `prisma project env ${options.command} ${positionalHint(options.command)}--branch feature/foo`], "app");
+	if (flags.roleName && flags.branchName) throw envUsageError(`prisma project env ${options.command} accepts either --role or --branch`, "--role targets a project-level config map; --branch targets a preview branch override.", "Pass exactly one scope flag.", [`prisma project env ${options.command} ${positionalHint(options.command)}--role preview`, `prisma project env ${options.command} ${positionalHint(options.command)}--branch feature/foo`]);
 	if (flags.roleName) {
-		if (!VALID_ROLES.has(flags.roleName)) throw usageError(`Unknown role "${flags.roleName}"`, "--role accepts production or preview.", "Pass --role production or --role preview.", [`prisma project env ${options.command} --role production`, `prisma project env ${options.command} --role preview`], "app");
+		if (!VALID_ROLES.has(flags.roleName)) throw envUsageError(`Unknown role "${flags.roleName}"`, "--role accepts production or preview.", "Pass --role production or --role preview.", [`prisma project env ${options.command} --role production`, `prisma project env ${options.command} --role preview`]);
 		return {
 			kind: "role",
 			role: flags.roleName
@@ -9122,16 +8709,16 @@ function resolveEnvScope(flags, options) {
 	};
 	if (options.requireExplicit) {
 		const positional = positionalHint(options.command);
-		throw usageError(`prisma project env ${options.command} requires --role or --branch`, "Writing without an explicit scope is rejected so the command never silently targets production.", "Pass --role production, --role preview, or --branch <git-name>.", [
+		throw envUsageError(`prisma project env ${options.command} requires --role or --branch`, "Writing without an explicit scope is rejected so the command never silently targets production.", "Pass --role production, --role preview, or --branch <git-name>.", [
 			`prisma project env ${options.command} ${positional}--role production`,
 			`prisma project env ${options.command} ${positional}--role preview`,
 			`prisma project env ${options.command} ${positional}--branch feature/foo`
-		], "app");
+		]);
 	}
 	return null;
 }
 function parseKeyValuePositional(raw, command, env = process.env) {
-	if (!raw) throw usageError(`prisma project env ${command} requires KEY=VALUE`, "No KEY=VALUE positional argument was supplied.", "Pass the variable as KEY=VALUE, e.g. STRIPE_KEY=sk_test_xxx.", [`prisma project env ${command} STRIPE_KEY=sk_test_xxx --role production`], "app");
+	if (!raw) throw envUsageError(`prisma project env ${command} requires KEY=VALUE`, "No KEY=VALUE positional argument was supplied.", "Pass the variable as KEY=VALUE, e.g. STRIPE_KEY=sk_test_xxx.", [`prisma project env ${command} STRIPE_KEY=sk_test_xxx --role production`]);
 	const separatorIndex = raw.indexOf("=");
 	if (separatorIndex === -1) {
 		if (KEY_SHAPE.test(raw)) {
@@ -9141,14 +8728,14 @@ function parseKeyValuePositional(raw, command, env = process.env) {
 				key: raw,
 				value
 			};
-			throw usageError(`Value for "${raw}" was not provided`, `No KEY=VALUE assignment was supplied, and ${raw} is not set in the current environment.`, "Pass KEY=VALUE or export the variable before running the command.", [`prisma project env ${command} ${raw}=value --role production`, `${raw}=value prisma project env ${command} ${raw} --role production`], "app");
+			throw envUsageError(`Value for "${raw}" was not provided`, `No KEY=VALUE assignment was supplied, and ${raw} is not set in the current environment.`, "Pass KEY=VALUE or export the variable before running the command.", [`prisma project env ${command} ${raw}=value --role production`, `${raw}=value prisma project env ${command} ${raw} --role production`]);
 		}
-		throw usageError(`KEY=VALUE argument is missing the = separator`, `"${raw}" does not contain an = character.`, "Pass the variable as KEY=VALUE, e.g. STRIPE_KEY=sk_test_xxx.", [`prisma project env ${command} STRIPE_KEY=sk_test_xxx --role production`], "app");
+		throw envUsageError(`KEY=VALUE argument is missing the = separator`, `"${raw}" does not contain an = character.`, "Pass the variable as KEY=VALUE, e.g. STRIPE_KEY=sk_test_xxx.", [`prisma project env ${command} STRIPE_KEY=sk_test_xxx --role production`]);
 	}
 	const key = raw.slice(0, separatorIndex);
 	const value = raw.slice(separatorIndex + 1);
 	validateKey(key, command);
-	if (value.length === 0) throw usageError(`KEY=VALUE argument has an empty value`, `"${raw}" has an empty value after the = separator.`, `Pass a non-empty value, or use prisma project env delete to delete a variable.`, [`prisma project env ${command} ${key}=value --role production`], "app");
+	if (value.length === 0) throw envUsageError(`KEY=VALUE argument has an empty value`, `"${raw}" has an empty value after the = separator.`, `Pass a non-empty value, or use prisma project env delete to delete a variable.`, [`prisma project env ${command} ${key}=value --role production`]);
 	return {
 		key,
 		value
@@ -9156,9 +8743,9 @@ function parseKeyValuePositional(raw, command, env = process.env) {
 }
 const KEY_SHAPE = /^[A-Z_][A-Z0-9_]*$/;
 function validateKey(key, command) {
-	if (key.length === 0) throw usageError(`Variable key cannot be empty`, "An empty key was passed.", "Pass an env-var key, e.g. STRIPE_KEY.", [`prisma project env ${command} STRIPE_KEY=value --role production`], "app");
-	if (key.length > 256) throw usageError(`Variable key "${key}" exceeds the 256-character limit`, "Env-var keys are capped at 256 characters by the platform.", "Use a shorter key.", [], "app");
-	if (!KEY_SHAPE.test(key)) throw usageError(`Variable key "${key}" must match the POSIX env-var shape`, "Keys must start with an uppercase letter or underscore and contain only uppercase letters, digits, and underscores.", "Rename the key to match [A-Z_][A-Z0-9_]*.", [`prisma project env ${command} STRIPE_KEY=value --role production`], "app");
+	if (key.length === 0) throw envUsageError(`Variable key cannot be empty`, "An empty key was passed.", "Pass an env-var key, e.g. STRIPE_KEY.", [`prisma project env ${command} STRIPE_KEY=value --role production`]);
+	if (key.length > 256) throw envUsageError(`Variable key "${key}" exceeds the 256-character limit`, "Env-var keys are capped at 256 characters by the platform.", "Use a shorter key.");
+	if (!KEY_SHAPE.test(key)) throw envUsageError(`Variable key "${key}" must match the POSIX env-var shape`, "Keys must start with an uppercase letter or underscore and contain only uppercase letters, digits, and underscores.", "Rename the key to match [A-Z_][A-Z0-9_]*.", [`prisma project env ${command} STRIPE_KEY=value --role production`]);
 }
 function formatScopeLabel(scope) {
 	if (scope.kind === "role") return scope.role;
@@ -9173,18 +8760,18 @@ async function readEnvFileAssignments(cwd, filePath, command) {
 	try {
 		contents = await readFile(resolvedPath, "utf8");
 	} catch (error) {
-		throw usageError(`Failed to read env file "${filePath}"`, error instanceof Error ? error.message : "The file could not be read.", "Pass a readable dotenv file path.", [`prisma project env ${command} --file .env --role preview`], "app");
+		throw envUsageError(`Failed to read env file "${filePath}"`, error instanceof Error ? error.message : "The file could not be read.", "Pass a readable dotenv file path.", [`prisma project env ${command} --file .env --role preview`]);
 	}
 	return parseEnvFileContents(contents, filePath, command);
 }
 function parseEnvFileContents(contents, filePath, command) {
 	const parsedKeys = extractParsedKeys(contents);
-	if (parsedKeys.length === 0) throw usageError(`No environment variables found in "${filePath}"`, "The file does not contain any KEY=VALUE assignments.", "Pass a dotenv file with at least one non-empty variable.", [], "app");
+	if (parsedKeys.length === 0) throw envUsageError(`No environment variables found in "${filePath}"`, "The file does not contain any KEY=VALUE assignments.", "Pass a dotenv file with at least one non-empty variable.");
 	const seen = /* @__PURE__ */ new Map();
 	for (const entry of parsedKeys) {
 		validateEnvFileKey(entry.key, entry.line, filePath, command);
 		const firstLine = seen.get(entry.key);
-		if (firstLine !== void 0) throw usageError(`Duplicate environment variable "${entry.key}" in "${filePath}"`, `Lines ${firstLine} and ${entry.line} both define ${entry.key}.`, "Keep one assignment for each key before importing the file.", [], "app");
+		if (firstLine !== void 0) throw envUsageError(`Duplicate environment variable "${entry.key}" in "${filePath}"`, `Lines ${firstLine} and ${entry.line} both define ${entry.key}.`, "Keep one assignment for each key before importing the file.");
 		seen.set(entry.key, entry.line);
 	}
 	const parsedValues = parse(contents);
@@ -9192,7 +8779,7 @@ function parseEnvFileContents(contents, filePath, command) {
 		const value = parsedValues[key];
 		if (typeof value !== "string" || value.length === 0) {
 			const line = seen.get(key);
-			throw usageError(`Environment variable "${key}" in "${filePath}" has an empty value`, line === void 0 ? `${key} has an empty value.` : `Line ${line} defines ${key} with an empty value.`, "Pass a non-empty value, or omit the key from the file.", [], "app");
+			throw envUsageError(`Environment variable "${key}" in "${filePath}" has an empty value`, line === void 0 ? `${key} has an empty value.` : `Line ${line} defines ${key} with an empty value.`, "Pass a non-empty value, or omit the key from the file.");
 		}
 		return {
 			key,
@@ -9228,7 +8815,7 @@ function validateEnvFileKey(key, line, filePath, command) {
 		validateKey(key, command);
 	} catch (error) {
 		const reason = error instanceof Error && error.message.length > 0 ? error.message : "Invalid environment variable key.";
-		throw usageError(`Invalid environment variable "${key}" in "${filePath}"`, `Line ${line}: ${reason}`, "Use a valid env-var key and retry the import.", [], "app");
+		throw envUsageError(`Invalid environment variable "${key}" in "${filePath}"`, `Line ${line}: ${reason}`, "Use a valid env-var key and retry the import.");
 	}
 }
 function hasClosingQuote(value, quote, startIndex) {
@@ -9277,15 +8864,18 @@ function apiCallError(summary, response, error) {
 	const apiCode = error?.error?.code;
 	const apiMessage = error?.error?.message;
 	const apiHint = error?.error?.hint;
-	if (status === 401 || status === 403) return authRequiredError(["prisma auth login"]);
-	return new CliError({
-		code: apiCode ?? "ENV_API_ERROR",
-		domain: "app",
-		summary,
+	if (status === 401 || status === 403) return new CliStructuredError("PROJECT.ENV_API_ERROR", summary, {
+		why: "The Management API rejected the request as unauthorized or forbidden.",
+		meta: { status },
+		nextActions: [runCommand("prisma auth login")]
+	});
+	return new CliStructuredError("PROJECT.ENV_API_ERROR", summary, {
 		why: apiMessage ?? `The Management API returned status ${status || "unknown"}.`,
-		fix: apiHint ?? "Re-run with --trace for the underlying API response details.",
-		exitCode: 1,
-		nextSteps: []
+		...status || apiCode !== void 0 ? { meta: {
+			...status ? { status } : {},
+			...apiCode !== void 0 ? { apiCode } : {}
+		} } : {},
+		nextActions: [userChoice(apiHint ?? "Re-run with --log-level verbose for the underlying API response details.")]
 	});
 }
 function formatDescriptorLabel(scope) {
@@ -9296,15 +8886,15 @@ function formatDescriptorLabel(scope) {
 //#endregion
 //#region src/controllers/app-env.ts
 function resolveEnvWriteSource(rawAssignment, filePath, command) {
-	if (filePath !== void 0 && rawAssignment !== void 0) throw usageError(`prisma project env ${command} accepts either KEY=VALUE or --file`, "The command received both a positional assignment and a dotenv file path.", "Pass one input source.", [`prisma project env ${command} KEY=value --role preview`, `prisma project env ${command} --file .env --role preview`], "app");
+	if (filePath !== void 0 && rawAssignment !== void 0) throw envUsageError(`prisma project env ${command} accepts either KEY=VALUE or --file`, "The command received both a positional assignment and a dotenv file path.", "Pass one input source.", [`prisma project env ${command} KEY=value --role preview`, `prisma project env ${command} --file .env --role preview`]);
 	if (filePath !== void 0) {
-		if (filePath.length === 0) throw usageError(`prisma project env ${command} --file requires a path`, "The --file flag was passed without a file path.", "Pass a readable dotenv file path.", [`prisma project env ${command} --file .env --role preview`], "app");
+		if (filePath.length === 0) throw envUsageError(`prisma project env ${command} --file requires a path`, "The --file flag was passed without a file path.", "Pass a readable dotenv file path.", [`prisma project env ${command} --file .env --role preview`]);
 		return {
 			kind: "file",
 			filePath
 		};
 	}
-	if (rawAssignment === void 0) throw usageError(`prisma project env ${command} requires KEY=VALUE or --file`, "No environment variable input was supplied.", "Pass a single KEY=VALUE assignment or a dotenv file path.", [`prisma project env ${command} KEY=value --role preview`, `prisma project env ${command} --file .env --role preview`], "app");
+	if (rawAssignment === void 0) throw envUsageError(`prisma project env ${command} requires KEY=VALUE or --file`, "No environment variable input was supplied.", "Pass a single KEY=VALUE assignment or a dotenv file path.", [`prisma project env ${command} KEY=value --role preview`, `prisma project env ${command} --file .env --role preview`]);
 	return {
 		kind: "single",
 		rawAssignment
@@ -9334,14 +8924,9 @@ async function resolveScopeToApi(client, projectId, scope, options) {
 		}
 	};
 	const branch = options.createBranchIfMissing ? await resolveOrCreateBranch(client, projectId, scope.branchName, options.signal) : await resolveExistingBranch(client, projectId, scope.branchName, options.signal);
-	if (branch.role === "production") throw new CliError({
-		code: "ENV_BRANCH_SCOPE_IS_PRODUCTION",
-		domain: "app",
-		summary: `Branch "${scope.branchName}" is the production branch`,
+	if (branch.role === "production") throw new CliStructuredError("PROJECT.ENV_BRANCH_SCOPE_IS_PRODUCTION", `Branch "${scope.branchName}" is the production branch`, {
 		why: "Production variables are project-level only; branch overrides apply to preview branches.",
-		fix: "Use --role production for the production branch.",
-		exitCode: 1,
-		nextSteps: ["prisma project env list --role production"]
+		nextActions: [userChoice("Use --role production for the production branch."), runCommand("prisma project env list --role production")]
 	});
 	return {
 		scope,
@@ -9420,28 +9005,18 @@ async function listBranchesByName(client, projectId, branchName, signal) {
 }
 async function resolveExistingBranch(client, projectId, branchName, signal) {
 	const branch = (await listBranchesByName(client, projectId, branchName, signal))[0];
-	if (!branch) throw new CliError({
-		code: "ENV_BRANCH_NOT_FOUND",
-		domain: "app",
-		summary: `Branch "${branchName}" not found`,
+	if (!branch) throw new CliStructuredError("PROJECT.ENV_BRANCH_NOT_FOUND", `Branch "${branchName}" not found`, {
 		why: "Branch update, list, and delete commands only target existing preview branches.",
-		fix: "Create the branch by deploying it, or use `project env add --branch` to create its first override.",
-		exitCode: 1,
-		nextSteps: [`prisma project env add KEY=value --branch ${branchName}`]
+		nextActions: [userChoice("Create the branch by deploying it, or use `project env add --branch` to create its first override."), runCommand(`prisma project env add KEY=value --branch ${branchName}`)]
 	});
 	return branch;
 }
 async function resolveOrCreateBranch(client, projectId, branchName, signal) {
 	const existing = (await listBranchesByName(client, projectId, branchName, signal))[0];
 	if (existing) return existing;
-	if (!await projectHasDefaultBranch(client, projectId, signal)) throw new CliError({
-		code: "ENV_BRANCH_CREATE_REQUIRES_DEFAULT_BRANCH",
-		domain: "app",
-		summary: `Cannot create branch "${branchName}" from project env`,
+	if (!await projectHasDefaultBranch(client, projectId, signal)) throw new CliStructuredError("PROJECT.ENV_BRANCH_CREATE_REQUIRES_DEFAULT_BRANCH", `Cannot create branch "${branchName}" from project env`, {
 		why: "Creating the first branch would make it the project default, but branch overrides are preview-only.",
-		fix: "Create or deploy the default branch first, then add the branch override.",
-		exitCode: 1,
-		nextSteps: ["prisma git connect <repository-url>"]
+		nextActions: [userChoice("Create or deploy the default branch first, then add the branch override."), runCommand("prisma git connect <repository-url>")]
 	});
 	const { data, error, response } = await client.POST("/v1/projects/{projectId}/branches", {
 		params: { path: { projectId } },
@@ -9529,18 +9104,13 @@ function materializeEffectiveRows(rows, resolved) {
 async function runEnvAddFile(context, client, projectId, resolved, filePath, assignments, verboseContext) {
 	const existing = await findVariablesByNaturalKey(client, projectId, assignments.map((assignment) => assignment.key), resolved, context.runtime.signal);
 	const existingKeys = assignments.map((assignment) => assignment.key).filter((key) => existing.has(key));
-	if (existingKeys.length > 0) throw new CliError({
-		code: "ENV_VARIABLE_ALREADY_EXISTS",
-		domain: "app",
-		summary: `${existingKeys.length} environment variable(s) already exist in ${formatScopeLabel(resolved.scope)}`,
+	if (existingKeys.length > 0) throw new CliStructuredError("PROJECT.ENV_VARIABLE_ALREADY_EXISTS", `${existingKeys.length} environment variable(s) already exist in ${formatScopeLabel(resolved.scope)}`, {
 		why: `Existing keys: ${formatKeyList(existingKeys)}.`,
-		fix: "Split the input file by key state: update existing keys and add new keys separately.",
-		exitCode: 1,
-		nextSteps: splitFileNextSteps(filePath, resolved.scope, {
+		meta: { keys: existingKeys },
+		nextActions: [userChoice("Split the input file by key state: update existing keys and add new keys separately."), ...splitFileActions(filePath, resolved.scope, {
 			existingKeys,
 			first: "update-existing"
-		}),
-		meta: { keys: existingKeys }
+		})]
 	});
 	const warnings = await missingPreviewDefaultWarnings(client, projectId, resolved.scope, assignments.map((assignment) => assignment.key), context.runtime.signal);
 	const variables = [];
@@ -9572,25 +9142,19 @@ async function runEnvAddFile(context, client, projectId, resolved, filePath, ass
 				count: variables.length
 			}
 		},
-		warnings,
-		nextSteps: []
+		warnings
 	};
 }
 async function runEnvUpdateFile(context, client, projectId, resolved, filePath, assignments, verboseContext) {
 	const existing = await findVariablesByNaturalKey(client, projectId, assignments.map((assignment) => assignment.key), resolved, context.runtime.signal);
 	const missingKeys = assignments.map((assignment) => assignment.key).filter((key) => !existing.has(key));
-	if (missingKeys.length > 0) throw new CliError({
-		code: "ENV_VARIABLE_NOT_FOUND",
-		domain: "app",
-		summary: `${missingKeys.length} environment variable(s) not found in ${formatScopeLabel(resolved.scope)}`,
+	if (missingKeys.length > 0) throw new CliStructuredError("PROJECT.ENV_VARIABLE_NOT_FOUND", `${missingKeys.length} environment variable(s) not found in ${formatScopeLabel(resolved.scope)}`, {
 		why: `Missing keys: ${formatKeyList(missingKeys)}.`,
-		fix: "Split the input file by key state: add missing keys and update existing keys separately.",
-		exitCode: 1,
-		nextSteps: splitFileNextSteps(filePath, resolved.scope, {
+		meta: { keys: missingKeys },
+		nextActions: [userChoice("Split the input file by key state: add missing keys and update existing keys separately."), ...splitFileActions(filePath, resolved.scope, {
 			missingKeys,
 			first: "add-missing"
-		}),
-		meta: { keys: missingKeys }
+		})]
 	});
 	const variables = [];
 	for (const assignment of assignments) {
@@ -9620,8 +9184,7 @@ async function runEnvUpdateFile(context, client, projectId, resolved, filePath,
 				count: variables.length
 			}
 		},
-		warnings: [],
-		nextSteps: []
+		warnings: []
 	};
 }
 async function findVariablesByNaturalKey(client, projectId, keys, resolved, signal) {
@@ -9656,20 +9219,20 @@ async function missingPreviewDefaultWarnings(client, projectId, scope, keys, sig
 }
 function envFileApplyFailedError(command, filePath, scope, failedKey, writtenVariables, error) {
 	const writtenKeys = writtenVariables.map((variable) => variable.key);
-	const cause = error instanceof CliError ? error.summary : error instanceof Error ? error.message : "Unknown error.";
-	return new CliError({
-		code: "ENV_FILE_APPLY_FAILED",
-		domain: "app",
-		summary: `Failed to ${command} "${failedKey}" from "${filePath}"`,
+	const cause = error instanceof Error ? error.message : "Unknown error.";
+	return new CliStructuredError("PROJECT.ENV_FILE_APPLY_FAILED", `Failed to ${command} "${failedKey}" from "${filePath}"`, {
 		why: writtenKeys.length === 0 ? `No variables were written before ${failedKey} failed. Cause: ${cause}` : `Written keys before failure: ${formatKeyList(writtenKeys)}. Cause: ${cause}`,
-		fix: "Inspect the target scope, then retry the remaining keys once the API issue is resolved.",
-		exitCode: 1,
-		nextSteps: [`prisma project env list ${formatScopeFlag(scope)}`, retryStepForApplyFailure(command, filePath, scope, writtenKeys)],
 		meta: {
 			file: filePath,
 			failedKey,
 			writtenKeys
-		}
+		},
+		cause: error,
+		nextActions: [
+			userChoice("Inspect the target scope, then retry the remaining keys once the API issue is resolved."),
+			runCommand(`prisma project env list ${formatScopeFlag(scope)}`),
+			runCommand(retryStepForApplyFailure(command, filePath, scope, writtenKeys))
+		]
 	});
 }
 function retryStepForApplyFailure(command, filePath, scope, writtenKeys) {
@@ -9677,22 +9240,13 @@ function retryStepForApplyFailure(command, filePath, scope, writtenKeys) {
 	if (writtenKeys.length === 0) return `prisma project env add --file ${filePath} ${formatScopeFlag(scope)}`;
 	return `prisma project env add --file <remaining.env> ${formatScopeFlag(scope)}`;
 }
-function splitFileNextSteps(filePath, scope, options) {
+/** Each command carries the key list it applies to as its reason. */
+function splitFileActions(filePath, scope, options) {
 	const scopeFlag = formatScopeFlag(scope);
 	const existingFile = `${filePath}.existing`;
 	const newFile = `${filePath}.new`;
-	if (options.first === "update-existing") return [
-		`# existing keys: ${formatKeyList(options.existingKeys)}`,
-		`prisma project env update --file ${existingFile} ${scopeFlag}`,
-		"# new keys only",
-		`prisma project env add --file ${newFile} ${scopeFlag}`
-	];
-	return [
-		`# missing keys: ${formatKeyList(options.missingKeys)}`,
-		`prisma project env add --file ${newFile} ${scopeFlag}`,
-		"# existing keys only",
-		`prisma project env update --file ${existingFile} ${scopeFlag}`
-	];
+	if (options.first === "update-existing") return [runCommand(`prisma project env update --file ${existingFile} ${scopeFlag}`, `existing keys: ${formatKeyList(options.existingKeys)}`), runCommand(`prisma project env add --file ${newFile} ${scopeFlag}`, "new keys only")];
+	return [runCommand(`prisma project env add --file ${newFile} ${scopeFlag}`, `missing keys: ${formatKeyList(options.missingKeys)}`), runCommand(`prisma project env update --file ${existingFile} ${scopeFlag}`, "existing keys only")];
 }
 function formatKeyList(keys) {
 	return keys.map((key) => `"${key}"`).join(", ");
@@ -9769,7 +9323,7 @@ function requireEnvScope(flags, command) {
 		requireExplicit: true,
 		command
 	});
-	if (!scope) throw usageError(`prisma project env ${command} requires --role or --branch`, "Writing without an explicit scope is rejected.", "Pass --role production, --role preview, or --branch <git-name>.", [`prisma project env ${command} KEY=value --role production`], "app");
+	if (!scope) throw envUsageError(`prisma project env ${command} requires --role or --branch`, "Writing without an explicit scope is rejected.", "Pass --role production, --role preview, or --branch <git-name>.", [`prisma project env ${command} KEY=value --role production`]);
 	return scope;
 }
 /** Workspace, pinned project and the API scope every env write needs. */
@@ -9923,74 +9477,63 @@ const projectEnvAddCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const source = resolveEnvWriteSource(args.positionals.assignment, args.flags.file, "add");
-			const scope = requireEnvScope(args.flags, "add");
-			const input = await resolveEnvWriteInput(legacyOperationContext(ctx), source, "add");
-			const { projectId, verboseContext, resolved } = await resolveEnvTarget(ctx, args.flags, scope, "project env add", true);
-			if (input.kind === "file") {
-				const written = await runEnvAddFile(legacyOperationContext(ctx), ctx.api, projectId, resolved, input.filePath, input.assignments, verboseContext);
-				const result = {
-					projectId,
-					scope: resolved.descriptor,
-					variables: written.result.variables,
-					file: written.result.file
-				};
-				return ok(ctx.present({
-					data: result,
-					diagnostics: previewDefaultDiagnostics(written.warnings)
-				}, fileWritePresentations({
-					title: "Setting new environment variables from file.",
-					emptyMessage: "No environment variables imported.",
-					scope: result.scope,
-					filePath: result.file.path,
-					variables: result.variables
-				}, result)));
-			}
-			if (await findVariableByNaturalKey(ctx.api, projectId, input.key, resolved, ctx.signal)) throw new CliError({
-				code: "ENV_VARIABLE_ALREADY_EXISTS",
-				domain: "app",
-				summary: `Variable "${input.key}" already exists in ${formatScopeLabel(scope)}`,
-				why: "A variable with this key already exists in the targeted scope.",
-				fix: "Use `prisma project env update` to change an existing variable's value.",
-				exitCode: 1,
-				nextSteps: [`prisma project env update ${input.key}=<new-value> ${formatScopeFlag$1(scope)}`]
-			});
-			const warnings = scope.kind === "branch" && !await findVariableByNaturalKey(ctx.api, projectId, input.key, {
-				descriptor: {
-					kind: "role",
-					role: "preview"
-				},
-				apiTarget: {
-					class: "preview",
-					branchId: null
-				}
-			}, ctx.signal) ? [`Variable "${input.key}" does not exist in preview. It will only exist on ${formatScopeLabel(scope)}.`] : [];
-			const { data, error, response } = await ctx.api.POST("/v1/environment-variables", {
-				body: {
-					projectId,
-					class: resolved.apiTarget.class,
-					...resolved.apiTarget.branchId !== null ? { branchId: resolved.apiTarget.branchId } : {},
-					key: input.key,
-					value: input.value
-				},
-				signal: ctx.signal
-			});
-			if (error || !data) throw apiCallError(`Failed to add ${input.key}`, response, error);
+		const source = resolveEnvWriteSource(args.positionals.assignment, args.flags.file, "add");
+		const scope = requireEnvScope(args.flags, "add");
+		const input = await resolveEnvWriteInput(legacyOperationContext(ctx), source, "add");
+		const { projectId, verboseContext, resolved } = await resolveEnvTarget(ctx, args.flags, scope, "project env add", true);
+		if (input.kind === "file") {
+			const written = await runEnvAddFile(legacyOperationContext(ctx), ctx.api, projectId, resolved, input.filePath, input.assignments, verboseContext);
 			const result = {
 				projectId,
 				scope: resolved.descriptor,
-				variable: toMetadata(data.data, resolved.descriptor)
+				variables: written.result.variables,
+				file: written.result.file
 			};
 			return ok(ctx.present({
 				data: result,
-				diagnostics: previewDefaultDiagnostics(warnings)
-			}, singlePresentations$1(result)));
-		} catch (error) {
-			const mapped = mapProjectOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+				diagnostics: previewDefaultDiagnostics(written.warnings)
+			}, fileWritePresentations({
+				title: "Setting new environment variables from file.",
+				emptyMessage: "No environment variables imported.",
+				scope: result.scope,
+				filePath: result.file.path,
+				variables: result.variables
+			}, result)));
+		}
+		if (await findVariableByNaturalKey(ctx.api, projectId, input.key, resolved, ctx.signal)) throw new CliStructuredError("PROJECT.ENV_VARIABLE_ALREADY_EXISTS", `Variable "${input.key}" already exists in ${formatScopeLabel(scope)}`, {
+			why: "A variable with this key already exists in the targeted scope.",
+			nextActions: [userChoice("Use `prisma project env update` to change an existing variable's value."), runCommand(`prisma project env update ${input.key}=<new-value> ${formatScopeFlag$1(scope)}`)]
+		});
+		const warnings = scope.kind === "branch" && !await findVariableByNaturalKey(ctx.api, projectId, input.key, {
+			descriptor: {
+				kind: "role",
+				role: "preview"
+			},
+			apiTarget: {
+				class: "preview",
+				branchId: null
+			}
+		}, ctx.signal) ? [`Variable "${input.key}" does not exist in preview. It will only exist on ${formatScopeLabel(scope)}.`] : [];
+		const { data, error, response } = await ctx.api.POST("/v1/environment-variables", {
+			body: {
+				projectId,
+				class: resolved.apiTarget.class,
+				...resolved.apiTarget.branchId !== null ? { branchId: resolved.apiTarget.branchId } : {},
+				key: input.key,
+				value: input.value
+			},
+			signal: ctx.signal
+		});
+		if (error || !data) throw apiCallError(`Failed to add ${input.key}`, response, error);
+		const result = {
+			projectId,
+			scope: resolved.descriptor,
+			variable: toMetadata(data.data, resolved.descriptor)
+		};
+		return ok(ctx.present({
+			data: result,
+			diagnostics: previewDefaultDiagnostics(warnings)
+		}, singlePresentations$1(result)));
 	}
 });
 //#endregion
@@ -10047,36 +9590,25 @@ const projectEnvDeleteCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const key = args.positionals.key;
-			const scope = requireEnvScope(args.flags, "delete");
-			const { projectId, resolved } = await resolveEnvTarget(ctx, args.flags, scope, "project env delete", false);
-			const existing = await findVariableByNaturalKey(ctx.api, projectId, key, resolved, ctx.signal);
-			if (!existing) throw new CliError({
-				code: "ENV_VARIABLE_NOT_FOUND",
-				domain: "app",
-				summary: `Variable "${key}" not found in ${formatScopeLabel(scope)}`,
-				why: "No variable with this key exists in the targeted scope, so there is nothing to delete.",
-				fix: "Run prisma project env list with the same scope to see the available variables.",
-				exitCode: 1,
-				nextSteps: [`prisma project env list ${formatScopeFlag$1(scope)}`]
-			});
-			const { error, response } = await ctx.api.DELETE("/v1/environment-variables/{envVarId}", {
-				params: { path: { envVarId: existing.id } },
-				signal: ctx.signal
-			});
-			if (error) throw apiCallError(`Failed to delete ${key}`, response, error);
-			const result = {
-				projectId,
-				scope: resolved.descriptor,
-				key
-			};
-			return ok(ctx.present({ data: result }, deletePresentations$1(result)));
-		} catch (error) {
-			const mapped = mapProjectOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const key = args.positionals.key;
+		const scope = requireEnvScope(args.flags, "delete");
+		const { projectId, resolved } = await resolveEnvTarget(ctx, args.flags, scope, "project env delete", false);
+		const existing = await findVariableByNaturalKey(ctx.api, projectId, key, resolved, ctx.signal);
+		if (!existing) throw new CliStructuredError("PROJECT.ENV_VARIABLE_NOT_FOUND", `Variable "${key}" not found in ${formatScopeLabel(scope)}`, {
+			why: "No variable with this key exists in the targeted scope, so there is nothing to delete.",
+			nextActions: [userChoice("Run prisma project env list with the same scope to see the available variables."), runCommand(`prisma project env list ${formatScopeFlag$1(scope)}`)]
+		});
+		const { error, response } = await ctx.api.DELETE("/v1/environment-variables/{envVarId}", {
+			params: { path: { envVarId: existing.id } },
+			signal: ctx.signal
+		});
+		if (error) throw apiCallError(`Failed to delete ${key}`, response, error);
+		const result = {
+			projectId,
+			scope: resolved.descriptor,
+			key
+		};
+		return ok(ctx.present({ data: result }, deletePresentations$1(result)));
 	}
 });
 //#endregion
@@ -10143,33 +9675,27 @@ const projectEnvListCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const explicit = resolveEnvScope({
-				roleName: args.flags.role,
-				branchName: args.flags.branch
-			}, {
-				requireExplicit: false,
-				command: "list"
-			});
-			const projectId = (await resolvePinnedProject(ctx, await resolveActiveWorkspace(ctx), args.flags.project, "project env list")).project.id;
-			const resolved = await resolveListScopeToApi(ctx.api, projectId, explicit ?? void 0, { signal: ctx.signal });
-			const rows = resolved.kind === "scoped" ? await listVariables(ctx.api, projectId, {
-				scope: resolved.addScope,
-				descriptor: resolved.descriptor,
-				apiTarget: resolved.apiTarget
-			}, ctx.signal) : await listOverviewVariables(ctx.api, projectId, ctx.signal);
-			const result = {
-				projectId,
-				scope: resolved.descriptor,
-				target: resolved.target,
-				variables: rows.map((row) => toMetadata(row, resolved.descriptor))
-			};
-			return ok(ctx.present({ data: result }, listPresentations$2(result, formatScopeFlag$1(resolved.addScope))));
-		} catch (error) {
-			const mapped = mapProjectOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const explicit = resolveEnvScope({
+			roleName: args.flags.role,
+			branchName: args.flags.branch
+		}, {
+			requireExplicit: false,
+			command: "list"
+		});
+		const projectId = (await resolvePinnedProject(ctx, await resolveActiveWorkspace(ctx), args.flags.project, "project env list")).project.id;
+		const resolved = await resolveListScopeToApi(ctx.api, projectId, explicit ?? void 0, { signal: ctx.signal });
+		const rows = resolved.kind === "scoped" ? await listVariables(ctx.api, projectId, {
+			scope: resolved.addScope,
+			descriptor: resolved.descriptor,
+			apiTarget: resolved.apiTarget
+		}, ctx.signal) : await listOverviewVariables(ctx.api, projectId, ctx.signal);
+		const result = {
+			projectId,
+			scope: resolved.descriptor,
+			target: resolved.target,
+			variables: rows.map((row) => toMetadata(row, resolved.descriptor))
+		};
+		return ok(ctx.present({ data: result }, listPresentations$2(result, formatScopeFlag$1(resolved.addScope))));
 	}
 });
 //#endregion
@@ -10215,54 +9741,43 @@ const projectEnvUpdateCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const source = resolveEnvWriteSource(args.positionals.assignment, args.flags.file, "update");
-			const scope = requireEnvScope(args.flags, "update");
-			const input = await resolveEnvWriteInput(legacyOperationContext(ctx), source, "update");
-			const { projectId, verboseContext, resolved } = await resolveEnvTarget(ctx, args.flags, scope, "project env update", false);
-			if (input.kind === "file") {
-				const written = await runEnvUpdateFile(legacyOperationContext(ctx), ctx.api, projectId, resolved, input.filePath, input.assignments, verboseContext);
-				const result = {
-					projectId,
-					scope: resolved.descriptor,
-					variables: written.result.variables,
-					file: written.result.file
-				};
-				return ok(ctx.present({ data: result }, fileWritePresentations({
-					title: "Replacing environment variable values from file.",
-					emptyMessage: "No environment variables updated.",
-					scope: result.scope,
-					filePath: result.file.path,
-					variables: result.variables
-				}, result)));
-			}
-			const existing = await findVariableByNaturalKey(ctx.api, projectId, input.key, resolved, ctx.signal);
-			if (!existing) throw new CliError({
-				code: "ENV_VARIABLE_NOT_FOUND",
-				domain: "app",
-				summary: `Variable "${input.key}" not found in ${formatScopeLabel(scope)}`,
-				why: "No variable with this key exists in the targeted scope.",
-				fix: "Use `prisma project env add` to create a new variable.",
-				exitCode: 1,
-				nextSteps: [`prisma project env add ${input.key}=<value> ${formatScopeFlag$1(scope)}`]
-			});
-			const { data, error, response } = await ctx.api.PATCH("/v1/environment-variables/{envVarId}", {
-				params: { path: { envVarId: existing.id } },
-				body: { value: input.value },
-				signal: ctx.signal
-			});
-			if (error || !data) throw apiCallError(`Failed to update value for ${input.key}`, response, error);
+		const source = resolveEnvWriteSource(args.positionals.assignment, args.flags.file, "update");
+		const scope = requireEnvScope(args.flags, "update");
+		const input = await resolveEnvWriteInput(legacyOperationContext(ctx), source, "update");
+		const { projectId, verboseContext, resolved } = await resolveEnvTarget(ctx, args.flags, scope, "project env update", false);
+		if (input.kind === "file") {
+			const written = await runEnvUpdateFile(legacyOperationContext(ctx), ctx.api, projectId, resolved, input.filePath, input.assignments, verboseContext);
 			const result = {
 				projectId,
 				scope: resolved.descriptor,
-				variable: toMetadata(data.data, resolved.descriptor)
+				variables: written.result.variables,
+				file: written.result.file
 			};
-			return ok(ctx.present({ data: result }, singlePresentations(result)));
-		} catch (error) {
-			const mapped = mapProjectOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+			return ok(ctx.present({ data: result }, fileWritePresentations({
+				title: "Replacing environment variable values from file.",
+				emptyMessage: "No environment variables updated.",
+				scope: result.scope,
+				filePath: result.file.path,
+				variables: result.variables
+			}, result)));
+		}
+		const existing = await findVariableByNaturalKey(ctx.api, projectId, input.key, resolved, ctx.signal);
+		if (!existing) throw new CliStructuredError("PROJECT.ENV_VARIABLE_NOT_FOUND", `Variable "${input.key}" not found in ${formatScopeLabel(scope)}`, {
+			why: "No variable with this key exists in the targeted scope.",
+			nextActions: [userChoice("Use `prisma project env add` to create a new variable."), runCommand(`prisma project env add ${input.key}=<value> ${formatScopeFlag$1(scope)}`)]
+		});
+		const { data, error, response } = await ctx.api.PATCH("/v1/environment-variables/{envVarId}", {
+			params: { path: { envVarId: existing.id } },
+			body: { value: input.value },
+			signal: ctx.signal
+		});
+		if (error || !data) throw apiCallError(`Failed to update value for ${input.key}`, response, error);
+		const result = {
+			projectId,
+			scope: resolved.descriptor,
+			variable: toMetadata(data.data, resolved.descriptor)
+		};
+		return ok(ctx.present({ data: result }, singlePresentations(result)));
 	}
 });
 //#endregion
@@ -10271,7 +9786,25 @@ const projectEnvUpdateCommand = defineCommand({
 const CREATE_CHOICE = "__create__";
 const CANCEL_CHOICE = "__cancel__";
 function setupCanceledError() {
-	return usageError("Project setup canceled", "Project link needs a Project before it can continue.", "Choose an existing Project or create a new one, then rerun project link.", ["prisma project link <id-or-name>", "prisma project create <name>"], "project");
+	return new CliStructuredError("PROJECT.USAGE_ERROR", "Project setup canceled", {
+		why: "Project link needs a Project before it can continue.",
+		nextActions: [
+			{
+				kind: "user-choice",
+				label: "Choose an existing Project or create a new one, then rerun project link."
+			},
+			{
+				kind: "run-command",
+				label: "prisma project link <id-or-name>",
+				command: "prisma project link <id-or-name>"
+			},
+			{
+				kind: "run-command",
+				label: "prisma project create <name>",
+				command: "prisma project create <name>"
+			}
+		]
+	});
 }
 function choiceOptions(projects) {
 	const sorted = sortProjects(projects);
@@ -10356,14 +9889,8 @@ const projectLinkCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const result = await linkDirectoryToProject(ctx, args.positionals.project);
-			return ok(ctx.present({ data: result }, setupPresentations(result)));
-		} catch (error) {
-			const mapped = mapProjectOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const result = await linkDirectoryToProject(ctx, args.positionals.project);
+		return ok(ctx.present({ data: result }, setupPresentations(result)));
 	}
 });
 //#endregion
@@ -10390,10 +9917,10 @@ function projectStdoutRows(result) {
 }
 function nextActionsFor(result) {
 	if (result.localBinding?.status === "linked") return [];
-	return toNextActions(buildProjectSetupNextActions({
+	return buildProjectSetupNextActions({
 		createCommand: `${CLI_NAME} project create <name>`,
 		reason: result.localBinding?.status === "invalid" ? "This directory has an invalid local Project binding. Ask the user which Prisma Project to link before running Project-scoped commands." : "This directory is not linked to a Prisma Project. Project list shows available Projects, but none is selected for this directory."
-	}));
+	});
 }
 function listPresentations$1(result) {
 	const rows = projectRows(result);
@@ -10438,21 +9965,15 @@ const projectListCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (_args, ctx) => {
-		try {
-			const workspace = await resolveActiveWorkspace(ctx);
-			const projects = sortProjects(await listWorkspaceProjects$1(ctx));
-			const localBinding = await readProjectListLocalBinding(ctx.cwd, projects, ctx.signal);
-			const result = {
-				workspace,
-				projects: projects.map(toProjectSummary),
-				localBinding
-			};
-			return ok(ctx.present({ data: result }, listPresentations$1(result)));
-		} catch (error) {
-			const mapped = mapProjectOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const workspace = await resolveActiveWorkspace(ctx);
+		const projects = sortProjects(await listWorkspaceProjects$1(ctx));
+		const localBinding = await readProjectListLocalBinding(ctx.cwd, projects, ctx.signal);
+		const result = {
+			workspace,
+			projects: projects.map(toProjectSummary),
+			localBinding
+		};
+		return ok(ctx.present({ data: result }, listPresentations$1(result)));
 	}
 });
 //#endregion
@@ -10510,26 +10031,20 @@ const projectRenameCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const workspace = await resolveActiveWorkspace(ctx);
-			const name = args.positionals.name.trim();
-			if (!isValidProjectSetupName(name)) throw projectSetupNameRequiredError("project rename");
-			const target = await resolvePinnedProject(ctx, workspace, args.flags.project, "project rename");
-			const result = {
-				workspace,
-				project: await createManagementProjectProvider(ctx.api).renameProject({
-					projectId: target.project.id,
-					name,
-					signal: ctx.signal
-				}),
-				previousName: target.project.name
-			};
-			return ok(ctx.present({ data: result }, renamePresentations(result)));
-		} catch (error) {
-			const mapped = mapProjectOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const workspace = await resolveActiveWorkspace(ctx);
+		const name = args.positionals.name.trim();
+		if (!isValidProjectSetupName(name)) throw projectSetupNameRequiredError("project rename");
+		const target = await resolvePinnedProject(ctx, workspace, args.flags.project, "project rename");
+		const result = {
+			workspace,
+			project: await createManagementProjectProvider(ctx.api).renameProject({
+				projectId: target.project.id,
+				name,
+				signal: ctx.signal
+			}),
+			previousName: target.project.name
+		};
+		return ok(ctx.present({ data: result }, renamePresentations(result)));
 	}
 });
 //#endregion
@@ -10631,12 +10146,12 @@ function showPresentations$1(result, cwd, env) {
 			rows
 		}],
 		stdout: () => stdoutFieldRows(result, cwd).map((row) => `${row.label}: ${row.value}`),
-		next: () => result.project === null ? toNextActions(buildProjectSetupNextActions({
+		next: () => result.project === null ? buildProjectSetupNextActions({
 			commandName: "project show",
 			retryCommand: "prisma project show <id-or-name>",
 			suggestedProjectName: result.suggestedProjectName,
 			reason: "This directory is not linked to a Prisma Project. Package and directory names can suggest setup defaults, but they do not select a Project."
-		})) : []
+		}) : []
 	};
 }
 const projectShowCommand = defineCommand({
@@ -10650,23 +10165,17 @@ const projectShowCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const workspace = await resolveActiveWorkspace(ctx);
-			const inspected = await inspectProjectBinding({
-				context: legacyOperationContext(ctx),
-				workspace,
-				explicitProject: args.positionals.project,
-				listProjects: () => listWorkspaceProjects$1(ctx),
-				commandName: "project show"
-			});
-			if (inspected.isErr()) throw projectResolutionErrorToCliError(inspected.error);
-			const result = inspected.value;
-			return ok(ctx.present({ data: result }, showPresentations$1(result, ctx.cwd, ctx.env)));
-		} catch (error) {
-			const mapped = mapProjectOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
-		}
+		const workspace = await resolveActiveWorkspace(ctx);
+		const inspected = await inspectProjectBinding({
+			context: legacyOperationContext(ctx),
+			workspace,
+			explicitProject: args.positionals.project,
+			listProjects: () => listWorkspaceProjects$1(ctx),
+			commandName: "project show"
+		});
+		if (inspected.isErr()) throw projectResolutionErrorToStructured(inspected.error);
+		const result = inspected.value;
+		return ok(ctx.present({ data: result }, showPresentations$1(result, ctx.cwd, ctx.env)));
 	}
 });
 //#endregion
@@ -10850,11 +10359,11 @@ const projectTransferCommand = defineCommand({
 	},
 	needs: { credentials: true },
 	handler: async (args, ctx) => {
-		try {
-			const workspace = await resolveActiveWorkspace(ctx);
-			const toWorkspace = args.flags.toWorkspace?.trim() || void 0;
-			const recipientToken = args.flags.recipientToken?.trim() || void 0;
-			if (toWorkspace && recipientToken) throw usageError("Choose one transfer recipient source", "--to-workspace and --recipient-token are mutually exclusive.", "Pass either --to-workspace <id-or-name> or --recipient-token <token>.", [formatCommand([
+		const workspace = await resolveActiveWorkspace(ctx);
+		const toWorkspace = args.flags.toWorkspace?.trim() || void 0;
+		const recipientToken = args.flags.recipientToken?.trim() || void 0;
+		if (toWorkspace && recipientToken) {
+			const retry = formatCommand([
 				"project",
 				"transfer",
 				"<project>",
@@ -10862,42 +10371,49 @@ const projectTransferCommand = defineCommand({
 				"<id-or-name>",
 				"--confirm",
 				"<project-id>"
-			])], "project");
-			if (!toWorkspace && !recipientToken) throw transferRecipientRequiredError(formatCommand);
-			const projects = await listWorkspaceProjects$1(ctx);
-			const project = toProjectSummary(resolveProjectForSetup(args.positionals.project.trim(), projects, workspace));
-			await ctx.prompt.consent(CONSENT_QUESTION, { token: project.id });
-			const recipient = await resolveRecipient(ctx, {
-				toWorkspace,
-				recipientToken
-			});
-			await createManagementProjectProvider(ctx.api).transferProject({
-				projectId: project.id,
-				recipientAccessToken: recipient.accessToken,
-				signal: ctx.signal
+			]);
+			throw new CliStructuredError("PROJECT.USAGE_ERROR", "Choose one transfer recipient source", {
+				why: "--to-workspace and --recipient-token are mutually exclusive.",
+				nextActions: [{
+					kind: "user-choice",
+					label: "Pass either --to-workspace <id-or-name> or --recipient-token <token>."
+				}, {
+					kind: "run-command",
+					label: retry,
+					command: retry
+				}]
 			});
-			const warnings = [];
-			const action = await rewriteOrClearLocalPinForProject(legacyOperationContext(ctx), project.id, recipient.workspaceId, { onError: (message) => warnings.push(message) });
-			const result = {
-				workspace,
-				project,
-				recipient: {
-					workspaceId: recipient.workspaceId,
-					workspaceName: recipient.workspaceName,
-					source: recipient.source
-				},
-				localPin: { action }
-			};
-			const diagnostics = localPinDiagnostics(warnings);
-			return ok(ctx.present({
-				data: result,
-				diagnostics
-			}, transferPresentations(result, toWorkspace)));
-		} catch (error) {
-			const mapped = mapProjectOperationError(error);
-			if (mapped) return notOk(mapped);
-			throw error;
 		}
+		if (!toWorkspace && !recipientToken) throw transferRecipientRequiredError(formatCommand);
+		const projects = await listWorkspaceProjects$1(ctx);
+		const project = toProjectSummary(resolveProjectForSetup(args.positionals.project.trim(), projects, workspace));
+		await ctx.prompt.consent(CONSENT_QUESTION, { token: project.id });
+		const recipient = await resolveRecipient(ctx, {
+			toWorkspace,
+			recipientToken
+		});
+		await createManagementProjectProvider(ctx.api).transferProject({
+			projectId: project.id,
+			recipientAccessToken: recipient.accessToken,
+			signal: ctx.signal
+		});
+		const warnings = [];
+		const action = await rewriteOrClearLocalPinForProject(legacyOperationContext(ctx), project.id, recipient.workspaceId, { onError: (message) => warnings.push(message) });
+		const result = {
+			workspace,
+			project,
+			recipient: {
+				workspaceId: recipient.workspaceId,
+				workspaceName: recipient.workspaceName,
+				source: recipient.source
+			},
+			localPin: { action }
+		};
+		const diagnostics = localPinDiagnostics(warnings);
+		return ok(ctx.present({
+			data: result,
+			diagnostics
+		}, transferPresentations(result, toWorkspace)));
 	}
 });
 //#endregion
@@ -10928,40 +10444,9 @@ function adviceAction(label) {
 		label
 	};
 }
-function toEngineNextAction(action) {
-	return {
-		kind: action.kind,
-		label: action.label,
-		...action.command !== void 0 ? { command: action.command } : {},
-		...action.commands !== void 0 ? { commands: action.commands } : {},
-		...action.reason !== void 0 ? { reason: action.reason } : {}
-	};
-}
 const CNAME_HINT = /\bcname(?:s)?\s+to\b/;
 const PRISMA_BUILD_HOST = /\b((?:[a-z0-9-]+\.)+prisma\.build)\b/i;
 /**
-* Maps a legacy CliError onto the engine error protocol: the flat code
-* becomes `SERVICE.<code>`, the free-text fix becomes a user-choice
-* action carried alongside any typed legacy actions, and each nextSteps
-* command line becomes a run-command action. Copy passes through
-* unchanged: the producers write the commands a user types today.
-*/
-function fromLegacyCliError(error) {
-	const fixAction = error.fix ? [adviceAction(error.fix)] : [];
-	const nextActions = error.nextActions.length > 0 ? [...error.nextActions.map(toEngineNextAction), ...fixAction] : [...fixAction, ...error.nextSteps.map((step) => ({
-		kind: "run-command",
-		label: "Run",
-		command: step
-	}))];
-	return new CliStructuredError(`SERVICE.${error.code}`, error.summary, {
-		...error.why ? { why: error.why } : {},
-		nextActions,
-		...error.where ? { where: { path: error.where } } : {},
-		...Object.keys(error.meta).length > 0 ? { meta: error.meta } : {},
-		...error.docsUrl ? { docsUrl: error.docsUrl } : {}
-	});
-}
-/**
 * Consent declined interactively. The engine settles this code as a
 * user cancellation (exit 3).
 */
@@ -11826,7 +11311,7 @@ function toBranchKind(name) {
 */
 async function listWorkspaceProjects(ctx) {
 	const { data, error, response } = await ctx.api.GET("/v1/projects", { signal: ctx.signal });
-	if (error || !data) throw fromLegacyCliError(projectApiError("Failed to list projects", response, error));
+	if (error || !data) throw projectApiError("Failed to list projects", response, error);
 	return sortProjects((data.data ?? []).map((project) => ({
 		id: project.id,
 		name: project.name,
@@ -11855,7 +11340,7 @@ async function resolveServiceProjectContext(ctx, explicitProject, options) {
 		listProjects: () => Promise.resolve(projects),
 		commandName: options.commandName
 	});
-	if (resolvedResult.isErr()) throw fromLegacyCliError(projectResolutionErrorToCliError(resolvedResult.error));
+	if (resolvedResult.isErr()) throw projectResolutionErrorToStructured(resolvedResult.error);
 	const resolved = resolvedResult.value;
 	const requested = options.branchName ? {
 		name: options.branchName,
@@ -13374,6 +12859,7 @@ const serviceVersionStopCommand = defineCommand({
 *  part of either product's. */
 const skillsCommandFamily = defineCommandFamily({
 	configSection: skillsConfigSection,
+	docsBaseUrl: DOCS_ERRORS_BASE_URL,
 	commands: {
 		sync: skillsSyncCommand,
 		list: defineCommand({
@@ -13417,63 +12903,66 @@ const skillsCommandFamily = defineCommandFamily({
 });
 //#endregion
 //#region src/cli.ts
-const platformCommandFamily = defineCommandFamily({ commands: {
-	login: authLoginCommand,
-	logout: authLogoutCommand,
-	whoami: authWhoamiCommand,
-	workspaceList: authWorkspaceListCommand,
-	workspaceUse: authWorkspaceUseCommand,
-	workspaceLogout: authWorkspaceLogoutCommand,
-	projectList: projectListCommand,
-	projectShow: projectShowCommand,
-	projectCreate: projectCreateCommand,
-	projectLink: projectLinkCommand,
-	projectRename: projectRenameCommand,
-	projectDelete: projectDeleteCommand,
-	projectTransfer: projectTransferCommand,
-	projectEnvAdd: projectEnvAddCommand,
-	projectEnvUpdate: projectEnvUpdateCommand,
-	projectEnvList: projectEnvListCommand,
-	projectEnvDelete: projectEnvDeleteCommand,
-	postgresList: postgresListCommand,
-	postgresShow: postgresShowCommand,
-	postgresCreate: postgresCreateCommand,
-	postgresUsage: postgresUsageCommand,
-	postgresBackupRestore: postgresBackupRestoreCommand,
-	postgresDelete: postgresDeleteCommand,
-	postgresBackupList: postgresBackupListCommand,
-	postgresConnectionList: postgresConnectionListCommand,
-	postgresConnectionCreate: postgresConnectionCreateCommand,
-	postgresConnectionRotate: postgresConnectionRotateCommand,
-	postgresConnectionDelete: postgresConnectionDeleteCommand,
-	bucketList: bucketListCommand,
-	bucketCreate: bucketCreateCommand,
-	bucketDelete: bucketDeleteCommand,
-	bucketKeyList: bucketKeyListCommand,
-	bucketKeyCreate: bucketKeyCreateCommand,
-	bucketKeyDelete: bucketKeyDeleteCommand,
-	branchList: branchListCommand,
-	gitConnect: gitConnectCommand,
-	gitDisconnect: gitDisconnectCommand,
-	serviceList: serviceListCommand,
-	serviceLogs: serviceLogsCommand,
-	serviceCreate: serviceCreateCommand,
-	serviceShow: serviceShowCommand,
-	serviceOpen: serviceOpenCommand,
-	serviceVersionList: serviceVersionListCommand,
-	serviceVersionShow: serviceVersionShowCommand,
-	serviceVersionPromote: serviceVersionPromoteCommand,
-	serviceVersionRollback: serviceVersionRollbackCommand,
-	serviceVersionStart: serviceVersionStartCommand,
-	serviceVersionStop: serviceVersionStopCommand,
-	serviceVersionDelete: serviceVersionDeleteCommand,
-	serviceDelete: serviceDeleteCommand,
-	serviceDomainAdd: serviceDomainAddCommand,
-	serviceDomainShow: serviceDomainShowCommand,
-	serviceDomainDelete: serviceDomainDeleteCommand,
-	serviceDomainRetry: serviceDomainRetryCommand,
-	serviceDomainWait: serviceDomainWaitCommand
-} });
+const platformCommandFamily = defineCommandFamily({
+	docsBaseUrl: DOCS_ERRORS_BASE_URL,
+	commands: {
+		login: authLoginCommand,
+		logout: authLogoutCommand,
+		whoami: authWhoamiCommand,
+		workspaceList: authWorkspaceListCommand,
+		workspaceUse: authWorkspaceUseCommand,
+		workspaceLogout: authWorkspaceLogoutCommand,
+		projectList: projectListCommand,
+		projectShow: projectShowCommand,
+		projectCreate: projectCreateCommand,
+		projectLink: projectLinkCommand,
+		projectRename: projectRenameCommand,
+		projectDelete: projectDeleteCommand,
+		projectTransfer: projectTransferCommand,
+		projectEnvAdd: projectEnvAddCommand,
+		projectEnvUpdate: projectEnvUpdateCommand,
+		projectEnvList: projectEnvListCommand,
+		projectEnvDelete: projectEnvDeleteCommand,
+		postgresList: postgresListCommand,
+		postgresShow: postgresShowCommand,
+		postgresCreate: postgresCreateCommand,
+		postgresUsage: postgresUsageCommand,
+		postgresBackupRestore: postgresBackupRestoreCommand,
+		postgresDelete: postgresDeleteCommand,
+		postgresBackupList: postgresBackupListCommand,
+		postgresConnectionList: postgresConnectionListCommand,
+		postgresConnectionCreate: postgresConnectionCreateCommand,
+		postgresConnectionRotate: postgresConnectionRotateCommand,
+		postgresConnectionDelete: postgresConnectionDeleteCommand,
+		bucketList: bucketListCommand,
+		bucketCreate: bucketCreateCommand,
+		bucketDelete: bucketDeleteCommand,
+		bucketKeyList: bucketKeyListCommand,
+		bucketKeyCreate: bucketKeyCreateCommand,
+		bucketKeyDelete: bucketKeyDeleteCommand,
+		branchList: branchListCommand,
+		gitConnect: gitConnectCommand,
+		gitDisconnect: gitDisconnectCommand,
+		serviceList: serviceListCommand,
+		serviceLogs: serviceLogsCommand,
+		serviceCreate: serviceCreateCommand,
+		serviceShow: serviceShowCommand,
+		serviceOpen: serviceOpenCommand,
+		serviceVersionList: serviceVersionListCommand,
+		serviceVersionShow: serviceVersionShowCommand,
+		serviceVersionPromote: serviceVersionPromoteCommand,
+		serviceVersionRollback: serviceVersionRollbackCommand,
+		serviceVersionStart: serviceVersionStartCommand,
+		serviceVersionStop: serviceVersionStopCommand,
+		serviceVersionDelete: serviceVersionDeleteCommand,
+		serviceDelete: serviceDeleteCommand,
+		serviceDomainAdd: serviceDomainAddCommand,
+		serviceDomainShow: serviceDomainShowCommand,
+		serviceDomainDelete: serviceDomainDeleteCommand,
+		serviceDomainRetry: serviceDomainRetryCommand,
+		serviceDomainWait: serviceDomainWaitCommand
+	}
+});
 /**
 * Composer's commands, contributed by composer's own package and run by
 * this process, mounted as shipped. Only the command definitions and