@uipath/solution-tool 1.201.0-preview.133 → 1.202.0-preview.134

package/dist/{packager-tool-zbp5p149.js → packager-tool-bahvrjbv.js}

@@ -1,7 +1,7 @@
 import {
   getStudioWebAuthWithOrganizationId,
   useStudioWebAuth
-} from "./packager-tool-yktm4v4r.js";
+} from "./packager-tool-xntjj1bt.js";
 import {
   activateDeploymentAsync,
   deployRunAsync,
@@ -9,53 +9,54 @@ import {
   formatDeploymentErrorsAsText,
   listDeploymentsAsync,
   listPackagesAsync,
-  uninstallDeploymentAsync
-} from "./packager-tool-wjhn59ft.js";
+  uninstallDeploymentAsync,
+  upgradeDeploymentAsync
+} from "./packager-tool-t89r1edr.js";
 import {
   SolutionInitError,
   solutionInitAsync
-} from "./packager-tool-67ssxgph.js";
+} from "./packager-tool-fh8pb2th.js";
 import {
   GOVERNANCE_OPTION_INSTRUCTIONS,
   PackCommandService,
+  SOLUTION_PATH_INSTRUCTIONS,
   SolutionPackOptions,
   applyAuthConnection,
+  checkSolutionPathAsync,
   createSolutionPackager,
   ensurePackagerTools,
   packSolutionAsync,
   readSolutionFileAsUint8Array,
   resolveSdkLogLevel,
   validateGovernanceOptions
-} from "./packager-tool-2yz7m5ny.js";
+} from "./packager-tool-nq2nq71y.js";
 import {
   publishSolutionAsync
-} from "./packager-tool-f7kj5fpa.js";
+} from "./packager-tool-5pfxgc8z.js";
 import {
   Configuration,
   PipelinesApi,
   feedResolutionFailureInstructions,
   feedScopeInitOverride,
-  folderKeyInitOverride,
   listSelectablePublishLocations,
-  resolveFeedScope,
-  resolvePersonalWorkspace
-} from "./packager-tool-c29pg93e.js";
+  resolveFeedScope
+} from "./packager-tool-hc6ybtdw.js";
 import {
   Configuration as Configuration2,
   DeploymentActivationStatus,
   DeploymentOperationStatus,
-  DeploymentsApi,
   PackagesApi,
   SearchApi,
+  StudioWebIncompatibleProjectError,
   bundleSolution,
   getProjectDebugStatus,
   importSolution,
   isDebugProvisioningSucceeded,
   isDebugProvisioningTerminal,
+  overwriteSolution,
   searchPackageVersions,
-  solutionExistsOnStudioWeb,
-  uploadOrOverwriteSolution
-} from "./packager-tool-9w3k4e77.js";
+  solutionExistsOnStudioWeb
+} from "./packager-tool-b16qemg2.js";
 import {
   Tokens,
   applyEntryPointEnhancementAsync,
@@ -63,6 +64,7 @@ import {
   createLocalResource,
   createProjectInSolutionBuilder,
   createResourceBuilderServices,
+  createResourceKindMetadataResolver,
   findMatchingLocalResource,
   findProjectFile,
   findResourceByKeyInRcs,
@@ -76,13 +78,13 @@ import {
   syncAndLog,
   syncResourcesFromBindings,
   writeSolutionFile
-} from "./packager-tool-krd5v2r5.js";
+} from "./packager-tool-0qva0ebq.js";
 import {
   ToolResult
-} from "./packager-tool-vpr77gre.js";
+} from "./packager-tool-x3ehbhsn.js";
 import {
   getSolutionAuthContext
-} from "./packager-tool-fzwxq48d.js";
+} from "./packager-tool-3y92zbg2.js";
 import {
   DEFAULT_PAGE_SIZE,
   Option,
@@ -90,11 +92,14 @@ import {
   Pagination,
   PollOutcome,
   RESULTS,
+  carriedInstructions,
   catchError,
   createHiddenDeprecatedTenantOption,
   extractErrorDetails,
   extractErrorMessage,
+  getFileSystem,
   getLoginStatusAsync,
+  isGuid,
   isPreviewBuild,
   logger,
   mapPackageMetadataOptions,
@@ -102,7 +107,6 @@ import {
   parseLimit,
   parseOffset,
   pollUntil,
-  previewOnly,
   processContext,
   registerPackageMetadataOptions,
   requireConfirmation,
@@ -113,21 +117,20 @@ import {
   unsupportedSolutionProjectType,
   updateUipxSolutionId,
   withCompleter
-} from "./packager-tool-bcpknnr8.js";
-import {
-  getFileSystem
-} from "./packager-tool-7eva0peq.js";
+} from "./packager-tool-hgx66d1p.js";
 import {
+  strFromU8,
+  unzip,
   unzipSync
-} from "./packager-tool-129wn232.js";
+} from "./packager-tool-dfrk01gn.js";
 import {
   __require
-} from "./packager-tool-0v6na3yp.js";
+} from "./packager-tool-1de529jm.js";
 // package.json
 var package_default = {
   name: "@uipath/solution-tool",
   license: "MIT",
-  version: "1.201.0-preview.133",
+  version: "1.202.0-preview.134",
   description: "Create, pack, publish, and deploy UiPath Automation Solutions.",
   repository: {
     type: "git",
@@ -188,7 +191,6 @@ var package_default = {
     "@uipath/filesystem": "workspace:*",
     "@uipath/orchestrator-sdk": "workspace:*",
     "@uipath/packager-tool-connector": "workspace:*",
-    "@uipath/packager-tool-webapp": "workspace:*",
     "@uipath/pipelines-sdk": "workspace:*",
     "@uipath/project-executor": "workspace:*",
     "@uipath/resource-builder-sdk": "^2025.11.0-alpha4202-3459",
@@ -211,13 +213,12 @@ class CleanupCommandService {
     this.fs = getFileSystem();
   }
   async execute(solutionPath, options, context) {
-    const absoluteSolutionPath = this.fs.path.resolve(solutionPath);
-    const [statError, stats] = await catchError(this.fs.stat(absoluteSolutionPath));
-    if (statError || !stats) {
-      const msg = statError?.message ?? `Solution path does not exist: ${absoluteSolutionPath}`;
-      this.reportFailureAndExit(context, msg, "Ensure the solution path exists and points to a solution directory (containing .uipx) or a .uis file.");
+    const check = await checkSolutionPathAsync(this.fs, solutionPath);
+    if (!check.ok) {
+      this.reportFailureAndExit(context, check.message, SOLUTION_PATH_INSTRUCTIONS, check.statError, check.errorCode);
       return;
     }
+    const { absoluteSolutionPath } = check;
     logger.info(options.dryRun ? `
 Detecting unused items (dry-run)...
 ` : `
@@ -229,11 +230,11 @@ Removing unused items...
     const [error, result] = await catchError(this.executeAsync(solutionPath, options));
     if (error) {
       const msg = error instanceof Error ? error.message : String(error);
-      this.reportFailureAndExit(context, msg, "Check that the solution can be loaded, the required packager tools are available, and the current login has access to the tenant.", error);
+      this.reportFailureAndExit(context, msg, carriedInstructions(error) ?? "Check that the solution can be loaded, the required packager tools are available, and the current login has access to the tenant.", error);
       return;
     }
     if (result.errorCode !== "SUCCESS" /* Success */) {
-      this.reportFailureAndExit(context, `Error code: ${result.errorCode} : ${result.message}`, result.message ?? "");
+      this.reportFailureAndExit(context, `Error code: ${result.errorCode} : ${result.message}`, result.instructions ?? result.message ?? "");
       return;
     }
     const changedFilesByProject = result.details?.changedFilesByProject ?? {};
@@ -248,11 +249,12 @@ Removing unused items...
       }
     });
   }
-  reportFailureAndExit(context, message, instructions, error) {
+  reportFailureAndExit(context, message, instructions, error, errorCode) {
     OutputFormatter.error({
       Result: RESULTS.Failure,
       Message: message,
-      Instructions: instructions
+      Instructions: instructions,
+      ErrorCode: errorCode
     });
     if (error instanceof Error && error.stack) {
       logger.error("Stack trace:");
@@ -261,22 +263,14 @@ Removing unused items...
     context.exit(1);
   }
   async executeAsync(solutionPath, options) {
-    const absoluteSolutionPath = this.fs.path.resolve(solutionPath);
     if (options.loginValidity !== undefined && Number.isNaN(options.loginValidity)) {
       return new ToolResult("INTERNAL_ERROR" /* InternalError */, `Invalid --login-validity value: ${options.loginValidity}`, []);
     }
-    if (!await this.fs.exists(absoluteSolutionPath)) {
-      return new ToolResult("INTERNAL_ERROR" /* InternalError */, `Solution path does not exist: ${absoluteSolutionPath}`, []);
-    }
-    const [statError, stats] = await catchError(this.fs.stat(absoluteSolutionPath));
-    if (statError || !stats) {
-      return new ToolResult("INTERNAL_ERROR" /* InternalError */, statError?.message ?? `Cannot access solution path: ${absoluteSolutionPath}`, []);
-    }
-    const isDirectory = stats.isDirectory();
-    const isUisFile = stats.isFile() && absoluteSolutionPath.endsWith(".uis");
-    if (!isDirectory && !isUisFile) {
-      return new ToolResult("INTERNAL_ERROR" /* InternalError */, `Solution path must be a directory or a .uis file: ${absoluteSolutionPath}`, []);
+    const check = await checkSolutionPathAsync(this.fs, solutionPath);
+    if (!check.ok) {
+      return new ToolResult("INTERNAL_ERROR" /* InternalError */, check.message, []);
     }
+    const { absoluteSolutionPath, isUisFile } = check;
     if (isUisFile && !options.dryRun) {
       return new ToolResult("INTERNAL_ERROR" /* InternalError */, `In-place cleanup of a .uis file is not supported: changes would be written to a temporary extraction and then discarded, leaving '${absoluteSolutionPath}' unchanged. Re-run with --dry-run to only detect unused items, or point at an unpacked solution directory to modify it in place.`, []);
     }
@@ -294,7 +288,7 @@ Removing unused items...
       return packager.cleanupSolutionAsync(cleanupOptions);
     });
     if (error) {
-      return new ToolResult("INTERNAL_ERROR" /* InternalError */, error instanceof Error ? error.message : String(error), []);
+      return new ToolResult("INTERNAL_ERROR" /* InternalError */, error instanceof Error ? error.message : String(error), [], carriedInstructions(error));
     }
     return result;
   }
@@ -310,7 +304,8 @@ Removing unused items...
       skipImports: options.skipImports ?? false
     };
     cleanupOptions.logLevel = resolveSdkLogLevel();
-    cleanupOptions.excludeConfiguredSources = false;
+    cleanupOptions.nuGetSourcesConfigPath = options.nugetSourcesConfigPath;
+    cleanupOptions.excludeConfiguredSources = options.excludeConfiguredSources ?? false;
     cleanupOptions.feedFolder = options.feedFolder;
     await applyAuthConnection(cleanupOptions, options.loginValidity);
     return cleanupOptions;
@@ -357,11 +352,13 @@ var SOLUTION_CLEANUP_EXAMPLES = [
   }
 ];
 var registerCleanupCommand = (program) => {
-  program.command("cleanup").description("Remove unused items from every project in a UiPath solution. Accepts a solution directory (containing .uipx) or a .uis file. For a directory the project sources are modified in place. Pass --dry-run to only detect unused items.").argument("<solutionPath>", "Path to a solution directory (containing .uipx) or a .uis file").option("--dry-run", "Detect unused items but do not modify any project files.").option("--skip-imports", "Do not clean up now-unused references to removed items in the project's files.").option("--feed-folder <name>", "Resolve project dependencies from this Orchestrator folder's library feed instead of every tenant feed. Accepts a folder name or fully qualified path.").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", (value) => Number.parseInt(value, 10), 10).examples(SOLUTION_CLEANUP_EXAMPLES).trackedAction(processContext, async (solutionPath, options) => {
+  program.command("cleanup").description("Remove unused items from every project in a UiPath solution. Accepts a solution directory (containing .uipx) or a .uis file. For a directory the project sources are modified in place. Pass --dry-run to only detect unused items.").argument("<solutionPath>", "Path to a solution directory (containing .uipx) or a .uis file").option("--dry-run", "Detect unused items but do not modify any project files.").option("--skip-imports", "Do not clean up now-unused references to removed items in the project's files.").option("--nuget-sources-config-path <path>", "Path to NuGet sources configuration file").option("--exclude-configured-sources", "Resolve project dependencies only from the tenant feeds and any --nuget-sources-config-path. Drops the built-in UiPath and nuget.org feeds, so a dependency that is not on those feeds fails to restore.").option("--feed-folder <name>", "Resolve project dependencies from this Orchestrator folder's library feed instead of every tenant feed. Accepts a folder name or fully qualified path.").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", (value) => Number.parseInt(value, 10), 10).examples(SOLUTION_CLEANUP_EXAMPLES).trackedAction(processContext, async (solutionPath, options) => {
     const service = new CleanupCommandService;
     const cleanupOptions = {
       dryRun: options.dryRun,
       skipImports: options.skipImports,
+      nugetSourcesConfigPath: options.nugetSourcesConfigPath,
+      excludeConfiguredSources: options.excludeConfiguredSources,
       feedFolder: options.feedFolder,
       loginValidity: options.loginValidity
     };
@@ -1079,9 +1076,7 @@ var SOLUTION_DEPLOY_LIST_EXAMPLES = [
 ];
 var registerDeployListCommand = (program) => {
   const command = program.command("list").description("List solution deployments. Shows deployment name, status, package version (current/target), pending operation, and folder path. --operation-status/--activation-status filter server-side; --folder-path filters after fetching.").addOption(createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>")).option("--folder-path <path>", "Filter by parent folder path (e.g., 'Shared')").option("--folder-key <key>", "Filter by parent folder key (GUID). Alternative to --folder-path.").option("-l, --limit <number>", "Max deployments to fetch. Note: --folder-path filtering happens after fetching, so increase this value if results seem incomplete.", parseLimit, DEFAULT_PAGE_SIZE).option("--offset <number>", "Number of deployments to skip (applied before --folder-path/--folder-key filtering)", parseOffset, 0).option("--sort-by <column>", "Column to sort by (default: startTime)", "startTime").option("--sort-order <direction>", "Sort direction: Ascending or Descending (default: Descending)", "Descending").option("--operation-status <statuses>", `Filter by deployment operation status, server-side (comma-separated). One or more of: ${OPERATION_STATUS_VALUES.join(", ")}.`).option("--activation-status <statuses>", `Filter by deployment activation status, server-side (comma-separated). One or more of: ${ACTIVATION_STATUS_VALUES.join(", ")}.`).option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10);
-  if (isPreviewBuild()) {
-    command.addOption(new Option("--feed <name-or-key>", "Only list deployments from this feed (name or folder key, from 'solution feeds list'). Mutually exclusive with --personal-workspace.").conflicts("personalWorkspace")).option("--personal-workspace", "Only list deployments from the current user's Personal Workspace feed.");
-  }
+  command.addOption(new Option("--feed <name-or-key>", "Only list deployments from this feed (name or folder key, from 'solution feeds list'). Mutually exclusive with --personal-workspace.").conflicts("personalWorkspace")).option("--personal-workspace", "Only list deployments from the current user's Personal Workspace feed.");
   command.examples(SOLUTION_DEPLOY_LIST_EXAMPLES).trackedAction(processContext, async (options) => {
     const operationStatus = parseStatusFilter(options.operationStatus, OPERATION_STATUS_VALUES, "--operation-status");
     if (!operationStatus.ok) {
@@ -1236,6 +1231,38 @@ var SOLUTION_DEPLOY_RUN_EXAMPLES = [
         NextSteps: "Deployment created in your Personal Workspace and will auto-activate. Check status with: uip solution deploy list."
       }
     }
+  },
+  {
+    Description: "Deploy into the Personal Workspace and wait for the install to finish before returning",
+    Command: "uip solution deploy run --name my-deployment --package-name my-package --package-version 1.0.0 --folder-name MySolution --personal-workspace --wait",
+    Output: {
+      Code: "SolutionDeployRun",
+      Data: {
+        Status: "DeploymentSucceeded",
+        DeploymentName: "my-deployment",
+        PackageName: "my-package",
+        PackageVersion: "1.0.0",
+        FolderName: "MySolution",
+        FolderPath: "alice@uipath.com/MySolution",
+        ActivationStatus: "Auto"
+      }
+    }
+  },
+  {
+    Description: "Deploy a second, separate copy of a package that is already deployed (each copy gets its own Orchestrator folder)",
+    Command: 'uip solution deploy run --name my-deployment-2 --package-name my-package --package-version 1.0.0 --folder-name MySolutionCopy --parent-folder-path "Shared" --yes',
+    Output: {
+      Code: "SolutionDeployRun",
+      Data: {
+        Status: "DeploymentSucceeded",
+        DeploymentKey: "a1b2c3d4-0000-0000-0000-000000000002",
+        PipelineDeploymentId: "b2c3d4e5-0000-0000-0000-000000000002",
+        InstanceId: "c3d4e5f6-0000-0000-0000-000000000002",
+        FolderName: "MySolutionCopy",
+        FolderPath: "Shared/MySolutionCopy",
+        ActivationStatus: "SuccessfulActivate"
+      }
+    }
   }
 ];
 var SOLUTION_DEPLOY_RUN_FEED_EXAMPLE = {
@@ -1256,14 +1283,12 @@ var SOLUTION_DEPLOY_RUN_FEED_EXAMPLE = {
   }
 };
 var registerDeployRunCommand = (program) => {
-  const command = program.command("run").description("Deploy a solution package to Orchestrator. Creates a folder, provisions resources, and (by default) activates the solution. Pass --skip-activate to leave the deployment in 'Inactive (Ready to activate)' state and activate later with 'deploy activate'. To customize resource settings before deploying, use 'config get' to fetch the default config, 'config set' / 'config link' to edit it, then pass it here with --config-file.").requiredOption("-n, --name <deployment-name>", "Name for the deployment").addOption(withCompleter(new Option("--package-name <name>", "Solution package name to deploy. Use 'solution packages list' to find available names.").makeOptionMandatory(), packageNameCompleter)).addOption(withCompleter(new Option("--package-version <version>", "Solution package version to deploy. Use 'solution packages list' to find available versions.").makeOptionMandatory(), packageVersionCompleter)).requiredOption("--folder-name <name>", "Name for the new Orchestrator folder created for this deployment (created under --parent-folder-path if specified)").addOption(new Option("--parent-folder-path <path>", "Parent folder path (e.g., 'Shared'). Solution folder is created under this.").conflicts("parentFolderKey")).option("--parent-folder-key <key>", "Parent folder key (GUID). Alternative to --parent-folder-path.").addOption(new Option("--personal-workspace", "Deploy into the current user's Personal Workspace. Resolves the workspace name from Orchestrator automatically. Mutually exclusive with --parent-folder-path and --parent-folder-key.").conflicts(["parentFolderPath", "parentFolderKey"])).option("--config-file <path>", "JSON or YAML configuration file. Generate with: uip solution deploy config get <name> -d config.json, then customize with 'config set' or 'config link'.").addOption(createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>")).option("--timeout <seconds>", "Timeout in seconds applied per polling phase — deploy and (when not skipped) activate (default: 360 each)", (v) => parseInt(v, 10), 360).option("--poll-interval <ms>", "Milliseconds between status polls during the deploy and activate phases (default: 5000)", (v) => parseInt(v, 10), 5000).option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).option("--skip-activate", "Skip auto-activation; leave the deployment in 'Inactive (Ready to activate)' state. Activate later with 'uip solution deploy activate <name>'.");
-  if (isPreviewBuild()) {
-    command.addOption(new Option("--feed <name-or-key>", "Deploy a package from a specific feed (name or folder key, from 'solution feeds list') instead of the tenant feed. Mutually exclusive with --personal-workspace.").conflicts("personalWorkspace"));
-  }
-  command.examples(isPreviewBuild() ? [
+  const command = program.command("run").description("Deploy a solution package to Orchestrator. Creates a folder, provisions resources, and (by default) activates the solution. This always creates a NEW deployment in a NEW folder — it never updates an existing one — so if the package is already deployed the command stops and points you at the upgrade path; pass --yes to deploy a second, separate copy anyway. Pass --skip-activate to leave the deployment in 'Inactive (Ready to activate)' state and activate later with 'deploy activate'. To customize resource settings before deploying, use 'config get' to fetch the default config, 'config set' / 'config link' to edit it, then pass it here with --config-file.").requiredOption("-n, --name <deployment-name>", "Name for the deployment").addOption(withCompleter(new Option("--package-name <name>", "Solution package name to deploy. Use 'solution packages list' to find available names.").makeOptionMandatory(), packageNameCompleter)).addOption(withCompleter(new Option("--package-version <version>", "Solution package version to deploy. Use 'solution packages list' to find available versions.").makeOptionMandatory(), packageVersionCompleter)).requiredOption("--folder-name <name>", "Name for the new Orchestrator folder created for this deployment (created under --parent-folder-path if specified)").addOption(new Option("--parent-folder-path <path>", "Parent folder path (e.g., 'Shared'). Solution folder is created under this.").conflicts("parentFolderKey")).option("--parent-folder-key <key>", "Parent folder key (GUID). Alternative to --parent-folder-path.").addOption(new Option("--personal-workspace", "Deploy into the current user's Personal Workspace. Resolves the workspace name from Orchestrator automatically. Mutually exclusive with --parent-folder-path and --parent-folder-key.").conflicts(["parentFolderPath", "parentFolderKey"])).option("--config-file <path>", "JSON or YAML configuration file. Generate with: uip solution deploy config get <name> -d config.json, then customize with 'config set' or 'config link'.").addOption(createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>")).option("--timeout <seconds>", "Timeout in seconds applied per polling phase — deploy and (when not skipped) activate (default: 360 each)", (v) => parseInt(v, 10), 360).option("--poll-interval <ms>", "Milliseconds between status polls during the deploy and activate phases (default: 5000)", (v) => parseInt(v, 10), 5000).option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).option("--wait", "Wait for a --personal-workspace / --feed deploy to finish instead of returning as soon as it starts. Bounded by --timeout. The tenant path always waits, so this changes nothing there.").option("--skip-activate", "Skip auto-activation; leave the deployment in 'Inactive (Ready to activate)' state. Activate later with 'uip solution deploy activate <name>'.").option("-y, --yes", "Deploy even when this package already has a deployment. Without it, deploy run looks the package up and stops if it is already deployed. That check is best-effort, not a guarantee: it reads the Solutions search, which needs a user session, so an application (client-credentials) login deploys without it, and a lookup failure only warns.");
+  command.addOption(new Option("--feed <name-or-key>", "Deploy a package from a specific feed (name or folder key, from 'solution feeds list') instead of the tenant feed. Mutually exclusive with --personal-workspace.").conflicts("personalWorkspace"));
+  command.examples([
     ...SOLUTION_DEPLOY_RUN_EXAMPLES,
     SOLUTION_DEPLOY_RUN_FEED_EXAMPLE
-  ] : SOLUTION_DEPLOY_RUN_EXAMPLES).trackedAction(processContext, async (options) => {
+  ]).trackedAction(processContext, async (options) => {
     const result = await deployRunAsync({
       tenant: options.tenant,
       deploymentName: options.name,
@@ -1275,17 +1300,21 @@ var registerDeployRunCommand = (program) => {
       personalWorkspace: options.personalWorkspace,
       feed: options.feed,
       configFile: options.configFile,
+      wait: options.wait,
       timeout: options.timeout,
       pollInterval: options.pollInterval,
       loginValidity: options.loginValidity,
       skipActivate: options.skipActivate,
+      yes: options.yes,
       signal: processContext.pollSignal
     });
     if (!result.ok) {
       OutputFormatter.error({
         Result: RESULTS.Failure,
         Message: result.message,
-        Instructions: result.instructions
+        Instructions: result.instructions,
+        ErrorCode: result.errorCode,
+        Retry: result.retry
       });
       processContext.exit(result.exitCode);
       return;
@@ -1433,7 +1462,9 @@ var registerDeployUninstallCommand = (program) => {
       OutputFormatter.error({
         Result: RESULTS.Failure,
         Message: result.message,
-        Instructions: result.instructions
+        Instructions: result.instructions,
+        ErrorCode: result.errorCode,
+        Retry: result.retry
       });
       processContext.exit(result.exitCode);
       return;
@@ -1473,97 +1504,6 @@ var registerDeployUninstallCommand = (program) => {
   });
 };
 
-// src/services/deploy-upgrade-service.ts
-var fail = (reason, message, instructions, exitCode = 1) => ({
-  ok: false,
-  reason,
-  message,
-  instructions,
-  exitCode
-});
-var AUTH_INSTRUCTIONS = "Run 'uip login' to refresh credentials, then retry. If the deployment is in a different tenant, switch with 'uip login tenant set <tenant>'.";
-async function upgradeDeploymentAsync(deploymentKey, options = {}) {
-  const [authError, auth] = await catchError(getSolutionAuthContext({
-    tenant: options.tenant,
-    loginValidity: options.loginValidity,
-    envFilePath: options.envFilePath
-  }));
-  if (authError) {
-    return fail("auth_failed", authError.message, AUTH_INSTRUCTIONS);
-  }
-  const config = new Configuration2({
-    basePath: auth.basePath,
-    accessToken: auth.accessToken
-  });
-  const deploymentsApi = new DeploymentsApi(config);
-  const searchApi = new SearchApi(config);
-  let feedScope;
-  if (options.personalWorkspace) {
-    const [pwError, pw] = await catchError(resolvePersonalWorkspace({
-      tenant: options.tenant,
-      loginValidity: options.loginValidity
-    }));
-    if (pwError || !pw) {
-      return fail("personal_workspace_failed", pwError?.message ?? "Personal Workspace could not be resolved.", "Ensure your user has a Personal Workspace, then retry.");
-    }
-    feedScope = folderKeyInitOverride(pw.key);
-  }
-  const [getError, deployment] = await catchError(deploymentsApi.deploymentsGetByKey({ deploymentKey }, feedScope));
-  if (getError || !deployment) {
-    const detail = getError && await extractErrorDetails(getError);
-    return fail("deployment_not_found", detail ? detail.details ? `${detail.message}: ${detail.details}` : detail.message : `Deployment '${deploymentKey}' was not found.`, "Run 'uip solution deploy list' to find the deployment key. Add '--personal-workspace' if it lives in your Personal Workspace.");
-  }
-  const upgradeScope = feedScope;
-  const take = 50;
-  let pkg;
-  for (let skip = 0;; ) {
-    const [searchError, packages] = await catchError(searchApi.searchSearchPackages({
-      searchFilter: {
-        searchTerm: deployment.packageName,
-        take,
-        skip
-      }
-    }, feedScope));
-    if (searchError) {
-      const { message, details } = await extractErrorDetails(searchError);
-      return fail("package_not_found", details ? `${message}: ${details}` : message, "Confirm the package is published to the tenant (or Personal Workspace) feed.");
-    }
-    const values = packages.values ?? [];
-    pkg = values.find((p) => p.name === deployment.packageName);
-    if (pkg || values.length < take) {
-      break;
-    }
-    skip += values.length;
-  }
-  if (!pkg) {
-    return fail("package_not_found", `Package '${deployment.packageName}' was not found in the feed.`, "Confirm the package is published to the tenant (or Personal Workspace) feed.");
-  }
-  if (options.version && options.version !== pkg.latestVersion) {
-    return fail("unsupported_version", `Upgrade supports only the latest published version ('${pkg.latestVersion}'); requested '${options.version}'.`, "Publish the desired version as the latest, or omit '--version' to upgrade to the newest.");
-  }
-  const currentVersion = deployment.currentPackageVersion ?? deployment.packageVersion;
-  if (currentVersion === pkg.latestVersion) {
-    return fail("no_upgrade_available", `Deployment '${deployment.name}' is already at the latest published version (${pkg.latestVersion}).`, "Publish a newer version of the package, then retry.");
-  }
-  const [upgradeError] = await catchError(deploymentsApi.deploymentsUpgrade({
-    deploymentKey,
-    packageVersionKey: pkg.packageVersionKey,
-    deploymentUpgradeRequest: {
-      packageVersionKey: pkg.packageVersionKey
-    }
-  }, upgradeScope));
-  if (upgradeError) {
-    const { message, details } = await extractErrorDetails(upgradeError);
-    return fail("request_failed", details ? `${message}: ${details}` : message, "The upgrade could not be started. Check the deployment key and that a newer version is published.");
-  }
-  return {
-    ok: true,
-    deploymentName: deployment.name,
-    fromVersion: currentVersion,
-    toVersion: pkg.latestVersion
-  };
-}
-
 // src/commands/deploy-upgrade.ts
 var SOLUTION_DEPLOY_UPGRADE_EXAMPLES = [
   {
@@ -1572,21 +1512,39 @@ var SOLUTION_DEPLOY_UPGRADE_EXAMPLES = [
     Output: {
       Code: "SolutionDeployUpgrade",
       Data: {
-        Status: "UpgradeInitiated",
+        Status: "Successful",
+        DeploymentName: "billing-solution",
+        FromVersion: "1.0.0",
+        ToVersion: "2.0.0",
+        VersionChangeKey: "b2c3d4e5-0000-0000-0000-000000000002"
+      }
+    }
+  },
+  {
+    Description: "Start the upgrade without waiting for it to finish",
+    Command: "uip solution deploy upgrade a1b2c3d4-0000-0000-0000-000000000001 --no-wait",
+    Output: {
+      Code: "SolutionDeployUpgrade",
+      Data: {
+        Status: "Draft",
         DeploymentName: "billing-solution",
         FromVersion: "1.0.0",
-        ToVersion: "2.0.0"
+        ToVersion: "2.0.0",
+        VersionChangeKey: "b2c3d4e5-0000-0000-0000-000000000002"
       }
     }
   }
 ];
 var registerDeployUpgradeCommand = (program) => {
-  program.command("upgrade").description("Upgrade an existing deployment to a newer package version in place — the CLI equivalent of the Orchestrator UI 'Upgrade' button. Use this when 'deploy run' is blocked because a deployment already exists. Initiates the upgrade; track it with 'deploy list'.").argument("<deployment-key>", "Key of the deployment to upgrade. Use 'solution deploy list' to find it.").addOption(createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>")).option("--version <version>", "Target package version (default: the newest available). Only the latest published version is supported today.").option("--personal-workspace", "Upgrade a deployment in your Personal Workspace feed instead of the tenant.").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).examples(SOLUTION_DEPLOY_UPGRADE_EXAMPLES).trackedAction(processContext, async (deploymentKey, options) => {
+  program.command("upgrade").description("Upgrade an existing deployment to a newer package version in place — the CLI equivalent of the Orchestrator UI 'Upgrade' button. Use this when 'deploy run' is blocked because a deployment already exists. The deployment's existing configuration is preserved, so values already set on it (for example a credential asset's secret) are not reset to the package defaults. Waits for the upgrade to finish unless --no-wait is passed.").argument("<deployment-key>", "Key of the deployment to upgrade. Use 'solution deploy list' to find it.").addOption(createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>")).option("--version <version>", "Target package version (default: the newest available). Only the latest published version is supported today.").option("--personal-workspace", "Upgrade a deployment in your Personal Workspace feed instead of the tenant.").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).option("--no-wait", "Return as soon as the upgrade is accepted instead of waiting for it to finish.").option("--timeout <seconds>", "Seconds to wait for the upgrade to finish (default: 300)", (v) => parseInt(v, 10), 300).option("--poll-interval <ms>", "Milliseconds between status polls (default: 5000)", (v) => parseInt(v, 10), 5000).examples(SOLUTION_DEPLOY_UPGRADE_EXAMPLES).trackedAction(processContext, async (deploymentKey, options) => {
     const result = await upgradeDeploymentAsync(deploymentKey, {
       tenant: options.tenant,
       version: options.version,
       personalWorkspace: options.personalWorkspace,
-      loginValidity: options.loginValidity
+      loginValidity: options.loginValidity,
+      noWait: options.wait === false,
+      timeout: options.timeout,
+      pollInterval: options.pollInterval
     });
     if (!result.ok) {
       OutputFormatter.error({
@@ -1601,10 +1559,11 @@ var registerDeployUpgradeCommand = (program) => {
       Result: RESULTS.Success,
       Code: "SolutionDeployUpgrade",
       Data: {
-        Status: "UpgradeInitiated",
+        Status: result.status,
         DeploymentName: result.deploymentName,
         FromVersion: result.fromVersion,
-        ToVersion: result.toVersion
+        ToVersion: result.toVersion,
+        VersionChangeKey: result.versionChangeKey
       }
     });
   });
@@ -1619,9 +1578,57 @@ var registerDeployCommand = (program) => {
   registerDeployActivateCommand(deploy);
   registerDeployUninstallCommand(deploy);
   registerDeployListCommand(deploy);
-  previewOnly(() => registerDeployUpgradeCommand(deploy));
+  registerDeployUpgradeCommand(deploy);
 };
 
+// src/services/agents-briefing.ts
+import { fileURLToPath } from "node:url";
+var BRIEFING_FILENAMES = ["AGENTS.md", "CLAUDE.md"];
+var CLI_VERSION_PLACEHOLDER = "{{cli_version}}";
+function agentsTemplateCandidateUrls() {
+  return [
+    new URL("./templates/AGENTS.md", import.meta.url),
+    new URL("../../templates/AGENTS.md", import.meta.url)
+  ];
+}
+async function renderBriefingTemplateAsync() {
+  const fs = getFileSystem();
+  const candidateUrls = agentsTemplateCandidateUrls();
+  let templateContent;
+  for (const candidateUrl of candidateUrls) {
+    const candidatePath = fileURLToPath(candidateUrl);
+    const [, content] = await catchError(fs.readFile(candidatePath, "utf-8"));
+    if (content !== undefined && content !== null) {
+      templateContent = content;
+      break;
+    }
+  }
+  if (templateContent === undefined) {
+    throw new Error(`AGENTS.md template asset not found in package. Tried: ${candidateUrls.map((u) => fileURLToPath(u)).join(", ")}`);
+  }
+  return templateContent.replaceAll(CLI_VERSION_PLACEHOLDER, package_default.version);
+}
+async function writeMissingBriefingFilesAsync(solutionDir) {
+  const fs = getFileSystem();
+  const targets = BRIEFING_FILENAMES.map((name) => fs.path.join(solutionDir, name));
+  const presence = await Promise.all(targets.map((path) => fs.exists(path)));
+  const missing = targets.filter((_, index) => !presence[index]);
+  if (missing.length === 0) {
+    return [];
+  }
+  const content = await renderBriefingTemplateAsync();
+  const written = [];
+  for (const path of missing) {
+    const [error] = await catchError(fs.writeFile(path, content));
+    if (error) {
+      logger.warn(`Could not write ${path}: ${error.message}`);
+      continue;
+    }
+    written.push(path);
+  }
+  return written;
+}
+
 // src/services/archive-extract.ts
 function resolveZipEntryPath(fs, destinationDir, entryName) {
   if (entryName.includes("\x00")) {
@@ -1660,6 +1667,36 @@ async function extractArchive(archivePath, destinationDir) {
   }
   await extractZipDataToDir(fs, data, destinationDir);
 }
+var SOLUTION_STORAGE_ENTRY = "SolutionStorage.json";
+function isRootUipxEntry(name) {
+  return !name.includes("/") && name.endsWith(".uipx");
+}
+function readSolutionIdField(bytes) {
+  if (!bytes) {
+    return;
+  }
+  const [parseError, parsed] = catchError(() => JSON.parse(strFromU8(bytes)));
+  if (parseError || !parsed) {
+    return;
+  }
+  const id = parsed.SolutionId;
+  return typeof id === "string" && isGuid(id) ? id : undefined;
+}
+function readBundledSolutionId(archive) {
+  const [unzipError, entries] = catchError(() => unzipSync(archive, {
+    filter: (file) => file.name === SOLUTION_STORAGE_ENTRY || isRootUipxEntry(file.name)
+  }));
+  if (unzipError || !entries) {
+    logger.debug(`Could not inspect the solution archive for its SolutionId: ${unzipError?.message ?? "no entries"}`);
+    return;
+  }
+  const rootUipxName = Object.keys(entries).find(isRootUipxEntry);
+  const solutionId = readSolutionIdField(entries[SOLUTION_STORAGE_ENTRY]) ?? readSolutionIdField(rootUipxName ? entries[rootUipxName] : undefined);
+  if (!solutionId) {
+    logger.debug("No SolutionId found in the solution archive.");
+  }
+  return solutionId;
+}
 
 // src/commands/download.ts
 var SOLUTION_DOWNLOAD_EXAMPLES = [
@@ -1672,13 +1709,17 @@ var SOLUTION_DOWNLOAD_EXAMPLES = [
         Status: "Solution exported successfully",
         SolutionId: "a1b2c3d4-0000-0000-0000-000000000001",
         Output: "./downloads/a1b2c3d4-0000-0000-0000-000000000001.uis",
-        ExtractedTo: "./downloads/a1b2c3d4-0000-0000-0000-000000000001"
+        ExtractedTo: "./downloads/a1b2c3d4-0000-0000-0000-000000000001",
+        BriefingFiles: [
+          "./downloads/a1b2c3d4-0000-0000-0000-000000000001/AGENTS.md",
+          "./downloads/a1b2c3d4-0000-0000-0000-000000000001/CLAUDE.md"
+        ]
       }
     }
   }
 ];
 function registerDownloadCommand(program) {
-  const download = program.command("download").description("Download/export a solution from Studio Web").argument("<solution-id>", "Solution UUID to export").option("-d, --destination <dir>", "Destination directory for the downloaded file", ".").option("-n, --name <name>", "Output filename (without extension). Existing files are overwritten; --extract uses this name for the directory").option("--extract", "Extract the downloaded .uis zip into a directory", false).examples(SOLUTION_DOWNLOAD_EXAMPLES);
+  const download = program.command("download").description("Download/export a solution from Studio Web").argument("<solution-id>", "Solution UUID to export").option("-d, --destination <dir>", "Destination directory for the downloaded file", ".").option("-n, --name <name>", "Output filename (without extension). Existing files are overwritten; --extract uses this name for the directory").option("--extract", "Extract the downloaded .uis zip into a directory, and add AGENTS.md / CLAUDE.md there if the archive did not already carry them", false).examples(SOLUTION_DOWNLOAD_EXAMPLES);
   useStudioWebAuth(download, { requireOrganizationId: true }).trackedAction(processContext, async (solutionId, options, command) => {
     const [error] = await catchError(downloadSolution(solutionId, options, command));
     if (error) {
@@ -1714,9 +1755,11 @@ async function downloadSolution(solutionId, options, command) {
   await fs.writeFile(outputPath, new Uint8Array(arrayBuffer));
   logger.info(`Downloaded solution to ${outputPath}`);
   const extractedTo = options.extract ? fs.path.join(outputDir, filename.replace(/\.uis$/, "")) : undefined;
+  let briefingFiles = [];
   if (extractedTo) {
     await extractArchive(outputPath, extractedTo);
     logger.info(`Extracted to ${extractedTo}`);
+    briefingFiles = await writeBriefingFiles(extractedTo);
   }
   OutputFormatter.success({
     Result: RESULTS.Success,
@@ -1725,10 +1768,22 @@ async function downloadSolution(solutionId, options, command) {
       Status: "Solution exported successfully",
       SolutionId: solutionId,
       Output: outputPath,
-      ...extractedTo ? { ExtractedTo: extractedTo } : {}
+      ...extractedTo ? { ExtractedTo: extractedTo } : {},
+      ...briefingFiles.length > 0 ? { BriefingFiles: briefingFiles } : {}
     }
   });
 }
+async function writeBriefingFiles(solutionDir) {
+  const [error, written] = await catchError(writeMissingBriefingFilesAsync(solutionDir));
+  if (error) {
+    logger.warn(`Extracted the solution but could not write its AGENTS.md / CLAUDE.md: ${error.message}`);
+    return [];
+  }
+  for (const path of written) {
+    logger.info(`Wrote agent instructions to ${path}`);
+  }
+  return written;
+}
 function getOutputFilename(name) {
   validatePlainFilename(name);
   return name.endsWith(".uis") ? name : `${name}.uis`;
@@ -1803,18 +1858,10 @@ var registerFeedsCommand = (program) => {
 };
 
 // src/commands/new.ts
-import { fileURLToPath } from "node:url";
 var SOLUTION_INIT_STAGE_MESSAGES = {
   directory: "Failed to create solution directory",
   briefing: "Failed to write AI-agent instruction files"
 };
-var CLI_VERSION_PLACEHOLDER = "{{cli_version}}";
-function agentsTemplateCandidateUrls() {
-  return [
-    new URL("./templates/AGENTS.md", import.meta.url),
-    new URL("../../templates/AGENTS.md", import.meta.url)
-  ];
-}
 var SOLUTION_NEW_EXAMPLES = [
   {
     Description: "Initialize a new empty UiPath solution",
@@ -1829,26 +1876,9 @@ var SOLUTION_NEW_EXAMPLES = [
     }
   }
 ];
-async function renderBriefingTemplate() {
-  const fs = getFileSystem();
-  const candidateUrls = agentsTemplateCandidateUrls();
-  let templateContent;
-  for (const candidateUrl of candidateUrls) {
-    const candidatePath = fileURLToPath(candidateUrl);
-    const [, content] = await catchError(fs.readFile(candidatePath, "utf-8"));
-    if (content !== undefined && content !== null) {
-      templateContent = content;
-      break;
-    }
-  }
-  if (templateContent === undefined) {
-    throw new Error(`AGENTS.md template asset not found in package. Tried: ${candidateUrls.map((u) => fileURLToPath(u)).join(", ")}`);
-  }
-  return templateContent.replaceAll(CLI_VERSION_PLACEHOLDER, package_default.version);
-}
 var registerNewCommand = (program) => {
   program.command("init").description("Initialize a new empty UiPath solution. Creates a directory named after the solution containing a .uipx manifest file with an empty Projects array, plus AGENTS.md and CLAUDE.md briefing files that orient AI coding agents to the solution. Use 'solution projects add' to add projects afterward.").argument("<solutionName>", "Solution name or path. Creates a directory with this name containing a .uipx manifest file.").examples(SOLUTION_NEW_EXAMPLES).trackedAction(processContext, async (solutionName) => {
-    const [briefingError, briefingContent] = await catchError(renderBriefingTemplate());
+    const [briefingError, briefingContent] = await catchError(renderBriefingTemplateAsync());
     if (briefingError) {
       OutputFormatter.error({
         Result: RESULTS.Failure,
@@ -1963,7 +1993,7 @@ var SOLUTION_PACK_EXAMPLES = [
   }
 ];
 var registerPackCommand = (program) => {
-  const command = program.command("pack").description("Pack a UiPath solution into a deployable .zip package. Accepts a solution directory (containing .uipx) or a .uis file. Output is used with 'solution publish' to upload to UiPath. Pass --dry-run to check that the solution packs without producing a package.").argument("<solutionPath>", "Path to a solution directory (containing .uipx) or a .uis file").argument("[output-path]", "Output directory where the packed solution will be saved. Required unless --dry-run is set.").option("-n, --name <name>", "Package name (default: solution folder name or .uis file name)").option("-v, --version <version>", "Package version (default: 1.0.0)", "1.0.0").option("--nuget-sources-config-path <path>", "Path to NuGet sources configuration file").option("--feed-folder <name>", "Resolve project dependencies from this Orchestrator folder's library feed instead of every tenant feed. Accepts a folder name or fully qualified path.").option("--signing-certificate-path <path>", "Path to .pfx certificate file used to sign each packed project .nupkg").option("--signing-certificate-password <password>", "Certificate password. Use env.ENV_NAME to read from an environment variable.").option("--signing-timestamp-server <url>", "Timestamp server URL").option("--skip-analyze", "Skip the workflow analyzer for every RPA project in the solution. Compilation and validation still run.").addOption(new Option("--governance-file-path <path>", "Analyze every RPA project against this local governance policy file, instead of the analyzer rules shipped with the WorkflowCompiler.").conflicts("automationOpsProfile")).addOption(new Option("--automation-ops-profile <profile>", "Analyze every RPA project against the governance policy published in AutomationOps for the signed-in tenant. The value is the product whose policy is downloaded, e.g. StudioWeb, Development, Business. Mutually exclusive with --governance-file-path.").conflicts("governanceFilePath"));
+  const command = program.command("pack").description("Pack a UiPath solution into a deployable .zip package. Accepts a solution directory (containing .uipx) or a .uis file. Output is used with 'solution publish' to upload to UiPath. Pass --dry-run to check that the solution packs without producing a package.").argument("<solutionPath>", "Path to a solution directory (containing .uipx) or a .uis file").argument("[output-path]", "Output directory where the packed solution will be saved. Required unless --dry-run is set.").option("-n, --name <name>", "Package name (default: solution folder name or .uis file name)").option("-v, --version <version>", "Package version (default: 1.0.0)", "1.0.0").option("--nuget-sources-config-path <path>", "Path to NuGet sources configuration file").option("--exclude-configured-sources", "Resolve project dependencies only from the tenant feeds and any --nuget-sources-config-path. Drops the built-in UiPath and nuget.org feeds, so a dependency that is not on those feeds fails to restore.").option("--feed-folder <name>", "Resolve project dependencies from this Orchestrator folder's library feed instead of every tenant feed. Accepts a folder name or fully qualified path.").option("--signing-certificate-path <path>", "Path to .pfx certificate file used to sign each packed project .nupkg").option("--signing-certificate-password <password>", "Certificate password. Use env.ENV_NAME to read from an environment variable.").option("--signing-timestamp-server <url>", "Timestamp server URL").option("--skip-analyze", "Skip the workflow analyzer for every RPA project in the solution. Compilation and validation still run.").addOption(new Option("--governance-file-path <path>", "Analyze every RPA project against this local governance policy file, instead of the analyzer rules shipped with the WorkflowCompiler.").conflicts("automationOpsProfile")).addOption(new Option("--automation-ops-profile <profile>", "Analyze every RPA project against the governance policy published in AutomationOps for the signed-in tenant. The value is the product whose policy is downloaded, e.g. StudioWeb, Development, Business. Mutually exclusive with --governance-file-path.").conflicts("governanceFilePath"));
   registerPackageMetadataOptions(command).option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).option("--dry-run", "Run the full pack pipeline against a temporary directory and discard the output. Catches pack-time failures; does not inspect the produced package contents.").examples(SOLUTION_PACK_EXAMPLES).trackedAction(processContext, async (solutionPath, outputPath, options) => {
     if (!options.dryRun && outputPath === undefined) {
       OutputFormatter.error({
@@ -1995,6 +2025,7 @@ var registerPackCommand = (program) => {
       loginValidity: options.loginValidity,
       dryRun: options.dryRun,
       nugetSourcesConfigPath: options.nugetSourcesConfigPath,
+      excludeConfiguredSources: options.excludeConfiguredSources,
       feedFolder: options.feedFolder,
       signingCertificatePath: options.signingCertificatePath,
       signingCertificatePassword: resolveEnvReference(options.signingCertificatePassword),
@@ -2040,10 +2071,7 @@ function packageDeleteFailureInstructions(scope, packageName) {
   if (scope.kind === "folder") {
     return `List packages in that feed with: uip solution packages list --feed <name-or-key> --name ${packageName}.`;
   }
-  if (isPreviewBuild()) {
-    return `${base} If the package was published to a Personal Workspace or folder feed, add --personal-workspace or --feed.`;
-  }
-  return `${base} If the package was published to a Personal Workspace, add --personal-workspace.`;
+  return `${base} If the package was published to a Personal Workspace or folder feed, add --personal-workspace or --feed.`;
 }
 async function resolvePackageVersionKey(auth, scope, packageName, packageVersion) {
   const config = new Configuration2({
@@ -2112,9 +2140,7 @@ async function deleteScopedPackageVersion(auth, scope, packageName, packageVersi
 }
 var registerPackagesDeleteCommand = (program) => {
   const command = program.command("delete").description("Delete a specific version of a solution package. " + "Use 'solution packages list' to find available package names and versions.").argument("<package-name>", "The name of the package").argument("<package-version>", "The version to delete (e.g. 1.0.0)").addOption(createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>")).option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).option("-y, --yes", "Confirm this irreversible operation (required; the CLI never prompts)").option("--personal-workspace", "Delete the package version from the current user's Personal Workspace feed.");
-  if (isPreviewBuild()) {
-    command.addOption(new Option("--feed <name-or-key>", "Delete the package version from this feed (name or folder key, from 'solution feeds list'). Mutually exclusive with --personal-workspace.").conflicts("personalWorkspace"));
-  }
+  command.addOption(new Option("--feed <name-or-key>", "Delete the package version from this feed (name or folder key, from 'solution feeds list'). Mutually exclusive with --personal-workspace.").conflicts("personalWorkspace"));
   command.examples(SOLUTION_PACKAGES_DELETE_EXAMPLES).trackedAction(processContext, async (packageName, packageVersion, options) => {
     if (!requireConfirmation(options, `delete package '${packageName}@${packageVersion}'`)) {
       return;
@@ -2376,9 +2402,7 @@ var SOLUTION_PACKAGES_LIST_EXAMPLES = [
 ];
 var registerPackagesListCommand = (program) => {
   const command = program.command("list").description("List solution packages published to UiPath. Returns package name, version, and publish date. Use the package name and version from this output when running 'solution deploy run'.").addOption(createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>")).option("-l, --limit <number>", "Number of packages to return", parseLimit, DEFAULT_PAGE_SIZE).option("--offset <number>", "Number of packages to skip", parseOffset, 0).option("--sort-by <column>", "Column to sort by (default: publishDate)", "publishDate").option("--sort-order <direction>", "Sort direction: Ascending or Descending (default: Descending)", "Descending").option("--name <pattern>", "Filter packages by name (server-side substring match)").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).option("--personal-workspace", "Only list packages in the current user's Personal Workspace feed.");
-  if (isPreviewBuild()) {
-    command.addOption(new Option("--feed <name-or-key>", "Only list packages in this feed (name or folder key, from 'solution feeds list'). Mutually exclusive with --personal-workspace.").conflicts("personalWorkspace"));
-  }
+  command.addOption(new Option("--feed <name-or-key>", "Only list packages in this feed (name or folder key, from 'solution feeds list'). Mutually exclusive with --personal-workspace.").conflicts("personalWorkspace"));
   command.examples(SOLUTION_PACKAGES_LIST_EXAMPLES).trackedAction(processContext, async (options) => {
     const result = await listPackagesAsync({
       tenant: options.tenant,
@@ -3022,6 +3046,14 @@ var registerProjectPublishCommand = (project) => {
       processContext.exit(1);
       return;
     }
+    trackShipSucceeded({
+      ship_kind: "publish",
+      target: "solution_package_feed",
+      project_type: "solution_project",
+      command_name: "uip.solution.projects.publish",
+      package_name: options.packageName,
+      package_version: options.packageVersion
+    });
     OutputFormatter.success({
       Result: RESULTS.Success,
       Code: "SolutionProjectPublish",
@@ -3396,22 +3428,46 @@ function readProjectTypesFromUipx(content) {
     return typeof project.Type === "string" ? project.Type : undefined;
   }).filter((projectType) => projectType !== undefined);
 }
+var MAX_INSPECTABLE_PACKAGE_BYTES = 256 * 1024 * 1024;
+function isProjectManifestEntry(name) {
+  return name.endsWith(".uipx");
+}
+function unzipProjectManifests(archive) {
+  return new Promise((resolve, reject) => {
+    unzip(archive, { filter: (file) => isProjectManifestEntry(file.name) }, (error, entries) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve(entries);
+    });
+  });
+}
 async function inspectSolutionPackageProjectTypes(packagePath) {
   const fs = getFileSystem();
+  const [statError, stats] = await catchError(fs.stat(packagePath));
+  if (statError || !stats) {
+    logger.debug(`[uip.ship.succeeded] Could not stat solution package for project type telemetry: ${statError?.message ?? "no stats"}`);
+    return { projectType: "unknown" };
+  }
+  if (stats.size > MAX_INSPECTABLE_PACKAGE_BYTES) {
+    logger.debug(`[uip.ship.succeeded] Solution package is ${stats.size} bytes, over the ${MAX_INSPECTABLE_PACKAGE_BYTES}-byte inspection cap; skipping project type telemetry.`);
+    return { projectType: "unknown" };
+  }
   const [readError, archive] = await catchError(fs.readFile(packagePath));
   if (readError || !archive) {
     logger.debug(`[uip.ship.succeeded] Could not read solution package for project type telemetry: ${readError?.message ?? "empty archive"}`);
     return { projectType: "unknown" };
   }
-  const [unzipError, entries] = await catchError(Promise.resolve().then(() => unzipSync(new Uint8Array(archive))));
-  if (unzipError) {
-    logger.debug(`[uip.ship.succeeded] Could not inspect solution package zip: ${unzipError.message}`);
+  const [unzipError, entries] = await catchError(unzipProjectManifests(new Uint8Array(archive)));
+  if (unzipError || !entries) {
+    logger.debug(`[uip.ship.succeeded] Could not inspect solution package zip: ${unzipError?.message ?? "no entries"}`);
     return { projectType: "unknown" };
   }
   const decoder = new TextDecoder;
   const projectTypes = [];
   for (const [entryName, entryBytes] of Object.entries(entries)) {
-    if (!entryName.endsWith(".uipx")) {
+    if (!isProjectManifestEntry(entryName)) {
       continue;
     }
     const [parseError, parsedTypes] = await catchError(Promise.resolve().then(() => readProjectTypesFromUipx(decoder.decode(entryBytes))));
@@ -3500,6 +3556,7 @@ var NOT_A_ZIP_INSTRUCTIONS = "Ensure file is a valid .zip solution package from:
 var UPLOAD_GENERIC_INSTRUCTIONS = "The upload did not complete. Check the error message; if it persists, retry with UIP_LOG_LEVEL=debug and report the output.";
 var UPLOAD_REJECTED_INSTRUCTIONS = "The solution feed rejected the package contents; re-packing the same source will reproduce it. Fix the project named in the error detail, or report the error code with your package name.";
 var NOT_PACKED_INSTRUCTIONS = "Pack the solution into a .zip first with 'uip solution pack <solution-path> <output-path>', then publish that .zip.";
+var PROJECT_PACKAGE_INSTRUCTIONS = "A .nupkg is a single project's package (e.g. from 'uip maestro flow pack') and the solution feed does not accept it. Pack the enclosing solution instead: 'uip solution pack <solution-path> <output-dir>', then publish the .zip it writes.";
 var suggestedPackOutput = (src) => `${src.replace(/\.(uis|uipx)$/i, "").replace(/[\\/]+$/, "")}.zip`;
 var POLL_PENDING_INSTRUCTIONS = "Package may still be pending. Check package state with: uip solution packages list.";
 var PUBLISH_INSTRUCTIONS = {
@@ -3507,6 +3564,7 @@ var PUBLISH_INSTRUCTIONS = {
   file_not_found: "Ensure the file path is correct. Build a package first with: uip solution pack",
   not_a_zip: NOT_A_ZIP_INSTRUCTIONS,
   not_packed: NOT_PACKED_INSTRUCTIONS,
+  project_package: PROJECT_PACKAGE_INSTRUCTIONS,
   file_read_failed: "",
   metadata_rewrite_failed: METADATA_REWRITE_INSTRUCTIONS,
   personal_workspace_resolution_failed: "Verify the current user has a Personal Workspace configured in Orchestrator, then retry. To publish to the tenant feed instead, omit --personal-workspace.",
@@ -3525,10 +3583,8 @@ var EXIT_CODES_BY_REASON = {
 };
 var registerPublishCommand = (program) => {
   const command = program.command("publish").description("Publish a solution package (.zip) to the UiPath solution feed. The .zip must be produced by 'solution pack'. By default the package lands in the tenant feed; use --personal-workspace to target the current user's Personal Workspace feed. After publishing, use 'solution deploy run' to deploy it.").addOption(createHiddenDeprecatedTenantOption("-t, --tenant <tenant-name>")).argument("<packagePath>", "Path to a .zip package file produced by 'solution pack'.").option("--personal-workspace", "Upload the package into the current user's Personal Workspace feed instead of the tenant feed. Resolves the workspace folder key from Orchestrator automatically.").option("--package-name <name>", "Publish under this package name instead of the one the .zip was packed with. Rewrites the archive's solutionMetadata.json in memory (with a fresh package version key); the file on disk is left untouched. The bundled project packages keep their own names and versions.").option("--package-version <version>", "Publish under this package version instead of the one the .zip was packed with. Use it to clear a 'version already exists' rejection when you have the packed .zip but not the solution source. Same in-memory rewrite as --package-name.").option("--wait", "Wait until the published package is Ready or Active").option("--timeout <seconds>", "Timeout in seconds for package state polling (default: 360)", (v) => parseInt(v, 10), 360).option("--poll-interval <ms>", "Milliseconds between package state polls (default: 5000)", (v) => parseInt(v, 10), 5000).option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10);
-  if (isPreviewBuild()) {
-    command.addOption(new Option("--feed <name-or-key>", "Publish into a feed by its name or folder key (from 'solution feeds list') instead of the tenant feed. Mutually exclusive with --personal-workspace.").conflicts("personalWorkspace"));
-  }
-  command.examples(isPreviewBuild() ? [...SOLUTION_PUBLISH_EXAMPLES, SOLUTION_PUBLISH_FEED_EXAMPLE] : SOLUTION_PUBLISH_EXAMPLES).trackedAction(processContext, async (packagePath, options) => {
+  command.addOption(new Option("--feed <name-or-key>", "Publish into a feed by its name or folder key (from 'solution feeds list') instead of the tenant feed. Mutually exclusive with --personal-workspace.").conflicts("personalWorkspace"));
+  command.examples([...SOLUTION_PUBLISH_EXAMPLES, SOLUTION_PUBLISH_FEED_EXAMPLE]).trackedAction(processContext, async (packagePath, options) => {
     const result = await publishSolutionAsync(packagePath, {
       tenant: options.tenant,
       personalWorkspace: options.personalWorkspace,
@@ -4193,6 +4249,21 @@ var RESOURCE_GET_EXAMPLES = [
       }
     }
   },
+  {
+    Description: "When the linked live resource has drifted from the local declaration (matchingOverwriteConfiguration: false), the live spec is returned as liveSpec next to the declared spec",
+    Command: "uip solution resources get 0f8a1c9e-2b47-4d0a-9c31-5e2f6d8a7b10",
+    Output: {
+      Code: "ResourceConfiguration",
+      Data: {
+        key: "0f8a1c9e-2b47-4d0a-9c31-5e2f6d8a7b10",
+        spec: { name: "Approval App", version: "7.0.0" },
+        liveSpec: { name: "Approval App", version: "12.0.0" },
+        resourceOverwrite: {
+          matchingOverwriteConfiguration: false
+        }
+      }
+    }
+  },
   {
     Description: "Get the configuration plus all dependency configurations",
     Command: "uip solution resources get fb39bc38-255e-4fea-93c6-7c7eb44d766f --solution-folder ./my-solution --include-dependencies",
@@ -4278,7 +4349,10 @@ var registerResourceGetCommand = (resource) => {
     const includeDeps = options.includeDependencies === true;
     const [fetchError, data] = await catchError(includeDeps ? builder.getAllConfigurationsAsync(resourceKey) : builder.getConfigurationAsync(resourceKey));
     if (!fetchError) {
-      await refreshArtefactSpecAsync(builder, data, includeDeps);
+      const resource2 = await refreshArtefactSpecAsync(builder, data, includeDeps);
+      if (!includeDeps) {
+        await attachLiveSpecOnMismatchAsync(services, resource2, data);
+      }
       await builder.disposeAsync();
       OutputFormatter.success({
         Result: RESULTS.Success,
@@ -4352,22 +4426,40 @@ function mapDefinitionToConfiguration(def) {
     isOverridable: def.isOverridable
   };
 }
+async function attachLiveSpecOnMismatchAsync(services, resource, config) {
+  const overwriteData = config.resourceOverwrite;
+  const overwrite = overwriteData?.resourceOverwrite?.overwrite;
+  if (overwriteData?.matchingOverwriteConfiguration !== false || !overwrite || !resource) {
+    return;
+  }
+  const importer = services.container.resolve(Tokens.IImportResourceHelper);
+  const [exportError, exported] = await catchError(importer.exportResourceOverwriteAsync(resource, overwrite));
+  if (exportError || !exported?.spec) {
+    return;
+  }
+  config.liveSpec = exported.spec;
+}
 async function refreshArtefactSpecAsync(builder, data, includeDeps) {
   const [loadError, solution] = await catchError(builder.context.loadAsync());
   if (loadError || !solution) {
     return;
   }
+  let requestedResource;
   const configs = includeDeps ? data.resources ?? [] : [data];
   for (const config of configs) {
     if (!config?.key) {
       continue;
     }
     const resource = solution.resources.find((r) => r.key === config.key);
+    if (!includeDeps) {
+      requestedResource = resource;
+    }
     if (!resource?.projectKey) {
       continue;
     }
     config.spec = await applyEntryPointEnhancementAsync(builder.context, resource, config.spec ?? {});
   }
+  return requestedResource;
 }
 async function findRemoteReferenceByKey(services, resourceKey) {
   const rcs = services.container.resolve(Tokens.IResourceCatalogClientProxy);
@@ -4396,9 +4488,130 @@ async function findRemoteReferenceByKey(services, resourceKey) {
   return null;
 }
 
+// src/services/resource-version-lookup.ts
+var VERSION_PROPERTY = "version";
+var LOOKUP_CONCURRENCY = 5;
+async function resolveResourceVersionsAsync(services, builder, targets) {
+  const versions = new Map;
+  if (targets.length === 0) {
+    return versions;
+  }
+  const resolveKind = await createResourceKindMetadataResolver(services);
+  const versioned = [];
+  for (const target of targets) {
+    const metadata = await resolveKind(target.kind, target.type);
+    if (metadata?.specProperties.has(VERSION_PROPERTY)) {
+      versioned.push(target);
+    }
+  }
+  if (versioned.length === 0) {
+    return versions;
+  }
+  const importer = services.container.resolve(Tokens.IImportResourceHelper);
+  for (let i = 0;i < versioned.length; i += LOOKUP_CONCURRENCY) {
+    const batch = versioned.slice(i, i + LOOKUP_CONCURRENCY);
+    const resolved = await Promise.all(batch.map((target) => target.source === "Local" ? readLocalVersionAsync(builder, target) : readRemoteVersionAsync(importer, target)));
+    for (const [id, version] of resolved) {
+      if (version !== undefined) {
+        versions.set(id, version);
+      }
+    }
+  }
+  return versions;
+}
+async function readLocalVersionAsync(builder, target) {
+  const [error, configuration] = await catchError(builder.getConfigurationAsync(target.key));
+  if (error || !configuration) {
+    warnLookupFailed(target, error);
+    return [target.id, undefined];
+  }
+  return [target.id, readVersion(configuration.spec)];
+}
+async function readRemoteVersionAsync(importer, target) {
+  const reference = {
+    kind: target.kind,
+    type: target.type,
+    key: target.key,
+    name: target.name,
+    folder: target.folderFullyQualifiedName ? {
+      fullyQualifiedName: target.folderFullyQualifiedName,
+      folderKey: target.folderKey
+    } : undefined
+  };
+  const [error, payload] = await catchError(importer.exportResourceAsync(reference));
+  if (error || !payload) {
+    warnLookupFailed(target, error);
+    return [target.id, undefined];
+  }
+  const definitions = payload.resourceDefinitions ?? [];
+  const primary = definitions.find((d) => d.key === target.key);
+  if (!primary) {
+    logger.warn(`Export for ${target.kind} '${target.name ?? target.key}' returned no definition for that key; version omitted.`);
+    return [target.id, undefined];
+  }
+  return [target.id, readVersion(primary.spec)];
+}
+function readVersion(spec) {
+  if (!spec) {
+    return;
+  }
+  let value = spec[VERSION_PROPERTY];
+  if (value === undefined) {
+    for (const [key, candidate] of Object.entries(spec)) {
+      if (key.toLowerCase() === VERSION_PROPERTY) {
+        value = candidate;
+        break;
+      }
+    }
+  }
+  if (value === undefined || value === null || value === "") {
+    return;
+  }
+  return typeof value === "string" ? value : String(value);
+}
+function warnLookupFailed(target, error) {
+  logger.warn(`Failed to read the version of ${target.kind} '${target.name ?? target.key}': ${error?.message ?? "no configuration returned"}`);
+}
+
 // src/commands/resource-list.ts
+var RESOURCE_LIST_EXAMPLES = [
+  {
+    Description: "List every resource the solution holds and every one available in Orchestrator",
+    Command: "uip solution resources list",
+    Output: {
+      Code: "ResourceList",
+      Data: [
+        {
+          Source: "Remote",
+          Key: "0c2b7f04-1d3e-4a55-9f77-2b1a6d9e4c81",
+          Name: "InvoiceQueue",
+          Kind: "queue",
+          Folder: "Shared"
+        }
+      ]
+    }
+  },
+  {
+    Description: "Show the version deployed per folder for classic Apps. --include-version reads the live `version` spec property, which is what Orchestrator's Automations > Apps page shows; it costs one extra call per resource, so it is off by default",
+    Command: "uip solution resources list --kind app --source remote --include-version",
+    Output: {
+      Code: "ResourceList",
+      Data: [
+        {
+          Source: "Remote",
+          Key: "a9c9d05f-6d85-41cd-8a54-a479d494bedc",
+          Name: "Validation App",
+          Kind: "app",
+          Folder: "Shared/Validation",
+          FolderKey: "0932a1f4-5cd1-44d4-9f02-cdc92244a6d2",
+          Version: "12.0.0"
+        }
+      ]
+    }
+  }
+];
 var registerResourceListCommand = (resource) => {
-  resource.command("list").description("List resources in the solution and/or available in Orchestrator. " + "Shows local solution resources, remote Orchestrator resources, or both.").option("--solution-folder <path>", "Path to the solution root folder (defaults to current directory)").option("--kind <kind>", "Filter by resource kind (e.g. Queue, Asset, Bucket, Process, Connection, App, Index, Trigger, Entity, ChoiceSet). Any kind RCS indexes is accepted.").option("--search <term>", "Filter resources by name").option("--source <source>", "Resource source: all, local, or remote (default: all)", "all").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).trackedAction(processContext, async (options) => {
+  resource.command("list").description("List resources in the solution and/or available in Orchestrator. " + "Shows local solution resources, remote Orchestrator resources, or both.").option("--solution-folder <path>", "Path to the solution root folder (defaults to current directory)").option("--kind <kind>", "Filter by resource kind (e.g. Queue, Asset, Bucket, Process, Connection, App, Index, Trigger, Entity, ChoiceSet). Any kind RCS indexes is accepted.").option("--search <term>", "Filter resources by name").option("--source <source>", "Resource source: all, local, or remote (default: all)", "all").option("--include-version", "Also report each resource's version, for the kinds that carry one (app, appVersion, package, process). " + "Remote rows report the version live in the folder, local rows the version the solution pins. " + "Costs one extra call per resource, so it is off by default.").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).examples(RESOURCE_LIST_EXAMPLES).trackedAction(processContext, async (options) => {
     const solutionPath = options.solutionFolder ?? ".";
     const fs = getFileSystem();
     const resolvedPath = fs.path.resolve(fs.env.cwd(), solutionPath);
@@ -4455,7 +4668,7 @@ var registerResourceListCommand = (resource) => {
       processContext.exit(1);
       return;
     }
-    const [listError, data] = await catchError(listResources(builder, services, source, normalizedKind, options.search));
+    const [listError, data] = await catchError(listResources(builder, services, source, normalizedKind, options.search, options.includeVersion === true));
     await builder.disposeAsync();
     if (listError) {
       OutputFormatter.error({
@@ -4473,7 +4686,14 @@ var registerResourceListCommand = (resource) => {
     });
   });
 };
-async function listResources(builder, services, source, kind, search) {
+async function listResources(builder, services, source, kind, search, includeVersion = false) {
+  const entries = await collectResources(builder, services, source, kind, search);
+  if (includeVersion) {
+    await annotateVersions(services, builder, entries);
+  }
+  return entries;
+}
+async function collectResources(builder, services, source, kind, search) {
   const includeLocal = source === "local" || source === "all";
   const includeRemote = source === "remote" || source === "all";
   if (kind) {
@@ -4491,6 +4711,40 @@ async function listResources(builder, services, source, kind, search) {
   }
   return all;
 }
+function versionLookupId(entry) {
+  return `${entry.Source}|${entry.Key}|${entry.Folder ?? ""}`;
+}
+async function annotateVersions(services, builder, entries) {
+  const targets = new Map;
+  for (const entry of entries) {
+    if (entry.Key === "") {
+      continue;
+    }
+    const id = versionLookupId(entry);
+    if (targets.has(id)) {
+      continue;
+    }
+    targets.set(id, {
+      id,
+      key: entry.Key,
+      kind: entry.Kind,
+      type: entry.Type,
+      name: entry.Name,
+      source: entry.Source === "Local" ? "Local" : "Remote",
+      folderFullyQualifiedName: entry.Folder,
+      folderKey: entry.FolderKey
+    });
+  }
+  const versions = await resolveResourceVersionsAsync(services, builder, [
+    ...targets.values()
+  ]);
+  for (const entry of entries) {
+    const version = versions.get(versionLookupId(entry));
+    if (version !== undefined) {
+      entry.Version = version;
+    }
+  }
+}
 async function listAllRemoteResources(services, search) {
   const rcs = services.container.resolve(Tokens.IResourceCatalogClientProxy);
   const entries = [];
@@ -4582,6 +4836,7 @@ var RESOURCE_REFRESH_EXAMPLES = [
         Created: 2,
         Imported: 1,
         Skipped: 5,
+        Pruned: 0,
         Warnings: [],
         Status: "Synced 3 resources (5 already in solution)"
       }
@@ -4595,7 +4850,7 @@ var FAILURE_MESSAGE = {
   sync_failed: "Failed to refresh resources"
 };
 var registerResourceRefreshSubcommand = (resource) => {
-  resource.command("refresh").description("Re-scan all projects in the solution and sync resource declarations from their bindings_v2.json files. " + "Creates new resources for bindings not yet in the solution, imports from Orchestrator when a matching resource exists. " + "Run this after editing project bindings to update the solution resource inventory.").option("--solution-folder <path>", "Path to the solution root folder (defaults to current directory)").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", "10").examples(RESOURCE_REFRESH_EXAMPLES).trackedAction(processContext, async (options) => {
+  resource.command("refresh").description("Re-scan all projects in the solution and sync resource declarations from their bindings_v2.json files. " + "Creates new resources for bindings not yet in the solution, imports from Orchestrator when a matching resource exists, " + "and removes duplicate copies of the solution's own projects that earlier runs imported from a deployed folder. " + "Run this after editing project bindings to update the solution resource inventory.").option("--solution-folder <path>", "Path to the solution root folder (defaults to current directory)").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", "10").examples(RESOURCE_REFRESH_EXAMPLES).trackedAction(processContext, async (options) => {
     const loginValidityMinutes = options.loginValidity ? parseInt(options.loginValidity, 10) : undefined;
     const result = await resourceRefreshAsync(options.solutionFolder ?? ".", { loginValidity: loginValidityMinutes });
     if (!result.ok) {
@@ -4607,6 +4862,7 @@ var registerResourceRefreshSubcommand = (resource) => {
       processContext.exit(1);
       return;
     }
+    const prunedNote = result.pruned > 0 ? `, ${result.pruned} duplicates removed` : "";
     OutputFormatter.success({
       Result: RESULTS.Success,
       Code: "ResourceRefresh",
@@ -4614,8 +4870,9 @@ var registerResourceRefreshSubcommand = (resource) => {
         Created: result.created,
         Imported: result.imported,
         Skipped: result.skipped,
+        Pruned: result.pruned,
         Warnings: result.warnings,
-        Status: `Synced ${result.created + result.imported} resources (${result.skipped} already in solution)`
+        Status: `Synced ${result.created + result.imported} resources (${result.skipped} already in solution${prunedNote})`
       }
     });
   });
@@ -4768,23 +5025,22 @@ class RestoreCommandService {
     this.fs = getFileSystem();
   }
   async execute(solutionPath, options, context) {
-    const absoluteSolutionPath = this.fs.path.resolve(solutionPath);
-    const [statError, stats] = await catchError(this.fs.stat(absoluteSolutionPath));
-    if (statError || !stats) {
-      const msg = statError?.message ?? `Solution path does not exist: ${absoluteSolutionPath}`;
+    const check = await checkSolutionPathAsync(this.fs, solutionPath);
+    if (!check.ok) {
       OutputFormatter.error({
         Result: RESULTS.Failure,
-        Message: msg,
-        Instructions: "Ensure the solution path exists and points to a solution directory (containing .uipx) or a .uis file."
+        Message: check.message,
+        Instructions: SOLUTION_PATH_INSTRUCTIONS,
+        ErrorCode: check.errorCode
       });
-      if (statError?.stack) {
+      if (check.statError?.stack) {
         logger.error("Stack trace:");
-        logger.error(statError.stack);
+        logger.error(check.statError.stack);
       }
       context.exit(1);
       return;
     }
-    const isUisFile = stats.isFile() && absoluteSolutionPath.endsWith(".uis");
+    const { absoluteSolutionPath, isUisFile } = check;
     const solutionName = isUisFile ? this.fs.path.basename(solutionPath, ".uis") : this.fs.path.basename(solutionPath);
     logger.info(`
 Restoring solution dependencies...
@@ -4798,7 +5054,7 @@ Restoring solution dependencies...
       OutputFormatter.error({
         Result: RESULTS.Failure,
         Message: msg,
-        Instructions: "Check that you are logged in (`uip auth login`) and that the solution path is accessible, then rerun: uip solution restore <solutionPath>"
+        Instructions: carriedInstructions(error) ?? "Check that you are logged in (`uip auth login`) and that the solution path is accessible, then rerun: uip solution restore <solutionPath>"
       });
       if (error instanceof Error && error.stack) {
         logger.error("Stack trace:");
@@ -4826,9 +5082,14 @@ Restoring solution dependencies...
     });
   }
   async executeAsync(solutionPath, options) {
-    const absoluteSolutionPath = this.fs.path.resolve(solutionPath);
-    const stats = await this.fs.stat(absoluteSolutionPath);
-    const isUisFile = !!stats && stats.isFile() && absoluteSolutionPath.endsWith(".uis");
+    const check = await checkSolutionPathAsync(this.fs, solutionPath);
+    if (!check.ok) {
+      if (check.statError) {
+        throw check.statError;
+      }
+      return new ToolResult("INTERNAL_ERROR" /* InternalError */, check.message, []);
+    }
+    const { absoluteSolutionPath, isUisFile } = check;
     const solutionName = isUisFile ? this.fs.path.basename(solutionPath, ".uis") : this.fs.path.basename(solutionPath);
     const packager = await this.ensurePackagerAsync();
     let inputPath;
@@ -4852,7 +5113,7 @@ Restoring solution dependencies...
     const restoreOptions = new SolutionPackOptions;
     restoreOptions.inputPath = inputPath;
     restoreOptions.configuration = "Release" /* Release */;
-    restoreOptions.excludeConfiguredSources = false;
+    restoreOptions.excludeConfiguredSources = options.excludeConfiguredSources ?? false;
     restoreOptions.package = {
       id: solutionName,
       version: "1.0.0",
@@ -4882,11 +5143,12 @@ var SOLUTION_RESTORE_EXAMPLES = [
   }
 ];
 var registerRestoreCommand = (program) => {
-  program.command("restore").description("Restore NuGet dependencies for every project in a UiPath solution using the authenticated session. Accepts a solution directory (containing .uipx) or a .uis file. Resolves dependencies in place and does not produce a package — run it before 'uip solution pack'.").argument("<solutionPath>", "Path to a solution directory (containing .uipx) or a .uis file").option("--nuget-sources-config-path <path>", "Path to NuGet sources configuration file").option("--feed-folder <name>", "Resolve project dependencies from this Orchestrator folder's library feed instead of every tenant feed. Accepts a folder name or fully qualified path.").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).examples(SOLUTION_RESTORE_EXAMPLES).trackedAction(processContext, async (solutionPath, options) => {
+  program.command("restore").description("Restore NuGet dependencies for every project in a UiPath solution using the authenticated session. Accepts a solution directory (containing .uipx) or a .uis file. Resolves dependencies in place and does not produce a package — run it before 'uip solution pack'.").argument("<solutionPath>", "Path to a solution directory (containing .uipx) or a .uis file").option("--nuget-sources-config-path <path>", "Path to NuGet sources configuration file").option("--exclude-configured-sources", "Resolve project dependencies only from the tenant feeds and any --nuget-sources-config-path. Drops the built-in UiPath and nuget.org feeds, so a dependency that is not on those feeds fails to restore.").option("--feed-folder <name>", "Resolve project dependencies from this Orchestrator folder's library feed instead of every tenant feed. Accepts a folder name or fully qualified path.").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).examples(SOLUTION_RESTORE_EXAMPLES).trackedAction(processContext, async (solutionPath, options) => {
     const service = new RestoreCommandService;
     await service.execute(solutionPath, {
       loginValidity: options.loginValidity,
       nugetSourcesConfigPath: options.nugetSourcesConfigPath,
+      excludeConfiguredSources: options.excludeConfiguredSources,
       feedFolder: options.feedFolder
     }, processContext);
   });
@@ -4975,7 +5237,7 @@ class ExecutorsFactoryRepository {
   getProjectExecutorFactory(projectType) {
     const factory = this.factoryMap.get(projectType);
     if (!factory) {
-      throw new Error(`No executor is registered for project type '${projectType}'. ` + `Registered types: ${this.registeredTypes.join(", ") || "none"}.`);
+      throw new Error(`Cannot run project type '${projectType}': no runner is installed for it. ` + `Project types that can be run: ${this.registeredTypes.join(", ") || "none"}.`);
     }
     return factory;
   }
@@ -5046,7 +5308,7 @@ class ProjectRunner {
     const { projectType, name } = options.project;
     if (!this.canRun(projectType)) {
       const known = this.runnableTypes.join(", ") || "none";
-      return RunResult.failed("UnsupportedProjectType" /* UnsupportedProjectType */, `No executor is registered for project type '${projectType}' ` + `(project '${name}'). Runnable types: ${known}.`);
+      return RunResult.failed("UnsupportedProjectType" /* UnsupportedProjectType */, `Cannot run project '${name}' (project type '${projectType}'): ` + `no runner is installed for it. Project types that can be run: ${known}.`);
     }
     let executor;
     try {
@@ -5093,7 +5355,7 @@ async function ensureExecutorTools(projectTypes) {
     if (toolVerb) {
       neededTools.add(toolVerb);
     } else {
-      logger.warn(`No CLI tool provides an executor for project type '${type}'. Run may fail.`);
+      logger.warn(`No installable tool runs project type '${type}'. Run may fail.`);
     }
   }
   for (const toolVerb of neededTools) {
@@ -5155,11 +5417,11 @@ async function provisionSolutionForDebugAsync(options, deps = {}) {
   logger.info("Resolving the personal workspace to deploy into...");
   const [locationsError, locations] = await catchError(listLocations(authOptions));
   if (locationsError) {
-    return fail2(`Could not resolve a personal workspace to deploy into: ${locationsError.message}`);
+    return fail(`Could not resolve a personal workspace to deploy into: ${locationsError.message}`);
   }
   const personal = locations.find((l) => l.isMyPersonalWorkspace);
   if (!personal) {
-    return fail2("This account has no personal workspace, so there is nowhere to deploy the solution for a debug run. " + "Ask an administrator to enable a personal workspace, or run with --no-provision-resources — " + "the run then starts without a deployment, and cross-project calls will not resolve.");
+    return fail("This account has no personal workspace, so there is nowhere to deploy the solution for a debug run. " + "Ask an administrator to enable a personal workspace, or run with --no-provision-resources — " + "the run then starts without a deployment, and cross-project calls will not resolve.");
   }
   const version = options.version ?? nextDebugVersion();
   const fs = getFileSystem();
@@ -5173,13 +5435,13 @@ async function provisionSolutionForDebugAsync(options, deps = {}) {
     outputPath
   });
   if (!uploaded.ok) {
-    return fail2(uploaded.message);
+    return fail(uploaded.message);
   }
   const packageVersionKey = uploaded.packageVersionKey;
   logger.info("Provisioning the solution's resources for the run...");
   const [builderError, builder] = await catchError(getBuilder(options.solutionDir));
   if (builderError) {
-    return fail2(`Could not read the solution: ${builderError.message}`);
+    return fail(`Could not read the solution: ${builderError.message}`);
   }
   const sessionId = newSessionId();
   const [debugError, debug] = await catchError(builder.debugProjectAsync(personal.key, options.solutionName, sessionId, packageVersionKey, true));
@@ -5190,11 +5452,11 @@ async function provisionSolutionForDebugAsync(options, deps = {}) {
   }
   await builder.disposeAsync().catch(() => {});
   if (debugError) {
-    return fail2(`Provisioning the solution failed: ${debugError.message}`);
+    return fail(`Provisioning the solution failed: ${debugError.message}`);
   }
   if (debug.complete === false) {
     if (!solutionKey) {
-      return fail2("The cloud is still provisioning the solution, but its key could not be read back from the .uipx, so the provisioning cannot be waited on. Retry the run.");
+      return fail("The cloud is still provisioning the solution, but its key could not be read back from the .uipx, so the provisioning cannot be waited on. Retry the run.");
     }
     return waitForProvisioningAsync({
       solutionKey,
@@ -5212,7 +5474,7 @@ async function provisionSolutionForDebugAsync(options, deps = {}) {
     packageVersionKey
   };
 }
-function fail2(message) {
+function fail(message) {
   return { ok: false, message };
 }
 async function packAndUploadAsync(args) {
@@ -5285,13 +5547,13 @@ async function waitForProvisioningAsync(args) {
     signal: processContext.pollSignal
   });
   if (poll.outcome !== PollOutcome.Completed || !poll.data) {
-    return fail2(describeIncompleteWait(poll, timeoutMs));
+    return fail(describeIncompleteWait(poll, timeoutMs));
   }
   const info = poll.data;
   if (!isDebugProvisioningSucceeded(info.status)) {
     const details = (info.errors ?? []).map((error) => error.resource ? `${error.resource.kind ?? "resource"} '${error.resource.name ?? error.resource.key ?? ""}': ${error.message}` : error.message).join(`
 `);
-    return fail2(`Provisioning the solution failed (${info.status}).` + (details ? `
+    return fail(`Provisioning the solution failed (${info.status}).` + (details ? `
 ${details}` : ""));
   }
   logger.info("Solution provisioned.");
@@ -5337,7 +5599,7 @@ async function runSolutionAsync(options, deps, cancellationToken) {
     }) : Promise.resolve(undefined)
   ]);
   if (executorOutcome.status === "rejected") {
-    return RunResult.failed("PrepareFailed" /* PrepareFailed */, `Could not load the executor for project type '${selected.projectType}': ${describeError(executorOutcome.reason)}`);
+    return RunResult.failed("PrepareFailed" /* PrepareFailed */, `Could not load the runner for project type '${selected.projectType}': ${describeError(executorOutcome.reason)}`);
   }
   if (provisionOutcome.status === "rejected") {
     return RunResult.failed("PrepareFailed" /* PrepareFailed */, `Could not deploy the solution before the run: ${describeError(provisionOutcome.reason)}`);
@@ -5401,7 +5663,9 @@ async function resolveConnection(folderPath, options, deps) {
   };
 }
 function describeError(reason) {
-  return reason instanceof Error ? reason.message : String(reason);
+  const message = reason instanceof Error ? reason.message : String(reason);
+  const instructions = carriedInstructions(reason);
+  return instructions ? `${message} ${instructions}` : message;
 }
 function selectProject(runnable, requested) {
   if (requested) {
@@ -5519,32 +5783,53 @@ function describeJson(value) {
 // src/commands/upload.ts
 var SOLUTION_UPLOAD_EXAMPLES = [
   {
-    Description: "Upload a solution directory to Studio Web as a new solution",
+    Description: "Upload a solution directory. Studio Web has no solution with its SolutionId, so it is imported as new and the local .uipx is updated with the assigned id (reported under Data.LocalSolutionIdUpdated).",
     Command: "uip solution upload ./my-solution",
     Output: {
       Code: "SolutionUpload",
       Data: {
         Status: "Uploaded successfully",
+        Action: "Imported",
         SolutionId: "a1b2c3d4-0000-0000-0000-000000000001",
-        DesignerUrl: "https://cloud.uipath.com/myorg/mytenant/studio_/designer/p1?solutionId=a1b2c3d4-0000-0000-0000-000000000001"
+        DesignerUrl: "https://cloud.uipath.com/myorg/studio_/designer/p1?solutionId=a1b2c3d4-0000-0000-0000-000000000001",
+        LocalSolutionIdUpdated: {
+          Path: "/workspace/my-solution/my-solution.uipx",
+          From: "00000000-0000-0000-0000-0000000000ff",
+          To: "a1b2c3d4-0000-0000-0000-000000000001"
+        }
       }
     }
   },
   {
-    Description: "Force-overwrite the existing Studio Web solution that the local .uipx points to (destroys cloud version history)",
-    Command: "uip solution upload ./my-solution --force",
+    Description: "Same command when the solution already exists on Studio Web: it is overwritten in place, with the replaced contents recorded first as a restorable version.",
+    Command: "uip solution upload ./my-solution",
     Output: {
       Code: "SolutionUpload",
       Data: {
         Status: "Uploaded successfully",
+        Action: "Overwritten",
         SolutionId: "a1b2c3d4-0000-0000-0000-000000000001",
-        DesignerUrl: "https://cloud.uipath.com/myorg/mytenant/studio_/designer/p1?solutionId=a1b2c3d4-0000-0000-0000-000000000001"
+        DesignerUrl: "https://cloud.uipath.com/myorg/studio_/designer/p1?solutionId=a1b2c3d4-0000-0000-0000-000000000001",
+        SnapshotCreated: true
+      }
+    }
+  },
+  {
+    Description: "Overwrite without recording a pre-overwrite version. Changes made in Studio Web since the last upload are lost; local files are unaffected.",
+    Command: "uip solution upload ./my-solution --no-snapshot",
+    Output: {
+      Code: "SolutionUpload",
+      Data: {
+        Status: "Uploaded successfully",
+        Action: "Overwritten",
+        SolutionId: "a1b2c3d4-0000-0000-0000-000000000001",
+        DesignerUrl: "https://cloud.uipath.com/myorg/studio_/designer/p1?solutionId=a1b2c3d4-0000-0000-0000-000000000001"
       }
     }
   }
 ];
 var registerUploadCommand = (program) => {
-  program.command("upload").description("Upload a solution to UiPath Studio Web for browser-based editing. Accepts a solution directory, .uipx file, or .uis file. The command probes Studio Web for the bundled SolutionId: if the cloud solution does not exist it is imported as new; if it already exists the upload is refused unless --force is passed. Forcing replaces the cloud project in place and wipes its Studio Web version history.").argument("<solutionPath>", "Path to a solution directory (containing .uipx), a .uipx file, or a .uis file.").option("--force", "Force-overwrite the existing Studio Web solution referenced by the SolutionId in the local .uipx. This replaces the cloud project in place and destroys its Studio Web version history. Required whenever the cloud already has a solution with that SolutionId; ignored when the cloud has none.").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).examples(SOLUTION_UPLOAD_EXAMPLES).trackedAction(processContext, async (solutionPath, options) => {
+  program.command("upload").description("Upload a solution to UiPath Studio Web for browser-based editing. Accepts a solution directory, .uipx file, or .uis file. If Studio Web has no solution with the bundled SolutionId, the solution is imported as new and the local .uipx is updated with the assigned id; otherwise it is overwritten in place, with the replaced contents recorded first as a restorable version (skip with --no-snapshot). The output field Data.Action says which happened: 'Imported' or 'Overwritten'.").argument("<solutionPath>", "Path to a solution directory (containing .uipx), a .uipx file, or a .uis file.").option("--force", "Skip the existence check and overwrite the Studio Web solution named by the bundled SolutionId directly. Not normally needed — an upload overwrites an existing cloud solution on its own. Fails if that solution does not exist. No effect when no SolutionId is bundled (a .uis archive without one): the upload imports as new.").option("--no-snapshot", "Do not record a restorable pre-overwrite version of the cloud solution before replacing its contents. Changes made in Studio Web since the last upload are lost; local files are unaffected. No effect when the upload imports a new solution.").option("--login-validity <minutes>", "Minimum minutes before token expiration to trigger a refresh (default: 10)", parseInt, 10).examples(SOLUTION_UPLOAD_EXAMPLES).trackedAction(processContext, async (solutionPath, options) => {
     const fs = getFileSystem();
     const [loginError, loginStatus] = await catchError(getLoginStatusAsync({
       ensureTokenValidityMinutes: options.loginValidity
@@ -5604,6 +5889,16 @@ var registerUploadCommand = (program) => {
         if (cleanupError) {
           logger.debug(`Failed to clean up temp dir: ${cleanupError.message}`);
         }
+        if (bundleError instanceof StudioWebIncompatibleProjectError) {
+          OutputFormatter.error({
+            Result: RESULTS.Failure,
+            ErrorCode: "invalid_argument",
+            Message: bundleError.message,
+            Instructions: "Convert the listed project(s) to a project.uiproj manifest before uploading: scaffold the accepted layout with 'uip api-workflow init <name>' inside the solution and move Workflow.json (plus entry-points.json and bindings_v2.json) into it, then remove the project.json-based entry from the .uipx. Note that 'uip solution pack' and 'uip solution publish' accept project.json — only Studio Web upload requires project.uiproj."
+          });
+          processContext.exit(1);
+          return;
+        }
         outputError(bundleError.message);
         return;
       }
@@ -5622,12 +5917,22 @@ var registerUploadCommand = (program) => {
         outputError(`Failed to read file: ${uisPath}${readError ? ` — ${readError.message}` : ""}`);
         return;
       }
+      const uisFileName = fs.path.basename(uisPath);
+      if (!solutionId) {
+        solutionId = readBundledSolutionId(fileBuffer);
+        if (solutionId) {
+          logger.info(`Read SolutionId ${solutionId} from ${uisFileName}`);
+        }
+      }
       const studioWebConfig = {
         baseUrl,
         authToken: accessToken,
         tenantId
       };
-      if (!options.force && solutionId) {
+      let overwriteExisting = false;
+      if (solutionId && options.force) {
+        overwriteExisting = true;
+      } else if (solutionId) {
         const [probeError, exists] = await catchError(solutionExistsOnStudioWeb(studioWebConfig, organizationName, solutionId));
         if (probeError) {
           const errorMessage = await extractErrorMessage(probeError);
@@ -5639,18 +5944,23 @@ var registerUploadCommand = (program) => {
           processContext.exit(1);
           return;
         }
-        if (exists) {
+        overwriteExisting = exists;
+      }
+      const createSnapshot = overwriteExisting && options.snapshot !== false;
+      logger.info(overwriteExisting ? `Overwriting existing Studio Web solution ${solutionId}...` : "Importing as a new Studio Web solution...");
+      const [uploadError, result] = await catchError(overwriteExisting && solutionId ? overwriteSolution(studioWebConfig, organizationName, fileBuffer, uisFileName, solutionId, createSnapshot) : importSolution(studioWebConfig, organizationName, fileBuffer, uisFileName));
+      if (uploadError) {
+        if (overwriteExisting && isSolutionNotFoundError(uploadError)) {
           OutputFormatter.error({
             Result: RESULTS.Failure,
-            Message: `Studio Web already has a solution with SolutionId ${solutionId}. Refusing to overwrite without --force.`,
-            Instructions: "Re-run with --force to replace the cloud solution in place (this destroys its Studio Web version history). To upload as an unrelated new solution instead, scaffold a fresh solution with 'uip solution init' or remove the SolutionId from the local .uipx before uploading."
+            ErrorCode: "not_found",
+            Message: `Studio Web has no solution with SolutionId ${solutionId}, so there is nothing to overwrite. It may have been deleted, or it may belong to a tenant or user you no longer have access to.`,
+            Instructions: `The SolutionId in ${uipxPath ?? uisPath} is stale. Re-run the upload${options.force ? " without --force" : ""} — the existence check will see the id is gone and import as a new Studio Web solution${uipxPath ? ", updating the local .uipx with the new id" : ""}. Nothing was uploaded.`,
+            Retry: "RetryWillNotFix"
           });
           processContext.exit(1);
           return;
         }
-      }
-      const [uploadError, result] = await catchError(options.force ? uploadOrOverwriteSolution(studioWebConfig, organizationName, fileBuffer, solutionId) : importSolution(studioWebConfig, organizationName, fileBuffer, fs.path.basename(uisPath)));
-      if (uploadError) {
         const errorMessage = await extractErrorMessage(uploadError);
         OutputFormatter.error({
           Result: RESULTS.Failure,
@@ -5660,20 +5970,25 @@ var registerUploadCommand = (program) => {
         processContext.exit(1);
         return;
       }
-      const returnedSolutionId = result.id ?? result.solutionId ?? solutionId;
-      if (returnedSolutionId && uipxPath) {
-        await updateUipxSolutionId(fs, uipxPath, returnedSolutionId);
-      }
+      const { returnedSolutionId, rewroteLocalSolutionId } = await updateLocalSolutionId(fs, result, solutionId, uipxPath);
       const projectId = result.projects?.[0]?.id;
-      const designerSolutionId = returnedSolutionId ?? solutionId;
-      const designerUrl = projectId && designerSolutionId ? `${baseUrl}/${organizationName}/studio_/designer/${projectId}?solutionId=${designerSolutionId}` : undefined;
+      const designerUrl = projectId && returnedSolutionId ? `${baseUrl}/${encodeURIComponent(organizationName)}/studio_/designer/${encodeURIComponent(projectId)}?solutionId=${encodeURIComponent(returnedSolutionId)}` : undefined;
       OutputFormatter.success({
         Result: RESULTS.Success,
         Code: "SolutionUpload",
         Data: {
           Status: "Uploaded successfully",
+          Action: overwriteExisting ? "Overwritten" : "Imported",
           SolutionId: returnedSolutionId,
           DesignerUrl: designerUrl,
+          ...createSnapshot ? { SnapshotCreated: true } : {},
+          ...rewroteLocalSolutionId ? {
+            LocalSolutionIdUpdated: {
+              Path: uipxPath,
+              From: solutionId,
+              To: returnedSolutionId
+            }
+          } : {},
           Response: result
         }
       });
@@ -5696,6 +6011,19 @@ var registerUploadCommand = (program) => {
     }
   });
 };
+async function updateLocalSolutionId(fs, result, solutionId, uipxPath) {
+  const returnedSolutionId = result.id ?? result.solutionId ?? solutionId;
+  const shouldUpdateUipx = uipxPath !== undefined && returnedSolutionId !== undefined && returnedSolutionId !== solutionId;
+  const rewroteLocalSolutionId = shouldUpdateUipx && solutionId !== undefined;
+  if (shouldUpdateUipx && returnedSolutionId && uipxPath) {
+    await updateUipxSolutionId(fs, uipxPath, returnedSolutionId);
+    logger.info(solutionId ? `Studio Web assigned SolutionId ${returnedSolutionId} — the local .uipx now points at it (was ${solutionId}).` : `Studio Web assigned SolutionId ${returnedSolutionId} — the local .uipx now points at it.`);
+  }
+  return { returnedSolutionId, rewroteLocalSolutionId };
+}
+function isSolutionNotFoundError(error) {
+  return error instanceof Error && "status" in error && error.status === 404;
+}
 function outputError(message) {
   OutputFormatter.error({
     Result: RESULTS.Failure,
@@ -5727,12 +6055,12 @@ var registerCommands = async (program) => {
   registerResourceCommand(program);
   registerDeleteCommand(program);
   if (isPreviewBuild()) {
-    const { registerListCommand } = await import("./list-skbehtq2.js");
+    const { registerListCommand } = await import("./list-3mrc9s3f.js");
     registerListCommand(program);
   }
-  previewOnly(() => registerFeedsCommand(program));
+  registerFeedsCommand(program);
 };
 
 export { metadata, registerCommands };
 
-//# debugId=E1FF366A75A1C81B64756E2164756E21
+//# debugId=58375CF8CAC8E11064756E2164756E21