@bigcommerce/catalyst 1.0.0-alpha.6 → 1.1.0

package/dist/cli.js

@@ -1,24 +1,21 @@
 #!/usr/bin/env node
 
-// src/cli/lib/auth-errors.ts
-var UnauthorizedError = class extends Error {
-  constructor() {
-    super(
-      "Your access token is invalid or has expired.\nRun `catalyst auth login` to re-authenticate."
-    );
-    this.name = "UnauthorizedError";
+// src/cli/lib/errors.ts
+var UserActionableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UserActionableError";
   }
 };
-function assertAuthorized(response) {
-  if (response.status === 401) {
-    throw new UnauthorizedError();
-  }
-}
 
 // src/cli/lib/logger.ts
 import { createConsola } from "consola";
 var consola = createConsola({
-  level: "3" ? parseInt("3", 10) : 3
+  level: "3" ? parseInt("3", 10) : 3,
+  // Drop the per-line timestamp. It adds noise for a short-lived CLI and, on
+  // long lines, consola can't right-align it so it falls back to an inline
+  // `[time]` prefix that breaks copy-pasteable command suggestions.
+  formatOptions: { date: false }
 });
 
 // src/cli/lib/telemetry.ts
@@ -28,8 +25,13 @@ import { randomBytes, randomUUID } from "crypto";
 // package.json
 var package_default = {
   name: "@bigcommerce/catalyst",
-  version: "1.0.0-alpha.6",
+  version: "1.1.0",
   type: "module",
+  repository: {
+    type: "git",
+    url: "https://github.com/bigcommerce/catalyst",
+    directory: "packages/catalyst"
+  },
   bin: {
     catalyst: "dist/cli.js"
   },
@@ -64,7 +66,9 @@ var package_default = {
     "lodash.kebabcase": "^4.1.1",
     nypm: "^0.5.4",
     open: "^10.1.0",
+    semver: "^7.7.4",
     "std-env": "^3.9.0",
+    tar: "^7.5.7",
     "yocto-spinner": "^1.0.0",
     zod: "^4.0.5"
   },
@@ -76,6 +80,7 @@ var package_default = {
     "@types/fs-extra": "^11.0.4",
     "@types/lodash.kebabcase": "^4.1.9",
     "@types/node": "^22.15.30",
+    "@types/semver": "^7.7.0",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     eslint: "^8.57.1",
@@ -128,7 +133,7 @@ var Telemetry = class {
     this.correlationId = randomUUID();
     this.startTime = Date.now();
     this.analytics = new Analytics({
-      writeKey: "not-a-valid-segment-write-key"
+      writeKey: "OCkxLj3KTc1N3ebEbnFBqbhxfE3tVb3Z"
     });
   }
   durationMs() {
@@ -195,26 +200,65 @@ function getTelemetry() {
 }
 
 // src/cli/program.ts
-import { Option as Option9 } from "@commander-js/extra-typings";
-import { Command as Command12 } from "commander";
-import { colorize as colorize9 } from "consola/utils";
-import { config } from "dotenv";
-import { existsSync as existsSync5 } from "fs";
-import { resolve } from "path";
+import { Command as Command15 } from "commander";
+import { colorize as colorize13 } from "consola/utils";
 
 // src/cli/commands/auth.ts
-import { Command, Option as Option2 } from "commander";
-import { z as z4 } from "zod";
+import { Command } from "commander";
+import { z as z5 } from "zod";
+
+// src/cli/lib/auth-errors.ts
+var UnauthorizedError = class extends UserActionableError {
+  constructor() {
+    super(
+      "Your access token is invalid or has expired.\nRun `catalyst auth login` to re-authenticate."
+    );
+    this.name = "UnauthorizedError";
+  }
+};
+function assertAuthorized(response) {
+  if (response.status === 401) {
+    throw new UnauthorizedError();
+  }
+}
 
 // src/cli/lib/login.ts
 import { confirm, input, password } from "@inquirer/prompts";
 import { colorize } from "consola/utils";
 import open from "open";
 import yoctoSpinner from "yocto-spinner";
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/cli/lib/auth.ts
+import { z as z2 } from "zod";
+
+// src/cli/lib/http-errors.ts
 import { z } from "zod";
+var apiErrorBodySchema = z.object({
+  title: z.string().optional(),
+  detail: z.string().optional(),
+  errors: z.record(z.string(), z.string()).optional()
+});
+var FALLBACK_CLIENT_ERROR = "The request was rejected. Check your input \u2014 your access token may be missing a required scope, or the resource may not exist.";
+var FALLBACK_SERVER_ERROR = "Something went wrong on our end. Please try again. If the issue persists, contact support.";
+function extractApiErrorMessage(body) {
+  const parsed = apiErrorBodySchema.safeParse(body);
+  if (!parsed.success) return void 0;
+  const { title, detail, errors } = parsed.data;
+  const fieldErrors = errors && Object.keys(errors).length > 0 ? Object.entries(errors).map(([field, message]) => `${field}: ${message}`).join("; ") : void 0;
+  const headline = detail ?? title;
+  if (headline && fieldErrors) return `${headline} (${fieldErrors})`;
+  return headline ?? fieldErrors;
+}
+async function httpError(response, action) {
+  const body = await response.json().catch(() => null);
+  const isServerError = response.status >= 500;
+  const detail = extractApiErrorMessage(body) ?? (isServerError ? FALLBACK_SERVER_ERROR : FALLBACK_CLIENT_ERROR);
+  const message = `${action}: ${detail}`;
+  return isServerError ? new Error(message) : new UserActionableError(message);
+}
+
+// src/cli/lib/auth.ts
 var DEVICE_OAUTH_CLIENT_ID = "b8063bu6hhml4e0lqh22yut63atsbyv";
 var DEVICE_OAUTH_SCOPES = [
   "store_v2_information",
@@ -224,18 +268,18 @@ var DEVICE_OAUTH_SCOPES = [
   "store_channel_settings"
 ].join(" ");
 var DEFAULT_LOGIN_URL = "https://login.bigcommerce.com";
-var DeviceCodeResponseSchema = z.object({
-  device_code: z.string(),
-  user_code: z.string(),
-  verification_uri: z.string(),
-  expires_in: z.number(),
-  interval: z.number()
-});
-var DeviceCodeSuccessSchema = z.object({
-  access_token: z.string(),
-  store_hash: z.string(),
-  context: z.string(),
-  api_uri: z.string()
+var DeviceCodeResponseSchema = z2.object({
+  device_code: z2.string(),
+  user_code: z2.string(),
+  verification_uri: z2.string(),
+  expires_in: z2.number(),
+  interval: z2.number()
+});
+var DeviceCodeSuccessSchema = z2.object({
+  access_token: z2.string(),
+  store_hash: z2.string(),
+  context: z2.string(),
+  api_uri: z2.string()
 });
 async function requestDeviceCode(loginUrl) {
   const response = await fetch(`${loginUrl}/device/token`, {
@@ -247,7 +291,7 @@ async function requestDeviceCode(loginUrl) {
     })
   });
   if (!response.ok) {
-    throw new Error(`Failed to request device code: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to request device code");
   }
   const res = await response.json();
   return DeviceCodeResponseSchema.parse(res);
@@ -278,6 +322,33 @@ async function waitForDeviceToken(loginUrl, deviceCode, interval) {
   return waitForDeviceToken(loginUrl, deviceCode, interval);
 }
 
+// src/cli/lib/clipboard.ts
+import { execa } from "execa";
+function clipboardCommand() {
+  switch (process.platform) {
+    case "darwin":
+      return { command: "pbcopy", args: [] };
+    case "win32":
+      return { command: "clip", args: [] };
+    case "linux":
+      return process.env.WAYLAND_DISPLAY ? { command: "wl-copy", args: [] } : { command: "xclip", args: ["-selection", "clipboard"] };
+    default:
+      return null;
+  }
+}
+async function copyToClipboard(text) {
+  const clipboard = clipboardCommand();
+  if (!clipboard) {
+    return false;
+  }
+  try {
+    await execa(clipboard.command, clipboard.args, { input: text });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/cli/lib/login.ts
 var LoginAbortedError = class extends Error {
   constructor() {
@@ -285,9 +356,9 @@ var LoginAbortedError = class extends Error {
     this.name = "LoginAbortedError";
   }
 };
-var StoreProfileSchema = z2.object({
-  data: z2.object({
-    store_name: z2.string()
+var StoreProfileSchema = z3.object({
+  data: z3.object({
+    store_name: z3.string()
   })
 });
 async function fetchStoreProfile(storeHash, accessToken, apiHost) {
@@ -313,6 +384,13 @@ async function deviceCodeLogin(loginUrl) {
   consola.info(
     `${colorize("yellow", "Your one-time code:")} ${colorize("bold", deviceCode.user_code)}`
   );
+  if (process.stdin.isTTY) {
+    await input({ message: "Press Enter to open your browser and sign in" });
+    const copied = await copyToClipboard(deviceCode.user_code);
+    if (copied) {
+      consola.info("Copied the code to your clipboard \u2014 paste it into the sign-in page.");
+    }
+  }
   try {
     await open(deviceCode.verification_uri);
     consola.info(`Opened ${deviceCode.verification_uri} in your browser.`);
@@ -340,12 +418,12 @@ Grant these OAuth scopes: ${DEVICE_OAUTH_SCOPES}`
   const storeHashInput = await input({ message: "Store hash:" });
   const storeHash = storeHashInput.trim();
   if (!storeHash) {
-    throw new Error("Store hash is required.");
+    throw new UserActionableError("Store hash is required.");
   }
   const accessTokenInput = await password({ message: "Access token:", mask: true });
   const accessToken = accessTokenInput.trim();
   if (!accessToken) {
-    throw new Error("Access token is required.");
+    throw new UserActionableError("Access token is required.");
   }
   const spinner = yoctoSpinner().start("Validating credentials...");
   try {
@@ -354,7 +432,7 @@ Grant these OAuth scopes: ${DEVICE_OAUTH_SCOPES}`
   } catch (error) {
     spinner.error("Failed to validate credentials.");
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(
+    throw new UserActionableError(
       `Could not validate credentials (${message}). Double-check your store hash and access token, then try again.`
     );
   }
@@ -378,19 +456,19 @@ async function login(loginUrl, apiHost) {
 }
 
 // src/cli/lib/project.ts
-import { z as z3 } from "zod";
-var InfrastructureProjectValidationError = class extends Error {
+import { z as z4 } from "zod";
+var InfrastructureProjectValidationError = class extends UserActionableError {
   constructor(message) {
     super(message);
     this.name = "InfrastructureProjectValidationError";
   }
 };
-var fetchProjectsSchema = z3.object({
-  data: z3.array(
-    z3.object({
-      uuid: z3.string(),
-      name: z3.string(),
-      deployment_hostnames: z3.array(z3.string())
+var fetchProjectsSchema = z4.object({
+  data: z4.array(
+    z4.object({
+      uuid: z4.string(),
+      name: z4.string(),
+      deployment_hostnames: z4.array(z4.string())
     })
   )
 });
@@ -411,9 +489,7 @@ async function hasProjectsAccess(storeHash, accessToken, apiHost) {
   assertAuthorized(response);
   if (response.status === 200) return true;
   if (response.status === 403) return false;
-  throw new Error(
-    `GET /v3/infrastructure/projects failed: ${response.status} ${response.statusText}`
-  );
+  throw await httpError(response, "Failed to check project access");
 }
 async function fetchProjects(storeHash, accessToken, apiHost) {
   const response = await fetch(projectsUrl(storeHash, apiHost), {
@@ -422,29 +498,29 @@ async function fetchProjects(storeHash, accessToken, apiHost) {
   });
   assertAuthorized(response);
   if (response.status === 403) {
-    throw new Error(
-      "Infrastructure Projects API not enabled. If you are part of the alpha, contact support@bigcommerce.com to enable it."
+    throw new UserActionableError(
+      "Infrastructure Projects API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
     );
   }
   if (!response.ok) {
-    throw new Error(`Failed to fetch projects: ${response.statusText}`);
+    throw await httpError(response, "Failed to fetch projects");
   }
   const res = await response.json();
   const { data } = fetchProjectsSchema.parse(res);
   return data;
 }
-var createProjectSchema = z3.object({
-  data: z3.object({
-    uuid: z3.string(),
-    name: z3.string(),
-    date_created: z3.coerce.date(),
-    date_modified: z3.coerce.date()
+var createProjectSchema = z4.object({
+  data: z4.object({
+    uuid: z4.string(),
+    name: z4.string(),
+    date_created: z4.coerce.date(),
+    date_modified: z4.coerce.date()
   })
 });
-var validationErrorBodySchema = z3.object({
-  title: z3.string().optional(),
-  detail: z3.string().optional(),
-  errors: z3.record(z3.string(), z3.string()).optional()
+var validationErrorBodySchema = z4.object({
+  title: z4.string().optional(),
+  detail: z4.string().optional(),
+  errors: z4.record(z4.string(), z4.string()).optional()
 });
 function extractValidationMessage(body) {
   const parsed = validationErrorBodySchema.safeParse(body);
@@ -472,16 +548,16 @@ async function createProject(name, storeHash, accessToken, apiHost) {
     const message = extractValidationMessage(body) ?? fallback;
     throw new InfrastructureProjectValidationError(message);
   }
-  if (response.status === 403) {
-    throw new Error(
-      "Infrastructure Projects API not enabled. If you are part of the alpha, contact support@bigcommerce.com to enable it."
+  if (response.status === 403 || response.status === 404) {
+    throw new UserActionableError(
+      "Infrastructure Projects API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
     );
   }
   if (response.status === 502) {
     throw new Error("Failed to create project, is the name already in use?");
   }
   if (!response.ok) {
-    throw new Error(`Failed to create project: ${response.statusText}`);
+    throw await httpError(response, "Failed to create project");
   }
   const res = await response.json();
   const { data } = createProjectSchema.parse(res);
@@ -494,15 +570,15 @@ async function deleteProject(projectUuid, storeHash, accessToken, apiHost) {
   });
   assertAuthorized(response);
   if (response.status === 403) {
-    throw new Error(
-      "Infrastructure Projects API not enabled. If you are part of the alpha, contact support@bigcommerce.com to enable it."
+    throw new UserActionableError(
+      "Infrastructure Projects API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
     );
   }
   if (response.status === 404) {
-    throw new Error(`Project ${projectUuid} not found.`);
+    throw new UserActionableError(`Project ${projectUuid} not found.`);
   }
   if (!response.ok) {
-    throw new Error(`Failed to delete project: ${response.statusText}`);
+    throw await httpError(response, "Failed to delete project");
   }
 }
 
@@ -523,6 +599,7 @@ function getProjectConfig() {
       },
       storeHash: { type: "string" },
       accessToken: { type: "string" },
+      apiHost: { type: "string" },
       env: {
         type: "object",
         additionalProperties: { type: "string" },
@@ -534,6 +611,7 @@ function getProjectConfig() {
 
 // src/cli/lib/shared-options.ts
 import { Option } from "commander";
+var DEFAULT_API_HOST = "api.bigcommerce.com";
 var storeHashOption = () => new Option(
   "--store-hash <hash>",
   "BigCommerce store hash. Can be found in the URL of your store Control Panel. Read from .bigcommerce/project.json or .env when not provided."
@@ -542,12 +620,19 @@ var accessTokenOption = () => new Option(
   "--access-token <token>",
   "BigCommerce access token. Can be found after creating a store-level API account. Read from .bigcommerce/project.json or .env when not provided."
 ).env("CATALYST_ACCESS_TOKEN");
-var apiHostOption = () => new Option("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com").hideHelp();
+var apiHostOption = () => new Option(
+  "--api-host <host>",
+  "BigCommerce API host. Read from .bigcommerce/project.json or CATALYST_API_HOST when not provided. Defaults to api.bigcommerce.com."
+).env("CATALYST_API_HOST").hideHelp();
 var loginUrlOption = () => new Option("--login-url <url>", "BigCommerce login URL.").env("BIGCOMMERCE_LOGIN_URL").default(DEFAULT_LOGIN_URL).hideHelp();
 var projectUuidOption = () => new Option(
   "--project-uuid <uuid>",
   "BigCommerce infrastructure project UUID. Read from .bigcommerce/project.json or .env when not provided."
 ).env("CATALYST_PROJECT_UUID");
+var envPathOption = () => new Option(
+  "--env-path <path>",
+  "Path to an environment file to load for the build (relative to the current working directory). When omitted, .env.local and .env are auto-loaded from the current directory. Other commands never load env files."
+);
 var resolveProjectUuid = (options) => {
   const config2 = getProjectConfig();
   const projectUuid = options.projectUuid ?? config2.get("projectUuid");
@@ -558,11 +643,12 @@ var resolveProjectUuid = (options) => {
   }
   return projectUuid;
 };
+var resolveApiHost = (options, config2) => options.apiHost ?? config2.get("apiHost") ?? DEFAULT_API_HOST;
 
 // src/cli/commands/auth.ts
-var StoreProfileSchema2 = z4.object({
-  data: z4.object({
-    store_name: z4.string()
+var StoreProfileSchema2 = z5.object({
+  data: z5.object({
+    store_name: z5.string()
   })
 });
 async function fetchStoreProfile2(storeHash, accessToken, apiHost) {
@@ -591,21 +677,10 @@ Example:
   $ catalyst auth whoami
 
   Logged in to My Store (abc123), connected to project my-project (43eba682-0c48-11f1-9bd5-827a48b0ce1e)`
-).addOption(
-  new Option2(
-    "--store-hash <hash>",
-    "BigCommerce store hash. Can be found in the URL of your store Control Panel."
-  ).env("CATALYST_STORE_HASH")
-).addOption(
-  new Option2(
-    "--access-token <token>",
-    "BigCommerce access token. Can be found after creating a store-level API account."
-  ).env("CATALYST_ACCESS_TOKEN")
-).addOption(
-  new Option2("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com").hideHelp()
-).action(async (options) => {
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).action(async (options) => {
   try {
     const config2 = getProjectConfig();
+    const apiHost = resolveApiHost(options, config2);
     const storeHash = options.storeHash ?? config2.get("storeHash");
     const accessToken = options.accessToken ?? config2.get("accessToken");
     if (!storeHash || !accessToken) {
@@ -616,10 +691,10 @@ Example:
       process.exit(1);
       return;
     }
-    const store = await fetchStoreProfile2(storeHash, accessToken, options.apiHost);
+    const store = await fetchStoreProfile2(storeHash, accessToken, apiHost);
     const projectUuid = config2.get("projectUuid");
     if (projectUuid) {
-      const projects = await fetchProjects(storeHash, accessToken, options.apiHost);
+      const projects = await fetchProjects(storeHash, accessToken, apiHost);
       const linkedProject = projects.find((p) => p.uuid === projectUuid);
       if (linkedProject) {
         consola.info(
@@ -659,21 +734,10 @@ Examples:
 
   # Login with existing credentials (skips interactive flow)
   $ catalyst auth login --store-hash <STORE_HASH> --access-token <ACCESS_TOKEN>`
-).addOption(
-  new Option2(
-    "--store-hash <hash>",
-    "BigCommerce store hash. Can be found in the URL of your store Control Panel."
-  ).env("CATALYST_STORE_HASH")
-).addOption(
-  new Option2(
-    "--access-token <token>",
-    "BigCommerce access token. Can be found after creating a store-level API account."
-  ).env("CATALYST_ACCESS_TOKEN")
-).addOption(
-  new Option2("--api-host <host>", "BigCommerce API host. The default is api.bigcommerce.com.").env("BIGCOMMERCE_API_HOST").default("api.bigcommerce.com").hideHelp()
-).addOption(loginUrlOption()).action(async (options) => {
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).action(async (options) => {
   try {
     const config2 = getProjectConfig();
+    const apiHost = resolveApiHost(options, config2);
     const storeHash = options.storeHash ?? config2.get("storeHash");
     const accessToken = options.accessToken ?? config2.get("accessToken");
     if (storeHash && accessToken) {
@@ -682,7 +746,7 @@ Examples:
       process.exit(0);
       return;
     }
-    const credentials = await login(options.loginUrl, options.apiHost);
+    const credentials = await login(options.loginUrl, apiHost);
     config2.set("storeHash", credentials.storeHash);
     config2.set("accessToken", credentials.accessToken);
     consola.success(`Logged in to store ${credentials.storeHash}.`);
@@ -728,10 +792,43 @@ Example:
 var auth = new Command("auth").configureHelp({ showGlobalOptions: true }).description("Manage authentication for the BigCommerce CLI.").addCommand(whoami).addCommand(login2).addCommand(logout);
 
 // src/cli/commands/build.ts
-import { Command as Command2, Option as Option3 } from "commander";
-import { execa } from "execa";
+import { Command as Command2, InvalidArgumentError, Option as Option2 } from "commander";
+import { execa as execa2 } from "execa";
 import { copyFile, cp, rm, writeFile } from "fs/promises";
 import { join as join4 } from "path";
+import { valid as validSemver } from "semver";
+
+// src/cli/lib/build-env.ts
+import { colorize as colorize2 } from "consola/utils";
+import { config } from "dotenv";
+import { existsSync } from "fs";
+import { resolve } from "path";
+var AUTO_ENV_FILES = [".env.local", ".env"];
+function loadBuildEnv({ envPath, cwd = process.cwd() }) {
+  if (envPath !== void 0) {
+    const envFilePath = resolve(cwd, envPath);
+    const result = config({ path: envFilePath, override: true });
+    if (result.error) {
+      const errCode = "code" in result.error && typeof result.error.code === "string" ? result.error.code : void 0;
+      const message = errCode === "ENOENT" ? `Env file not found: ${envFilePath}` : `Failed to load --env-path ${envPath}: ${result.error.message}`;
+      throw new UserActionableError(message);
+    }
+    consola.log(colorize2("cyanBright", `Loaded environment variables from ${envFilePath}
+`));
+    return;
+  }
+  const loaded = AUTO_ENV_FILES.filter((file) => {
+    const envFilePath = resolve(cwd, file);
+    if (!existsSync(envFilePath)) {
+      return false;
+    }
+    return !config({ path: envFilePath, override: false }).error;
+  });
+  if (loaded.length > 0) {
+    consola.log(colorize2("cyanBright", `Loaded environment variables from ${loaded.join(", ")}
+`));
+  }
+}
 
 // src/cli/lib/get-module-cli-path.ts
 import { dirname, join as join2 } from "path";
@@ -743,14 +840,14 @@ function getModuleCliPath() {
 }
 
 // src/cli/lib/project-state.ts
-import { existsSync, readFileSync } from "fs";
+import { existsSync as existsSync2, readFileSync } from "fs";
 import { join as join3 } from "path";
-import { z as z5 } from "zod";
-var projectJsonSchema = z5.looseObject({
-  projectUuid: z5.string().optional()
+import { z as z6 } from "zod";
+var projectJsonSchema = z6.looseObject({
+  projectUuid: z6.string().optional()
 });
-var packageJsonSchema = z5.looseObject({
-  dependencies: z5.record(z5.string(), z5.string()).optional()
+var packageJsonSchema = z6.looseObject({
+  dependencies: z6.record(z6.string(), z6.string()).optional()
 });
 var safeReadJson = (path) => {
   try {
@@ -764,8 +861,8 @@ function getProjectState(cwd = process.cwd()) {
     safeReadJson(join3(cwd, ".bigcommerce", "project.json"))
   );
   const projectUuid = projectJson.success ? projectJson.data.projectUuid : void 0;
-  const hasMiddleware = existsSync(join3(cwd, "middleware.ts"));
-  const hasProxy = existsSync(join3(cwd, "proxy.ts"));
+  const hasMiddleware = existsSync2(join3(cwd, "middleware.ts"));
+  const hasProxy = existsSync2(join3(cwd, "proxy.ts"));
   const pkgJson = packageJsonSchema.safeParse(safeReadJson(join3(cwd, "package.json")));
   const hasOpenNextDep = pkgJson.success ? Boolean(pkgJson.data.dependencies?.["@opennextjs/cloudflare"]) : false;
   const isLinked = Boolean(projectUuid);
@@ -782,6 +879,34 @@ function getProjectState(cwd = process.cwd()) {
   };
 }
 
+// src/cli/lib/required-build-env.ts
+var REQUIRED_BUILD_ENV_VARS = [
+  "BIGCOMMERCE_STORE_HASH",
+  "BIGCOMMERCE_STOREFRONT_TOKEN",
+  "BIGCOMMERCE_CHANNEL_ID",
+  "AUTH_SECRET"
+];
+var findMissingBuildEnv = (env2 = process.env) => {
+  return REQUIRED_BUILD_ENV_VARS.filter((name) => {
+    const value = env2[name];
+    return value === void 0 || value.trim() === "";
+  });
+};
+var assertRequiredBuildEnv = (env2 = process.env) => {
+  const missing = findMissingBuildEnv(env2);
+  if (missing.length === 0) {
+    return;
+  }
+  const missingList = missing.map((name) => `  - ${name}`).join("\n");
+  throw new UserActionableError(
+    `Missing required environment variable${missing.length === 1 ? "" : "s"} for the build:
+${missingList}
+
+These are read by the build itself, so they must be set before it runs. The build automatically loads \`.env.local\` and \`.env\` from the current directory (${process.cwd()}) \u2014 add the variables above to one of those files (\`.env.local\` takes precedence).
+To load an env file from a different location, pass \`--env-path <path>\` (for example \`--env-path ../.env.local\` when running from a subdirectory).`
+  );
+};
+
 // src/cli/lib/wrangler-config.ts
 function getCompatibilityDate(now = /* @__PURE__ */ new Date()) {
   const date = new Date(now);
@@ -847,7 +972,17 @@ function getWranglerConfig(projectUuid) {
 
 // src/cli/commands/build.ts
 var WRANGLER_VERSION = "4.90.0";
-async function buildCatalystProject(projectUuid) {
+var DIST_TAG_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+var parseWranglerVersion = (value) => {
+  if (!validSemver(value) && !DIST_TAG_PATTERN.test(value)) {
+    throw new InvalidArgumentError(
+      `"${value}" is not a valid Wrangler version or dist-tag (e.g. 4.90.0 or latest).`
+    );
+  }
+  return value;
+};
+async function buildCatalystProject(projectUuid, wranglerVersion = WRANGLER_VERSION) {
+  assertRequiredBuildEnv();
   const coreDir = process.cwd();
   const openNextOutDir = join4(coreDir, ".open-next");
   const bigcommerceDistDir = join4(coreDir, ".bigcommerce", "dist");
@@ -864,7 +999,7 @@ async function buildCatalystProject(projectUuid) {
   );
   consola.success("Templates copied");
   consola.start("Building project...");
-  await execa(
+  await execa2(
     "pnpm",
     [
       "exec",
@@ -879,11 +1014,11 @@ async function buildCatalystProject(projectUuid) {
       cwd: coreDir
     }
   );
-  await execa(
+  await execa2(
     "pnpm",
     [
       "dlx",
-      `wrangler@${WRANGLER_VERSION}`,
+      `wrangler@${wranglerVersion}`,
       "deploy",
       "--config",
       join4(coreDir, ".bigcommerce", "wrangler.jsonc"),
@@ -912,18 +1047,28 @@ Examples:
   $ catalyst build
 
   # Include project UUID
-  $ catalyst build --project-uuid <UUID>`
+  $ catalyst build --project-uuid <UUID>
+
+  # Build with a specific Wrangler version
+  $ catalyst build --wrangler-version 4.24.3`
 ).addOption(
-  new Option3(
+  new Option2(
     "--project-uuid <uuid>",
     "Project UUID to be included in the deployment configuration."
   ).env("CATALYST_PROJECT_UUID")
-).action(async (options) => {
+).addOption(
+  new Option2(
+    "--wrangler-version <version>",
+    `Wrangler version or dist-tag to build with. Defaults to ${WRANGLER_VERSION}.`
+  ).argParser(parseWranglerVersion)
+).addOption(envPathOption()).action(async (options) => {
+  loadBuildEnv({ envPath: options.envPath });
   const state = getProjectState();
   if (!state.isTransformed) {
     consola.info("Project is not set up for Commerce Hosting \u2014 running `next build`.");
     consola.info("To deploy to Commerce Hosting, run `catalyst deploy`.");
-    await execa("pnpm", ["exec", "next", "build"], {
+    assertRequiredBuildEnv();
+    await execa2("pnpm", ["exec", "next", "build"], {
       stdio: "inherit",
       cwd: process.cwd()
     });
@@ -936,21 +1081,19 @@ Examples:
       "Project UUID is required. Please run `catalyst project create` or `catalyst project link` or this command again with --project-uuid <uuid>."
     );
   }
-  await buildCatalystProject(projectUuid);
+  await buildCatalystProject(projectUuid, options.wranglerVersion);
 });
 
 // src/cli/commands/channel.ts
-import { select as select3 } from "@inquirer/prompts";
-import { Command as Command3, InvalidArgumentError, Option as Option4 } from "commander";
-import { colorize as colorize3 } from "consola/utils";
-import { outputFileSync } from "fs-extra/esm";
-import { join as join6 } from "path";
+import { select as select4 } from "@inquirer/prompts";
+import { Command as Command3, InvalidArgumentError as InvalidArgumentError2, Option as Option3 } from "commander";
+import { colorize as colorize5 } from "consola/utils";
 
 // src/cli/lib/channel-site-flow.ts
 import { select as select2 } from "@inquirer/prompts";
 
 // src/cli/lib/channels.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var cliApiUrl = (origin, storeHash, path) => `${origin}/stores/${storeHash}/cli-api/v3${path}`;
 var channelsUrl = (storeHash, apiHost, query2 = {}) => {
   const params = new URLSearchParams(query2).toString();
@@ -961,14 +1104,14 @@ var authHeaders2 = (accessToken) => ({
   "X-Correlation-Id": getTelemetry().correlationId,
   Accept: "application/json"
 });
-var envVarsSchema = z6.record(z6.string(), z6.coerce.string());
-var channelSchema = z6.object({
-  id: z6.number(),
-  name: z6.string(),
-  platform: z6.string()
+var envVarsSchema = z7.record(z7.string(), z7.coerce.string());
+var channelSchema = z7.object({
+  id: z7.number(),
+  name: z7.string(),
+  platform: z7.string()
 });
-var channelsResponseSchema = z6.object({
-  data: z6.array(channelSchema)
+var channelsResponseSchema = z7.object({
+  data: z7.array(channelSchema)
 });
 var CHANNEL_PLATFORM_ORDER = ["catalyst", "next", "bigcommerce"];
 function sortChannelsByPlatform(channels) {
@@ -984,30 +1127,30 @@ function sortChannelsByPlatform(channels) {
 function channelPlatformLabel(platform) {
   return platform === "bigcommerce" ? "Stencil" : platform.charAt(0).toUpperCase() + platform.slice(1);
 }
-var initResponseSchema = z6.object({
-  data: z6.object({
-    storefront_api_token: z6.string(),
+var initResponseSchema = z7.object({
+  data: z7.object({
+    storefront_api_token: z7.string(),
     envVars: envVarsSchema
   })
 });
-var createChannelResponseSchema = z6.object({
-  data: z6.object({
-    id: z6.number(),
-    storefront_api_token: z6.string(),
+var createChannelResponseSchema = z7.object({
+  data: z7.object({
+    id: z7.number(),
+    storefront_api_token: z7.string(),
     envVars: envVarsSchema
   })
 });
-var eligibilityResponseSchema = z6.object({
-  data: z6.object({
-    eligible: z6.boolean(),
-    message: z6.string()
+var eligibilityResponseSchema = z7.object({
+  data: z7.object({
+    eligible: z7.boolean(),
+    message: z7.string()
   })
 });
-var channelSiteSchema = z6.object({
-  data: z6.object({
-    id: z6.number(),
-    url: z6.string(),
-    channel_id: z6.number()
+var channelSiteSchema = z7.object({
+  data: z7.object({
+    id: z7.number(),
+    url: z7.string(),
+    channel_id: z7.number()
   })
 });
 async function getChannelInit(channelId, storeHash, accessToken, origin) {
@@ -1016,9 +1159,7 @@ async function getChannelInit(channelId, storeHash, accessToken, origin) {
     headers: authHeaders2(accessToken)
   });
   if (!response.ok) {
-    throw new Error(
-      `GET /channels/${channelId}/init failed: ${response.status} ${response.statusText}`
-    );
+    throw await httpError(response, "Failed to initialize channel");
   }
   const { data } = initResponseSchema.parse(await response.json());
   return { storefrontToken: data.storefront_api_token, envVars: data.envVars };
@@ -1029,9 +1170,7 @@ async function checkChannelEligibility(storeHash, accessToken, origin) {
     headers: authHeaders2(accessToken)
   });
   if (!response.ok) {
-    throw new Error(
-      `GET /channels/catalyst/eligibility failed: ${response.status} ${response.statusText}`
-    );
+    throw await httpError(response, "Failed to check Catalyst eligibility");
   }
   return eligibilityResponseSchema.parse(await response.json()).data;
 }
@@ -1049,7 +1188,7 @@ async function createChannel(name, storefrontLocale, additionalLocales, installS
     })
   });
   if (!response.ok) {
-    throw new Error(`POST /channels/catalyst failed: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to create channel");
   }
   const { data } = createChannelResponseSchema.parse(await response.json());
   return {
@@ -1072,7 +1211,7 @@ async function fetchAvailableChannels(storeHash, accessToken, apiHost) {
   );
   assertAuthorized(response);
   if (!response.ok) {
-    throw new Error(`GET /v3/channels failed: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to fetch channels");
   }
   return channelsResponseSchema.parse(await response.json()).data;
 }
@@ -1091,12 +1230,12 @@ async function updateChannelSiteUrl(channelId, siteUrl, storeHash, accessToken,
     }
   );
   if (response.status === 401 || response.status === 403) {
-    throw new Error(
+    throw new UserActionableError(
       `Failed to update channel site (${response.status}). Re-run \`catalyst auth login\` to refresh your access token with the store_channel_settings scope.`
     );
   }
   if (!response.ok) {
-    throw new Error(`Failed to update channel site: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to update channel site");
   }
   const res = await response.json();
   const { data } = channelSiteSchema.parse(res);
@@ -1105,18 +1244,10 @@ async function updateChannelSiteUrl(channelId, siteUrl, storeHash, accessToken,
 
 // src/cli/lib/commerce-hosting.ts
 import { confirm as confirm2, input as input2, select, Separator } from "@inquirer/prompts";
-import { colorize as colorize2 } from "consola/utils";
-import {
-  existsSync as existsSync2,
-  lstatSync,
-  mkdirSync,
-  readFileSync as readFileSync2,
-  symlinkSync,
-  unlinkSync,
-  writeFileSync
-} from "fs";
+import { colorize as colorize3 } from "consola/utils";
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync2, unlinkSync, writeFileSync } from "fs";
 import { dirname as dirname2, join as join5 } from "path";
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 
 // src/cli/lib/sort-package-json.ts
 var FIELD_ORDER = [
@@ -1146,65 +1277,51 @@ function sortPackageJsonFields(pkg) {
 
 // src/cli/lib/commerce-hosting.ts
 var OPENNEXT_CLOUDFLARE_VERSION = "1.17.3";
-var corePackageJsonSchema = z7.looseObject({
-  dependencies: z7.record(z7.string(), z7.string()).optional()
+var corePackageJsonSchema = z8.looseObject({
+  dependencies: z8.record(z8.string(), z8.string()).optional()
 });
 var writeJson = (path, value) => {
   mkdirSync(dirname2(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify(value, null, 2)}
 `);
 };
-var symlinkRootEnvToCore = (projectDir) => {
-  const coreEnvPath = join5(projectDir, "core", ".env.local");
-  if (lstatSync(coreEnvPath, { throwIfNoEntry: false })) return;
-  try {
-    symlinkSync("../.env.local", coreEnvPath);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "unknown error";
-    consola.warn(
-      `Could not create symlink at core/.env.local: ${message}
-On Windows, enable Developer Mode or run as administrator to allow symlinks.
-You will need to keep .env.local and core/.env.local in sync manually.`
-    );
-  }
-};
 var convertProxyToMiddleware = (projectDir) => {
-  const proxyPath = join5(projectDir, "core", "proxy.ts");
-  const middlewarePath = join5(projectDir, "core", "middleware.ts");
-  if (!existsSync2(proxyPath)) return;
+  const proxyPath = join5(projectDir, "proxy.ts");
+  const middlewarePath = join5(projectDir, "middleware.ts");
+  if (!existsSync3(proxyPath)) return;
   const contents = readFileSync2(proxyPath, "utf-8").replace("export const proxy", "export const middleware").replace("export const config = {", "export const config = {\n  runtime: 'experimental-edge',");
   writeFileSync(middlewarePath, contents);
   unlinkSync(proxyPath);
 };
 var cleanupCloudflareIncompatibilities = async (projectDir) => {
-  const instrumentationPath = join5(projectDir, "core", "instrumentation.ts");
-  if (!existsSync2(instrumentationPath)) return;
+  const instrumentationPath = join5(projectDir, "instrumentation.ts");
+  if (!existsSync3(instrumentationPath)) return;
   if (!process.stdin.isTTY) {
     consola.warn(
-      "core/instrumentation.ts is present and may be incompatible with the Cloudflare Workers bundle (the default @vercel/otel scaffolding throws at cold start under workerd). Skipping automatic cleanup in non-interactive mode \u2014 re-run interactively to remove it, or delete/gate it manually."
+      "instrumentation.ts is present and may be incompatible with the Cloudflare Workers bundle (the default @vercel/otel scaffolding throws at cold start under workerd). Skipping automatic cleanup in non-interactive mode \u2014 re-run interactively to remove it, or delete/gate it manually."
     );
     return;
   }
   const shouldRemove = await confirm2({
-    message: 'Catalyst found core/instrumentation.ts, which is incompatible with the Cloudflare Workers bundle when it uses @vercel/otel (causes "Failed to prepare server" at cold start). Remove it and drop @vercel/otel from core/package.json?',
+    message: 'Catalyst found instrumentation.ts, which is incompatible with the Cloudflare Workers bundle when it uses @vercel/otel (causes "Failed to prepare server" at cold start). Remove it and drop @vercel/otel from package.json?',
     default: true
   });
   if (!shouldRemove) {
     consola.info(
-      'Leaving core/instrumentation.ts in place. The Cloudflare worker will continue to log "Failed to prepare server" at cold start until this is resolved manually.'
+      'Leaving instrumentation.ts in place. The Cloudflare worker will continue to log "Failed to prepare server" at cold start until this is resolved manually.'
     );
     return;
   }
   unlinkSync(instrumentationPath);
-  consola.info("Removed core/instrumentation.ts (incompatible with Cloudflare Workers).");
-  const corePackageJsonPath = join5(projectDir, "core", "package.json");
-  if (existsSync2(corePackageJsonPath)) {
+  consola.info("Removed instrumentation.ts (incompatible with Cloudflare Workers).");
+  const corePackageJsonPath = join5(projectDir, "package.json");
+  if (existsSync3(corePackageJsonPath)) {
     const pkg = corePackageJsonSchema.parse(JSON.parse(readFileSync2(corePackageJsonPath, "utf-8")));
     if (pkg.dependencies && "@vercel/otel" in pkg.dependencies) {
       const { "@vercel/otel": _removedVercelOtel, ...preservedDeps } = pkg.dependencies;
       pkg.dependencies = preservedDeps;
       writeJson(corePackageJsonPath, sortPackageJsonFields(pkg));
-      consola.info("Dropped @vercel/otel from core/package.json.");
+      consola.info("Dropped @vercel/otel from package.json.");
     }
   }
 };
@@ -1215,7 +1332,7 @@ var setupCommerceHosting = async ({
   accessToken
 }) => {
   await cleanupCloudflareIncompatibilities(projectDir);
-  const corePackageJsonPath = join5(projectDir, "core", "package.json");
+  const corePackageJsonPath = join5(projectDir, "package.json");
   const pkg = corePackageJsonSchema.parse(JSON.parse(readFileSync2(corePackageJsonPath, "utf-8")));
   pkg.dependencies = {
     ...pkg.dependencies,
@@ -1228,8 +1345,7 @@ var setupCommerceHosting = async ({
   };
   if (storeHash) projectJson.storeHash = storeHash;
   if (accessToken) projectJson.accessToken = accessToken;
-  writeJson(join5(projectDir, "core", ".bigcommerce", "project.json"), projectJson);
-  symlinkRootEnvToCore(projectDir);
+  writeJson(join5(projectDir, ".bigcommerce", "project.json"), projectJson);
   convertProxyToMiddleware(projectDir);
 };
 var NoLinkedProjectError = class extends Error {
@@ -1260,7 +1376,7 @@ async function selectOrCreateInfrastructureProject(api, linkedProjectUuid) {
   }
   const choices = [
     ...existingProjects.map((p) => ({
-      name: p.uuid === linkedProjectUuid ? `${p.name} ${colorize2("green", "[linked]")}` : p.name,
+      name: p.uuid === linkedProjectUuid ? `${p.name} ${colorize3("green", "[linked]")}` : p.name,
       value: p.uuid,
       description: p.uuid
     })),
@@ -1357,7 +1473,7 @@ async function promptAndCreateCommerceHostingProject(api, takenNames, defaultNam
     },
     theme: {
       style: {
-        help: () => colorize2(
+        help: () => colorize3(
           "dim",
           "(The project that hosts your storefront on Commerce \u2014 often matches your folder name.)"
         )
@@ -1503,17 +1619,149 @@ async function runChannelSiteUrlFlow(options) {
   consola.success(`Updated channel ${channelLabel} site URL to ${siteUrl}.`);
 }
 
+// src/cli/lib/create-channel-flow.ts
+import { checkbox, input as input3, select as select3 } from "@inquirer/prompts";
+import { colorize as colorize4 } from "consola/utils";
+
+// src/cli/lib/localization.ts
+import { z as z9 } from "zod";
+var allowedLocales = [
+  "en",
+  "da",
+  "es-AR",
+  "es-CL",
+  "es-CO",
+  "es-MX",
+  "es-PE",
+  "es-419",
+  "es",
+  "it",
+  "nl",
+  "pl",
+  "pt",
+  "de",
+  "fr",
+  "ja",
+  "no",
+  "pt-BR",
+  "sv"
+];
+var AvailableLocalesSuccessSchema = z9.object({
+  data: z9.array(
+    z9.object({
+      id: z9.string(),
+      name: z9.string(),
+      fallback: z9.string().nullable(),
+      is_supported: z9.boolean()
+    })
+  )
+});
+var getAvailableLocales = async (storeHash, accessToken, apiHost) => {
+  const response = await fetch(
+    `https://${apiHost}/stores/${storeHash}/v3/settings/store/available-locales`,
+    {
+      method: "GET",
+      headers: {
+        "X-Auth-Token": accessToken,
+        "X-Correlation-Id": getTelemetry().correlationId,
+        Accept: "application/json"
+      }
+    }
+  );
+  assertAuthorized(response);
+  if (!response.ok) {
+    throw await httpError(response, "Failed to fetch available locales");
+  }
+  return AvailableLocalesSuccessSchema.parse(await response.json()).data.filter(({ id }) => allowedLocales.includes(id)).map(({ name, id }) => ({ name: `${name} (${id})`, value: id }));
+};
+
+// src/cli/lib/create-channel-flow.ts
+var ALLOWED_CHANNEL_NAME_CHARS = "letters, numbers, spaces, hyphens (-), and underscores (_)";
+var CHANNEL_NAME_PATTERN = /^[\p{L}\p{N} _-]+$/u;
+function getChannelNameError(name) {
+  if (name.trim().length === 0) {
+    return "Channel name cannot be empty.";
+  }
+  if (!CHANNEL_NAME_PATTERN.test(name)) {
+    return `"${name}" is not a valid channel name. Channel names may contain only ${ALLOWED_CHANNEL_NAME_CHARS}.`;
+  }
+  return void 0;
+}
+async function runCreateChannelFlow(options) {
+  const { storeHash, accessToken, apiHost, cliApiOrigin } = options;
+  if (options.name !== void 0) {
+    const nameError = getChannelNameError(options.name);
+    if (nameError) {
+      throw new UserActionableError(nameError);
+    }
+  }
+  const name = options.name ?? await input3({
+    message: "What would you like to name your new channel?",
+    validate: (value) => getChannelNameError(value) ?? true
+  });
+  let availableLocales;
+  const loadLocales = async () => {
+    availableLocales ?? (availableLocales = await getAvailableLocales(storeHash, accessToken, apiHost));
+    return availableLocales;
+  };
+  const storefrontLocale = options.locale ?? await select3({
+    message: "Which default language would you like to set for your channel?",
+    default: "en",
+    choices: await loadLocales(),
+    theme: {
+      style: {
+        help: () => colorize4("dim", "(Select locale from the list or start typing the name)")
+      }
+    }
+  });
+  let additionalLocales = options.additionalLocales;
+  if (additionalLocales === void 0) {
+    const shouldAddAdditionalLocales = await select3({
+      message: "Would you like to add additional languages?",
+      choices: [
+        { name: "Yes", value: true },
+        { name: "No", value: false }
+      ]
+    });
+    additionalLocales = [];
+    if (shouldAddAdditionalLocales) {
+      const localeChoices = (await loadLocales()).filter(({ value }) => value !== storefrontLocale).map(({ name: localeName, value }) => ({ name: localeName, value, description: value }));
+      additionalLocales = await checkbox({
+        message: "Which additional languages would you like to add to your channel?",
+        choices: localeChoices,
+        validate: (items) => items.length <= 4 || "You can only select up to 4 additional languages."
+      });
+    }
+  }
+  const shouldInstallSampleData = options.sampleData ?? await select3({
+    message: "Would you like to install sample data?",
+    choices: [
+      { name: "Yes", value: true },
+      { name: "No", value: false }
+    ]
+  });
+  return createChannel(
+    name,
+    storefrontLocale,
+    additionalLocales,
+    shouldInstallSampleData,
+    storeHash,
+    accessToken,
+    cliApiOrigin
+  );
+}
+
 // src/cli/lib/env-config.ts
 var ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
-var parseEnvAssignment = (input5) => {
-  const separatorIndex = input5.indexOf("=");
+var parseEnvAssignment = (input6) => {
+  const separatorIndex = input6.indexOf("=");
   if (separatorIndex === -1) {
-    throw new Error(`Invalid env var format: ${input5}. Expected format: KEY=VALUE`);
+    throw new Error(`Invalid env var format: ${input6}. Expected format: KEY=VALUE`);
   }
-  const key = input5.slice(0, separatorIndex).trim();
-  const value = input5.slice(separatorIndex + 1).trim();
+  const key = input6.slice(0, separatorIndex).trim();
+  const value = input6.slice(separatorIndex + 1).trim();
   if (!key || !value) {
-    throw new Error(`Invalid env var format: ${input5}. Expected format: KEY=VALUE`);
+    throw new Error(`Invalid env var format: ${input6}. Expected format: KEY=VALUE`);
   }
   if (!ENV_KEY_PATTERN.test(key)) {
     throw new Error(
@@ -1550,22 +1798,89 @@ function resolveCredentials(options, config2) {
   return { storeHash, accessToken };
 }
 
+// src/cli/lib/write-env.ts
+import { outputFileSync } from "fs-extra/esm";
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
+import { join as join6 } from "path";
+var ACTIVE_KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+var keyFromLine = (line) => {
+  const match = ACTIVE_KEY_LINE.exec(line);
+  return match ? match[1] : null;
+};
+var parseEnvValues = (contents) => {
+  const values = /* @__PURE__ */ new Map();
+  contents.split("\n").forEach((line) => {
+    const match = ACTIVE_KEY_LINE.exec(line);
+    if (match) {
+      values.set(match[1], match[2]);
+    }
+  });
+  return values;
+};
+var writeEnv = (projectDir, envVars) => {
+  const examplePath = join6(projectDir, ".env.example");
+  const localPath = join6(projectDir, ".env.local");
+  const existingLocal = existsSync4(localPath) ? parseEnvValues(readFileSync3(localPath, "utf-8")) : /* @__PURE__ */ new Map();
+  const resolve2 = (key) => {
+    if (key in envVars && envVars[key] !== "") {
+      return envVars[key];
+    }
+    return existingLocal.get(key);
+  };
+  if (!existsSync4(examplePath)) {
+    const keys = [.../* @__PURE__ */ new Set([...existingLocal.keys(), ...Object.keys(envVars)])];
+    outputFileSync(localPath, `${keys.map((key) => `${key}=${resolve2(key) ?? ""}`).join("\n")}
+`);
+    return;
+  }
+  const exampleLines = readFileSync3(examplePath, "utf-8").replace(/\n$/, "").split("\n");
+  const exampleKeys = /* @__PURE__ */ new Set();
+  const lines = exampleLines.map((line) => {
+    const key = keyFromLine(line);
+    if (key === null) {
+      return line;
+    }
+    exampleKeys.add(key);
+    const value = resolve2(key);
+    return value === void 0 ? line : `${key}=${value}`;
+  });
+  const extraKeys = [];
+  [...existingLocal.keys()].forEach((key) => {
+    if (!exampleKeys.has(key)) {
+      extraKeys.push(key);
+    }
+  });
+  Object.keys(envVars).forEach((key) => {
+    if (!exampleKeys.has(key) && !extraKeys.includes(key)) {
+      extraKeys.push(key);
+    }
+  });
+  if (extraKeys.length > 0) {
+    lines.push("", "# Additional variables set by the Catalyst CLI (not in .env.example).");
+    extraKeys.forEach((key) => {
+      lines.push(`${key}=${resolve2(key) ?? ""}`);
+    });
+  }
+  outputFileSync(localPath, `${lines.join("\n")}
+`);
+};
+
 // src/cli/commands/channel.ts
 var parseChannelId = (value) => {
   const parsed = Number.parseInt(value, 10);
   if (Number.isNaN(parsed)) {
-    throw new InvalidArgumentError(`"${value}" is not a valid channel ID (expected a number).`);
+    throw new InvalidArgumentError2(`"${value}" is not a valid channel ID (expected a number).`);
   }
   return parsed;
 };
-async function resolveCredentialsWithLogin(options, config2) {
+async function resolveCredentialsWithLogin(options, config2, apiHost) {
   const storeHash = options.storeHash ?? config2.get("storeHash");
   const accessToken = options.accessToken ?? config2.get("accessToken");
   if (storeHash && accessToken) {
     return { storeHash, accessToken };
   }
   try {
-    const credentials = await login(options.loginUrl, options.apiHost);
+    const credentials = await login(options.loginUrl, apiHost);
     config2.set("storeHash", credentials.storeHash);
     config2.set("accessToken", credentials.accessToken);
     return credentials;
@@ -1588,24 +1903,25 @@ Examples:
   # Skip both prompts
   $ catalyst channel update --channel-id 123 --hostname my-storefront.example.com`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).addOption(
-  new Option4(
+  new Option3(
     "--channel-id <id>",
     "Skip the channel prompt and target this channel directly."
   ).argParser((value) => Number(value))
 ).addOption(
-  new Option4(
+  new Option3(
     "--hostname <hostname>",
     "Skip the hostname prompt and use this hostname directly. Must be one of the project's deployment_hostnames."
   )
 ).action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   await getTelemetry().identify(storeHash);
   try {
     await runChannelSiteUrlFlow({
       storeHash,
       accessToken,
-      apiHost: options.apiHost,
+      apiHost,
       projectUuid: options.projectUuid ?? config2.get("projectUuid"),
       channelId: options.channelId,
       hostname: options.hostname
@@ -1637,17 +1953,18 @@ Examples:
   # Append extra environment variables to .env.local
   $ catalyst channel link --channel-id 123 --env MY_FLAG=1`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).addOption(
-  new Option4("--channel-id <id>", "Link this channel directly, skipping the picker.").argParser(
+  new Option3("--channel-id <id>", "Link this channel directly, skipping the picker.").argParser(
     parseChannelId
   )
 ).option(
   "--env <vars...>",
   "Arbitrary environment variables to set in .env.local. Format: KEY=VALUE (repeatable)."
 ).addOption(
-  new Option4("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
+  new Option3("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
 ).action(async (options) => {
   const config2 = getProjectConfig();
-  const credentials = await resolveCredentialsWithLogin(options, config2);
+  const apiHost = resolveApiHost(options, config2);
+  const credentials = await resolveCredentialsWithLogin(options, config2, apiHost);
   if (!credentials) {
     consola.info(
       "Login aborted. Re-run `catalyst channel link` when you have your credentials ready."
@@ -1660,7 +1977,7 @@ Examples:
   let channelId = options.channelId;
   let channelName;
   if (channelId === void 0) {
-    const channels = await fetchAvailableChannels(storeHash, accessToken, options.apiHost);
+    const channels = await fetchAvailableChannels(storeHash, accessToken, apiHost);
     if (channels.length === 0) {
       consola.info(
         "No storefront channels found on this store. Create one with `catalyst create` and try again."
@@ -1668,7 +1985,7 @@ Examples:
       process.exit(0);
       return;
     }
-    channelId = await select3({
+    channelId = await select4({
       message: "Which channel would you like to link?",
       choices: sortChannelsByPlatform(channels).map((c) => ({
         name: c.name,
@@ -1686,164 +2003,226 @@ Examples:
       envVars[key] = value;
     });
   }
-  outputFileSync(
-    join6(process.cwd(), ".env.local"),
-    `${Object.entries(envVars).map(([key, value]) => `${key}=${value}`).join("\n")}
-`
-  );
+  writeEnv(process.cwd(), envVars);
   const label = channelName ? `"${channelName}" (${channelId})` : `${channelId}`;
   consola.success(
-    `Linked to channel ${label} and wrote ${colorize3("cyanBright", ".env.local")}.`
+    `Linked to channel ${label} and wrote ${colorize5("cyanBright", ".env.local")}.`
   );
   consola.log(`Next steps:
 
-  ${colorize3("yellow", "pnpm run dev")}`);
+  ${colorize5("yellow", "pnpm run dev")}`);
   process.exit(0);
 });
-var channel = new Command3("channel").configureHelp({ showGlobalOptions: true }).description("Manage BigCommerce channels.").addCommand(link).addCommand(update);
+var create = new Command3("create").configureHelp({ showGlobalOptions: true }).description("Create a new Catalyst storefront channel on your BigCommerce store.").addHelpText(
+  "after",
+  `
+Examples:
+  # Create a channel interactively (logs you in if needed)
+  $ catalyst channel create
 
-// src/cli/commands/create.ts
-import { Command as Command4, InvalidArgumentError as InvalidArgumentError2, Option as Option5 } from "@commander-js/extra-typings";
-import { checkbox, input as input3, select as select4 } from "@inquirer/prompts";
-import { execSync as execSync4 } from "child_process";
-import { colorize as colorize4 } from "consola/utils";
-import { pathExistsSync } from "fs-extra/esm";
-import kebabCase from "lodash.kebabcase";
-import { join as join10 } from "path";
+  # Non-interactive, and link it to this project afterwards
+  $ catalyst channel create --name "My Store" --locale en --no-sample-data --link
 
-// src/cli/lib/build-workspace-packages.ts
-import { execSync } from "child_process";
-import { existsSync as existsSync3 } from "fs";
-import { join as join7 } from "path";
-import yoctoSpinner2 from "yocto-spinner";
-var WORKSPACE_PACKAGES = ["packages/catalyst", "packages/client"];
-var buildWorkspacePackages = (projectDir) => {
-  const hasCore = existsSync3(join7(projectDir, "core"));
-  const hasAllWorkspacePackages = WORKSPACE_PACKAGES.every(
-    (pkg) => existsSync3(join7(projectDir, pkg))
+  # Add additional storefront languages (max 4)
+  $ catalyst channel create --name "My Store" --additional-locales es fr`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).option("--name <name>", "Name for the new channel. Skips the name prompt.").option(
+  "--locale <locale>",
+  'Default storefront locale (e.g. "en"). Skips the default-language prompt.'
+).option(
+  "--additional-locales <locales...>",
+  "Additional storefront locales, max 4 (e.g. --additional-locales es fr). Skips the additional-languages prompt."
+).addOption(new Option3("--sample-data", "Install sample data on the new channel.")).addOption(new Option3("--no-sample-data", "Create the channel without sample data.")).option(
+  "--link",
+  "Link the new channel to this project \u2014 write its credentials to .env.local without prompting."
+).addOption(
+  new Option3("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
+).action(async (options) => {
+  if (options.additionalLocales && options.additionalLocales.length > 4) {
+    consola.error("You can only set up to 4 additional locales.");
+    process.exit(1);
+    return;
+  }
+  const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
+  const credentials = await resolveCredentialsWithLogin(options, config2, apiHost);
+  if (!credentials) {
+    consola.info(
+      "Login aborted. Re-run `catalyst channel create` when you have your credentials ready."
+    );
+    process.exit(0);
+    return;
+  }
+  const { storeHash, accessToken } = credentials;
+  await getTelemetry().identify(storeHash);
+  const eligibility = await checkChannelEligibility(storeHash, accessToken, options.cliApiOrigin);
+  if (!eligibility.eligible) {
+    consola.warn(eligibility.message);
+    process.exit(0);
+    return;
+  }
+  const channelData = await runCreateChannelFlow({
+    storeHash,
+    accessToken,
+    apiHost,
+    cliApiOrigin: options.cliApiOrigin,
+    name: options.name,
+    locale: options.locale,
+    additionalLocales: options.additionalLocales,
+    sampleData: options.sampleData
+  });
+  consola.success(`Created channel ${channelData.channelId}.`);
+  consola.warn(
+    "A preview storefront has been deployed in your BigCommerce control panel. This preview may look different from your local environment as it may be running different code. Additionally, it may take a few minutes for the channel storefront to be accessible."
   );
-  if (!hasCore || !hasAllWorkspacePackages) return;
-  WORKSPACE_PACKAGES.forEach((pkg) => {
-    const spinner = yoctoSpinner2().start(`Building ${pkg}...`);
-    try {
-      execSync("pnpm build", { cwd: join7(projectDir, pkg), stdio: "ignore" });
-      spinner.success(`Built ${pkg}.`);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "unknown error";
-      spinner.error(`Failed to build ${pkg}: ${message}`);
-      throw error;
-    }
+  const shouldLink = options.link ? true : await select4({
+    message: "Would you like to link this channel to your project?",
+    choices: [
+      { name: "Yes", value: true },
+      { name: "No", value: false }
+    ]
   });
-};
-
-// src/cli/lib/clone-catalyst.ts
-import { execSync as execSync3 } from "child_process";
+  if (shouldLink) {
+    writeEnv(process.cwd(), channelData.envVars);
+    consola.success(
+      `Linked to channel ${channelData.channelId} and wrote ${colorize5("cyanBright", ".env.local")}.`
+    );
+    consola.log(`Next steps:
 
-// src/cli/lib/checkout-ref.ts
-import { sync as spawnSync } from "cross-spawn";
+  ${colorize5("yellow", "pnpm run dev")}`);
+  }
+  process.exit(0);
+});
+var channel = new Command3("channel").configureHelp({ showGlobalOptions: true }).description("Manage BigCommerce channels.").addCommand(create).addCommand(link).addCommand(update);
 
-// src/cli/lib/is-exec-exception.ts
-function isExecException(error) {
-  return typeof error === "object" && error !== null && "stdout" in error && "stderr" in error;
-}
+// src/cli/commands/create.ts
+import { Command as Command4, InvalidArgumentError as InvalidArgumentError3, Option as Option4 } from "@commander-js/extra-typings";
+import { input as input4, select as select5 } from "@inquirer/prompts";
+import { execSync as execSync2 } from "child_process";
+import { colorize as colorize6 } from "consola/utils";
+import { pathExistsSync } from "fs-extra/esm";
+import kebabCase from "lodash.kebabcase";
+import { join as join10 } from "path";
 
-// src/cli/lib/checkout-ref.ts
-function checkoutRef(repoDir, ref) {
-  try {
-    const spawn = spawnSync("git", ["checkout", ref, "--"], {
-      cwd: repoDir,
-      encoding: "utf8",
-      shell: false
-    });
-    const stderr = spawn.stderr.trim();
-    if (spawn.status !== 0 && stderr) {
-      throw new Error(stderr);
-    }
-    consola.success(`Checked out ref ${ref} successfully.`);
-  } catch (error) {
-    if (isExecException(error)) {
-      const stderr = error.stderr ? error.stderr.toString() : "";
-      if (stderr.includes(`fatal: reference is not a tree: ${ref}`) || stderr.includes(`fatal: ambiguous argument '${ref}'`) || stderr.includes(`unknown revision or path not in the working tree`)) {
-        consola.error(`Ref '${ref}' not found in the repository.`);
-      } else {
-        consola.error(`Error checking out ref '${ref}':`, stderr.trim());
-      }
-    } else if (error instanceof Error) {
-      consola.error(`Error checking out ref '${ref}':`, error.message);
-    } else {
-      consola.error(`Unknown error occurred while checking out ref '${ref}'.`);
-    }
-    consola.warn(`Falling back to the default branch.`);
+// src/cli/lib/detect-package-manager.ts
+import { detectPackageManager as detectFromDir } from "nypm";
+var detectPackageManager = () => {
+  const userAgent = process.env.npm_config_user_agent ?? "";
+  const name = userAgent.split(" ")[0]?.split("/")[0];
+  if (name === "pnpm" || name === "yarn" || name === "bun") {
+    return name;
+  }
+  if (process.versions.bun) {
+    return "bun";
+  }
+  return "npm";
+};
+var detectProjectPackageManager = async (projectDir) => {
+  const detected = await detectFromDir(projectDir);
+  const name = detected?.name;
+  if (name === "pnpm" || name === "yarn" || name === "bun" || name === "npm") {
+    return name;
   }
-}
+  return "npm";
+};
 
-// src/cli/lib/has-github-ssh.ts
-import { execSync as execSync2 } from "child_process";
-function hasGitHubSSH() {
+// src/cli/lib/extract-catalyst.ts
+import { mkdirSync as mkdirSync2 } from "fs";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+import { x } from "tar";
+var SUBDIR = "core";
+var MAX_ATTEMPTS = 3;
+var codeloadUrl = (repository, ref) => `https://codeload.github.com/${repository}/tar.gz/${encodeURIComponent(ref)}`;
+var wait = (ms) => new Promise((resolve2) => {
+  setTimeout(resolve2, ms);
+});
+var downloadAndExtract = async (repository, ref, projectDir) => {
+  const url = codeloadUrl(repository, ref);
+  const response = await fetch(url);
+  if (!response.ok || !response.body) {
+    throw new Error(`Failed to download ${url} (HTTP ${response.status})`);
+  }
+  await pipeline(
+    // Node's global fetch types `body` as the DOM ReadableStream; it is the same
+    // object Readable.fromWeb expects at runtime.
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    Readable.fromWeb(response.body),
+    x({
+      cwd: projectDir,
+      strip: 2,
+      filter: (path) => path.split("/")[1] === SUBDIR
+    })
+  );
+};
+var attemptDownload = async (repository, ref, projectDir, attempt = 1) => {
   try {
-    const output = execSync2("ssh -T git@github.com", {
-      encoding: "utf8",
-      stdio: "pipe"
-    }).toString();
-    return output.includes("successfully authenticated");
+    await downloadAndExtract(repository, ref, projectDir);
   } catch (error) {
-    if (isExecException(error)) {
-      const stdout = error.stdout ? error.stdout.toString() : "";
-      const stderr = error.stderr ? error.stderr.toString() : "";
-      const combinedOutput = stdout + stderr;
-      if (combinedOutput.includes("successfully authenticated")) {
-        return true;
-      }
+    const message = error instanceof Error ? error.message : "unknown error";
+    if (attempt >= MAX_ATTEMPTS) {
+      throw new Error(`Failed to download Catalyst after ${MAX_ATTEMPTS} attempts: ${message}`);
     }
-    return false;
-  }
-}
-
-// src/cli/lib/reset-branch-to-ref.ts
-import { sync as spawnSync2 } from "cross-spawn";
-function resetBranchToRef(projectDir, ghRef) {
-  const spawn = spawnSync2("git", ["reset", "--hard", ghRef, "--"], {
-    cwd: projectDir,
-    encoding: "utf8",
-    shell: false
-  });
-  const stderr = spawn.stderr.trim();
-  if (spawn.status !== 0 && stderr) {
-    throw new Error(stderr);
+    consola.warn(`Download attempt ${attempt} failed (${message}). Retrying...`);
+    await wait(attempt * 1e3);
+    return attemptDownload(repository, ref, projectDir, attempt + 1);
   }
-}
-
-// src/cli/lib/clone-catalyst.ts
-var cloneCatalyst = ({
+};
+var extractCatalyst = async ({
   repository,
-  projectName,
-  projectDir,
-  ghRef,
-  resetMain = false
+  ref,
+  projectDir
 }) => {
-  const useSSH = hasGitHubSSH();
-  consola.info(`Cloning ${repository} using ${useSSH ? "SSH" : "HTTPS"}...`);
-  const cloneCommand = `git clone ${useSSH ? `git@github.com:${repository}` : `https://github.com/${repository}`}.git${projectName ? ` ${projectName}` : ""}`;
-  execSync3(cloneCommand, { stdio: "inherit" });
-  execSync3("git remote rename origin upstream", { cwd: projectDir, stdio: "inherit" });
-  if (ghRef) {
-    if (resetMain) {
-      execSync3("git checkout -b main", { cwd: projectDir, stdio: "inherit" });
-      resetBranchToRef(projectDir, ghRef);
-      consola.success(`Reset main to ${ghRef} successfully.`);
-      return;
-    }
-    checkoutRef(projectDir, ghRef);
+  consola.info(`Downloading ${repository}#${ref}...`);
+  mkdirSync2(projectDir, { recursive: true });
+  await attemptDownload(repository, ref, projectDir);
+};
+
+// src/cli/lib/init-git-repo.ts
+import { execSync } from "child_process";
+import { rmSync } from "fs";
+import { join as join7 } from "path";
+var run = (command, cwd) => execSync(command, { cwd, stdio: "ignore" });
+var initGitRepo = (projectDir) => {
+  try {
+    run("git init", projectDir);
+    run("git add -A", projectDir);
+    run('git commit -m "Initial commit from Catalyst"', projectDir);
+    consola.success("Initialized a git repository.");
+  } catch {
+    rmSync(join7(projectDir, ".git"), { recursive: true, force: true });
+    consola.warn("Could not initialize a git repository. Skipping.");
   }
 };
 
 // src/cli/lib/install-dependencies.ts
 import { installDependencies as installDeps } from "nypm";
-import yoctoSpinner3 from "yocto-spinner";
-var installDependencies = async (projectDir) => {
-  const spinner = yoctoSpinner3().start("Installing dependencies. This could take a minute...");
+import yoctoSpinner2 from "yocto-spinner";
+var restoreEnv = (key, previous) => {
+  if (previous === void 0) {
+    Reflect.deleteProperty(process.env, key);
+  } else {
+    process.env[key] = previous;
+  }
+};
+var withQuietInstallEnv = async (run2) => {
+  var _a, _b;
+  const prevNodeNoWarnings = process.env.NODE_NO_WARNINGS;
+  const prevDownloadPrompt = process.env.COREPACK_ENABLE_DOWNLOAD_PROMPT;
+  (_a = process.env).NODE_NO_WARNINGS ?? (_a.NODE_NO_WARNINGS = "1");
+  (_b = process.env).COREPACK_ENABLE_DOWNLOAD_PROMPT ?? (_b.COREPACK_ENABLE_DOWNLOAD_PROMPT = "0");
+  try {
+    return await run2();
+  } finally {
+    restoreEnv("NODE_NO_WARNINGS", prevNodeNoWarnings);
+    restoreEnv("COREPACK_ENABLE_DOWNLOAD_PROMPT", prevDownloadPrompt);
+  }
+};
+var installDependencies = async (projectDir, packageManager = "pnpm") => {
+  const spinner = yoctoSpinner2().start(
+    `Installing dependencies with ${packageManager}. This could take a minute...`
+  );
   try {
-    await installDeps({ cwd: projectDir, silent: true, packageManager: "pnpm" });
+    await withQuietInstallEnv(() => installDeps({ cwd: projectDir, silent: true, packageManager }));
     spinner.success("Dependencies installed successfully.");
   } catch (error) {
     const message = error instanceof Error ? error.message : "unknown error";
@@ -1852,100 +2231,107 @@ var installDependencies = async (projectDir) => {
   }
 };
 
-// src/cli/lib/localization.ts
-import { z as z8 } from "zod";
-var allowedLocales = [
-  "en",
-  "da",
-  "es-AR",
-  "es-CL",
-  "es-CO",
-  "es-MX",
-  "es-PE",
-  "es-419",
-  "es",
-  "it",
-  "nl",
-  "pl",
-  "pt",
-  "de",
-  "fr",
-  "ja",
-  "no",
-  "pt-BR",
-  "sv"
+// src/cli/lib/rewrite-core-package.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { join as join8 } from "path";
+import { z as z10 } from "zod";
+var NATIVE_BUILD_ALLOWLIST = [
+  "@parcel/watcher",
+  "@swc/core",
+  "@vercel/speed-insights",
+  "esbuild",
+  "msw",
+  "protobufjs",
+  "puppeteer",
+  "sharp",
+  "workerd"
 ];
-var AvailableLocalesSuccessSchema = z8.object({
-  data: z8.array(
-    z8.object({
-      id: z8.string(),
-      name: z8.string(),
-      fallback: z8.string().nullable(),
-      is_supported: z8.boolean()
-    })
-  )
+var DEP_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies"
+];
+var corePackageJsonSchema2 = z10.looseObject({
+  version: z10.string().optional(),
+  private: z10.boolean().optional(),
+  scripts: z10.record(z10.string(), z10.string()).optional(),
+  dependencies: z10.record(z10.string(), z10.string()).optional(),
+  devDependencies: z10.record(z10.string(), z10.string()).optional(),
+  optionalDependencies: z10.record(z10.string(), z10.string()).optional(),
+  peerDependencies: z10.record(z10.string(), z10.string()).optional(),
+  pnpm: z10.looseObject({}).optional(),
+  catalyst: z10.looseObject({}).optional()
 });
-var getAvailableLocales = async (storeHash, accessToken, apiHost) => {
-  const response = await fetch(
-    `https://${apiHost}/stores/${storeHash}/v3/settings/store/available-locales`,
-    {
-      method: "GET",
-      headers: {
-        "X-Auth-Token": accessToken,
-        "X-Correlation-Id": getTelemetry().correlationId,
-        Accept: "application/json"
-      }
-    }
-  );
-  assertAuthorized(response);
+var registryVersionSchema = z10.object({ version: z10.string() });
+var resolvePublishedVersion = async (pkgName) => {
+  const response = await fetch(`https://registry.npmjs.org/${pkgName}/latest`);
   if (!response.ok) {
     throw new Error(
-      `GET /v3/settings/store/available-locales failed: ${response.status} ${response.statusText}`
+      `Could not resolve a published version for "${pkgName}" (HTTP ${response.status}). The extracted project still references it via the workspace protocol and cannot be installed.`
     );
   }
-  return AvailableLocalesSuccessSchema.parse(await response.json()).data.filter(({ id }) => allowedLocales.includes(id)).map(({ name, id }) => ({ name: `${name} (${id})`, value: id }));
+  const { version: version2 } = registryVersionSchema.parse(await response.json());
+  return `^${version2}`;
+};
+var rewriteCorePackage = async (projectDir, ref) => {
+  const packageJsonPath = join8(projectDir, "package.json");
+  const pkg = corePackageJsonSchema2.parse(JSON.parse(readFileSync4(packageJsonPath, "utf-8")));
+  const workspaceDeps = DEP_FIELDS.flatMap((field) => {
+    const deps = pkg[field];
+    if (!deps) return [];
+    return Object.entries(deps).filter(([, range]) => range.startsWith("workspace:")).map(([name]) => ({ deps, name }));
+  });
+  await Promise.all(
+    workspaceDeps.map(async ({ deps, name }) => {
+      const resolved = await resolvePublishedVersion(name);
+      deps[name] = resolved;
+      consola.info(`Resolved ${name} to ${resolved}`);
+    })
+  );
+  delete pkg.private;
+  if (pkg.scripts) {
+    pkg.scripts = Object.fromEntries(
+      Object.entries(pkg.scripts).filter(([, command]) => !command.includes("turbo"))
+    );
+  }
+  pkg.pnpm = { ...pkg.pnpm, onlyBuiltDependencies: NATIVE_BUILD_ALLOWLIST };
+  pkg.trustedDependencies = NATIVE_BUILD_ALLOWLIST;
+  pkg.catalyst = { ...pkg.catalyst, version: pkg.version, ref };
+  writeFileSync2(packageJsonPath, `${JSON.stringify(sortPackageJsonFields(pkg), null, 2)}
+`);
+  writeFileSync2(join8(projectDir, ".npmrc"), "legacy-peer-deps=true\n");
 };
 
 // src/cli/lib/setup-core-project.ts
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname3, join as join8 } from "path";
-import { z as z9 } from "zod";
-var corePackageJsonSchema2 = z9.looseObject({
-  scripts: z9.record(z9.string(), z9.string()).optional(),
-  dependencies: z9.record(z9.string(), z9.string()).optional()
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname3, join as join9 } from "path";
+import { z as z11 } from "zod";
+var corePackageJsonSchema3 = z11.looseObject({
+  scripts: z11.record(z11.string(), z11.string()).optional(),
+  devDependencies: z11.record(z11.string(), z11.string()).optional()
 });
 var writeJson2 = (path, value) => {
-  mkdirSync2(dirname3(path), { recursive: true });
-  writeFileSync2(path, `${JSON.stringify(value, null, 2)}
+  mkdirSync3(dirname3(path), { recursive: true });
+  writeFileSync3(path, `${JSON.stringify(value, null, 2)}
 `);
 };
 var setupCoreProject = (projectDir) => {
-  const corePackageJsonPath = join8(projectDir, "core", "package.json");
-  const pkg = corePackageJsonSchema2.parse(JSON.parse(readFileSync3(corePackageJsonPath, "utf-8")));
+  const corePackageJsonPath = join9(projectDir, "package.json");
+  const pkg = corePackageJsonSchema3.parse(JSON.parse(readFileSync5(corePackageJsonPath, "utf-8")));
   pkg.scripts = {
     ...pkg.scripts,
     build: "npm run generate && catalyst build",
     start: "catalyst start",
     deploy: "npm run generate && catalyst deploy"
   };
-  pkg.dependencies = {
-    ...pkg.dependencies,
+  pkg.devDependencies = {
+    ...pkg.devDependencies,
     "@bigcommerce/catalyst": package_default.version
   };
   writeJson2(corePackageJsonPath, sortPackageJsonFields(pkg));
 };
 
-// src/cli/lib/write-env.ts
-import { outputFileSync as outputFileSync2 } from "fs-extra/esm";
-import { join as join9 } from "path";
-var writeEnv = (projectDir, envVars) => {
-  outputFileSync2(
-    join9(projectDir, "core", ".env.local"),
-    `${Object.entries(envVars).map(([key, value]) => `${key}=${value}`).join("\n")}
-`
-  );
-};
-
 // src/cli/commands/create.ts
 function getPlatformCheckCommand(command) {
   const isWindows = process.platform === "win32";
@@ -1954,73 +2340,25 @@ function getPlatformCheckCommand(command) {
 function parseChannelId2(value) {
   const parsed = parseInt(value, 10);
   if (Number.isNaN(parsed)) {
-    throw new InvalidArgumentError2(`"${value}" is not a valid channel ID (expected a number).`);
+    throw new InvalidArgumentError3(`"${value}" is not a valid channel ID (expected a number).`);
   }
   return parsed;
 }
 function parseEnvFlag(value, previous = {}) {
   const eqIdx = value.indexOf("=");
   if (eqIdx <= 0) {
-    throw new InvalidArgumentError2(`Expected KEY=VALUE, got "${value}".`);
+    throw new InvalidArgumentError3(`Expected KEY=VALUE, got "${value}".`);
   }
   const key = value.substring(0, eqIdx);
   const val = value.substring(eqIdx + 1);
   if (!val) {
-    throw new InvalidArgumentError2(`Expected KEY=VALUE with non-empty value, got "${value}".`);
+    throw new InvalidArgumentError3(`Expected KEY=VALUE with non-empty value, got "${value}".`);
   }
   return { ...previous, [key]: val };
 }
-async function handleChannelCreation(storeHash, accessToken, apiHost, cliApiOrigin) {
-  const newChannelName = await input3({
-    message: "What would you like to name your new channel?"
-  });
-  const availableLocales = await getAvailableLocales(storeHash, accessToken, apiHost);
-  const storefrontLocale = await select4({
-    message: "Which default language would you like to set for your channel?",
-    default: "en",
-    choices: availableLocales,
-    theme: {
-      style: {
-        help: () => colorize4("dim", "(Select locale from the list or start typing the name)")
-      }
-    }
-  });
-  const shouldAddAdditionalLocales = await select4({
-    message: "Would you like to add additional languages?",
-    choices: [
-      { name: "Yes", value: true },
-      { name: "No", value: false }
-    ]
-  });
-  let additionalLocales = [];
-  if (shouldAddAdditionalLocales) {
-    const localeChoices = availableLocales.filter(({ value }) => value !== storefrontLocale).map(({ name, value }) => ({ name, value, description: value }));
-    additionalLocales = await checkbox({
-      message: "Which additional languages would you like to add to your channel?",
-      choices: localeChoices,
-      validate: (items) => items.length <= 4 || "You can only select up to 4 additional languages."
-    });
-  }
-  const shouldInstallSampleData = await select4({
-    message: "Would you like to install sample data?",
-    choices: [
-      { name: "Yes", value: true },
-      { name: "No", value: false }
-    ]
-  });
-  return createChannel(
-    newChannelName,
-    storefrontLocale,
-    additionalLocales,
-    shouldInstallSampleData,
-    storeHash,
-    accessToken,
-    cliApiOrigin
-  );
-}
 async function handleChannelSelection(storeHash, accessToken, apiHost) {
   const channels = await fetchAvailableChannels(storeHash, accessToken, apiHost);
-  const existingChannel = await select4({
+  const existingChannel = await select5({
     message: "Which channel would you like to use?",
     choices: sortChannelsByPlatform(channels).map((ch) => ({
       name: ch.name,
@@ -2054,7 +2392,7 @@ async function setupProject(options) {
       projectDir = targetDir;
       return true;
     };
-    await input3({
+    await input4({
       message: "What do you want to name your project directory?",
       default: "my-catalyst-app",
       validate: validateProjectName
@@ -2066,21 +2404,13 @@ async function setupProject(options) {
 }
 function checkRequiredTools() {
   try {
-    execSync4(getPlatformCheckCommand("git"), { stdio: "ignore" });
+    execSync2(getPlatformCheckCommand("git"), { stdio: "ignore" });
   } catch {
     consola.error("git is required to create a Catalyst project");
     process.exit(1);
   }
-  try {
-    execSync4(getPlatformCheckCommand("pnpm"), { stdio: "ignore" });
-  } catch {
-    consola.error(
-      "pnpm is required to create a Catalyst project. Enable it by running `corepack enable pnpm`."
-    );
-    process.exit(1);
-  }
 }
-var create = new Command4("create").configureHelp({ showGlobalOptions: true }).description("Scaffold and connect a Catalyst storefront to your BigCommerce store.").addHelpText(
+var create2 = new Command4("create").configureHelp({ showGlobalOptions: true }).description("Scaffold and connect a Catalyst storefront to your BigCommerce store.").addHelpText(
   "after",
   `
 Examples:
@@ -2094,14 +2424,14 @@ Examples:
   $ catalyst create --project-name my-store --hosting commerce`
 ).option("--project-name <name>", "Name of your Catalyst project").option("--project-dir <dir>", "Directory in which to create your project", process.cwd()).addOption(storeHashOption()).addOption(accessTokenOption()).option("--channel-id <id>", "BigCommerce channel ID", parseChannelId2).option("--storefront-token <token>", "BigCommerce storefront token").option(
   "--gh-ref <ref>",
-  "Clone a specific ref from the source repository",
+  "Extract a specific ref (tag, branch, or commit) from the source repository",
   "@bigcommerce/catalyst-core@latest"
-).option("--reset-main", "Reset the main branch to the gh-ref").option("--repository <repository>", "GitHub repository to clone from", "bigcommerce/catalyst").option(
+).option("--repository <repository>", "GitHub repository to extract from", "bigcommerce/catalyst").option(
   "--env <vars...>",
   "Arbitrary environment variables to set in .env.local. Format: KEY=VALUE (repeatable).",
   parseEnvFlag
 ).addOption(
-  new Option5(
+  new Option4(
     "--hosting <mode>",
     'Hosting mode: "self-hosted" (default) or "commerce" to set up Commerce Hosting at create time. When omitted, scaffolding is hosting-agnostic; run `catalyst deploy` later to opt in.'
   ).choices(["self-hosted", "commerce"])
@@ -2109,11 +2439,11 @@ Examples:
   "--use-existing",
   "Only used with --hosting commerce and --project-name. When the named project already exists on the store, reuse it instead of prompting. Has no effect without --hosting commerce."
 ).addOption(
-  new Option5("--bigcommerce-hostname <hostname>", "BigCommerce hostname").default("bigcommerce.com").hideHelp()
+  new Option4("--bigcommerce-hostname <hostname>", "BigCommerce hostname").default("bigcommerce.com").hideHelp()
 ).addOption(
-  new Option5("--login-url <url>", "BigCommerce login URL.").env("BIGCOMMERCE_LOGIN_URL").default(DEFAULT_LOGIN_URL).hideHelp()
+  new Option4("--login-url <url>", "BigCommerce login URL.").env("BIGCOMMERCE_LOGIN_URL").default(DEFAULT_LOGIN_URL).hideHelp()
 ).addOption(
-  new Option5("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
+  new Option4("--cli-api-origin <origin>", "Catalyst CLI API origin").default("https://cxm-prd.bigcommerceapp.com").hideHelp()
 ).action(async (options) => {
   const { ghRef, repository } = options;
   if (options.useExisting && options.hosting !== "commerce") {
@@ -2167,7 +2497,7 @@ Examples:
       }
       let shouldCreateChannel;
       if (eligibility.eligible) {
-        shouldCreateChannel = await select4({
+        shouldCreateChannel = await select5({
           message: "Would you like to create a new channel?",
           choices: [
             { name: "Yes", value: true },
@@ -2176,12 +2506,12 @@ Examples:
         });
       }
       if (shouldCreateChannel) {
-        const channelData = await handleChannelCreation(
+        const channelData = await runCreateChannelFlow({
           storeHash,
           accessToken,
           apiHost,
           cliApiOrigin
-        );
+        });
         channelId = channelData.channelId;
         storefrontToken = channelData.storefrontToken;
         envVars = { ...channelData.envVars };
@@ -2226,8 +2556,10 @@ Examples:
     );
   }
   consola.info(`Creating '${projectName}' at '${projectDir}'`);
+  const packageManager = detectPackageManager();
   try {
-    cloneCatalyst({ repository, projectName, projectDir, ghRef, resetMain: options.resetMain });
+    await extractCatalyst({ repository, ref: ghRef, projectDir });
+    await rewriteCorePackage(projectDir, ghRef);
     setupCoreProject(projectDir);
     if (useCommerceHosting && commerceHostingProject && storeHash && accessToken) {
       await setupCommerceHosting({
@@ -2238,8 +2570,8 @@ Examples:
       });
     }
     writeEnv(projectDir, envVars);
-    await installDependencies(projectDir);
-    buildWorkspacePackages(projectDir);
+    await installDependencies(projectDir, packageManager);
+    initGitRepo(projectDir);
   } catch (error) {
     if (pathExistsSync(projectDir)) {
       consola.warn(
@@ -2249,28 +2581,289 @@ Examples:
     throw error;
   }
   consola.success(`Created '${projectName}' at '${projectDir}'`);
-  const steps = [`cd ${projectName}/core && pnpm run dev`];
+  const steps = [`cd ${projectName} && ${packageManager} run dev`];
   if (useCommerceHosting) {
     steps.push(
-      `Run 'cd ${projectName}/core && pnpm run deploy' when ready to deploy to Commerce Hosting.`
+      `Run 'cd ${projectName} && ${packageManager} run deploy' when ready to deploy to Commerce Hosting.`
     );
   }
   consola.log(
     `Next steps:
 
-${steps.map((step) => `  ${colorize4("yellow", step)}`).join("\n")}`
+${steps.map((step) => `  ${colorize6("yellow", step)}`).join("\n")}`
+  );
+});
+
+// src/cli/commands/debug.ts
+import { Command as Command5, Option as Option5 } from "commander";
+
+// src/cli/lib/collect-diagnostics.ts
+import { parse } from "dotenv";
+import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
+import { release } from "os";
+import { dirname as dirname4, join as join11 } from "path";
+import { z as z12 } from "zod";
+var CLI_ENV_VARS = [
+  "CATALYST_STORE_HASH",
+  "CATALYST_ACCESS_TOKEN",
+  "CATALYST_PROJECT_UUID",
+  "CATALYST_API_HOST",
+  "BIGCOMMERCE_LOGIN_URL",
+  "CATALYST_TELEMETRY_DISABLED"
+];
+var BUILD_ENV_VARS = [
+  "BIGCOMMERCE_STORE_HASH",
+  "BIGCOMMERCE_STOREFRONT_TOKEN",
+  "BIGCOMMERCE_CHANNEL_ID",
+  "AUTH_SECRET"
+];
+var ENV_FILES = [".env.local", ".env"];
+var PROJECT_LOCKFILES = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["package-lock.json", "npm"]
+];
+var hasValue = (value) => value !== void 0 && value.trim() !== "";
+var buildEnvLayers = (cwd, env2) => {
+  const layers = [{ source: "process.env", values: env2 }];
+  ENV_FILES.forEach((file) => {
+    const path = join11(cwd, file);
+    if (!existsSync5(path)) {
+      return;
+    }
+    try {
+      layers.push({ source: file, values: parse(readFileSync6(path, "utf-8")) });
+    } catch {
+    }
+  });
+  return layers;
+};
+var resolveEnvSource = (layers, ...keys) => layers.find((layer) => keys.some((key) => hasValue(layer.values[key])))?.source;
+var resolveEnvVars = (layers, names) => Object.fromEntries(names.map((name) => [name, resolveEnvSource(layers, name) ?? "unset"]));
+var resolveValue = (envSource, configValue) => {
+  if (envSource) {
+    return { present: true, source: envSource };
+  }
+  if (hasValue(configValue)) {
+    return { present: true, source: "project.json" };
+  }
+  return { present: false, source: "unset" };
+};
+var asString = (value) => typeof value === "string" ? value : void 0;
+var lockfileManager = (dir) => PROJECT_LOCKFILES.find(([file]) => existsSync5(join11(dir, file)))?.[1];
+var detectProjectPackageManager2 = (cwd) => {
+  let dir = cwd;
+  for (; ; ) {
+    const match = lockfileManager(dir);
+    if (match) {
+      return match;
+    }
+    const parent = dirname4(dir);
+    if (parent === dir) {
+      return detectPackageManager();
+    }
+    dir = parent;
+  }
+};
+var projectJsonSchema2 = z12.looseObject({});
+var safeReadJson2 = (path) => {
+  try {
+    return JSON.parse(readFileSync6(path, "utf-8"));
+  } catch {
+    return null;
+  }
+};
+var readProjectJson = (cwd) => {
+  const result = projectJsonSchema2.safeParse(
+    safeReadJson2(join11(cwd, ".bigcommerce", "project.json"))
   );
+  return result.success ? result.data : null;
+};
+var storefrontPackageSchema = z12.looseObject({
+  name: z12.string().optional(),
+  version: z12.string().optional(),
+  catalyst: z12.looseObject({ version: z12.string().optional() }).optional()
+});
+var readStorefrontInfo = (cwd) => {
+  const result = storefrontPackageSchema.safeParse(safeReadJson2(join11(cwd, "package.json")));
+  if (!result.success) {
+    return { name: null, version: null };
+  }
+  return {
+    name: result.data.name ?? null,
+    version: result.data.catalyst?.version ?? result.data.version ?? null
+  };
+};
+var readStoredEnvKeys = (projectJson) => {
+  const env2 = projectJson?.env;
+  if (typeof env2 === "object" && env2 !== null && !Array.isArray(env2)) {
+    return Object.keys(env2).sort();
+  }
+  return [];
+};
+function collectDiagnostics({
+  cwd = process.cwd(),
+  env: env2 = process.env
+} = {}) {
+  const state = getProjectState(cwd);
+  const telemetry3 = getTelemetry();
+  const projectJson = readProjectJson(cwd);
+  const storefront = readStorefrontInfo(cwd);
+  const cliEnv = [{ source: "process.env", values: env2 }];
+  const buildEnv = buildEnvLayers(cwd, env2);
+  return {
+    cli: {
+      name: package_default.name,
+      version: package_default.version
+    },
+    runtime: {
+      node: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      osRelease: release(),
+      packageManager: detectProjectPackageManager2(cwd)
+    },
+    project: {
+      cwd,
+      storefrontName: storefront.name,
+      storefrontVersion: storefront.version,
+      projectUuid: state.projectUuid ?? null,
+      isLinked: state.isLinked,
+      isTransformed: state.isTransformed,
+      isFullySetUp: state.isFullySetUp,
+      hasMiddleware: state.hasMiddleware,
+      hasProxy: state.hasProxy,
+      hasOpenNextDep: state.hasOpenNextDep
+    },
+    config: {
+      storeHash: resolveValue(
+        resolveEnvSource(cliEnv, "CATALYST_STORE_HASH", "BIGCOMMERCE_STORE_HASH"),
+        asString(projectJson?.storeHash)
+      ),
+      accessToken: resolveValue(
+        resolveEnvSource(cliEnv, "CATALYST_ACCESS_TOKEN"),
+        asString(projectJson?.accessToken)
+      ),
+      projectUuid: resolveValue(
+        resolveEnvSource(cliEnv, "CATALYST_PROJECT_UUID"),
+        asString(projectJson?.projectUuid)
+      ),
+      apiHost: resolveValue(
+        resolveEnvSource(cliEnv, "CATALYST_API_HOST"),
+        asString(projectJson?.apiHost)
+      ),
+      projectJsonKeys: projectJson ? Object.keys(projectJson).sort() : [],
+      storedEnvKeys: readStoredEnvKeys(projectJson),
+      cliEnvVars: resolveEnvVars(cliEnv, CLI_ENV_VARS),
+      buildEnvVars: resolveEnvVars(buildEnv, BUILD_ENV_VARS)
+    },
+    telemetry: {
+      enabled: telemetry3.isEnabled(),
+      correlationId: telemetry3.correlationId
+    },
+    files: {
+      ".env.local": existsSync5(join11(cwd, ".env.local")),
+      ".env": existsSync5(join11(cwd, ".env")),
+      ".bigcommerce/project.json": existsSync5(join11(cwd, ".bigcommerce", "project.json")),
+      ".bigcommerce/wrangler.jsonc": existsSync5(join11(cwd, ".bigcommerce", "wrangler.jsonc")),
+      ".open-next/": existsSync5(join11(cwd, ".open-next")),
+      "package.json": existsSync5(join11(cwd, "package.json"))
+    }
+  };
+}
+
+// src/cli/commands/debug.ts
+var yesNo = (value) => value ? "yes" : "no";
+var presence = (value) => value ? "present" : "absent";
+var formatResolved = (value) => value.present ? `present (source: ${value.source})` : "not set";
+var formatSource = (source) => source === "unset" ? "not set" : `set (${source})`;
+var formatStorefront = (name, version2) => {
+  if (!version2) {
+    return "(unknown)";
+  }
+  return name ? `${name}@${version2}` : version2;
+};
+var formatList = (values) => values.length > 0 ? values.join(", ") : "(none)";
+var envVarLines = (vars) => Object.entries(vars).map(([name, source]) => `  ${name}: ${formatSource(source)}`);
+var formatReport = (d) => {
+  const lines = [
+    "Catalyst CLI Diagnostics",
+    "",
+    "CLI",
+    `  Package:            ${d.cli.name}`,
+    `  Version:            ${d.cli.version}`,
+    "",
+    "Runtime",
+    `  Node:               ${d.runtime.node}`,
+    `  Platform:           ${d.runtime.platform} (${d.runtime.arch})`,
+    `  OS release:         ${d.runtime.osRelease}`,
+    `  Package manager:    ${d.runtime.packageManager}`,
+    "",
+    "Project",
+    `  Directory:          ${d.project.cwd}`,
+    `  Storefront:         ${formatStorefront(d.project.storefrontName, d.project.storefrontVersion)}`,
+    `  Project UUID:       ${d.project.projectUuid ?? "(not linked)"}`,
+    `  Linked:             ${yesNo(d.project.isLinked)}`,
+    `  Transformed:        ${yesNo(d.project.isTransformed)}`,
+    `  Fully set up:       ${yesNo(d.project.isFullySetUp)}`,
+    `  middleware.ts:      ${presence(d.project.hasMiddleware)}`,
+    `  proxy.ts:           ${presence(d.project.hasProxy)}`,
+    `  OpenNext dep:       ${d.project.hasOpenNextDep ? "installed" : "not installed"}`,
+    "",
+    "Config (resolved without secrets)",
+    `  Store hash:         ${formatResolved(d.config.storeHash)}`,
+    `  Access token:       ${formatResolved(d.config.accessToken)}`,
+    `  Project UUID:       ${formatResolved(d.config.projectUuid)}`,
+    `  API host:           ${d.config.apiHost.present ? formatResolved(d.config.apiHost) : "default (api.bigcommerce.com)"}`,
+    `  project.json keys:  ${formatList(d.config.projectJsonKeys)}`,
+    `  Stored env keys:    ${formatList(d.config.storedEnvKeys)}`,
+    "",
+    "CLI environment variables (used to run the CLI)",
+    ...envVarLines(d.config.cliEnvVars),
+    "",
+    "Build environment variables (used to build the Next.js app)",
+    ...envVarLines(d.config.buildEnvVars),
+    "",
+    "Telemetry",
+    `  Enabled:            ${yesNo(d.telemetry.enabled)}`,
+    `  Correlation ID:     ${d.telemetry.correlationId}`,
+    "",
+    "Files",
+    ...Object.entries(d.files).map(([name, exists]) => `  ${name}: ${presence(exists)}`)
+  ];
+  return lines.join("\n");
+};
+var debug = new Command5("debug").configureHelp({ showGlobalOptions: true }).description(
+  "Print a diagnostic report (CLI, runtime, project, and config state) to include when filing a bug report. Never prints secret values \u2014 credentials and env vars are reported by presence only."
+).addHelpText(
+  "after",
+  `
+Examples:
+  # Print a human-readable report
+  $ catalyst debug
+
+  # Print machine-readable JSON (useful for copy/paste or piping)
+  $ catalyst debug --json`
+).addOption(new Option5("--json", "Output the report as JSON.")).action((options) => {
+  const diagnostics = collectDiagnostics();
+  if (options.json) {
+    consola.log(JSON.stringify(diagnostics, null, 2));
+    return;
+  }
+  consola.log(formatReport(diagnostics));
 });
 
 // src/cli/commands/deploy.ts
 import { confirm as confirm3 } from "@inquirer/prompts";
 import AdmZip from "adm-zip";
-import { Command as Command5, Option as Option6 } from "commander";
-import { colorize as colorize5 } from "consola/utils";
+import { Command as Command6, Option as Option6 } from "commander";
+import { colorize as colorize7 } from "consola/utils";
 import { access, readdir, readFile } from "fs/promises";
-import { dirname as dirname4, join as join11 } from "path";
-import yoctoSpinner4 from "yocto-spinner";
-import { z as z10 } from "zod";
+import { join as join12 } from "path";
+import yoctoSpinner3 from "yocto-spinner";
+import { z as z13 } from "zod";
 
 // src/cli/lib/deployment-errors.ts
 var ERROR_MESSAGES = {
@@ -2289,7 +2882,7 @@ function getDeploymentErrorMessage(code) {
 }
 
 // src/cli/commands/deploy.ts
-var stepsEnum = z10.enum([
+var stepsEnum = z13.enum([
   "initializing",
   "downloading",
   "unzipping",
@@ -2307,41 +2900,41 @@ var STEPS = {
   finalizing: "Finalizing...",
   complete: "Complete"
 };
-var UploadSignatureSchema = z10.object({
-  data: z10.object({
-    upload_url: z10.url(),
-    upload_uuid: z10.string()
+var UploadSignatureSchema = z13.object({
+  data: z13.object({
+    upload_url: z13.url(),
+    upload_uuid: z13.string()
   })
 });
-var CreateDeploymentSchema = z10.object({
-  data: z10.object({
-    deployment_uuid: z10.uuid()
+var CreateDeploymentSchema = z13.object({
+  data: z13.object({
+    deployment_uuid: z13.uuid()
   })
 });
-var ProjectSchema = z10.object({
-  data: z10.array(
-    z10.object({
-      uuid: z10.uuid(),
-      name: z10.string()
+var ProjectSchema = z13.object({
+  data: z13.array(
+    z13.object({
+      uuid: z13.uuid(),
+      name: z13.string()
     })
   )
 });
-var DeploymentStatusSchema = z10.object({
-  deployment_uuid: z10.uuid(),
-  deployment_status: z10.enum(["queued", "in_progress", "failed", "completed"]),
-  event: z10.object({
+var DeploymentStatusSchema = z13.object({
+  deployment_uuid: z13.uuid(),
+  deployment_status: z13.enum(["queued", "in_progress", "failed", "completed"]),
+  event: z13.object({
     step: stepsEnum,
-    progress: z10.number()
+    progress: z13.number()
   }).nullable(),
-  deployment_hostnames: z10.array(z10.string()).optional(),
-  error: z10.object({
-    code: z10.number()
+  deployment_hostnames: z13.array(z13.string()).optional(),
+  error: z13.object({
+    code: z13.number()
   }).optional()
 });
 var generateBundleZip = async () => {
   consola.info("Generating bundle...");
-  const bigcommerceDir = join11(process.cwd(), ".bigcommerce");
-  const distDir = join11(process.cwd(), ".bigcommerce", "dist");
+  const bigcommerceDir = join12(process.cwd(), ".bigcommerce");
+  const distDir = join12(process.cwd(), ".bigcommerce", "dist");
   try {
     await access(distDir);
   } catch {
@@ -2351,7 +2944,7 @@ var generateBundleZip = async () => {
   if (buildDirContents.length === 0) {
     throw new Error(`Dist directory is empty: ${distDir}`);
   }
-  const outputZip = join11(bigcommerceDir, "bundle.zip");
+  const outputZip = join12(bigcommerceDir, "bundle.zip");
   const zip = new AdmZip();
   zip.addLocalFolder(distDir, "output");
   zip.writeZip(outputZip);
@@ -2374,7 +2967,7 @@ var generateUploadSignature = async (storeHash, accessToken, apiHost) => {
   );
   assertAuthorized(response);
   if (!response.ok) {
-    throw new Error(`Failed to fetch upload signature: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to generate upload signature");
   }
   const res = await response.json();
   const { data } = UploadSignatureSchema.parse(res);
@@ -2383,7 +2976,7 @@ var generateUploadSignature = async (storeHash, accessToken, apiHost) => {
 };
 var uploadBundleZip = async (uploadUrl) => {
   consola.info("Uploading bundle...");
-  const zipPath = join11(process.cwd(), ".bigcommerce", "bundle.zip");
+  const zipPath = join12(process.cwd(), ".bigcommerce", "bundle.zip");
   const fileBuffer = await readFile(zipPath);
   const response = await fetch(uploadUrl, {
     method: "PUT",
@@ -2393,7 +2986,7 @@ var uploadBundleZip = async (uploadUrl) => {
     body: fileBuffer
   });
   if (!response.ok) {
-    throw new Error(`Failed to upload bundle: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to upload bundle");
   }
   consola.success("Bundle uploaded successfully.");
   return true;
@@ -2429,7 +3022,7 @@ var createDeployment = async (projectUuid, uploadUuid, storeHash, accessToken, a
   );
   assertAuthorized(response);
   if (!response.ok) {
-    throw new Error(`Failed to create deployment: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to create deployment");
   }
   const res = await response.json();
   const { data } = CreateDeploymentSchema.parse(res);
@@ -2438,7 +3031,7 @@ var createDeployment = async (projectUuid, uploadUuid, storeHash, accessToken, a
 };
 var getDeploymentStatus = async (deploymentUuid, storeHash, accessToken, apiHost) => {
   consola.info("Fetching deployment status...");
-  const spinner = yoctoSpinner4().start("Fetching...");
+  const spinner = yoctoSpinner3().start("Fetching...");
   const response = await fetch(
     `https://${apiHost}/stores/${storeHash}/v3/infrastructure/deployments/${deploymentUuid}/events`,
     {
@@ -2453,7 +3046,7 @@ var getDeploymentStatus = async (deploymentUuid, storeHash, accessToken, apiHost
   );
   assertAuthorized(response);
   if (!response.ok) {
-    throw new Error(`Failed to open event stream: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to open deployment event stream");
   }
   const reader = response.body?.getReader();
   if (!reader) {
@@ -2494,7 +3087,7 @@ var getDeploymentStatus = async (deploymentUuid, storeHash, accessToken, apiHost
   spinner.success("Deployment completed successfully.");
   if (deploymentHostname) {
     consola.success(
-      `View your deployment at: ${colorize5("blue", `https://${deploymentHostname}`)}`
+      `View your deployment at: ${colorize7("blue", `https://${deploymentHostname}`)}`
     );
   }
   return deploymentHostname;
@@ -2514,13 +3107,13 @@ var fetchProject = async (projectUuid, storeHash, accessToken, apiHost) => {
   );
   assertAuthorized(response);
   if (!response.ok) {
-    throw new Error(`Failed to fetch projects: ${response.status} ${response.statusText}`);
+    throw await httpError(response, "Failed to fetch projects");
   }
   const res = await response.json();
   const { data } = ProjectSchema.parse(res);
   return data.find((project2) => project2.uuid === projectUuid);
 };
-var deploy = new Command5("deploy").configureHelp({ showGlobalOptions: true }).description("Deploy your application to Cloudflare.").addHelpText(
+var deploy = new Command6("deploy").configureHelp({ showGlobalOptions: true }).description("Deploy your application to Cloudflare.").addHelpText(
   "after",
   `
 Environment variables saved with \`catalyst env add\` are sent automatically on every deploy.
@@ -2541,8 +3134,14 @@ Example:
 ).option("--dry-run", "Run the command to generate the bundle without uploading or deploying.").option(
   "--prebuilt",
   "Skip the build step. Requires .bigcommerce/dist/ to already contain build output."
-).action(async (options) => {
+).addOption(
+  new Option6(
+    "--wrangler-version <version>",
+    `Wrangler version or dist-tag to build with. Ignored with --prebuilt. Defaults to ${WRANGLER_VERSION}.`
+  ).argParser(parseWranglerVersion)
+).addOption(envPathOption()).action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   const telemetry3 = getTelemetry();
   await telemetry3.identify(storeHash);
@@ -2553,7 +3152,7 @@ Example:
       return await selectOrCreateInfrastructureProject({
         storeHash,
         accessToken,
-        apiHost: options.apiHost
+        apiHost
       });
     } catch (error) {
       if (error instanceof NoLinkedProjectError) {
@@ -2566,12 +3165,7 @@ Example:
     }
   };
   if (linkedProjectUuid) {
-    const existing = await fetchProject(
-      linkedProjectUuid,
-      storeHash,
-      accessToken,
-      options.apiHost
-    );
+    const existing = await fetchProject(linkedProjectUuid, storeHash, accessToken, apiHost);
     if (existing) {
       projectUuid = linkedProjectUuid;
     } else {
@@ -2599,15 +3193,16 @@ Example:
       consola.info("When you're ready to deploy, re-run `catalyst deploy` to complete setup.");
       process.exit(0);
     }
-    const projectDir = dirname4(process.cwd());
+    const projectDir = process.cwd();
     await setupCommerceHosting({ projectDir, projectUuid, storeHash, accessToken });
     consola.success("Commerce Hosting setup complete.");
-    await installDependencies(projectDir);
+    const packageManager = await detectProjectPackageManager(projectDir);
+    await installDependencies(projectDir, packageManager);
   } else {
-    await cleanupCloudflareIncompatibilities(dirname4(process.cwd()));
+    await cleanupCloudflareIncompatibilities(process.cwd());
   }
   if (options.prebuilt) {
-    const distDir = join11(process.cwd(), ".bigcommerce", "dist");
+    const distDir = join12(process.cwd(), ".bigcommerce", "dist");
     try {
       await access(distDir);
     } catch {
@@ -2623,7 +3218,8 @@ Example:
     }
     consola.info("Using existing build output (--prebuilt).");
   } else {
-    await buildCatalystProject(projectUuid);
+    loadBuildEnv({ envPath: options.envPath });
+    await buildCatalystProject(projectUuid, options.wranglerVersion);
   }
   await generateBundleZip();
   if (options.dryRun) {
@@ -2634,7 +3230,7 @@ Example:
     consola.info("- Create deployment");
     process.exit(0);
   }
-  const uploadSignature = await generateUploadSignature(storeHash, accessToken, options.apiHost);
+  const uploadSignature = await generateUploadSignature(storeHash, accessToken, apiHost);
   await uploadBundleZip(uploadSignature.upload_url);
   const flagSecrets = parseEnvironmentVariables(options.secret) ?? [];
   const persistedSecrets = toDeploymentSecrets(getStoredEnv(config2));
@@ -2645,40 +3241,772 @@ Example:
     uploadSignature.upload_uuid,
     storeHash,
     accessToken,
-    options.apiHost,
+    apiHost,
     environmentVariables
   );
   const deploymentHostname = await getDeploymentStatus(
     deploymentUuid,
     storeHash,
     accessToken,
-    options.apiHost
+    apiHost
+  );
+  if (!options.updateSiteUrl) {
+    return;
+  }
+  try {
+    await runChannelSiteUrlFlow({
+      storeHash,
+      accessToken,
+      apiHost,
+      projectUuid,
+      preferHostname: deploymentHostname
+    });
+  } catch (error) {
+    consola.warn(
+      `Failed to update channel site URL: ${error instanceof Error ? error.message : String(error)}`
+    );
+    consola.info(
+      "Update it manually in the control panel, or re-run `catalyst auth login` if the token is missing the store_channel_settings scope."
+    );
+  }
+});
+
+// src/cli/commands/domains.ts
+import { confirm as confirm4, select as select6 } from "@inquirer/prompts";
+import { Command as Command7, Option as Option7 } from "commander";
+import { colorize as colorize9 } from "consola/utils";
+
+// src/cli/lib/domains.ts
+import { z as z15 } from "zod";
+
+// src/cli/lib/observability.ts
+import { colorize as colorize8 } from "consola/utils";
+import { z as z14 } from "zod";
+var LOG_LEVELS = ["debug", "info", "warn", "error"];
+var SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1e3;
+var logEntrySchema = z14.object({
+  timestamp: z14.string().nullable().optional(),
+  level: z14.string().optional(),
+  messages: z14.array(z14.unknown()).optional(),
+  is_exception: z14.boolean().optional(),
+  exception_name: z14.string().optional(),
+  request: z14.object({
+    method: z14.string().optional(),
+    url: z14.string().optional(),
+    status_code: z14.number().optional()
+  }).nullable().optional()
+});
+var queryLogsSchema = z14.object({
+  data: z14.array(logEntrySchema)
+});
+var v3ErrorSchema = z14.object({
+  title: z14.string().optional(),
+  errors: z14.record(z14.string(), z14.string()).optional()
+});
+function formatV3Error(body) {
+  const parsed = v3ErrorSchema.safeParse(body);
+  if (!parsed.success) return void 0;
+  const { title, errors } = parsed.data;
+  const fieldErrors = errors && Object.keys(errors).length > 0 ? Object.entries(errors).map(([field, message]) => `${field}: ${message}`).join("; ") : void 0;
+  if (title && fieldErrors) return `${title} (${fieldErrors})`;
+  return title ?? fieldErrors;
+}
+function parseTimeInput(value) {
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) {
+    return Number(trimmed) * 1e3;
+  }
+  const ms = Date.parse(trimmed);
+  return Number.isNaN(ms) ? null : ms;
+}
+var DURATION_UNIT_MS = {
+  s: 1e3,
+  m: 60 * 1e3,
+  h: 60 * 60 * 1e3,
+  d: 24 * 60 * 60 * 1e3
+};
+function parseDuration(value) {
+  const match = /^(\d+)([smhd])$/.exec(value.trim());
+  if (!match) return null;
+  return Number(match[1]) * DURATION_UNIT_MS[match[2]];
+}
+function resolveTimeWindow(opts, nowMs = Date.now()) {
+  const { since } = opts;
+  let { start: start2, end } = opts;
+  let startMs;
+  let endMs;
+  if (end) {
+    endMs = parseTimeInput(end);
+    if (endMs === null) {
+      throw new UserActionableError(
+        `Invalid --end value "${end}". Provide an ISO-8601 timestamp or a Unix epoch (seconds).`
+      );
+    }
+  } else {
+    endMs = nowMs;
+    end = new Date(endMs).toISOString();
+  }
+  if (since) {
+    const durationMs = parseDuration(since);
+    if (durationMs === null) {
+      throw new UserActionableError(
+        `Invalid --since value "${since}". Provide a duration like 30m, 6h, or 2d (units: s, m, h, d).`
+      );
+    }
+    startMs = endMs - durationMs;
+    start2 = new Date(startMs).toISOString();
+  } else if (start2) {
+    startMs = parseTimeInput(start2);
+    if (startMs === null) {
+      throw new UserActionableError(
+        `Invalid --start value "${start2}". Provide an ISO-8601 timestamp or a Unix epoch (seconds).`
+      );
+    }
+  } else {
+    throw new UserActionableError(
+      "Provide a time window with --since <duration> or --start <time>."
+    );
+  }
+  if (startMs > endMs) {
+    throw new UserActionableError("Invalid time window: --start must be before or equal to --end.");
+  }
+  if (endMs - startMs > SEVEN_DAYS_MS) {
+    throw new UserActionableError("Invalid time window: the range must not exceed 7 days.");
+  }
+  return { start: start2, end };
+}
+var LEVEL_COLORS = {
+  debug: "gray",
+  info: "green",
+  warn: "yellow",
+  error: "red"
+};
+var UNKNOWN_TIME = "unknown";
+function isRedundantExceptionName(name, message) {
+  const parts = name.split("<*>").map((part) => part.trim()).filter((part) => part.length > 0);
+  return parts.length > 0 && parts.every((part) => message.includes(part));
+}
+var stringifyMessage = (message) => typeof message === "string" ? message : JSON.stringify(message);
+function formatLogEntry(entry, format = "default") {
+  const message = (entry.messages ?? []).map(stringifyMessage).join(" ").replace(/\s+/g, " ").trim();
+  if (format === "short") return message;
+  const level = entry.level ?? "unknown";
+  const coloredLevel = colorize8(LEVEL_COLORS[level.toLowerCase()] ?? "white", level.toUpperCase());
+  const exceptionStr = entry.is_exception && entry.exception_name && !isRedundantExceptionName(entry.exception_name, message) ? ` ${colorize8("red", `[${entry.exception_name}]`)}` : "";
+  let requestStr = "";
+  if (format === "request" && entry.request) {
+    const parts = [];
+    if (entry.request.method) parts.push(entry.request.method);
+    if (entry.request.url) parts.push(entry.request.url);
+    const status = entry.request.status_code ? ` (${entry.request.status_code})` : "";
+    if (parts.length > 0) requestStr = ` ${parts.join(" ")}${status}`;
+  }
+  return `[${entry.timestamp ?? UNKNOWN_TIME}] [${coloredLevel}]${requestStr}${exceptionStr} ${message}`;
+}
+async function queryLogs(projectUuid, storeHash, accessToken, apiHost, params) {
+  const search = new URLSearchParams();
+  search.set("start", params.start);
+  search.set("end", params.end);
+  if (params.method) search.set("method", params.method);
+  if (params.statusCode != null) search.set("status_code", String(params.statusCode));
+  if (params.urlLike) search.set("url:like", params.urlLike);
+  if (params.levelMin) search.set("level:min", params.levelMin);
+  if (params.limit != null) search.set("limit", String(params.limit));
+  const response = await fetch(
+    `https://${apiHost}/stores/${storeHash}/v3/infrastructure/logs/${projectUuid}?${search.toString()}`,
+    {
+      method: "GET",
+      headers: {
+        "X-Auth-Token": accessToken,
+        "X-Correlation-Id": getTelemetry().correlationId,
+        Accept: "application/json"
+      }
+    }
+  );
+  assertAuthorized(response);
+  if (response.status === 403) {
+    throw new UserActionableError(
+      "Infrastructure Logs API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it."
+    );
+  }
+  if (response.status === 404) {
+    throw new UserActionableError("Project not found. Check the project UUID.");
+  }
+  if (response.status === 400 || response.status === 422) {
+    const body = await response.json().catch(() => null);
+    throw new UserActionableError(formatV3Error(body) ?? "Invalid log query.");
+  }
+  if (!response.ok) {
+    throw await httpError(response, "Failed to fetch logs");
+  }
+  const res = await response.json();
+  return queryLogsSchema.parse(res);
+}
+
+// src/cli/lib/domains.ts
+var domainStatusSchema = z15.enum(["pending", "verified", "failed", "unknown"]);
+var domainSchema = z15.object({
+  domain: z15.string(),
+  project_uuid: z15.string(),
+  verification_status: domainStatusSchema
+});
+var ownershipVerificationSchema = z15.object({
+  type: z15.string(),
+  name: z15.string(),
+  value: z15.string().optional()
+});
+var ownershipVerificationMetaSchema = z15.object({
+  meta: z15.object({
+    ownership_verification: ownershipVerificationSchema
+  })
+});
+var DomainOwnershipVerificationError = class extends UserActionableError {
+  constructor(message, ownershipVerification) {
+    super(message);
+    this.name = "DomainOwnershipVerificationError";
+    this.ownershipVerification = ownershipVerification;
+  }
+};
+function parseOwnershipVerification(body) {
+  const parsed = ownershipVerificationMetaSchema.safeParse(body);
+  return parsed.success ? parsed.data.meta.ownership_verification : void 0;
+}
+var boundProjectMetaSchema = z15.object({
+  meta: z15.object({
+    project_uuid: z15.string()
+  })
+});
+var DomainBoundToProjectError = class extends UserActionableError {
+  constructor(message, projectUuid) {
+    super(message);
+    this.name = "DomainBoundToProjectError";
+    this.projectUuid = projectUuid;
+  }
+};
+function parseBoundProjectUuid(body) {
+  const parsed = boundProjectMetaSchema.safeParse(body);
+  return parsed.success ? parsed.data.meta.project_uuid : void 0;
+}
+var domainResponseSchema = z15.object({
+  data: domainSchema
+});
+var domainListResponseSchema = z15.object({
+  data: z15.array(domainSchema)
+});
+var DOMAINS_API_NOT_ENABLED = "Infrastructure Domains API not enabled. If you are part of the beta, contact support@bigcommerce.com to enable it.";
+function domainsUrl(storeHash, projectUuid, apiHost) {
+  return `https://${apiHost}/stores/${storeHash}/v3/infrastructure/projects/${projectUuid}/domains`;
+}
+function domainUrl(storeHash, projectUuid, domain, apiHost) {
+  return `${domainsUrl(storeHash, projectUuid, apiHost)}/${encodeURIComponent(domain)}`;
+}
+function domainClaimUrl(storeHash, projectUuid, domain, apiHost) {
+  return `${domainUrl(storeHash, projectUuid, domain, apiHost)}/claim`;
+}
+function domainTransferUrl(storeHash, projectUuid, domain, apiHost) {
+  return `${domainUrl(storeHash, projectUuid, domain, apiHost)}/transfer`;
+}
+function authHeaders3(accessToken) {
+  return {
+    Accept: "application/json",
+    "X-Auth-Token": accessToken,
+    "X-Correlation-Id": getTelemetry().correlationId
+  };
+}
+function formatResponseStatus(response, message) {
+  return [response.status, response.statusText || message].filter(Boolean).join(" ");
+}
+function buildErrorMessage(response, body, action) {
+  const message = formatV3Error(body);
+  if (response.status >= 500) {
+    const status = formatResponseStatus(response, message);
+    return `${action}: ${status}. This is a server-side response from the Domains API.`;
+  }
+  return message ?? `${action}: ${response.statusText}`;
+}
+async function assertDomainResponse(response, action) {
+  assertAuthorized(response);
+  if (response.status === 403) {
+    throw new UserActionableError(DOMAINS_API_NOT_ENABLED);
+  }
+  if (response.ok) {
+    return;
+  }
+  const body = await response.json().catch(() => null);
+  const message = buildErrorMessage(response, body, action);
+  const ownershipVerification = parseOwnershipVerification(body);
+  if (ownershipVerification) {
+    throw new DomainOwnershipVerificationError(message, ownershipVerification);
+  }
+  const boundProjectUuid = parseBoundProjectUuid(body);
+  if (boundProjectUuid) {
+    throw new DomainBoundToProjectError(message, boundProjectUuid);
+  }
+  if (response.status >= 500) {
+    throw new Error(message);
+  }
+  throw new UserActionableError(message);
+}
+async function createDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainsUrl(storeHash, projectUuid, apiHost), {
+    method: "POST",
+    headers: {
+      ...authHeaders3(accessToken),
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ domain })
+  });
+  await assertDomainResponse(response, "Failed to add domain");
+  const result = await response.json();
+  return domainResponseSchema.parse(result).data;
+}
+async function getDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainUrl(storeHash, projectUuid, domain, apiHost), {
+    method: "GET",
+    headers: authHeaders3(accessToken)
+  });
+  await assertDomainResponse(response, "Failed to fetch domain");
+  const result = await response.json();
+  return domainResponseSchema.parse(result).data;
+}
+async function findDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainUrl(storeHash, projectUuid, domain, apiHost), {
+    method: "GET",
+    headers: authHeaders3(accessToken)
+  });
+  if (response.status === 404) {
+    return null;
+  }
+  await assertDomainResponse(response, "Failed to fetch domain");
+  const result = await response.json();
+  return domainResponseSchema.parse(result).data;
+}
+async function listDomains(projectUuid, storeHash, accessToken, apiHost, filters = {}) {
+  const search = new URLSearchParams();
+  if (filters.domains && filters.domains.length > 0) {
+    search.set("domain:in", filters.domains.join(","));
+  }
+  if (filters.verificationStatus) {
+    search.set("verification_status", filters.verificationStatus);
+  }
+  const query2 = search.toString();
+  const url = `${domainsUrl(storeHash, projectUuid, apiHost)}${query2 ? `?${query2}` : ""}`;
+  const response = await fetch(url, {
+    method: "GET",
+    headers: authHeaders3(accessToken)
+  });
+  await assertDomainResponse(response, "Failed to fetch domains");
+  const result = await response.json();
+  return domainListResponseSchema.parse(result).data;
+}
+async function deleteDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainUrl(storeHash, projectUuid, domain, apiHost), {
+    method: "DELETE",
+    headers: authHeaders3(accessToken)
+  });
+  await assertDomainResponse(response, `Failed to remove domain: ${response.statusText}`);
+}
+async function claimDomain(domain, projectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainClaimUrl(storeHash, projectUuid, domain, apiHost), {
+    method: "POST",
+    headers: authHeaders3(accessToken)
+  });
+  await assertDomainResponse(response, "Failed to claim domain");
+}
+async function transferDomain(domain, projectUuid, newProjectUuid, storeHash, accessToken, apiHost) {
+  const response = await fetch(domainTransferUrl(storeHash, projectUuid, domain, apiHost), {
+    method: "POST",
+    headers: {
+      ...authHeaders3(accessToken),
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ new_project_uuid: newProjectUuid })
+  });
+  await assertDomainResponse(response, "Failed to transfer domain");
+}
+
+// src/cli/commands/domains.ts
+var WAIT_INTERVAL_MS = 5e3;
+var WAIT_TIMEOUT_MS = 5 * 60 * 1e3;
+var DOMAIN_STATUS_FILTERS = ["pending", "verified", "failed"];
+var STATUS_COLORS = {
+  pending: "yellow",
+  verified: "green",
+  failed: "red",
+  unknown: "gray"
+};
+var STATUS_LABELS = {
+  pending: "pending",
+  verified: "active",
+  failed: "failed",
+  unknown: "unknown"
+};
+var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+function resolveDomainCommandContext(options) {
+  const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
+  const { storeHash, accessToken } = resolveCredentials(options, config2);
+  const projectUuid = resolveProjectUuid(options);
+  return {
+    projectUuid,
+    storeHash,
+    accessToken,
+    apiHost
+  };
+}
+async function resolveDestinationProject(domain, context, toProjectUuid) {
+  if (toProjectUuid) {
+    if (toProjectUuid === context.projectUuid) {
+      throw new UserActionableError("The destination project must differ from the source project.");
+    }
+    return toProjectUuid;
+  }
+  consola.start("Fetching projects...");
+  const projects = await fetchProjects(context.storeHash, context.accessToken, context.apiHost);
+  consola.success("Projects fetched.");
+  const destinations = projects.filter((project2) => project2.uuid !== context.projectUuid);
+  if (destinations.length === 0) {
+    throw new UserActionableError(
+      "No other projects to transfer to. Create another project with `catalyst project create` first."
+    );
+  }
+  return select6({
+    message: `Select the project to transfer ${domain} to (Press <enter> to select).`,
+    choices: destinations.map((project2) => ({
+      name: project2.name,
+      value: project2.uuid,
+      description: project2.uuid
+    }))
+  });
+}
+function formatDomainStatus(status) {
+  return colorize9(STATUS_COLORS[status], STATUS_LABELS[status]);
+}
+function formatDomain(domain) {
+  return `${domain.domain} ${formatDomainStatus(domain.verification_status)}`;
+}
+function formatOwnershipVerification(record) {
+  const lines = [
+    "Add this DNS record to verify ownership:",
+    `  Type:  ${record.type}`,
+    `  Name:  ${record.name}`
+  ];
+  if (record.value) {
+    lines.push(`  Value: ${record.value}`);
+  }
+  return lines.join("\n");
+}
+async function waitForDomainVerification({
+  domain,
+  projectUuid,
+  storeHash,
+  accessToken,
+  apiHost,
+  intervalMs = WAIT_INTERVAL_MS,
+  timeoutMs = WAIT_TIMEOUT_MS
+}) {
+  const startedAt = Date.now();
+  let current = await getDomain(domain, projectUuid, storeHash, accessToken, apiHost);
+  while (current.verification_status === "pending" && Date.now() - startedAt < timeoutMs) {
+    await sleep(intervalMs);
+    current = await getDomain(domain, projectUuid, storeHash, accessToken, apiHost);
+  }
+  return current;
+}
+var add = new Command7("add").configureHelp({ showGlobalOptions: true }).description("Add a custom domain to the current Native Hosting project.").argument("<domain>", "Custom domain to add.").addHelpText(
+  "after",
+  `
+Examples:
+  $ catalyst domains add www.example.com
+
+  # Wait until the domain leaves pending verification
+  $ catalyst domains add www.example.com --wait`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--wait", "Poll until domain verification completes or times out.").action(async (domain, options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start(`Adding domain ${domain}...`);
+  let result;
+  try {
+    result = await createDomain(
+      domain,
+      context.projectUuid,
+      context.storeHash,
+      context.accessToken,
+      context.apiHost
+    );
+  } catch (error) {
+    if (error instanceof DomainOwnershipVerificationError) {
+      consola.warn(`${domain} is already in use on another store.`);
+      consola.log(formatOwnershipVerification(error.ownershipVerification));
+      consola.info("Once the record is live, claim it with:");
+      consola.log(`  catalyst domains claim ${domain}`);
+      process.exit(1);
+      return;
+    }
+    if (error instanceof DomainBoundToProjectError) {
+      consola.warn(`${domain} is already bound to another project in this store.`);
+      consola.info("To move it to this project, run:");
+      consola.log(
+        `  catalyst domains transfer ${domain} --project-uuid ${error.projectUuid} --to-project-uuid ${context.projectUuid}`
+      );
+      process.exit(1);
+      return;
+    }
+    throw error;
+  }
+  consola.success(`Domain ${result.domain} added.`);
+  if (options.wait && result.verification_status === "pending") {
+    consola.start(`Waiting for ${result.domain} to verify...`);
+    result = await waitForDomainVerification({ domain: result.domain, ...context });
+  }
+  consola.log(formatDomain(result));
+  process.exit(0);
+});
+var list = new Command7("list").configureHelp({ showGlobalOptions: true }).description("List custom domains for the current Native Hosting project.").addHelpText(
+  "after",
+  `
+Examples:
+  $ catalyst domains list
+
+  # Show pending domains only
+  $ catalyst domains list --status pending`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--domain <domain>", "Only show a specific domain.").addOption(
+  new Option7("--status <status>", "Filter by verification status.").choices(
+    DOMAIN_STATUS_FILTERS
+  )
+).action(async (options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start("Fetching domains...");
+  const result = await listDomains(
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost,
+    {
+      domains: options.domain ? [options.domain] : void 0,
+      verificationStatus: options.status
+    }
+  );
+  consola.success("Domains fetched.");
+  if (result.length === 0) {
+    consola.info("No custom domains found.");
+    process.exit(0);
+    return;
+  }
+  result.forEach((item) => consola.log(formatDomain(item)));
+  process.exit(0);
+});
+var showStatus = new Command7("status").configureHelp({ showGlobalOptions: true }).description("Show the status of a custom domain on the current Native Hosting project.").argument("<domain>", "Custom domain to check.").addHelpText(
+  "after",
+  `
+Examples:
+  $ catalyst domains status www.example.com
+
+  # Wait until the domain leaves pending verification
+  $ catalyst domains status www.example.com --wait`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--wait", "Poll until domain verification completes or times out.").action(async (domain, options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start(`Fetching status for ${domain}...`);
+  let result = await getDomain(
+    domain,
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  consola.success("Domain status fetched.");
+  if (options.wait && result.verification_status === "pending") {
+    consola.start(`Waiting for ${result.domain} to verify...`);
+    result = await waitForDomainVerification({ domain: result.domain, ...context });
+  }
+  consola.log(formatDomain(result));
+  process.exit(0);
+});
+var claim = new Command7("claim").configureHelp({ showGlobalOptions: true }).description("Claim a custom domain that is currently in use on another store.").argument("<domain>", "Custom domain to claim.").addHelpText(
+  "after",
+  `
+Claiming requires publishing the ownership-verification TXT record returned when
+you try to add a domain that is already in use on another store. Publish the
+record with your DNS provider, then run this command to complete the claim.
+
+Examples:
+  $ catalyst domains claim www.example.com
+
+  # Wait until the claimed domain leaves pending verification
+  $ catalyst domains claim www.example.com --wait`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--wait", "Poll until domain verification completes or times out.").action(async (domain, options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start(`Claiming domain ${domain}...`);
+  try {
+    await claimDomain(
+      domain,
+      context.projectUuid,
+      context.storeHash,
+      context.accessToken,
+      context.apiHost
+    );
+  } catch (error) {
+    if (error instanceof DomainOwnershipVerificationError) {
+      consola.warn(`Ownership of ${domain} could not be verified yet.`);
+      consola.log(formatOwnershipVerification(error.ownershipVerification));
+      consola.info("Once the record is live, run the claim again:");
+      consola.log(`  catalyst domains claim ${domain}`);
+      process.exit(1);
+      return;
+    }
+    throw error;
+  }
+  consola.success(`Domain ${domain} claimed.`);
+  let result = await getDomain(
+    domain,
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  if (options.wait && result.verification_status === "pending") {
+    consola.start(`Waiting for ${result.domain} to verify...`);
+    result = await waitForDomainVerification({ domain: result.domain, ...context });
+  }
+  consola.log(formatDomain(result));
+  process.exit(0);
+});
+var transfer = new Command7("transfer").configureHelp({ showGlobalOptions: true }).description("Transfer a custom domain to another project in the same store.").argument("<domain>", "Custom domain to transfer.").addHelpText(
+  "after",
+  `
+The domain is transferred from the current project to the destination project.
+Omit --to-project-uuid to pick the destination from a list of your projects.
+
+Examples:
+  # Pick the destination project interactively
+  $ catalyst domains transfer www.example.com
+
+  # Transfer to a specific project
+  $ catalyst domains transfer www.example.com --to-project-uuid <uuid>`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--to-project-uuid <uuid>", "Destination project UUID. Prompts to choose one if omitted.").option("--wait", "Poll until domain verification completes or times out.").action(async (domain, options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start(`Checking ${domain} on the current project...`);
+  const owned = await findDomain(
+    domain,
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
   );
-  if (!options.updateSiteUrl) {
+  if (!owned) {
+    consola.start(`Locating the project that owns ${domain}...`);
+    const projects = await fetchProjects(context.storeHash, context.accessToken, context.apiHost);
+    const candidates = projects.filter((project2) => project2.uuid !== context.projectUuid);
+    const matches = await Promise.all(
+      candidates.map(async (project2) => ({
+        project: project2,
+        found: await findDomain(
+          domain,
+          project2.uuid,
+          context.storeHash,
+          context.accessToken,
+          context.apiHost
+        )
+      }))
+    );
+    const owner = matches.find((match) => match.found)?.project;
+    if (!owner) {
+      throw new UserActionableError(
+        `${domain} isn't on any project in this store. If it's in use on another store, claim it with \`catalyst domains claim ${domain}\`; otherwise double-check the domain name.`
+      );
+    }
+    const toSuffix = options.toProjectUuid ? ` --to-project-uuid ${options.toProjectUuid}` : "";
+    consola.warn(
+      `${domain} is on project "${owner.name}" (${owner.uuid}), not the current project.`
+    );
+    consola.info("Re-run the transfer from that project:");
+    consola.log(`  catalyst domains transfer ${domain} --project-uuid ${owner.uuid}${toSuffix}`);
+    process.exit(1);
     return;
   }
-  try {
-    await runChannelSiteUrlFlow({
-      storeHash,
-      accessToken,
-      apiHost: options.apiHost,
-      projectUuid,
-      preferHostname: deploymentHostname
+  consola.success(`${domain} found on the current project.`);
+  const newProjectUuid = await resolveDestinationProject(domain, context, options.toProjectUuid);
+  consola.start(`Transferring domain ${domain}...`);
+  await transferDomain(
+    domain,
+    context.projectUuid,
+    newProjectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  consola.success(`Domain ${domain} transferred.`);
+  let result = await getDomain(
+    domain,
+    newProjectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  if (options.wait && result.verification_status === "pending") {
+    consola.start(`Waiting for ${result.domain} to verify...`);
+    result = await waitForDomainVerification({
+      domain: result.domain,
+      projectUuid: newProjectUuid,
+      storeHash: context.storeHash,
+      accessToken: context.accessToken,
+      apiHost: context.apiHost
     });
-  } catch (error) {
-    consola.warn(
-      `Failed to update channel site URL: ${error instanceof Error ? error.message : String(error)}`
-    );
-    consola.info(
-      "Update it manually in the control panel, or re-run `catalyst auth login` if the token is missing the store_channel_settings scope."
-    );
   }
+  consola.log(formatDomain(result));
+  process.exit(0);
+});
+var remove = new Command7("remove").configureHelp({ showGlobalOptions: true }).description("Remove a custom domain from the current Native Hosting project.").argument("<domain>", "Custom domain to remove.").addHelpText(
+  "after",
+  `
+Examples:
+  $ catalyst domains remove www.example.com
+
+  # Skip confirmation for an active domain
+  $ catalyst domains remove www.example.com --force`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--force", "Skip the confirmation prompt before removing an active domain.").action(async (domain, options) => {
+  const context = resolveDomainCommandContext(options);
+  await getTelemetry().identify(context.storeHash);
+  consola.start(`Fetching status for ${domain}...`);
+  const current = await getDomain(
+    domain,
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  if (current.verification_status === "verified" && !options.force) {
+    const confirmed = await confirm4({
+      message: `Remove active domain ${current.domain}? Traffic may stop routing to this project.`,
+      default: false
+    });
+    if (!confirmed) {
+      consola.info("Aborted. No domain was removed.");
+      process.exit(0);
+      return;
+    }
+  }
+  consola.start(`Removing domain ${current.domain}...`);
+  await deleteDomain(
+    current.domain,
+    context.projectUuid,
+    context.storeHash,
+    context.accessToken,
+    context.apiHost
+  );
+  consola.success(`Domain ${current.domain} removed.`);
+  process.exit(0);
 });
+var domains = new Command7("domains").configureHelp({ showGlobalOptions: true }).description("Manage custom domains for the current Native Hosting project.").addCommand(add).addCommand(list).addCommand(showStatus).addCommand(claim).addCommand(transfer).addCommand(remove);
 
 // src/cli/commands/env.ts
-import { Command as Command6 } from "commander";
+import { Command as Command8 } from "commander";
 var MASK = "\u2022\u2022\u2022\u2022\u2022\u2022";
-var add = new Command6("add").configureHelp({ showGlobalOptions: true }).description(
+var add2 = new Command8("add").configureHelp({ showGlobalOptions: true }).description(
   "Add or update one or more deployment environment variables. Stored in .bigcommerce/project.json and sent as secrets on every `catalyst deploy`."
 ).argument("<vars...>", "One or more environment variables in KEY=VALUE format.").addHelpText(
   "after",
@@ -2700,7 +4028,7 @@ Example:
   keys.forEach((key) => consola.log(`  ${key}=${MASK}`));
   process.exit(0);
 });
-var remove = new Command6("remove").configureHelp({ showGlobalOptions: true }).description("Remove one or more stored deployment environment variables.").argument("<keys...>", "One or more environment variable names to remove.").addHelpText(
+var remove2 = new Command8("remove").configureHelp({ showGlobalOptions: true }).description("Remove one or more stored deployment environment variables.").argument("<keys...>", "One or more environment variable names to remove.").addHelpText(
   "after",
   `
 Example:
@@ -2726,7 +4054,7 @@ Example:
   }
   process.exit(0);
 });
-var list = new Command6("list").configureHelp({ showGlobalOptions: true }).description("List stored deployment environment variables (values are masked).").addHelpText(
+var list2 = new Command8("list").configureHelp({ showGlobalOptions: true }).description("List stored deployment environment variables (values are masked).").addHelpText(
   "after",
   `
 Example:
@@ -2743,41 +4071,41 @@ Example:
   keys.forEach((key) => consola.log(`${key}=${MASK}`));
   process.exit(0);
 });
-var env = new Command6("env").configureHelp({ showGlobalOptions: true }).description(
+var env = new Command8("env").configureHelp({ showGlobalOptions: true }).description(
   "Manage persistent deployment environment variables. These are sent as secrets on every `catalyst deploy`, so you no longer need to pass `--secret` each time."
-).addCommand(add).addCommand(remove).addCommand(list);
+).addCommand(add2).addCommand(remove2).addCommand(list2);
 
 // src/cli/commands/logs.ts
-import { Command as Command7, Option as Option7 } from "commander";
-import { colorize as colorize6 } from "consola/utils";
-import { z as z11 } from "zod";
+import { Command as Command9, InvalidArgumentError as InvalidArgumentError4, Option as Option8 } from "commander";
+import { colorize as colorize10 } from "consola/utils";
+import { z as z16 } from "zod";
 var telemetry = new Telemetry();
 var DEFAULT_CONNECTION_TTL_MS = 1 * 60 * 1e3;
 var MAX_RETRIES = 5;
 var isFatalStatusCode = (status) => status >= 400 && status < 500;
-var LEVEL_COLORS = {
+var LEVEL_COLORS2 = {
   INFO: "green",
   WARN: "yellow",
   ERROR: "red",
   DEBUG: "gray"
 };
-var LogEventSchema = z11.object({
-  uuid: z11.string(),
-  project_uuid: z11.string(),
-  request: z11.object({
-    method: z11.string(),
-    url: z11.string(),
-    status_code: z11.number()
+var LogEventSchema = z16.object({
+  uuid: z16.string(),
+  project_uuid: z16.string(),
+  request: z16.object({
+    method: z16.string(),
+    url: z16.string(),
+    status_code: z16.number()
   }),
-  logs: z11.array(
-    z11.object({
-      timestamp: z11.string(),
-      level: z11.string(),
-      messages: z11.array(z11.unknown())
+  logs: z16.array(
+    z16.object({
+      timestamp: z16.string(),
+      level: z16.string(),
+      messages: z16.array(z16.unknown())
     })
   ),
-  exceptions: z11.array(z11.unknown()),
-  timestamp: z11.string()
+  exceptions: z16.array(z16.unknown()),
+  timestamp: z16.string()
 }).loose();
 var StreamError = class extends Error {
   constructor(message, fatal) {
@@ -2791,7 +4119,7 @@ var formatLogEvent = (event, format) => {
   logEntries.forEach((entry) => {
     const msg = formatMessages(entry.messages);
     const level = entry.level.toUpperCase();
-    const coloredLevel = colorize6(LEVEL_COLORS[level] ?? "white", level);
+    const coloredLevel = colorize10(LEVEL_COLORS2[level] ?? "white", level);
     switch (format) {
       case "short":
         consola.log(msg);
@@ -2862,10 +4190,8 @@ var openLogStream = async (projectUuid, storeHash, accessToken, apiHost) => {
     throw new StreamError(new UnauthorizedError().message, true);
   }
   if (!response.ok) {
-    throw new StreamError(
-      `Failed to open log stream: ${response.status} ${response.statusText}`,
-      isFatalStatusCode(response.status)
-    );
+    const error = await httpError(response, "Failed to open log stream");
+    throw new StreamError(error.message, isFatalStatusCode(response.status));
   }
   const reader = response.body?.getReader();
   if (!reader) {
@@ -2934,7 +4260,7 @@ var tailLogs = async (projectUuid, storeHash, accessToken, apiHost, format, conn
     }
   }
 };
-var tail = new Command7("tail").configureHelp({ showGlobalOptions: true }).description("Tail live logs from your deployed application.").addHelpText(
+var tail = new Command9("tail").configureHelp({ showGlobalOptions: true }).description("Tail live logs from your deployed application.").addHelpText(
   "after",
   `
 Examples:
@@ -2946,44 +4272,127 @@ Examples:
   # Tail logs as raw JSON (useful for piping to other tools)
   $ catalyst logs tail --format json`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).addOption(
-  new Option7("--format <format>", "Output format for log events.").choices(["json", "pretty", "default", "short", "request"]).default("default")
+  new Option8("--format <format>", "Output format for log events.").choices(["json", "pretty", "default", "short", "request"]).default("default")
 ).action(async (options) => {
   try {
     const config2 = getProjectConfig();
+    const apiHost = resolveApiHost(options, config2);
     const { storeHash, accessToken } = resolveCredentials(options, config2);
     await telemetry.identify(storeHash);
     const projectUuid = resolveProjectUuid(options);
-    await tailLogs(projectUuid, storeHash, accessToken, options.apiHost, options.format);
+    await tailLogs(projectUuid, storeHash, accessToken, apiHost, options.format);
   } catch (error) {
     consola.error(error);
     process.exit(1);
   }
 });
-var query = new Command7("query").configureHelp({ showGlobalOptions: true }).description("Query historical logs from your deployed application.").addHelpText(
+var parseIntInRange = (flag, min, max) => (value) => {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw new InvalidArgumentError4(`${flag} must be an integer between ${min} and ${max}.`);
+  }
+  return parsed;
+};
+var query = new Command9("query").configureHelp({ showGlobalOptions: true }).description("Query historical logs from your deployed application.").addHelpText(
   "after",
   `
-Example:
-  $ catalyst logs query`
-).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).action((options) => {
-  const config2 = getProjectConfig();
-  resolveCredentials(options, config2);
-  consola.error("The query command is not yet implemented.");
-  process.exit(1);
+Specify a time window with \`--since\` (relative to now) or \`--start\`/\`--end\`
+(ISO-8601 timestamps or Unix epoch seconds, UTC). The window may not exceed
+7 days. Entries print oldest-first; timestamps are UTC.
+
+Examples:
+  # Last hour of logs
+  $ catalyst logs query --since 1h
+
+  # Everything from today (UTC)
+  $ catalyst logs query --start 2026-06-11T00:00:00Z
+
+  # Errors only for a specific path
+  $ catalyst logs query --since 24h --level-min error --url-like /cart
+
+  # Errors with request details (method, URL, status)
+  $ catalyst logs query --since 1h --level-min error --format request
+
+  # Raw JSON (NDJSON) for piping to other tools
+  $ catalyst logs query --since 2d --format json`
+).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).addOption(
+  new Option8(
+    "--since <duration>",
+    "Relative window ending at --end (default: now), e.g. 30m, 6h, 2d (units: s, m, h, d)."
+  ).conflicts("start")
+).option("--start <time>", "Window start: ISO-8601 timestamp or Unix epoch (seconds).").option(
+  "--end <time>",
+  "Window end: ISO-8601 timestamp or Unix epoch (seconds). Defaults to now. The window must not exceed 7 days."
+).option("--method <method>", "Filter by request HTTP method (case-insensitive).").addOption(
+  new Option8("--status-code <code>", "Filter by response status code (100-599).").argParser(
+    parseIntInRange("--status-code", 100, 599)
+  )
+).option("--url-like <substring>", "Filter by URL substring (case-sensitive).").addOption(
+  new Option8("--level-min <level>", "Minimum log level.").choices(Array.from(LOG_LEVELS))
+).addOption(
+  new Option8("--limit <n>", "Maximum number of entries to return (1-500).").argParser(parseIntInRange("--limit", 1, 500)).default(100)
+).addOption(
+  new Option8("--format <format>", "Output format for log entries.").choices(["json", "pretty", "default", "short", "request"]).default("default")
+).action(async (options) => {
+  try {
+    const config2 = getProjectConfig();
+    const apiHost = resolveApiHost(options, config2);
+    const { storeHash, accessToken } = resolveCredentials(options, config2);
+    await telemetry.identify(storeHash);
+    const projectUuid = resolveProjectUuid(options);
+    const { start: start2, end } = resolveTimeWindow(options);
+    const result = await queryLogs(projectUuid, storeHash, accessToken, apiHost, {
+      start: start2,
+      end,
+      method: options.method,
+      statusCode: options.statusCode,
+      urlLike: options.urlLike,
+      levelMin: options.levelMin,
+      limit: options.limit
+    });
+    const entries = result.data;
+    const ordered = [...entries].reverse();
+    if (options.format === "json") {
+      ordered.forEach((entry) => process.stdout.write(`${JSON.stringify(entry)}
+`));
+      return;
+    }
+    if (options.format === "pretty") {
+      ordered.forEach((entry) => consola.log(JSON.stringify(entry, null, 2)));
+      return;
+    }
+    if (entries.length === 0) {
+      consola.info("No log entries found for the given window and filters.");
+      return;
+    }
+    const lineFormat = options.format;
+    ordered.forEach((entry) => consola.log(formatLogEntry(entry, lineFormat)));
+    consola.info(
+      `${entries.length} ${entries.length === 1 ? "entry" : "entries"} shown (oldest first, times in UTC).`
+    );
+    if (entries.length === options.limit) {
+      consola.info(
+        `Limit of ${options.limit} reached; older entries may exist. Narrow the time window or raise --limit (max 500) to see more.`
+      );
+    }
+  } catch (error) {
+    consola.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
 });
-var logs = new Command7("logs").configureHelp({ showGlobalOptions: true }).description("View logs from your deployed application.").addCommand(tail, { isDefault: true }).addCommand(query);
+var logs = new Command9("logs").configureHelp({ showGlobalOptions: true }).description("View logs from your deployed application.").addCommand(tail, { isDefault: true }).addCommand(query);
 
 // src/cli/commands/project.ts
-import { confirm as confirm4, input as input4, select as select5 } from "@inquirer/prompts";
-import { Command as Command8 } from "commander";
-import { colorize as colorize7 } from "consola/utils";
-import { dirname as dirname5 } from "path";
+import { confirm as confirm5, input as input5, select as select7 } from "@inquirer/prompts";
+import { Command as Command10 } from "commander";
+import { colorize as colorize11 } from "consola/utils";
 async function offerCommerceHostingSetup(projectUuid, credentials) {
-  const projectDir = dirname5(process.cwd());
+  const projectDir = process.cwd();
   if (getProjectState().isTransformed) {
     await cleanupCloudflareIncompatibilities(projectDir);
     return;
   }
-  const shouldSetup = await confirm4({
+  const shouldSetup = await confirm5({
     message: "Your project has been linked, but is not fully set up for Commerce Hosting deployments yet. Would you like to run the setup now?",
     default: true
   });
@@ -2995,19 +4404,21 @@ async function offerCommerceHostingSetup(projectUuid, credentials) {
     accessToken: credentials?.accessToken
   });
   consola.success("Commerce Hosting setup complete.");
-  await installDependencies(projectDir);
+  const packageManager = await detectProjectPackageManager(projectDir);
+  await installDependencies(projectDir, packageManager);
 }
-var list2 = new Command8("list").configureHelp({ showGlobalOptions: true }).description("List BigCommerce infrastructure projects for your store.").addHelpText(
+var list3 = new Command10("list").configureHelp({ showGlobalOptions: true }).description("List BigCommerce infrastructure projects for your store.").addHelpText(
   "after",
   `
 Example:
   $ catalyst project list`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   await getTelemetry().identify(storeHash);
   consola.start("Fetching projects...");
-  const projects = await fetchProjects(storeHash, accessToken, options.apiHost);
+  const projects = await fetchProjects(storeHash, accessToken, apiHost);
   consola.success("Projects fetched.");
   if (projects.length === 0) {
     consola.info("No projects found.");
@@ -3016,16 +4427,16 @@ Example:
   }
   const linkedProjectUuid = config2.get("projectUuid");
   const projectList = projects.map((p) => {
-    const marker = p.uuid === linkedProjectUuid ? ` ${colorize7("green", "[linked]")}` : "";
+    const marker = p.uuid === linkedProjectUuid ? ` ${colorize11("green", "[linked]")}` : "";
     const hostnames = p.deployment_hostnames.length === 0 ? ["  (not deployed)"] : p.deployment_hostnames.map(
-      (hostname) => `  ${colorize7("blue", `https://${hostname}`)}`
+      (hostname) => `  ${colorize11("blue", `https://${hostname}`)}`
     );
     return [`${p.name} (${p.uuid})${marker}`, ...hostnames].join("\n");
   });
   consola.log(projectList.join("\n\n"));
   process.exit(0);
 });
-var create2 = new Command8("create").configureHelp({ showGlobalOptions: true }).description(
+var create3 = new Command10("create").configureHelp({ showGlobalOptions: true }).description(
   "Create a new BigCommerce infrastructure project and link it to your local Catalyst project. Walks you through logging in if you are not authenticated yet."
 ).addHelpText(
   "after",
@@ -3034,6 +4445,7 @@ Example:
   $ catalyst project create`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(loginUrlOption()).action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   let storeHash = options.storeHash ?? config2.get("storeHash");
   let accessToken = options.accessToken ?? config2.get("accessToken");
   if (!storeHash || !accessToken) {
@@ -3041,7 +4453,7 @@ Example:
       "You're not logged in yet. Let's get you authenticated before creating a project."
     );
     try {
-      const credentials = await login(options.loginUrl, options.apiHost);
+      const credentials = await login(options.loginUrl, apiHost);
       storeHash = credentials.storeHash;
       accessToken = credentials.accessToken;
       config2.set("storeHash", storeHash);
@@ -3059,8 +4471,8 @@ Example:
     }
   }
   await getTelemetry().identify(storeHash);
-  const newProjectName = await input4({ message: "Enter a name for the new project:" });
-  const data = await createProject(newProjectName, storeHash, accessToken, options.apiHost);
+  const newProjectName = await input5({ message: "Enter a name for the new project:" });
+  const data = await createProject(newProjectName, storeHash, accessToken, apiHost);
   consola.success(`Project "${data.name}" created successfully.`);
   consola.start("Writing project UUID to .bigcommerce/project.json...");
   config2.set("projectUuid", data.uuid);
@@ -3069,7 +4481,7 @@ Example:
   consola.success("Project UUID written to .bigcommerce/project.json.");
   process.exit(0);
 });
-var link2 = new Command8("link").configureHelp({ showGlobalOptions: true }).description(
+var link2 = new Command10("link").configureHelp({ showGlobalOptions: true }).description(
   "Link your local Catalyst project to a BigCommerce infrastructure project. You can provide a project UUID directly, or fetch and select from available projects using your store credentials."
 ).addHelpText(
   "after",
@@ -3082,6 +4494,7 @@ Examples:
   $ catalyst project link --project-uuid <UUID>`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   const writeProjectConfig = (uuid, credentials) => {
     consola.start("Writing project UUID to .bigcommerce/project.json...");
     config2.set("projectUuid", uuid);
@@ -3102,7 +4515,7 @@ Examples:
   let selected;
   try {
     selected = await selectOrCreateInfrastructureProject(
-      { storeHash, accessToken, apiHost: options.apiHost },
+      { storeHash, accessToken, apiHost },
       config2.get("projectUuid")
     );
   } catch (error) {
@@ -3119,7 +4532,7 @@ Examples:
   await offerCommerceHostingSetup(selected.uuid, { storeHash, accessToken });
   process.exit(0);
 });
-var del = new Command8("delete").configureHelp({ showGlobalOptions: true }).description(
+var del = new Command10("delete").configureHelp({ showGlobalOptions: true }).description(
   "Permanently delete a BigCommerce infrastructure project. This action is irreversible."
 ).addHelpText(
   "after",
@@ -3135,13 +4548,14 @@ Examples:
   $ catalyst project delete --project-uuid <UUID> --force`
 ).addOption(storeHashOption()).addOption(accessTokenOption()).addOption(apiHostOption()).addOption(projectUuidOption()).option("--force", "Skip the confirmation prompt before deleting.").action(async (options) => {
   const config2 = getProjectConfig();
+  const apiHost = resolveApiHost(options, config2);
   const { storeHash, accessToken } = resolveCredentials(options, config2);
   await getTelemetry().identify(storeHash);
   let targetUuid = options.projectUuid;
   let targetName;
   if (!targetUuid) {
     consola.start("Fetching projects...");
-    const projects = await fetchProjects(storeHash, accessToken, options.apiHost);
+    const projects = await fetchProjects(storeHash, accessToken, apiHost);
     consola.success("Projects fetched.");
     if (projects.length === 0) {
       consola.info("No projects found.");
@@ -3149,11 +4563,11 @@ Examples:
       return;
     }
     const linkedProjectUuid = config2.get("projectUuid");
-    const selected = await select5({
+    const selected = await select7({
       message: "Select a project to delete (Press <enter> to select).",
       choices: [
         ...projects.map((p) => ({
-          name: p.uuid === linkedProjectUuid ? `${p.name} ${colorize7("green", "[linked]")}` : p.name,
+          name: p.uuid === linkedProjectUuid ? `${p.name} ${colorize11("green", "[linked]")}` : p.name,
           value: p.uuid,
           description: p.uuid
         })),
@@ -3174,7 +4588,7 @@ Examples:
   }
   if (!options.force) {
     const label = targetName ? `"${targetName}" (${targetUuid})` : targetUuid;
-    const confirmed = await confirm4({
+    const confirmed = await confirm5({
       message: `Are you sure you want to delete project ${label}? This action is irreversible and will permanently destroy the project and all of its data.`,
       default: false
     });
@@ -3185,7 +4599,7 @@ Examples:
     }
   }
   consola.start(`Deleting project ${targetUuid}...`);
-  await deleteProject(targetUuid, storeHash, accessToken, options.apiHost);
+  await deleteProject(targetUuid, storeHash, accessToken, apiHost);
   consola.success(`Project ${targetUuid} deleted.`);
   if (config2.get("projectUuid") === targetUuid) {
     config2.delete("projectUuid");
@@ -3193,14 +4607,14 @@ Examples:
   }
   process.exit(0);
 });
-var project = new Command8("project").configureHelp({ showGlobalOptions: true }).description("Manage your BigCommerce infrastructure project.").addCommand(create2).addCommand(list2).addCommand(link2).addCommand(del);
+var project = new Command10("project").configureHelp({ showGlobalOptions: true }).description("Manage your BigCommerce infrastructure project.").addCommand(create3).addCommand(list3).addCommand(link2).addCommand(del);
 
 // src/cli/commands/start.ts
-import { Command as Command9 } from "commander";
-import { execa as execa2 } from "execa";
-import { existsSync as existsSync4, lstatSync as lstatSync2, symlinkSync as symlinkSync2 } from "fs";
-import { join as join12, relative } from "path";
-var start = new Command9("start").configureHelp({ showGlobalOptions: true }).description(
+import { Command as Command11 } from "commander";
+import { execa as execa3 } from "execa";
+import { existsSync as existsSync6, lstatSync, symlinkSync } from "fs";
+import { join as join13, relative } from "path";
+var start = new Command11("start").configureHelp({ showGlobalOptions: true }).description(
   "Start a local preview of your Catalyst storefront using the OpenNext Cloudflare adapter."
 ).addHelpText(
   "after",
@@ -3211,20 +4625,20 @@ Example:
   const state = getProjectState();
   if (!state.isTransformed) {
     consola.info("Project is not set up for Commerce Hosting \u2014 running `next start`.");
-    await execa2("pnpm", ["exec", "next", "start"], {
+    await execa3("pnpm", ["exec", "next", "start"], {
       stdio: "inherit",
       cwd: process.cwd()
     });
     return;
   }
-  const envLocal = join12(process.cwd(), ".env.local");
-  const devVars = join12(process.cwd(), ".bigcommerce", ".dev.vars");
-  if (existsSync4(envLocal)) {
-    if (!existsSync4(devVars)) {
-      const target = relative(join12(process.cwd(), ".bigcommerce"), envLocal);
-      symlinkSync2(target, devVars);
+  const envLocal = join13(process.cwd(), ".env.local");
+  const devVars = join13(process.cwd(), ".bigcommerce", ".dev.vars");
+  if (existsSync6(envLocal)) {
+    if (!existsSync6(devVars)) {
+      const target = relative(join13(process.cwd(), ".bigcommerce"), envLocal);
+      symlinkSync(target, devVars);
       consola.success("Symlinked .bigcommerce/.dev.vars \u2192 .env.local");
-    } else if (!lstatSync2(devVars).isSymbolicLink()) {
+    } else if (!lstatSync(devVars).isSymbolicLink()) {
       consola.warn(
         ".bigcommerce/.dev.vars already exists and is not a symlink. Wrangler will use it instead of .env.local."
       );
@@ -3234,14 +4648,14 @@ Example:
       "No .env.local file found. The preview server may fail without environment variables.\nCreate a .env.local file in your project root with the required variables."
     );
   }
-  await execa2(
+  await execa3(
     "pnpm",
     [
       "exec",
       "opennextjs-cloudflare",
       "preview",
       "--config",
-      join12(".bigcommerce", "wrangler.jsonc")
+      join13(".bigcommerce", "wrangler.jsonc")
     ],
     {
       stdio: "inherit",
@@ -3251,11 +4665,11 @@ Example:
 });
 
 // src/cli/commands/telemetry.ts
-import { Argument, Command as Command10, Option as Option8 } from "commander";
-import { colorize as colorize8 } from "consola/utils";
+import { Argument, Command as Command12, Option as Option9 } from "commander";
+import { colorize as colorize12 } from "consola/utils";
 var telemetryService = getTelemetry();
 var isEnabled = telemetryService.isEnabled();
-var telemetry2 = new Command10("telemetry").configureHelp({ showGlobalOptions: true }).description(
+var telemetry2 = new Command12("telemetry").configureHelp({ showGlobalOptions: true }).description(
   "View or change CLI telemetry collection status. Enabling telemetry helps BigCommerce support diagnose and troubleshoot errors you encounter when using the CLI."
 ).addHelpText(
   "after",
@@ -3269,7 +4683,7 @@ Examples:
 
   # Disable telemetry collection
   $ catalyst telemetry --disable`
-).addArgument(new Argument("[arg]").choices(["disable", "enable", "status"])).addOption(new Option8("--enable", `Enables CLI telemetry collection.`).conflicts("disable")).option("--disable", `Disables CLI telemetry collection.`).action((arg, options) => {
+).addArgument(new Argument("[arg]").choices(["disable", "enable", "status"])).addOption(new Option9("--enable", `Enables CLI telemetry collection.`).conflicts("disable")).option("--disable", `Disables CLI telemetry collection.`).action((arg, options) => {
   if (options.enable || arg === "enable") {
     telemetryService.setEnabled(true);
     isEnabled = true;
@@ -3286,7 +4700,7 @@ Examples:
     consola.info("Catalyst CLI Telemetry\n");
   }
   consola.info(
-    `Status: ${colorize8("bold", isEnabled ? colorize8("green", "Enabled") : colorize8("red", "Disabled"))}`
+    `Status: ${colorize12("bold", isEnabled ? colorize12("green", "Enabled") : colorize12("red", "Disabled"))}`
   );
   if (!isEnabled) {
     consola.info(
@@ -3295,9 +4709,649 @@ Examples:
   }
 });
 
+// src/cli/commands/upgrade.ts
+import { Command as Command13, Option as Option10 } from "@commander-js/extra-typings";
+import { confirm as confirm6 } from "@inquirer/prompts";
+import { execa as execa4 } from "execa";
+import {
+  access as access2,
+  copyFile as copyFile2,
+  cp as cp2,
+  mkdir,
+  mkdtemp,
+  readdir as readdir2,
+  readFile as readFile2,
+  rename,
+  rm as rm2,
+  writeFile as writeFile2
+} from "fs/promises";
+import { homedir, tmpdir } from "os";
+import { dirname as dirname5, join as join14, relative as relative2 } from "path";
+import yoctoSpinner4 from "yocto-spinner";
+import { z as z17 } from "zod";
+var CorePackageJson = z17.object({
+  name: z17.string().optional(),
+  version: z17.string(),
+  catalyst: z17.object({ version: z17.string(), ref: z17.string() }).optional()
+});
+var DEFAULT_REPOSITORY = "bigcommerce/catalyst";
+var MOVING_TAGS = /* @__PURE__ */ new Set(["latest", "canary", "alpha"]);
+var KNOWN_FAMILIES = /* @__PURE__ */ new Set([
+  "@bigcommerce/catalyst-core",
+  "@bigcommerce/catalyst-makeswift",
+  "@bigcommerce/catalyst-b2b-makeswift",
+  "@bigcommerce/catalyst-b2b"
+]);
+var CACHE_DIR = join14(homedir(), ".cache", "catalyst-cli", "cores");
+var pathExists = (p) => access2(p).then(() => true).catch(() => false);
+async function listFiles(dir, prefix = "") {
+  const entries = await readdir2(dir, { withFileTypes: true }).catch(() => []);
+  const nested = await Promise.all(
+    entries.map((entry) => {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      return entry.isDirectory() ? listFiles(join14(dir, entry.name), rel) : Promise.resolve([rel]);
+    })
+  );
+  return nested.flat();
+}
+async function filesEqual(a, b) {
+  const [ba, bb] = await Promise.all([
+    readFile2(a).catch(() => null),
+    readFile2(b).catch(() => null)
+  ]);
+  return ba !== null && bb !== null && ba.equals(bb);
+}
+async function computeBaseSimilarity(baseDir, destDir) {
+  const baseFiles = await listFiles(baseDir);
+  if (baseFiles.length === 0) return 0;
+  const matches = await Promise.all(
+    baseFiles.map((rel) => filesEqual(join14(baseDir, rel), join14(destDir, rel)))
+  );
+  return matches.filter(Boolean).length / baseFiles.length;
+}
+async function isBinary(p) {
+  const buf = await readFile2(p).catch(() => null);
+  if (!buf) return false;
+  return buf.subarray(0, 8e3).includes(0);
+}
+async function copyInto(src, dest) {
+  await mkdir(dirname5(dest), { recursive: true });
+  await copyFile2(src, dest);
+}
+function parseRef(ref) {
+  const lastAt = ref.lastIndexOf("@");
+  if (lastAt <= 0) throw new Error(`Cannot parse ref "${ref}" \u2014 expected <package>@<version>.`);
+  return { packageName: ref.slice(0, lastAt), version: ref.slice(lastAt + 1) };
+}
+async function readResolvedVersion(coreDir) {
+  const raw = await readFile2(join14(coreDir, "package.json"), "utf-8");
+  const pkg = CorePackageJson.parse(JSON.parse(raw));
+  return pkg.catalyst?.version ?? pkg.version;
+}
+async function mergeFile(oursPath, basePath, theirsPath) {
+  const merged = await execa4(
+    "git",
+    [
+      "merge-file",
+      "-p",
+      "-L",
+      "ours",
+      "-L",
+      "base",
+      "-L",
+      "theirs",
+      oursPath,
+      basePath,
+      theirsPath
+    ],
+    { reject: false, stripFinalNewline: false }
+  );
+  if (merged.stderr) throw new Error(`git merge-file failed: ${merged.stderr}`);
+  await writeFile2(oursPath, merged.stdout);
+  return (merged.exitCode ?? 0) > 0;
+}
+async function mergeModified(rel, baseDir, theirsDir, catalystRoot) {
+  const basePath = join14(baseDir, rel);
+  const theirsPath = join14(theirsDir, rel);
+  const oursPath = join14(catalystRoot, rel);
+  if (await filesEqual(basePath, theirsPath)) return null;
+  if (!await pathExists(oursPath)) {
+    await copyInto(theirsPath, oursPath);
+    return "conflicted";
+  }
+  if (await isBinary(basePath) || await isBinary(theirsPath) || await isBinary(oursPath)) {
+    if (await filesEqual(oursPath, basePath)) {
+      await copyInto(theirsPath, oursPath);
+      return "applied";
+    }
+    return "conflicted";
+  }
+  return await mergeFile(oursPath, basePath, theirsPath) ? "conflicted" : "applied";
+}
+async function mergeAdded(rel, theirsDir, catalystRoot, emptyFile) {
+  const theirsPath = join14(theirsDir, rel);
+  const oursPath = join14(catalystRoot, rel);
+  if (!await pathExists(oursPath)) {
+    await copyInto(theirsPath, oursPath);
+    return "added";
+  }
+  if (await filesEqual(oursPath, theirsPath)) return "applied";
+  if (await isBinary(oursPath) || await isBinary(theirsPath)) return "conflicted";
+  const hadConflict = await mergeFile(oursPath, emptyFile, theirsPath);
+  return hadConflict ? "conflicted" : "applied";
+}
+async function mergeDeleted(rel, baseDir, catalystRoot) {
+  const basePath = join14(baseDir, rel);
+  const oursPath = join14(catalystRoot, rel);
+  if (!await pathExists(oursPath)) return null;
+  if (await filesEqual(oursPath, basePath)) {
+    await rm2(oursPath, { force: true });
+    return "deleted";
+  }
+  return "conflicted";
+}
+async function mergeCorePerFile(baseDir, theirsDir, catalystRoot, emptyFile) {
+  const baseFiles = new Set(await listFiles(baseDir));
+  const theirsFiles = new Set(await listFiles(theirsDir));
+  const result = { applied: [], added: [], deleted: [], conflicted: [] };
+  const decide = async (rel) => {
+    const inBase = baseFiles.has(rel);
+    const inTheirs = theirsFiles.has(rel);
+    let outcome;
+    if (inBase && inTheirs) {
+      outcome = await mergeModified(rel, baseDir, theirsDir, catalystRoot);
+    } else if (inTheirs) {
+      outcome = await mergeAdded(rel, theirsDir, catalystRoot, emptyFile);
+    } else {
+      outcome = await mergeDeleted(rel, baseDir, catalystRoot);
+    }
+    if (outcome) result[outcome].push(rel);
+  };
+  await Promise.all([.../* @__PURE__ */ new Set([...baseFiles, ...theirsFiles])].map(decide));
+  return result;
+}
+async function gitSupportsMergeTree() {
+  try {
+    const { stdout } = await execa4("git", ["--version"]);
+    const match = /(\d+)\.(\d+)/.exec(stdout);
+    if (!match) return false;
+    const [major, minor] = [Number(match[1]), Number(match[2])];
+    return major > 2 || major === 2 && minor >= 38;
+  } catch {
+    return false;
+  }
+}
+async function resolveStrategy(strategy) {
+  if (strategy !== "auto") return strategy;
+  if (await gitSupportsMergeTree()) return "tree";
+  consola.warn("git < 2.38 \u2014 using the per-file merge engine (no `git merge-tree`).");
+  return "per-file";
+}
+async function mergeCoreTree(baseDir, theirsDir, catalystRoot) {
+  const scratch = await mkdtemp(join14(tmpdir(), "catalyst-merge-"));
+  try {
+    await execa4("git", ["init", "-q", scratch]);
+    await execa4("git", ["config", "core.autocrlf", "false"], {
+      env: { ...process.env, GIT_DIR: join14(scratch, ".git") }
+    });
+    const env2 = {
+      ...process.env,
+      GIT_DIR: join14(scratch, ".git"),
+      GIT_AUTHOR_NAME: "catalyst",
+      GIT_AUTHOR_EMAIL: "catalyst@bigcommerce.com",
+      GIT_COMMITTER_NAME: "catalyst",
+      GIT_COMMITTER_EMAIL: "catalyst@bigcommerce.com"
+    };
+    const writeTree = async (workTree, tag) => {
+      const sideEnv = {
+        ...env2,
+        GIT_WORK_TREE: workTree,
+        GIT_INDEX_FILE: join14(scratch, `index.${tag}`)
+      };
+      await execa4("git", ["add", "-A"], { env: sideEnv });
+      return (await execa4("git", ["write-tree"], { env: sideEnv })).stdout.trim();
+    };
+    const commitTree = (tree, parent) => execa4("git", ["commit-tree", tree, "-m", "x", ...parent ? ["-p", parent] : []], {
+      env: env2
+    }).then((r) => r.stdout.trim());
+    const baseTree = await writeTree(baseDir, "base");
+    const oursTree = await writeTree(catalystRoot, "ours");
+    const theirsTree = await writeTree(theirsDir, "theirs");
+    const baseCommit = await commitTree(baseTree);
+    const [oursCommit, theirsCommit] = await Promise.all([
+      commitTree(oursTree, baseCommit),
+      commitTree(theirsTree, baseCommit)
+    ]);
+    await Promise.all([
+      execa4("git", ["branch", "ours", oursCommit], { env: env2 }),
+      execa4("git", ["branch", "theirs", theirsCommit], { env: env2 })
+    ]);
+    const merge = await execa4(
+      "git",
+      [
+        "merge-tree",
+        "--write-tree",
+        "-z",
+        "--name-only",
+        `--merge-base=${baseCommit}`,
+        "ours",
+        "theirs"
+      ],
+      { env: env2, reject: false }
+    );
+    if ((merge.exitCode ?? 0) > 1)
+      throw new Error(merge.stderr || merge.stdout.slice(0, 500) || "git merge-tree failed");
+    const fields = merge.stdout.split("\0");
+    const mergedTree = fields[0];
+    const afterOid = fields.slice(1);
+    const emptyAt = afterOid.indexOf("");
+    const conflicted = afterOid.slice(0, emptyAt === -1 ? afterOid.length : emptyAt);
+    const conflictedSet = new Set(conflicted);
+    const outEnv = {
+      ...env2,
+      GIT_WORK_TREE: catalystRoot,
+      GIT_INDEX_FILE: join14(scratch, "index.out")
+    };
+    await execa4("git", ["read-tree", mergedTree], { env: outEnv });
+    await execa4("git", ["checkout-index", "-a", "-f"], { env: outEnv });
+    const diff = await execa4(
+      "git",
+      ["diff", "-z", "--no-renames", "--name-status", oursTree, mergedTree],
+      { env: env2 }
+    );
+    const tokens = diff.stdout.split("\0");
+    const changes = [];
+    for (let i = 0; i + 1 < tokens.length; i += 2) {
+      const status = tokens[i];
+      const path = tokens[i + 1];
+      if (status && path && !conflictedSet.has(path)) {
+        changes.push({ status, path });
+      }
+    }
+    const deleted = changes.filter((change) => change.status === "D").map((change) => change.path);
+    await Promise.all(deleted.map((path) => rm2(join14(catalystRoot, path), { force: true })));
+    return {
+      applied: changes.filter((change) => change.status !== "A" && change.status !== "D").map((change) => change.path),
+      added: changes.filter((change) => change.status === "A").map((change) => change.path),
+      deleted,
+      conflicted
+    };
+  } finally {
+    await rm2(scratch, { recursive: true, force: true, maxRetries: 10, retryDelay: 500 });
+  }
+}
+async function applyIndexState(gitRoot, relDir, baseDir, theirsDir, result, stampedPkg) {
+  const toRepoPath = (rel) => relDir === "." ? rel : `${relDir}/${rel}`;
+  const pkgRel = "package.json";
+  const stillConflicted = result.conflicted.filter((rel) => !(stampedPkg && rel === pkgRel));
+  const conflictedRepoPaths = new Set(stillConflicted.map(toRepoPath));
+  const clean = [...result.applied, ...result.added, ...result.deleted].map(toRepoPath);
+  if (stampedPkg) clean.push(toRepoPath(pkgRel));
+  const toStage = [...new Set(clean)].filter((path) => !conflictedRepoPaths.has(path));
+  if (toStage.length) {
+    await execa4("git", ["add", "-A", "--", ...toStage], { cwd: gitRoot });
+  }
+  if (stillConflicted.length === 0) return;
+  const OID = /^[0-9a-f]{40,64}$/;
+  const gitFormat = (await execa4("git", ["rev-parse", "--show-object-format"], { cwd: gitRoot, reject: false })).stdout.trim();
+  const NULL_OID = gitFormat === "sha256" ? "0".repeat(64) : "0".repeat(40);
+  const hashBlob = async (file) => {
+    if (!await pathExists(file)) return null;
+    const oid = (await execa4("git", ["hash-object", "-w", "--", file], { cwd: gitRoot })).stdout.trim();
+    return OID.test(oid) ? oid : null;
+  };
+  const headEntry = async (repoPath) => {
+    const { stdout } = await execa4("git", ["ls-tree", "HEAD", "--", repoPath], {
+      cwd: gitRoot,
+      reject: false
+    });
+    const match = /^(\d{6}) blob ([0-9a-f]+)\t/.exec(stdout);
+    return match ? { mode: match[1], oid: match[2] } : null;
+  };
+  const records = await Promise.all(
+    stillConflicted.map(async (rel) => {
+      const repoPath = toRepoPath(rel);
+      const [base, ours, theirs] = await Promise.all([
+        hashBlob(join14(baseDir, rel)),
+        headEntry(repoPath),
+        hashBlob(join14(theirsDir, rel))
+      ]);
+      return [
+        `0 ${NULL_OID}	${repoPath}`,
+        ...base ? [`100644 ${base} 1	${repoPath}`] : [],
+        ...ours ? [`${ours.mode} ${ours.oid} 2	${repoPath}`] : [],
+        ...theirs ? [`100644 ${theirs} 3	${repoPath}`] : []
+      ].join("\n");
+    })
+  );
+  await execa4("git", ["update-index", "--index-info"], {
+    cwd: gitRoot,
+    input: `${records.join("\n")}
+`
+  });
+}
+async function resolveProject2(cwd) {
+  let gitRoot;
+  try {
+    gitRoot = (await execa4("git", ["rev-parse", "--show-toplevel"], { cwd })).stdout.trim();
+  } catch {
+    return null;
+  }
+  const candidateDirs = [.../* @__PURE__ */ new Set([join14(gitRoot, "core"), gitRoot, join14(cwd, "core"), cwd])];
+  const parsed = (await Promise.all(
+    candidateDirs.map(async (dir) => {
+      const pkgPath = join14(dir, "package.json");
+      const raw = await readFile2(pkgPath, "utf-8").catch(() => null);
+      if (!raw) return null;
+      let pkgJson;
+      try {
+        pkgJson = JSON.parse(raw);
+      } catch {
+        return null;
+      }
+      const result = CorePackageJson.safeParse(pkgJson);
+      return result.success ? { dir, pkgPath, raw, pkg: result.data } : null;
+    })
+  )).filter((entry) => entry !== null);
+  if (parsed.length === 0) return null;
+  const chosen = parsed.find((p) => p.pkg.catalyst?.ref) ?? parsed.find((p) => p.pkg.name !== void 0 && KNOWN_FAMILIES.has(p.pkg.name)) ?? parsed[0];
+  return {
+    gitRoot,
+    catalystRoot: chosen.dir,
+    relDir: relative2(gitRoot, chosen.dir) || ".",
+    pkgPath: chosen.pkgPath,
+    rawContent: chosen.raw,
+    pkg: chosen.pkg
+  };
+}
+async function downloadCore(repository, ref, destDir, token) {
+  const cacheable = !MOVING_TAGS.has(parseRef(ref).version);
+  const cacheKey = `${repository.replace(/[^a-zA-Z0-9._-]/g, "_")}__${ref.replace(/[^a-zA-Z0-9._-]/g, "_")}`;
+  const cachePath = join14(CACHE_DIR, cacheKey);
+  if (cacheable && await pathExists(cachePath) && await pathExists(join14(cachePath, "package.json"))) {
+    await cp2(cachePath, destDir, { recursive: true });
+    return;
+  }
+  const url = `https://api.github.com/repos/${repository}/tarball/${encodeURIComponent(ref)}`;
+  const headers = {
+    "User-Agent": "catalyst-cli",
+    Accept: "application/vnd.github+json"
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const res = await fetch(url, { headers });
+  if (!res.ok) {
+    let hint = "";
+    if (res.status === 404) hint = ` \u2014 tag "${ref}" not found in ${repository}`;
+    if (res.status === 403) hint = " \u2014 GitHub rate limit hit; set GITHUB_TOKEN to raise it";
+    throw new Error(`GitHub returned ${res.status} for ${ref}${hint}`);
+  }
+  const tarballPath = `${destDir}.tgz`;
+  const rawDir = `${destDir}.raw`;
+  await writeFile2(tarballPath, Buffer.from(await res.arrayBuffer()));
+  await mkdir(rawDir, { recursive: true });
+  await execa4("tar", ["-xzf", tarballPath, "-C", rawDir, "--strip-components=1"]);
+  const coreDir = join14(rawDir, "core");
+  const sourceDir = await pathExists(coreDir) ? coreDir : rawDir;
+  await rename(sourceDir, destDir);
+  await rm2(tarballPath, { force: true });
+  await rm2(rawDir, { recursive: true, force: true });
+  if (cacheable) {
+    await mkdir(CACHE_DIR, { recursive: true });
+    await cp2(destDir, cachePath, { recursive: true }).catch(() => {
+    });
+  }
+}
+async function resolveBaseRef(project2, fromOption, assumeYes) {
+  if (project2.pkg.catalyst?.ref) return project2.pkg.catalyst.ref;
+  if (fromOption) return fromOption;
+  const family = project2.pkg.name && KNOWN_FAMILIES.has(project2.pkg.name) ? project2.pkg.name : "@bigcommerce/catalyst-core";
+  const guess = `${family}@${project2.pkg.version}`;
+  consola.warn(`No \`catalyst.ref\` found in package.json. Inferred base: ${guess}`);
+  if (assumeYes) return guess;
+  const ok = await confirm6({ message: `Upgrade from ${guess}?`, default: true }).catch(() => false);
+  if (!ok) {
+    consola.info("Re-run with `--from <ref>` to set the base version explicitly.");
+    return null;
+  }
+  return guess;
+}
+function printSummary(result, relDir, stampedPkg) {
+  const unresolved = result.conflicted.filter((f) => !(stampedPkg && f === "package.json"));
+  const parts = [
+    `${result.applied.length} updated`,
+    `${result.added.length} added`,
+    `${result.deleted.length} removed`
+  ];
+  if (unresolved.length) parts.push(`${unresolved.length} with conflicts`);
+  consola.log(`
+${parts.join(", ")}`);
+  if (unresolved.length) {
+    const files = unresolved.map((f) => `  ${f}`).join("\n");
+    consola.warn(
+      `
+Staged the clean changes. ${unresolved.length} file(s) need conflict resolution (the <<<ours/===/theirs>>> markers):
+${files}
+
+Resolve them, then: git add ${relDir} && git commit`
+    );
+  } else {
+    consola.success("Staged all changes \u2014 review with `git diff --cached`, then commit.");
+  }
+}
+var upgrade = new Command13("upgrade").configureHelp({ showGlobalOptions: true }).aliases([
+  "up",
+  // These are hidden aliases
+  "upgrayedd",
+  "ugrad"
+]).description("Upgrade your Catalyst project to a newer version by applying a 3-way merge.").argument("[version]", "Target version to upgrade to (default: latest)").addOption(
+  new Option10(
+    "--ref <ref>",
+    "Full git tag to upgrade to, e.g. an integration family like @bigcommerce/catalyst-makeswift@1.7.0. Overrides [version]."
+  )
+).addOption(new Option10("--from <ref>", "Base ref to upgrade from (when catalyst.ref is missing)")).option("--dry-run", "Generate and display the diff without applying it").option("--yes", "Skip confirmation prompts (e.g. inferred base ref)").addOption(
+  new Option10(
+    "--strategy <strategy>",
+    "Merge engine: tree (git merge-tree, full fidelity), per-file (git merge-file, no-history fallback), or auto (tree when git >= 2.38, else per-file)"
+  ).choices(["auto", "tree", "per-file"]).default("auto").hideHelp()
+).addOption(
+  new Option10("--repository <owner/repo>", "GitHub repository to pull versions from").default(
+    DEFAULT_REPOSITORY
+  )
+).addHelpText(
+  "after",
+  `
+Examples:
+  # Upgrade to the latest Catalyst version
+  $ catalyst upgrade
+
+  # Upgrade to a specific version
+  $ catalyst upgrade 1.8.0
+
+  # Preview what would change without applying
+  $ catalyst upgrade --dry-run
+
+  # Upgrade to an integration family (makeswift, b2b-makeswift, ...)
+  $ catalyst upgrade --ref @bigcommerce/catalyst-makeswift@1.7.0
+
+Conflicts are written as standard <<<ours/===/theirs>>> markers \u2014 the upgrade
+never aborts. Versions are git tags on the repository (not npm). Set GITHUB_TOKEN
+to raise the GitHub API rate limit.`
+).action(async (version2, options) => {
+  const project2 = await resolveProject2(process.cwd());
+  if (!project2) {
+    consola.error(
+      "Run `catalyst upgrade` from inside a Catalyst git repository (flat core/ repo or a project containing core/)."
+    );
+    process.exit(1);
+  }
+  const { gitRoot, catalystRoot, relDir, pkgPath } = project2;
+  const baseRef = await resolveBaseRef(project2, options.from, options.yes ?? false);
+  if (!baseRef) process.exit(1);
+  let basePackage;
+  let upstreamRef;
+  let upstreamTagVersion;
+  try {
+    ({ packageName: basePackage } = parseRef(baseRef));
+    upstreamRef = options.ref ?? `${basePackage}@${version2 ?? "latest"}`;
+    ({ version: upstreamTagVersion } = parseRef(upstreamRef));
+  } catch {
+    consola.error(
+      `Invalid ref format \u2014 expected <package>@<version> (e.g. @bigcommerce/catalyst-core@1.7.0). Got: "${baseRef}"`
+    );
+    process.exit(1);
+  }
+  if (upstreamRef === baseRef) {
+    consola.success("Already up to date.");
+    return;
+  }
+  if (!options.dryRun) {
+    const statusArgs = relDir === "." ? [] : ["--", relDir];
+    const status = await execa4("git", ["status", "--porcelain", ...statusArgs], {
+      cwd: gitRoot,
+      reject: false
+    });
+    if (status.stdout.trim()) {
+      const where = relDir === "." ? "The repo" : `${relDir}/`;
+      consola.error(
+        `${where} has uncommitted changes. Commit or stash them before upgrading, so the upgrade is isolated and reversible:
+  git add ${relDir} && git commit -m "snapshot before upgrade"
+  # or: git stash`
+      );
+      process.exit(1);
+    }
+  }
+  if (!project2.pkg.catalyst?.ref && !options.from && !options.dryRun) {
+    const { version: baseVersion } = parseRef(baseRef);
+    const rawPkg = await readFile2(pkgPath, "utf-8");
+    const parsedPkg = z17.record(z17.string(), z17.unknown()).parse(JSON.parse(rawPkg));
+    parsedPkg.catalyst = { version: baseVersion, ref: baseRef };
+    await writeFile2(pkgPath, `${JSON.stringify(parsedPkg, null, 2)}
+`);
+    await execa4("git", ["add", "--", pkgPath], { cwd: gitRoot });
+    consola.success(`Added catalyst.ref \u2192 ${baseRef}`);
+  }
+  const token = process.env.GITHUB_TOKEN;
+  const tmpDir = await mkdtemp(join14(tmpdir(), "catalyst-upgrade-"));
+  try {
+    const baseDir = join14(tmpDir, "base");
+    const theirsDir = join14(tmpDir, "theirs");
+    const emptyFile = join14(tmpDir, ".empty");
+    await writeFile2(emptyFile, "");
+    const downloadSpinner = yoctoSpinner4().start(`Downloading ${baseRef} and ${upstreamRef}...`);
+    try {
+      await Promise.all([
+        downloadCore(options.repository, baseRef, baseDir, token),
+        downloadCore(options.repository, upstreamRef, theirsDir, token)
+      ]);
+      downloadSpinner.success("Downloaded both versions.");
+    } catch (err) {
+      downloadSpinner.error("Download failed");
+      throw err;
+    }
+    if (!project2.pkg.catalyst?.ref && !options.from) {
+      const similarity = await computeBaseSimilarity(baseDir, catalystRoot);
+      const pct = Math.round(similarity * 100);
+      if (similarity < 0.5) {
+        consola.warn(
+          `Low confidence in inferred base ${baseRef} (${pct}% of base files match your project). If the merge result looks off, re-run with \`--from <correct-version>\` to set the base explicitly.`
+        );
+      }
+    }
+    const resolvedVersion = MOVING_TAGS.has(upstreamTagVersion) ? await readResolvedVersion(theirsDir) : upstreamTagVersion;
+    const newRef = MOVING_TAGS.has(upstreamTagVersion) ? `${basePackage}@${resolvedVersion}` : upstreamRef;
+    if (options.dryRun) {
+      const diffSpinner = yoctoSpinner4().start("Generating diff...");
+      const diff = await execa4(
+        "git",
+        ["diff", "--no-index", "--binary", "--diff-algorithm=histogram", "base", "theirs"],
+        { cwd: tmpDir, reject: false, stripFinalNewline: false }
+      );
+      if ((diff.exitCode ?? 0) > 1) {
+        diffSpinner.error("Failed to generate diff");
+        throw new Error(diff.stderr);
+      }
+      if (!diff.stdout.trim()) {
+        diffSpinner.success("No differences between versions \u2014 already up to date.");
+        return;
+      }
+      const fileCount = (diff.stdout.match(/^diff --git /gm) ?? []).length;
+      diffSpinner.success(`Diff ready \u2014 ${fileCount} file(s) affected.`);
+      consola.log("\nDiff preview (--dry-run, not applied):\n");
+      consola.log(diff.stdout);
+      return;
+    }
+    const strategy = await resolveStrategy(options.strategy);
+    const mergeSpinner = yoctoSpinner4().start(`Merging changes (${strategy})...`);
+    const result = strategy === "tree" ? await mergeCoreTree(baseDir, theirsDir, catalystRoot) : await mergeCorePerFile(baseDir, theirsDir, catalystRoot, emptyFile);
+    const total = result.applied.length + result.added.length + result.deleted.length + result.conflicted.length;
+    if (total === 0) {
+      mergeSpinner.success("No differences between versions \u2014 already up to date.");
+      return;
+    }
+    if (result.conflicted.length) {
+      mergeSpinner.warning("Merged with conflicts \u2014 resolve the markers, then commit.");
+    } else {
+      mergeSpinner.success("Merged cleanly.");
+    }
+    const patchedRaw = await readFile2(pkgPath, "utf-8");
+    let stampedPkg = false;
+    try {
+      const patchedPkg = z17.record(z17.string(), z17.unknown()).parse(JSON.parse(patchedRaw));
+      patchedPkg.catalyst = { version: resolvedVersion, ref: newRef };
+      await writeFile2(pkgPath, `${JSON.stringify(patchedPkg, null, 2)}
+`);
+      stampedPkg = true;
+      consola.success(`catalyst.ref updated \u2192 ${newRef}`);
+    } catch {
+      const catalystReplacement = JSON.stringify(
+        { version: resolvedVersion, ref: newRef },
+        null,
+        2
+      ).split("\n").map((line, i) => i === 0 ? line : `  ${line}`).join("\n");
+      const updated = patchedRaw.replace(
+        /"catalyst":\s*\{[^}]*\}/,
+        () => `"catalyst": ${catalystReplacement}`
+      );
+      if (updated !== patchedRaw) {
+        await writeFile2(pkgPath, updated);
+        consola.success(`catalyst.ref updated \u2192 ${newRef}`);
+        consola.info(
+          "package.json still has conflicts in other sections \u2014 resolve them, then: git add package.json"
+        );
+      } else {
+        consola.warn(
+          `package.json has conflicts \u2014 after resolving, add:
+  "catalyst": { "version": "${resolvedVersion}", "ref": "${newRef}" }`
+        );
+      }
+    }
+    try {
+      await applyIndexState(gitRoot, relDir, baseDir, theirsDir, result, stampedPkg);
+    } catch (err) {
+      consola.warn(
+        `Couldn't auto-stage the changes (${err instanceof Error ? err.message : String(err)}). Your files are merged on disk \u2014 run \`git add ${relDir}\` yourself.`
+      );
+    }
+    const gitVersion = await execa4("git", ["--version"]).then((r) => r.stdout.trim()).catch(() => "unknown");
+    await getTelemetry().track("upgrade", {
+      strategy,
+      gitVersion,
+      dryRun: Boolean(options.dryRun),
+      applied: result.applied.length,
+      added: result.added.length,
+      deleted: result.deleted.length,
+      conflicts: result.conflicted.length,
+      hasConflicts: result.conflicted.length > 0
+    });
+    printSummary(result, relDir, stampedPkg);
+  } finally {
+    await rm2(tmpDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 500 });
+  }
+});
+
 // src/cli/commands/version.ts
-import { Command as Command11 } from "commander";
-var version = new Command11("version").configureHelp({ showGlobalOptions: true }).description("Display detailed version information.").addHelpText(
+import { Command as Command14 } from "commander";
+var version = new Command14("version").configureHelp({ showGlobalOptions: true }).description("Display detailed version information.").addHelpText(
   "after",
   `
 Example:
@@ -3358,41 +5412,15 @@ var telemetryPostHook = async () => {
 };
 
 // src/cli/program.ts
-var defaultEnvPath = resolve(process.cwd(), ".env.local");
-if (existsSync5(defaultEnvPath)) {
-  config({ path: defaultEnvPath });
-}
 if (!process.env.CATALYST_STORE_HASH && process.env.BIGCOMMERCE_STORE_HASH) {
   process.env.CATALYST_STORE_HASH = process.env.BIGCOMMERCE_STORE_HASH;
 }
-var program = new Command12();
-consola.log(colorize9("cyanBright", `\u25E2 ${package_default.name} v${package_default.version}
+var program = new Command15();
+consola.log(colorize13("cyanBright", `\u25E2 ${package_default.name} v${package_default.version}
 `));
 program.name(package_default.name).version(package_default.version).summary("CLI tool for Catalyst development").description(
-  "CLI tool for Catalyst development.\n\nConfiguration priority: flags > env file (--env-path) > process.env > .env.local (auto-loaded from cwd) > .bigcommerce/project.json.\n\nCATALYST_STORE_HASH falls back to BIGCOMMERCE_STORE_HASH if unset.\n\nRun `catalyst <command> --help` for details on a specific command."
-).configureHelp({ showGlobalOptions: true }).addOption(
-  new Option9(
-    "--env-path <path>",
-    "Path to environment file to load (relative to current working directory)"
-    // We are using argParser, because commander loads in environment variables before executing hooks.
-  ).argParser((value) => {
-    if (value) {
-      const envFilePath = resolve(process.cwd(), value);
-      const result = config({
-        path: envFilePath,
-        override: true
-      });
-      if (result.error) {
-        const errCode = "code" in result.error && typeof result.error.code === "string" ? result.error.code : void 0;
-        const message = errCode === "ENOENT" ? `Env file not found: ${envFilePath}` : `Failed to load --env-path ${value}: ${result.error.message}`;
-        throw new Error(message);
-      }
-      consola.log(colorize9("cyanBright", `Loaded environment variables from ${envFilePath}
-`));
-    }
-    return value;
-  })
-).addCommand(version).addCommand(create).addCommand(start).addCommand(build).addCommand(deploy).addCommand(logs).addCommand(project).addCommand(env).addCommand(channel).addCommand(auth).addCommand(telemetry2).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
+  "CLI tool for Catalyst development.\n\nConfiguration priority: flags > process.env > .bigcommerce/project.json. `build` and `deploy` additionally load env files (--env-path, or an auto-loaded .env.local/.env) for the build.\n\nCATALYST_STORE_HASH falls back to BIGCOMMERCE_STORE_HASH if unset.\n\nRun `catalyst <command> --help` for details on a specific command."
+).configureHelp({ showGlobalOptions: true }).addCommand(version).addCommand(create2).addCommand(start).addCommand(build).addCommand(deploy).addCommand(domains).addCommand(logs).addCommand(project).addCommand(env).addCommand(channel).addCommand(auth).addCommand(upgrade).addCommand(telemetry2).addCommand(debug).hook("preAction", telemetryPreHook).hook("postAction", telemetryPostHook);
 
 // src/cli/index.ts
 var handleFatalError = async (error) => {
@@ -3409,7 +5437,7 @@ var handleFatalError = async (error) => {
     await telemetry3.analytics.closeAndFlush();
   } catch {
   }
-  if (error instanceof UnauthorizedError) {
+  if (error instanceof UserActionableError) {
     consola.error(errorMessage);
     process.exit(1);
   }