@fluid-app/fluid-cli-mist 0.1.10 → 0.1.12

package/dist/index.mjs

@@ -3,10 +3,10 @@ import chalk from "chalk";
 import { getAuthToken } from "@fluid-app/fluid-cli";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path, { join, resolve } from "node:path";
-import ora from "ora";
-import prompts from "prompts";
 import os from "node:os";
 import { execa } from "execa";
+import ora from "ora";
+import prompts from "prompts";
 import open from "open";
 //#region src/api/client.ts
 /**
@@ -131,28 +131,28 @@ async function resolveMistId(client, slugOrId) {
 }
 //#endregion
 //#region src/api/mists.ts
-const BASE$3 = "/api/v202604/mists";
+const BASE$4 = "/api/v202604/mists";
 function listMists(client, params = {}) {
-	return client.get(BASE$3, params);
+	return client.get(BASE$4, params);
 }
 async function showMist(client, slug) {
 	const id = await resolveMistId(client, slug);
-	return client.get(`${BASE$3}/${id}`);
+	return client.get(`${BASE$4}/${id}`);
 }
 function createMist(client, body) {
-	return client.post(BASE$3, body);
+	return client.post(BASE$4, body);
 }
 async function updateMist(client, slug, body) {
 	const id = await resolveMistId(client, slug);
-	return client.patch(`${BASE$3}/${id}`, body);
+	return client.patch(`${BASE$4}/${id}`, body);
 }
 async function deleteMist(client, slug) {
 	const id = await resolveMistId(client, slug);
-	return client.delete(`${BASE$3}/${id}`);
+	return client.delete(`${BASE$4}/${id}`);
 }
 async function restoreMist(client, slug) {
 	const id = await resolveMistId(client, slug);
-	return client.post(`${BASE$3}/${id}/restore`);
+	return client.post(`${BASE$4}/${id}/restore`);
 }
 //#endregion
 //#region src/lib/hostable.ts
@@ -210,1519 +210,1752 @@ function canonicalizeHostableType(typePart) {
 	throw new HostableParseError(`Unknown hostable type "${typePart}". Use one of: ${SHORTHAND_LIST}.`);
 }
 //#endregion
-//#region src/lib/slug-resolver.ts
+//#region src/lib/git.ts
 /**
-* Slug resolution — spec §3 conventions:
-*   1. If a slug arg is passed, use it.
-*   2. Otherwise look for a `.mist` file in CWD (written by `fluid mist
-*      clone`) and use the slug from it.
-*   3. Otherwise error: tell the user to pass a slug or cd into a cloned dir.
+* Git wrapper — shells out to system `git` via execa. Spec §11.1: we
+* deliberately do NOT bundle git or use a pure-JS impl; users are expected
+* to have it installed.
+*
+* Security: token-bearing `remote_url` from POST /git_credential must never
+* be logged, persisted, *or* exposed in the process table. The token is
+* stripped from the URL and handed to git through a GIT_ASKPASS script via
+* env vars (MIST_GIT_USER / MIST_GIT_PASS) — so it never appears in argv
+* (visible to `ps aux` on macOS, `/proc/<pid>/cmdline` on Linux) and is
+* never written to `.git/config`.
 */
-const MIST_FILE = ".mist";
-var SlugResolutionError = class extends Error {
-	constructor(message) {
+var GitError = class extends Error {
+	exitCode;
+	constructor(message, exitCode = 1) {
 		super(message);
-		this.name = "SlugResolutionError";
+		this.name = "GitError";
+		this.exitCode = exitCode;
 	}
 };
-function readMistFile(dir) {
-	const filePath = join(dir, MIST_FILE);
-	if (!existsSync(filePath)) return null;
-	try {
-		const raw = readFileSync(filePath, "utf8");
-		const parsed = JSON.parse(raw);
-		if (!parsed || typeof parsed !== "object") return null;
-		const obj = parsed;
-		if (typeof obj["slug"] !== "string") return null;
-		return {
-			slug: obj["slug"],
-			vendor_name: typeof obj["vendor_name"] === "string" ? obj["vendor_name"] : "",
-			public_url: typeof obj["public_url"] === "string" ? obj["public_url"] : null
-		};
-	} catch {
-		return null;
-	}
-}
-/** Returns the slug from arg or `.mist` file; throws if neither is present. */
-function resolveSlug(arg, cwd = process.cwd()) {
-	if (arg && arg.trim().length > 0) return arg.trim();
-	const file = readMistFile(cwd);
-	if (file) return file.slug;
-	throw new SlugResolutionError("No slug provided and no `.mist` file in this directory. Pass the slug as an argument or cd into a cloned mist.");
-}
-/** Write a `.mist` file after `fluid mist clone`. */
-function writeMistFile(dir, mist) {
-	const payload = {
-		slug: mist.slug,
-		vendor_name: mist.vendor_name,
-		public_url: mist.public_url
-	};
-	writeFileSync(join(dir, MIST_FILE), JSON.stringify(payload, null, 2) + "\n", "utf8");
-}
-//#endregion
-//#region src/lib/error-handler.ts
 /**
-* Centralized error handling — maps thrown errors to spec'd exit codes
-* and friendly messages. Imported by every command's `.action()` so each
-* file doesn't repeat the same try/catch.
+* Git author for Mist publish commits. Mist app repos are connected to the
+* we-commerce Vercel team via Vercel's GitHub integration, and Vercel
+* attributes a git-triggered deploy to the *commit author's* GitHub account.
+* If that author is a user's personal GitHub account (not a member of the
+* Vercel team), Vercel blocks the deployment ("… does not have a Vercel
+* account linked to their GitHub account"). Authoring every publish commit as
+* the Mist GitHub App bot — which the Vercel integration recognizes — keeps
+* deploys unblocked regardless of the user's local/global git identity. Human
+* attribution is preserved in the commit *message* (see push.ts), not the
+* author field.
 *
-* Exit codes (spec §3 "Conventions"):
-*   0 success | 1 user error | 2 API 4xx | 3 API 5xx / vendor | 4 network
+* These MUST match the identity set on cloned repos in Mist Desktop
+* (apps/mist-desktop/src/main/ipc.ts) so both paths produce the same author.
 */
-/** Run an async action and translate failures into pretty output + exit. */
-async function runAction(fn) {
-	try {
-		await fn();
-	} catch (err) {
-		handle(err);
-	}
-}
-function handle(err) {
-	if (err instanceof SlugResolutionError) {
-		console.error(chalk.red(err.message));
-		process.exit(1);
-	}
-	if (err instanceof HostableParseError) {
-		console.error(chalk.red(err.message));
-		process.exit(1);
-	}
-	if (err instanceof MistApiError) {
-		if (err.status === 403) {
-			const action = err.details?.["permission"];
-			console.error(chalk.red(action ? `Your role doesn't include \`mist.${String(action)}\` — ask your Fluid admin to grant it.` : err.message));
-		} else if (err.status === 409) {
-			const date = err.details?.["scheduled_destroy_at"];
-			console.error(chalk.yellow(typeof date === "string" ? `This mist is scheduled for destruction on ${date.slice(0, 10)}. Run \`fluid mist restore <slug>\` first.` : err.message));
-		} else if (err.status === 422) {
-			const details = err.details ?? {};
-			const idErrors = details["integratable_id"] ?? details["hostable_id"];
-			const managedKey = typeof err.message === "string" && /managed_by|managed by mist|FLUID_DROPLET|FLUID_WEBHOOK/i.test(err.message);
-			if (Array.isArray(idErrors) && idErrors.some((e) => /already taken|already attached/i.test(String(e)))) console.error(chalk.yellow("That droplet is already attached to another mist. Detach it first or pick a different one."));
-			else if (managedKey) console.error(chalk.yellow("That env var is Mist-managed (FLUID_DROPLET_UUID / FLUID_DROPLET_SECRET / FLUID_WEBHOOK_AUTH_TOKEN) — it's set automatically when a droplet is attached and can't be written directly."));
-			else if (typeof err.message === "string" && /Droplet not found|integratable/i.test(err.message)) {
-				const id = details["integratable_id"] ?? details["hostable_id"];
-				console.error(chalk.yellow(`Couldn't find droplet${id != null ? ` #${String(id)}` : ""} in this company.`));
-			} else console.error(chalk.red(err.message));
-		} else if (err.status === 410) console.error(chalk.red("Grace period expired — vendor teardown is in flight. Create a fresh mist with `fluid mist create`."));
-		else console.error(chalk.red(err.message));
-		process.exit(err.exitCode);
-	}
-	if (err instanceof Error) console.error(chalk.red(err.message));
-	else console.error(chalk.red(String(err)));
-	process.exit(1);
+const MIST_GIT_AUTHOR_NAME = "mist-we-commerce[bot]";
+const MIST_GIT_AUTHOR_EMAIL = "293596226+mist-we-commerce[bot]@users.noreply.github.com";
+/** execa throws ENOENT when the git binary itself is missing — the
+*  single most common failure on non-developer machines. Translate it
+*  into an actionable message instead of "git <verb> failed (exit 1)".
+*  Returns null for every other failure so call sites keep their
+*  specific messages. */
+function gitMissingError(err) {
+	if (err?.code !== "ENOENT") return null;
+	return new GitError("Git isn't installed on this machine. In Mist Desktop, use the Install button in the yellow banner at the top of the app. From a terminal: macOS `xcode-select --install`, or download from https://git-scm.com/downloads.", 127);
 }
-//#endregion
-//#region src/lib/output.ts
 /**
-* Output helpers — human-readable by default, `--json` emits raw API
-* payload. NO_COLOR respected via chalk's built-in detection.
+* Split a token-bearing remote URL into the userless URL + creds. Used
+* to keep the token off git's argv: we pass `cleanUrl` to git and feed
+* `username` / `password` back through GIT_ASKPASS env vars.
+*
+* If the URL has no embedded credentials, returns empty strings — fine
+* for public repos where git won't even invoke askpass.
 */
-function printJson(payload) {
-	process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-}
-const STATE_COLOR$1 = {
-	pending: chalk.gray,
-	provisioning: chalk.yellow,
-	live: chalk.green,
-	failed: chalk.red,
-	pending_destroy: chalk.magenta,
-	archived: chalk.dim
-};
-function colorState(state) {
-	return STATE_COLOR$1[state](state);
+function splitRemoteCredentials(remoteUrl) {
+	const u = new URL(remoteUrl);
+	const username = decodeURIComponent(u.username);
+	const password = decodeURIComponent(u.password);
+	u.username = "";
+	u.password = "";
+	return {
+		cleanUrl: u.toString(),
+		username,
+		password
+	};
 }
 /**
-* Bold display label for a mist, falling back to a dim "(unnamed)"
-* placeholder when both `name` and `vendorName` are missing. Never nests
-* `chalk.bold(chalk.dim(...))` — most terminals render that as plain bold,
-* losing the "this is a placeholder" muted intent.
+* Write a stub GIT_ASKPASS shell script to a per-process tmpdir and
+* return its path. The script itself contains no secret — it just
+* echoes back whichever env var (MIST_GIT_USER / MIST_GIT_PASS)
+* matches git's prompt ("Username for …" / "Password for …"). The
+* credentials only live in the spawned git process's env for the
+* duration of the call.
+*
+* One POSIX script for all platforms: Git for Windows executes
+* GIT_ASKPASS through its bundled sh, so a .cmd askpass fails with
+* "unable to read askpass response" (git 2.52.0.windows.1) while a
+* plain sh script works.
+*
+* Idempotent: subsequent calls reuse the same script path.
 */
-function mistLabel(name, vendorName) {
-	const raw = name ?? vendorName;
-	return raw ? chalk.bold(raw) : chalk.dim("(unnamed)");
+let askpassPath = null;
+function ensureAskpassScript() {
+	if (askpassPath && existsSync(askpassPath)) return askpassPath;
+	const dir = path.join(os.tmpdir(), `mist-cli-askpass-${process.pid}`);
+	if (!existsSync(dir)) mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const p = path.join(dir, "askpass.sh");
+	writeFileSync(p, `#!/bin/sh\ncase "$1" in\n  Username*) printf '%s' "$MIST_GIT_USER" ;;\n  *) printf '%s' "$MIST_GIT_PASS" ;;\nesac\n`, { mode: 448 });
+	chmodSync(p, 448);
+	askpassPath = p;
+	return askpassPath;
 }
 /**
-* Pad columns to width — cheap manual table; avoids cli-table3 dep for v1.
-* Cells are defensively normalized: API records can legitimately have every
-* optional label field (`name`, `vendor_name`, `droplet.name`, ...) come back
-* null/absent at once (e.g. a `pending_destroy` mist), so callers sometimes
-* hand us `undefined`/`null` after chaining `??` — that must render as an
-* empty cell, not crash the whole table.
+* Build the spawn env + cleaned URL for a credentialed git invocation.
+* Returns:
+*   - `cleanUrl`: URL with userinfo stripped — safe to pass as argv.
+*   - `env`: parent env plus GIT_ASKPASS + MIST_GIT_USER / MIST_GIT_PASS.
+*            GIT_TERMINAL_PROMPT=0 prevents the TTY-prompt fallback if
+*            the credentials are empty (we want auth to fail fast, not
+*            hang the desktop waiting for interactive input).
 */
-function printTable(rows) {
-	if (rows.length === 0) return;
-	const widths = [];
-	for (const row of rows) row.forEach((cell, i) => {
-		const visible = stripAnsi(cell).length;
-		widths[i] = Math.max(widths[i] ?? 0, visible);
-	});
-	for (const row of rows) {
-		const padded = row.map((cell, i) => {
-			const w = widths[i] ?? 0;
-			const text = cell ?? "";
-			return text + " ".repeat(Math.max(0, w - stripAnsi(text).length));
-		});
-		process.stdout.write(padded.join("  ") + "\n");
-	}
+function gitAuthSpawn(remoteUrl) {
+	const { cleanUrl, username, password } = splitRemoteCredentials(remoteUrl);
+	return {
+		cleanUrl,
+		env: {
+			...process.env,
+			GIT_ASKPASS: ensureAskpassScript(),
+			GIT_TERMINAL_PROMPT: "0",
+			MIST_GIT_USER: username,
+			MIST_GIT_PASS: password
+		}
+	};
 }
-function stripAnsi(s) {
-	return (s ?? "").replace(/\x1b\[[0-9;]*m/g, "");
+/** Confirm git is installed. Cheap call once at startup. */
+async function ensureGitAvailable() {
+	try {
+		await execa("git", ["--version"]);
+	} catch {
+		throw new GitError("`git` is required but not found on your PATH. Install it from https://git-scm.com/downloads or via `brew install git`.");
+	}
 }
-function relativeDate(iso) {
-	if (!iso) return "—";
-	const diff = Date.now() - new Date(iso).getTime();
-	const minutes = Math.floor(diff / 6e4);
-	if (minutes < 1) return "just now";
-	if (minutes < 60) return `${minutes}m ago`;
-	const hours = Math.floor(minutes / 60);
-	if (hours < 24) return `${hours}h ago`;
-	const days = Math.floor(hours / 24);
-	if (days < 30) return `${days}d ago`;
-	return new Date(iso).toISOString().slice(0, 10);
-}
-/** Human-friendly absolute date for one-off prints (scheduled_destroy_at). */
-function formatAbsolute(iso) {
-	return new Date(iso).toISOString().slice(0, 10);
-}
-//#endregion
-//#region src/commands/list.ts
-/** `fluid mist list` — GET /mists with optional filters. Spec §3. */
-const listCommand = new Command("list").description("List the mists you have access to").option("--state <state>", "Filter by state: live | provisioning | failed | pending_destroy | archived").option("--kind <kind>", "Filter by kind (default: next_app)").option("--limit <n>", "Page size 1..100 (default 25)").option("--json", "Emit raw API JSON").action((opts) => runAction(async () => {
-	const client = createMistClient();
-	const limit = opts.limit ? parseInt(opts.limit, 10) : void 0;
-	const response = await listMists(client, {
-		...opts.state ? { state: opts.state } : {},
-		...opts.kind ? { kind: opts.kind } : {},
-		...limit && Number.isFinite(limit) ? { limit } : {}
-	});
-	if (opts.json) return printJson(response);
-	const mists = response.mists ?? [];
-	if (mists.length === 0) {
-		console.log(chalk.dim("No mists found."));
-		return;
+/**
+* `git clone <cleanUrl> <targetDir>`. The original remoteUrl carries a
+* token; gitAuthSpawn strips it from the URL and re-injects it via
+* GIT_ASKPASS so it never appears in argv. `credential.helper=` stops
+* git from caching what askpass returned to any system credential
+* store.
+*/
+async function gitClone(remoteUrl, targetDir) {
+	const { cleanUrl, env } = gitAuthSpawn(remoteUrl);
+	try {
+		await execa("git", [
+			"-c",
+			"credential.helper=",
+			"clone",
+			"--quiet",
+			cleanUrl,
+			targetDir
+		], {
+			env,
+			stdio: [
+				"ignore",
+				"inherit",
+				"inherit"
+			]
+		});
+	} catch (err) {
+		const missing = gitMissingError(err);
+		if (missing) throw missing;
+		const e = err;
+		throw new GitError(`git clone failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
 	}
-	printTable([[
-		chalk.bold("SLUG"),
-		chalk.bold("NAME"),
-		chalk.bold("STATE"),
-		chalk.bold("ATTACHED"),
-		chalk.bold("UPDATED")
-	], ...mists.map((m) => [
-		m.slug,
-		m.name ?? m.droplet?.name ?? m.vendor_name ?? chalk.dim("(unnamed)"),
-		colorState(m.state),
-		m.hostable_type ?? chalk.dim("standalone"),
-		relativeDate(m.updated_at)
-	])]);
-}));
-//#endregion
-//#region src/api/integration_points.ts
-function basePath(mistId) {
-	return `/api/v202604/mists/${mistId}/integration_points`;
-}
-async function listIntegrationPoints(client, slug) {
-	const id = await resolveMistId(client, slug);
-	return client.get(basePath(id));
+	await ensureBotIdentity(targetDir);
 }
-async function createIntegrationPoint(client, slug, input) {
-	const id = await resolveMistId(client, slug);
-	return client.post(basePath(id), { integration_point: input });
+/** `git push origin <branch>` — credentials supplied via GIT_ASKPASS,
+*  never in argv. The `.extraheader=` override clears any cached
+*  Authorization header that a CI-style git config might inject. */
+async function gitPush(cwd, remoteUrl, branch = "main") {
+	const { cleanUrl, env } = gitAuthSpawn(remoteUrl);
+	try {
+		await execa("git", [
+			"-c",
+			"credential.helper=",
+			"-c",
+			`http.https://github.com/.extraheader=`,
+			"push",
+			cleanUrl,
+			`HEAD:${branch}`
+		], {
+			cwd,
+			env,
+			stdio: [
+				"ignore",
+				"inherit",
+				"inherit"
+			]
+		});
+	} catch (err) {
+		const missing = gitMissingError(err);
+		if (missing) throw missing;
+		const e = err;
+		throw new GitError(`git push failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
+	}
 }
-async function deleteIntegrationPoint(client, slug, integrationPointId) {
-	const id = await resolveMistId(client, slug);
-	return client.delete(`${basePath(id)}/${integrationPointId}`);
+/** `git pull origin <branch>`. Token supplied via GIT_ASKPASS, same as push. */
+async function gitPull(cwd, remoteUrl, branch = "main") {
+	const { cleanUrl, env } = gitAuthSpawn(remoteUrl);
+	try {
+		await execa("git", [
+			"-c",
+			"credential.helper=",
+			"pull",
+			"--ff-only",
+			cleanUrl,
+			branch
+		], {
+			cwd,
+			env,
+			stdio: [
+				"ignore",
+				"inherit",
+				"inherit"
+			]
+		});
+	} catch (err) {
+		const missing = gitMissingError(err);
+		if (missing) throw missing;
+		const e = err;
+		throw new GitError(`git pull failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
+	}
 }
 /**
-* First droplet-kind integration point in a list, or undefined. A droplet is
-* 1-per-mist (it provisions the managed env), so this is the idempotency key
-* for the droplet create+attach flow.
+* Are there uncommitted changes (working tree or index) in this repo?
+* `git status --porcelain` is empty when everything is clean, non-empty
+* otherwise — so the count is just "is the output non-trivial".
 */
-function findDropletIntegrationPoint(integrationPoints) {
-	return (integrationPoints ?? []).find((ip) => ip.kind === "droplet");
+async function hasUncommittedChanges(cwd) {
+	try {
+		const { stdout } = await execa("git", ["status", "--porcelain"], { cwd });
+		return stdout.trim().length > 0;
+	} catch {
+		return false;
+	}
 }
 /**
-* Find an integration point that already links a specific surface — matched
-* by uuid (droplet/drop-zone) or numeric id (mobile-embed), optionally scoped
-* to a kind. Used to make attach-existing idempotent (avoid the server's 422
-* "already taken"). Uses the `integratable_uuid` echo (#19689) when present.
+* Fetch the given branch from the token-bearing remote URL, writing
+* `FETCH_HEAD` so `git rev-list HEAD...FETCH_HEAD` is meaningful.
+*
+* Same security stance as gitPush — installation token comes through
+* GIT_ASKPASS, never argv or `.git/config`.
 */
-function findIntegrationPointBySurface(integrationPoints, target) {
-	return (integrationPoints ?? []).find((ip) => {
-		if (target.kind && ip.kind !== target.kind) return false;
-		if (target.uuid && ip.integratable_uuid === target.uuid) return true;
-		if (target.id != null && ip.integratable_id === target.id) return true;
-		return false;
-	});
-}
-//#endregion
-//#region src/commands/show.ts
-/** `fluid mist show <slug>` — single mist detail, including its attached
-*  surfaces (integration points). Surfaces scheduled_destroy_at when state is
-*  pending_destroy. */
-/** Display ref for an attached surface: the uuid echo when present, else id. */
-function surfaceRef(ip) {
-	if (ip.integratable_uuid) return ip.integratable_uuid;
-	if (ip.integratable_id != null) return `#${ip.integratable_id}`;
-	return "(unknown)";
-}
-const showCommand = new Command("show").description("Show one mist by slug").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("--json", "Emit raw API JSON").action((slug, opts) => runAction(async () => {
-	const resolved = resolveSlug(slug);
-	const client = createMistClient();
-	const { mist } = await showMist(client, resolved);
-	const integrationPoints = (await listIntegrationPoints(client, resolved)).integration_points;
-	if (opts.json) return printJson({
-		mist,
-		integration_points: integrationPoints
-	});
-	const lines = [];
-	const label = mistLabel(mist.name, mist.vendor_name);
-	lines.push(`${label}  ${chalk.dim(mist.slug)}`);
-	if (mist.vendor_name && mist.name && mist.name !== mist.vendor_name) lines.push(`  vendor   ${chalk.dim(mist.vendor_name)}`);
-	lines.push(`  state    ${colorState(mist.state)}`);
-	if (mist.kind) lines.push(`  kind     ${mist.kind}`);
-	if (mist.public_url) lines.push(`  url      ${chalk.cyan(mist.public_url)}`);
-	if (integrationPoints.length > 0) {
-		lines.push(`  surfaces ${integrationPoints.length}`);
-		for (const ip of integrationPoints) lines.push(`    ${chalk.dim("·")} ${ip.kind}  ${surfaceRef(ip)}  ${chalk.dim(`integration ${ip.id}`)}`);
+async function gitFetch(cwd, remoteUrl, branch = "main") {
+	const { cleanUrl, env } = gitAuthSpawn(remoteUrl);
+	try {
+		await execa("git", [
+			"-c",
+			"credential.helper=",
+			"fetch",
+			"--quiet",
+			cleanUrl,
+			branch
+		], {
+			cwd,
+			env
+		});
+	} catch (err) {
+		const missing = gitMissingError(err);
+		if (missing) throw missing;
+		const e = err;
+		throw new GitError(`git fetch failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
 	}
-	if (mist.provisioned_at) lines.push(`  live     ${relativeDate(mist.provisioned_at)}`);
-	lines.push(`  updated  ${relativeDate(mist.updated_at)}`);
-	if (mist.scheduled_destroy_at) lines.push(chalk.magenta(`  destroy  scheduled ${formatAbsolute(mist.scheduled_destroy_at)} (run \`fluid mist restore ${mist.slug}\` to undo)`));
-	console.log(lines.join("\n"));
-}));
-//#endregion
-//#region src/lib/ora-reporter.ts
+}
 /**
-* Spinner-backed `StepReporter` for interactive human runs. Split from
-* `step-reporter.ts` so tests can use the recording reporter without pulling
-* in `ora`'s ESM-only dependency chain.
+* Count commits in local HEAD vs `FETCH_HEAD` (after `gitFetch`). Returns
+* `{ahead, behind}`: how many commits HEAD has that the remote doesn't,
+* and vice versa. A `0/0` result means "in sync".
 */
-function createOraReporter() {
-	const spinner = ora();
-	return {
-		start(text) {
-			spinner.start(text);
-		},
-		update(text) {
-			spinner.text = text;
-		},
-		succeed(text) {
-			spinner.succeed(text);
-		},
-		skip(text) {
-			spinner.info(text);
-		},
-		info(text) {
-			spinner.stopAndPersist({
-				symbol: "•",
-				text
-			});
-		},
-		warn(text) {
-			spinner.warn(text);
-		},
-		fail(text) {
-			spinner.fail(text);
-		}
-	};
+async function gitAheadBehindVsFetchHead(cwd) {
+	try {
+		const { stdout } = await execa("git", [
+			"rev-list",
+			"--left-right",
+			"--count",
+			"HEAD...FETCH_HEAD"
+		], { cwd });
+		const [a, b] = stdout.trim().split(/\s+/);
+		const ahead = Number.parseInt(a ?? "0", 10);
+		const behind = Number.parseInt(b ?? "0", 10);
+		return {
+			ahead: Number.isFinite(ahead) ? ahead : 0,
+			behind: Number.isFinite(behind) ? behind : 0
+		};
+	} catch {
+		return {
+			ahead: 0,
+			behind: 0
+		};
+	}
 }
-//#endregion
-//#region src/lib/step-reporter.ts
-/** No-op reporter for `--json` mode (final payload printed by the command). */
-function createSilentReporter() {
-	return {
-		start() {},
-		update() {},
-		succeed() {},
-		skip() {},
-		info() {},
-		warn() {},
-		fail() {}
-	};
+/** Fast-forward `HEAD` to `FETCH_HEAD`. Fails (non-zero exit) if not
+*  fast-forwardable — caller must check ahead-count first. */
+async function gitMergeFastForward(cwd) {
+	try {
+		await execa("git", [
+			"merge",
+			"--ff-only",
+			"FETCH_HEAD"
+		], { cwd });
+	} catch (err) {
+		const missing = gitMissingError(err);
+		if (missing) throw missing;
+		const e = err;
+		throw new GitError(`git fast-forward merge failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
+	}
 }
-//#endregion
-//#region src/api/droplets.ts
-const BASE$2 = "/api/droplets";
 /**
-* Full scope set from `Droplet::Installation::VALID_SCOPES`. We request
-* them all by default so a Mist-created droplet's installations carry write
-* access out of the box — matching what Mist Desktop sends. Callers can
-* narrow this via the flow's `requestedScopes` option.
+* Stash working-tree + untracked changes with a Mist-tagged message.
+* Returns the stash ref (`stash@{0}`) we created. Callers should pair
+* this with `gitStashPop` after the dangerous step is done.
 */
-const DEFAULT_DROPLET_SCOPES = [
-	"main",
-	"prospects",
-	"members",
-	"web",
-	"settings",
-	"products",
-	"orders",
-	"users",
-	"website",
-	"header_menus",
-	"payments"
-];
-/** Lifecycle webhook paths a Mist Next app serves (mirrors Mist Desktop). */
-function dropletWebhookUrls(embedUrl) {
-	const base = embedUrl.replace(/\/+$/, "");
-	return {
-		install_webhook_url: `${base}/api/webhooks/installed`,
-		uninstall_webhook_url: `${base}/api/webhooks/uninstalled`
-	};
+async function gitStash(cwd, message) {
+	try {
+		await execa("git", [
+			"stash",
+			"push",
+			"--include-untracked",
+			"--message",
+			message
+		], { cwd });
+	} catch (err) {
+		const missing = gitMissingError(err);
+		if (missing) throw missing;
+		throw new GitError(`git stash push failed`, err.exitCode ?? 1);
+	}
 }
 /**
-* Build a droplet create body from a name + (optional) embed URL. When the
-* embed URL is known we also derive the lifecycle webhook URLs from it.
+* Pop the most recent stash. Throws on conflict so callers can surface
+* the situation (the working tree will have conflict markers; the user
+* needs to resolve manually).
 */
-function buildDropletCreateInput(opts) {
-	const scopes = [...opts.requestedScopes ?? DEFAULT_DROPLET_SCOPES];
-	const summary = "Created by Fluid Mist";
-	const input = {
-		name: opts.name,
-		requested_scopes: scopes,
-		settings: {
-			marketplace_page: { summary },
-			details_page: { summary }
-		}
-	};
-	if (opts.embedUrl) {
-		input.embed_url = opts.embedUrl;
-		Object.assign(input, dropletWebhookUrls(opts.embedUrl));
+async function gitStashPop(cwd) {
+	try {
+		await execa("git", ["stash", "pop"], { cwd });
+	} catch (err) {
+		const missing = gitMissingError(err);
+		if (missing) throw missing;
+		throw new GitError(`Couldn't restore your local changes after pulling — the file edits collided with a teammate's. Run \`git stash list\` and resolve manually.`, err.exitCode ?? 1);
 	}
-	return input;
-}
-function createDroplet(client, body) {
-	return client.post(BASE$2, body);
-}
-/** PATCH the droplet's embed URL (+ derived webhook URLs) once known. */
-function updateDroplet(client, uuid, input) {
-	return client.patch(`${BASE$2}/${encodeURIComponent(uuid)}`, { droplet: input });
-}
-/** Convenience: set embed URL + derived webhook URLs in one PATCH. */
-function setDropletEmbedUrl(client, uuid, embedUrl) {
-	return updateDroplet(client, uuid, {
-		embed_url: embedUrl,
-		...dropletWebhookUrls(embedUrl)
-	});
 }
-//#endregion
-//#region src/api/drop_zones.ts
-const BASE$1 = "/api/drop_zones";
 /**
-* Build a drop-zone create body. The slot id is `page__zone` (same split the
-* storefront preview uses, e.g. `checkout__below_total`) → `settings.page` +
-* `settings.zone`; height (px) → `settings.height`. Without a slot the zone
-* never renders, so the backend needs it to know WHERE to inject.
+* Persist the Mist bot as the repo's LOCAL git identity
+* (`git config --local user.{name,email}`).
+*
+* `gitAutoCommit` already forces the bot author on the publish commit
+* via `-c`/env, but that only covers commits WE make. Commits made any
+* other way against the same checkout — the Mist chat agent shelling out
+* `git commit` via run_cli, or the user in a terminal — inherit the
+* repo's configured identity, which is the person's personal GitHub
+* account. Vercel rejects a deploy whose commit author isn't a
+* we-commerce team member, so those personal-authored commits silently
+* block the deploy (exactly the www-* "stuck project" case).
+*
+* Setting the identity at the repo level makes EVERY commit path
+* bot-authored, and heals repos cloned before this was in place on their
+* next publish. Best-effort: a config failure must never abort a push —
+* the publish commit is still bot-forced by gitAutoCommit regardless.
 */
-function buildDropZoneCreateInput(opts) {
-	const [page, zone] = (opts.zone ?? "").split("__");
-	const settings = {};
-	if (page) settings.page = page;
-	if (zone) settings.zone = zone;
-	if (opts.heightPx != null) settings.height = opts.heightPx;
-	const input = { name: opts.name };
-	if (opts.embedUrl) input.embed_url = opts.embedUrl;
-	if (Object.keys(settings).length > 0) input.settings = settings;
-	return input;
-}
-function createDropZone(client, body) {
-	return client.post(BASE$1, body);
+async function ensureBotIdentity(cwd) {
+	try {
+		await execa("git", [
+			"config",
+			"--local",
+			"user.name",
+			MIST_GIT_AUTHOR_NAME
+		], { cwd });
+		await execa("git", [
+			"config",
+			"--local",
+			"user.email",
+			MIST_GIT_AUTHOR_EMAIL
+		], { cwd });
+	} catch {}
 }
-//#endregion
-//#region src/api/mobile_widgets.ts
-const BASE = "/api/company/mobile_widgets";
 /**
-* Build a mobile-widget create body. `cover_image_url` and `height` are
-* REQUIRED by the API (422 without them); we fall back to the Fluid
-* placeholder + default height when the caller doesn't supply them.
+* Append `.mist` to `.git/info/exclude` if it isn't already listed, so
+* git treats the marker file (spec §3 — the local-only `.mist` file that
+* `writeMistFile` drops after `fluid mist clone`) as ignored without ever
+* touching the template's tracked `.gitignore`.
+*
+* Why local exclude and not `.gitignore`: `.gitignore` lives in the
+* template repo and would need a template release to reach existing
+* clones. `.git/info/exclude` is per-checkout, so writing it here (at
+* clone time) AND defensively at the top of every `gitAutoCommit` (at
+* push time) heals pre-existing clones on their very next push, with no
+* template change required.
+*
+* Idempotent and best-effort: never throws. A repo with an unusual
+* `.git` layout (missing `info/`, `.git` as a worktree pointer file,
+* etc.) just skips the exclude — `gitAutoCommit`'s `git reset -- .mist`
+* after staging is the second line of defense that keeps `.mist` out of
+* the commit regardless.
 */
-function buildMobileWidgetCreateInput(opts) {
-	return {
-		name: opts.name,
-		embed_url: opts.embedUrl,
-		cover_image_url: opts.coverImageUrl || "https://ik.imagekit.io/fluid/s3/app/image-placeholder.svg",
-		height: opts.heightPx ?? 600,
-		scrollable: true
-	};
-}
-function createMobileWidget(client, body) {
-	return client.post(BASE, body);
-}
-//#endregion
-//#region src/api/env_vars.ts
-function path$1(id, key) {
-	return key ? `/api/v202604/mists/${id}/env_vars/${encodeURIComponent(key)}` : `/api/v202604/mists/${id}/env_vars`;
-}
-async function listEnvVars(client, slug) {
-	const id = await resolveMistId(client, slug);
-	return client.get(path$1(id));
-}
-/** Create a new env var (the spec routes `set` to POST for new keys). */
-async function createEnvVar(client, slug, key, value, targets) {
-	const id = await resolveMistId(client, slug);
-	return client.post(path$1(id), { env_var: {
-		key,
-		value,
-		targets
-	} });
-}
-/** Update an existing env var (the spec routes `set` to PATCH for existing keys). */
-async function updateEnvVar(client, slug, key, value, targets) {
-	const id = await resolveMistId(client, slug);
-	return client.patch(path$1(id, key), { env_var: {
-		value,
-		targets
-	} });
-}
-async function deleteEnvVar(client, slug, key) {
-	const id = await resolveMistId(client, slug);
-	return client.delete(path$1(id, key));
+function excludeMistMarkerFromGit(cwd) {
+	try {
+		const gitDir = path.join(cwd, ".git");
+		if (!existsSync(gitDir)) return;
+		const infoDir = path.join(gitDir, "info");
+		if (!existsSync(infoDir)) mkdirSync(infoDir, { recursive: true });
+		const excludePath = path.join(infoDir, "exclude");
+		const existing = existsSync(excludePath) ? readFileSync(excludePath, "utf8") : "";
+		if (existing.split("\n").some((line) => line.trim() === ".mist")) return;
+		writeFileSync(excludePath, `${existing}${existing.length > 0 && !existing.endsWith("\n") ? "\n" : ""}.mist\n`, "utf8");
+	} catch {}
 }
-//#endregion
-//#region src/types.ts
 /**
-* Managed env keys the backend writes onto a Mist once a droplet is
-* attached (backfill + redeploy). The CLI VERIFIES these appear with
-* `managed_by: "mist"` — it never sets them (the API 422s on write).
+* `git add -A && git commit -m <message>` in `cwd`.
 *
-* Source: settled backend contract (#19685 auto-provisions the droplet
-* env on integration-point create).
-*/
-const MANAGED_DROPLET_ENV_KEYS = [
-	"FLUID_DROPLET_UUID",
-	"FLUID_DROPLET_SECRET",
-	"FLUID_WEBHOOK_AUTH_TOKEN"
-];
-//#endregion
-//#region src/lib/surface-provision.ts
-/**
-* Surface provisioning engine — the one place the "create a Fluid surface and
-* wire it to a mist" flow lives, at parity with Mist Desktop's
-* mist-integration-points-api.service.ts. Exposed via `fluid mist create`
-* (create a bare mist first, then run this), `fluid mist attach` (any kind),
-* and `fluid mist attach-droplet` (droplet shortcut).
+* Mist Desktop's "Publish" UX target is non-technical: the user expects
+* "ship my changes" to ship the changes they made, not to know about
+* staging or commit messages. This helper bundles working-tree edits
+* into one commit per publish so push has something to send.
 *
-* Three surface kinds, each with its own create endpoint + attach identifier:
-*   - droplet     → POST /api/droplets              → drp_ uuid → integratable_uuid
-*   - drop-zone   → POST /api/drop_zones            → dz_  uuid → integratable_uuid
-*   - mobile-embed→ POST /api/company/mobile_widgets→ numeric id → integratable_id
+* The commit author is ALWAYS forced to the Mist GitHub App bot identity
+* (MIST_GIT_AUTHOR_*), overriding whatever local/global git identity the
+* machine has. This is what keeps Vercel from blocking the deploy: a commit
+* authored by a user's personal GitHub account that isn't a we-commerce Vercel
+* team member gets rejected. Passing `-c user.name=… -c user.email=…` beats
+* even a `--local` config, so every publish is bot-authored regardless of how
+* the repo landed on disk (fresh clone, pre-existing clone, or terminal CLI).
+* The real person is still recorded in the commit *message* (see push.ts).
 *
-* Design tenets (repo philosophy — "server is source of truth"):
-*   - No local progress file. State is re-derived from the API each run.
-*   - Attach-existing is idempotent: if an integration point already links the
-*     target surface (matched via the #19689 integratable_uuid echo, or the
-*     numeric id for mobile), skip. A droplet is 1-per-mist, so creating a new
-*     droplet also skips when one is already attached. Drop-zones/mobile
-*     embeds are additive (a mist can have many).
-*   - Only a droplet attach provisions managed env keys
-*     (FLUID_DROPLET_UUID/_SECRET/_WEBHOOK_AUTH_TOKEN); this flow only
-*     VERIFIES they landed — it never writes them (the API 422s on write).
+* `.mist` marker handling: `writeMistFile` already writes `.mist` to
+* `.git/info/exclude` at clone time, but this heals two other cases —
+* a clone made before that existed, or a repo whose exclude write
+* silently failed. Belt AND suspenders:
+*   1. Re-run the exclude write here (idempotent) — heals pre-existing
+*      clones on their very next push. Anchored to the repository root
+*      (`git rev-parse --show-toplevel`), not cwd, so a push run from a
+*      repo subdirectory heals the real `.git/info/exclude`.
+*   2. After `git add -A`, run `git reset -- ':(top).mist' .mist`
+*      (root-anchored + cwd-relative pathspecs; best-effort,
+*      ignored if it fails or matches nothing) to unstage the marker in
+*      case the exclude write above failed and `.mist` got swept in
+*      anyway. We deliberately do NOT ask `git add` to exclude `.mist`
+*      via a `:(exclude)` pathspec — when a path is *also* already
+*      listed in `.git/info/exclude`, combining `-A` with an explicit
+*      exclude pathspec on that same path makes git exit 1 with
+*      "paths are ignored by one of your .gitignore files" (a real git
+*      quirk, confirmed against git 2.41), which would turn the normal
+*      case (exclude already written) into a hard failure. Add-then-
+*      reset avoids that entirely and is a no-op when there's nothing
+*      to unstage.
+* Note: a `.mist` file already committed in an existing repo's history
+* is left alone — this only prevents *new* adds, it does not untrack
+* anything or rewrite history.
 */
-const DEFAULT_TIMING = {
-	publicUrlTimeoutMs: 9e4,
-	publicUrlIntervalMs: 3e3,
-	envTimeoutMs: 12e4,
-	envIntervalMs: 5e3
-};
-const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-const KIND_LABEL$1 = {
-	droplet: "droplet",
-	"drop-zone": "drop zone",
-	"mobile-embed": "mobile embed"
+async function gitAutoCommit(cwd, message) {
+	await ensureBotIdentity(cwd);
+	let repoRoot = cwd;
+	try {
+		const { stdout } = await execa("git", ["rev-parse", "--show-toplevel"], { cwd });
+		if (stdout.trim().length > 0) repoRoot = stdout.trim();
+	} catch {}
+	excludeMistMarkerFromGit(repoRoot);
+	try {
+		await execa("git", ["add", "-A"], { cwd });
+	} catch (err) {
+		const missing = gitMissingError(err);
+		if (missing) throw missing;
+		throw new GitError(`git add failed`, err.exitCode ?? 1);
+	}
+	try {
+		await execa("git", [
+			"reset",
+			"-q",
+			"--",
+			":(top).mist",
+			".mist"
+		], { cwd });
+	} catch {}
+	const identityArgs = [
+		"-c",
+		`user.name=${MIST_GIT_AUTHOR_NAME}`,
+		"-c",
+		`user.email=${MIST_GIT_AUTHOR_EMAIL}`
+	];
+	const identityEnv = {
+		GIT_AUTHOR_NAME: MIST_GIT_AUTHOR_NAME,
+		GIT_AUTHOR_EMAIL: MIST_GIT_AUTHOR_EMAIL,
+		GIT_COMMITTER_NAME: MIST_GIT_AUTHOR_NAME,
+		GIT_COMMITTER_EMAIL: MIST_GIT_AUTHOR_EMAIL
+	};
+	try {
+		await execa("git", [
+			...identityArgs,
+			"commit",
+			"-m",
+			message
+		], {
+			cwd,
+			env: {
+				...process.env,
+				...identityEnv
+			},
+			stdio: [
+				"ignore",
+				"inherit",
+				"inherit"
+			]
+		});
+	} catch (err) {
+		const missing = gitMissingError(err);
+		if (missing) throw missing;
+		const e = err;
+		if (typeof e.stderr === "string" && /nothing to commit/i.test(e.stderr)) return;
+		throw new GitError(`git commit failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
+	}
+}
+//#endregion
+//#region src/lib/slug-resolver.ts
+/**
+* Slug resolution — spec §3 conventions:
+*   1. If a slug arg is passed, use it.
+*   2. Otherwise look for a `.mist` file in CWD (written by `fluid mist
+*      clone`) and use the slug from it.
+*   3. Otherwise error: tell the user to pass a slug or cd into a cloned dir.
+*/
+const MIST_FILE = ".mist";
+var SlugResolutionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SlugResolutionError";
+	}
 };
+function readMistFile(dir) {
+	const filePath = join(dir, MIST_FILE);
+	if (!existsSync(filePath)) return null;
+	try {
+		const raw = readFileSync(filePath, "utf8");
+		const parsed = JSON.parse(raw);
+		if (!parsed || typeof parsed !== "object") return null;
+		const obj = parsed;
+		if (typeof obj["slug"] !== "string") return null;
+		return {
+			slug: obj["slug"],
+			vendor_name: typeof obj["vendor_name"] === "string" ? obj["vendor_name"] : "",
+			public_url: typeof obj["public_url"] === "string" ? obj["public_url"] : null
+		};
+	} catch {
+		return null;
+	}
+}
+/** Returns the slug from arg or `.mist` file; throws if neither is present. */
+function resolveSlug(arg, cwd = process.cwd()) {
+	if (arg && arg.trim().length > 0) return arg.trim();
+	const file = readMistFile(cwd);
+	if (file) return file.slug;
+	throw new SlugResolutionError("No slug provided and no `.mist` file in this directory. Pass the slug as an argument or cd into a cloned mist. (if you reverted a commit that removed .mist, pass the slug explicitly or re-run fluid mist clone)");
+}
 /**
-* Create (or reuse) a surface of `kind` and wire it to the mist. Idempotent
-* for droplet + attach-existing; additive for new drop-zones/mobile embeds.
+* Write a `.mist` file after `fluid mist clone`.
+*
+* Also excludes `.mist` via `.git/info/exclude` so it can never be swept
+* into a publish commit by `gitAutoCommit`'s `git add -A` — a commit
+* containing `.mist` that later gets `git revert`-ed deletes the marker
+* and locks every subsequent `fluid mist <cmd>` out of slug resolution
+* in that clone. Best-effort: if the exclude write fails (e.g. `.git`
+* isn't set up yet), `writeFileSync` below still runs — this is a
+* defense-in-depth step, not a precondition for the marker itself.
 */
-async function provisionSurface(client, options) {
-	const { reporter, slugOrId, kind } = options;
-	const timing = {
-		...DEFAULT_TIMING,
-		...options.timing
+function writeMistFile(dir, mist) {
+	excludeMistMarkerFromGit(dir);
+	const payload = {
+		slug: mist.slug,
+		vendor_name: mist.vendor_name,
+		public_url: mist.public_url
 	};
-	const sleep = options.sleep ?? defaultSleep;
-	const label = KIND_LABEL$1[kind];
-	reporter.start("Resolving mist…");
-	const mist = (await showMist(client, slugOrId)).mist;
-	reporter.succeed(`Mist ${mist.slug} (${mist.state})`);
-	reporter.start("Checking existing integrations…");
-	const points = (await listIntegrationPoints(client, slugOrId)).integration_points;
-	let surfaceUuid = null;
-	let surfaceNumericId = null;
-	let surfaceName = null;
-	let surfaceCreated = false;
-	let embedUrlSet = false;
-	let integrationPoint;
-	const attachingExisting = options.existingUuid != null || options.existingId != null;
-	const alreadyLinked = attachingExisting ? findIntegrationPointBySurface(points, {
-		kind,
-		uuid: options.existingUuid,
-		id: options.existingId
-	}) : kind === "droplet" ? findDropletIntegrationPoint(points) : void 0;
-	if (alreadyLinked) {
-		reporter.skip(`${label} already attached (integration #${alreadyLinked.id}) — skipping`);
-		surfaceUuid = alreadyLinked.integratable_uuid ?? options.existingUuid ?? null;
-		surfaceNumericId = alreadyLinked.integratable_id ?? options.existingId ?? null;
-		integrationPoint = {
-			id: alreadyLinked.id,
-			integratableUuid: alreadyLinked.integratable_uuid ?? null,
-			created: false
-		};
-	} else {
-		reporter.succeed("No matching integration yet");
-		let attachUuid = options.existingUuid;
-		let attachId = options.existingId;
-		if (!attachingExisting) {
-			const embedUrl = await resolvePublicUrl(client, {
-				slugOrId,
-				initial: mist.public_url,
-				reporter,
-				timing,
-				sleep
-			});
-			const name = options.name?.trim() || mist.name?.trim() || mist.vendor_name || mist.slug;
-			reporter.start(`Creating ${label} "${name}"…`);
-			if (kind === "droplet") {
-				const created = await createDroplet(client, { droplet: buildDropletCreateInput({
-					name,
-					embedUrl,
-					requestedScopes: options.requestedScopes
-				}) });
-				surfaceUuid = created.droplet.uuid;
-				surfaceNumericId = created.droplet.id ?? null;
-				surfaceName = created.droplet.name;
-				attachUuid = created.droplet.uuid;
-				embedUrlSet = Boolean(embedUrl);
-				reporter.succeed(`Created droplet ${surfaceUuid}${embedUrl ? "" : " (embed URL pending)"}`);
-				if (!embedUrl && surfaceUuid) {
-					const laterUrl = await resolvePublicUrl(client, {
-						slugOrId,
-						initial: null,
-						reporter,
-						timing,
-						sleep
-					});
-					if (laterUrl) {
-						reporter.start("Backfilling droplet embed URL…");
-						await setDropletEmbedUrl(client, surfaceUuid, laterUrl);
-						embedUrlSet = true;
-						reporter.succeed("Embed URL set");
-					} else reporter.warn("Mist public_url not ready yet — re-run once the first deploy finishes to set the embed URL");
-				}
-			} else if (kind === "drop-zone") {
-				if (!embedUrl) throw new Error("The mist has no public_url yet — wait for the first deploy, then attach the drop zone.");
-				const created = await createDropZone(client, { drop_zone: buildDropZoneCreateInput({
-					name,
-					embedUrl,
-					zone: options.zone,
-					heightPx: options.heightPx
-				}) });
-				surfaceUuid = created.drop_zone.uuid;
-				surfaceName = created.drop_zone.name;
-				attachUuid = created.drop_zone.uuid;
-				embedUrlSet = true;
-				reporter.succeed(`Created drop zone ${surfaceUuid}`);
-			} else {
-				if (!embedUrl) throw new Error("The mist has no public_url yet — wait for the first deploy, then attach the mobile embed.");
-				const created = await createMobileWidget(client, { mobile_widget: buildMobileWidgetCreateInput({
-					name,
-					embedUrl,
-					coverImageUrl: options.coverImageUrl,
-					heightPx: options.heightPx
-				}) });
-				surfaceNumericId = created.mobile_widget.id;
-				surfaceName = created.mobile_widget.name;
-				attachId = created.mobile_widget.id;
-				embedUrlSet = true;
-				reporter.succeed(`Created mobile embed #${surfaceNumericId}`);
-			}
-			surfaceCreated = true;
-		} else {
-			surfaceUuid = options.existingUuid ?? null;
-			surfaceNumericId = options.existingId ?? null;
-			embedUrlSet = true;
-		}
-		const attachInput = kind === "mobile-embed" ? {
-			kind,
-			integratable_id: attachId
-		} : {
-			kind,
-			integratable_uuid: attachUuid
-		};
-		reporter.start(`Attaching ${label}…`);
-		let ipResp;
-		try {
-			ipResp = await createIntegrationPoint(client, slugOrId, attachInput);
-		} catch (err) {
-			reporter.fail("Attach failed");
-			throw normalizeAttachError(err, attachUuid ?? String(attachId), kind);
-		}
-		integrationPoint = {
-			id: ipResp.integration_point.id,
-			integratableUuid: ipResp.integration_point.integratable_uuid ?? null,
-			created: true
-		};
-		if (!surfaceUuid) surfaceUuid = ipResp.integration_point.integratable_uuid ?? attachUuid ?? null;
-		if (surfaceNumericId == null) surfaceNumericId = ipResp.integration_point.integratable_id ?? null;
-		reporter.succeed(kind === "droplet" ? "Droplet attached — provisioning env + redeploy…" : `${label} attached`);
+	writeFileSync(join(dir, MIST_FILE), JSON.stringify(payload, null, 2) + "\n", "utf8");
+}
+//#endregion
+//#region src/lib/error-handler.ts
+/**
+* Centralized error handling — maps thrown errors to spec'd exit codes
+* and friendly messages. Imported by every command's `.action()` so each
+* file doesn't repeat the same try/catch.
+*
+* Exit codes (spec §3 "Conventions"):
+*   0 success | 1 user error | 2 API 4xx | 3 API 5xx / vendor | 4 network
+*/
+/** Run an async action and translate failures into pretty output + exit. */
+async function runAction(fn) {
+	try {
+		await fn();
+	} catch (err) {
+		handle(err);
 	}
-	const managedEnv = kind === "droplet" ? await verifyManagedEnv(client, {
-		slugOrId,
-		reporter,
-		timing,
-		sleep,
-		enabled: options.verifyEnv !== false
-	}) : null;
+}
+function handle(err) {
+	if (err instanceof SlugResolutionError) {
+		console.error(chalk.red(err.message));
+		process.exit(1);
+	}
+	if (err instanceof HostableParseError) {
+		console.error(chalk.red(err.message));
+		process.exit(1);
+	}
+	if (err instanceof MistApiError) {
+		if (err.status === 403) {
+			const action = err.details?.["permission"];
+			console.error(chalk.red(action ? `Your role doesn't include \`mist.${String(action)}\` — ask your Fluid admin to grant it.` : err.message));
+		} else if (err.status === 409) {
+			const date = err.details?.["scheduled_destroy_at"];
+			console.error(chalk.yellow(typeof date === "string" ? `This mist is scheduled for destruction on ${date.slice(0, 10)}. Run \`fluid mist restore <slug>\` first.` : err.message));
+		} else if (err.status === 422) {
+			const details = err.details ?? {};
+			const idErrors = details["integratable_id"] ?? details["hostable_id"];
+			const managedKey = typeof err.message === "string" && /managed_by|managed by mist|FLUID_DROPLET|FLUID_WEBHOOK/i.test(err.message);
+			if (Array.isArray(idErrors) && idErrors.some((e) => /already taken|already attached/i.test(String(e)))) console.error(chalk.yellow("That droplet is already attached to another mist. Detach it first or pick a different one."));
+			else if (managedKey) console.error(chalk.yellow("That env var is Mist-managed (FLUID_DROPLET_UUID / FLUID_DROPLET_SECRET / FLUID_WEBHOOK_AUTH_TOKEN) — it's set automatically when a droplet is attached and can't be written directly."));
+			else if (typeof err.message === "string" && /Droplet not found|integratable/i.test(err.message)) {
+				const id = details["integratable_id"] ?? details["hostable_id"];
+				console.error(chalk.yellow(`Couldn't find droplet${id != null ? ` #${String(id)}` : ""} in this company.`));
+			} else console.error(chalk.red(err.message));
+		} else if (err.status === 410) console.error(chalk.red("Grace period expired — vendor teardown is in flight. Create a fresh mist with `fluid mist create`."));
+		else console.error(chalk.red(err.message));
+		process.exit(err.exitCode);
+	}
+	if (err instanceof Error) console.error(chalk.red(err.message));
+	else console.error(chalk.red(String(err)));
+	process.exit(1);
+}
+//#endregion
+//#region src/lib/output.ts
+/**
+* Output helpers — human-readable by default, `--json` emits raw API
+* payload. NO_COLOR respected via chalk's built-in detection.
+*/
+function printJson(payload) {
+	process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+}
+const STATE_COLOR$1 = {
+	pending: chalk.gray,
+	provisioning: chalk.yellow,
+	live: chalk.green,
+	failed: chalk.red,
+	pending_destroy: chalk.magenta,
+	archived: chalk.dim
+};
+function colorState(state) {
+	return STATE_COLOR$1[state](state);
+}
+/**
+* Bold display label for a mist, falling back to a dim "(unnamed)"
+* placeholder when both `name` and `vendorName` are missing. Never nests
+* `chalk.bold(chalk.dim(...))` — most terminals render that as plain bold,
+* losing the "this is a placeholder" muted intent.
+*/
+function mistLabel(name, vendorName) {
+	const raw = name ?? vendorName;
+	return raw ? chalk.bold(raw) : chalk.dim("(unnamed)");
+}
+/**
+* Pad columns to width — cheap manual table; avoids cli-table3 dep for v1.
+* Cells are defensively normalized: API records can legitimately have every
+* optional label field (`name`, `vendor_name`, `droplet.name`, ...) come back
+* null/absent at once (e.g. a `pending_destroy` mist), so callers sometimes
+* hand us `undefined`/`null` after chaining `??` — that must render as an
+* empty cell, not crash the whole table.
+*/
+function printTable(rows) {
+	if (rows.length === 0) return;
+	const widths = [];
+	for (const row of rows) row.forEach((cell, i) => {
+		const visible = stripAnsi(cell).length;
+		widths[i] = Math.max(widths[i] ?? 0, visible);
+	});
+	for (const row of rows) {
+		const padded = row.map((cell, i) => {
+			const w = widths[i] ?? 0;
+			const text = cell ?? "";
+			return text + " ".repeat(Math.max(0, w - stripAnsi(text).length));
+		});
+		process.stdout.write(padded.join("  ") + "\n");
+	}
+}
+function stripAnsi(s) {
+	return (s ?? "").replace(/\x1b\[[0-9;]*m/g, "");
+}
+function relativeDate(iso) {
+	if (!iso) return "—";
+	const diff = Date.now() - new Date(iso).getTime();
+	const minutes = Math.floor(diff / 6e4);
+	if (minutes < 1) return "just now";
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+	const days = Math.floor(hours / 24);
+	if (days < 30) return `${days}d ago`;
+	return new Date(iso).toISOString().slice(0, 10);
+}
+/** Human-friendly absolute date for one-off prints (scheduled_destroy_at). */
+function formatAbsolute(iso) {
+	return new Date(iso).toISOString().slice(0, 10);
+}
+//#endregion
+//#region src/commands/list.ts
+/** `fluid mist list` — GET /mists with optional filters. Spec §3. */
+const listCommand = new Command("list").description("List the mists you have access to").option("--state <state>", "Filter by state: live | provisioning | failed | pending_destroy | archived").option("--kind <kind>", "Filter by kind (default: next_app)").option("--limit <n>", "Page size 1..100 (default 25)").option("--json", "Emit raw API JSON").action((opts) => runAction(async () => {
+	const client = createMistClient();
+	const limit = opts.limit ? parseInt(opts.limit, 10) : void 0;
+	const response = await listMists(client, {
+		...opts.state ? { state: opts.state } : {},
+		...opts.kind ? { kind: opts.kind } : {},
+		...limit && Number.isFinite(limit) ? { limit } : {}
+	});
+	if (opts.json) return printJson(response);
+	const mists = response.mists ?? [];
+	if (mists.length === 0) {
+		console.log(chalk.dim("No mists found."));
+		return;
+	}
+	printTable([[
+		chalk.bold("SLUG"),
+		chalk.bold("NAME"),
+		chalk.bold("STATE"),
+		chalk.bold("ATTACHED"),
+		chalk.bold("UPDATED")
+	], ...mists.map((m) => [
+		m.slug,
+		m.name ?? m.droplet?.name ?? m.vendor_name ?? chalk.dim("(unnamed)"),
+		colorState(m.state),
+		m.hostable_type ?? chalk.dim("standalone"),
+		relativeDate(m.updated_at)
+	])]);
+}));
+//#endregion
+//#region src/api/integration_points.ts
+function basePath(mistId) {
+	return `/api/v202604/mists/${mistId}/integration_points`;
+}
+async function listIntegrationPoints(client, slug) {
+	const id = await resolveMistId(client, slug);
+	return client.get(basePath(id));
+}
+async function createIntegrationPoint(client, slug, input) {
+	const id = await resolveMistId(client, slug);
+	return client.post(basePath(id), { integration_point: input });
+}
+async function deleteIntegrationPoint(client, slug, integrationPointId) {
+	const id = await resolveMistId(client, slug);
+	return client.delete(`${basePath(id)}/${integrationPointId}`);
+}
+/**
+* First droplet-kind integration point in a list, or undefined. A droplet is
+* 1-per-mist (it provisions the managed env), so this is the idempotency key
+* for the droplet create+attach flow.
+*/
+function findDropletIntegrationPoint(integrationPoints) {
+	return (integrationPoints ?? []).find((ip) => ip.kind === "droplet");
+}
+/**
+* Find an integration point that already links a specific surface — matched
+* by uuid (droplet/drop-zone) or numeric id (mobile-embed), optionally scoped
+* to a kind. Used to make attach-existing idempotent (avoid the server's 422
+* "already taken"). Uses the `integratable_uuid` echo (#19689) when present.
+*/
+function findIntegrationPointBySurface(integrationPoints, target) {
+	return (integrationPoints ?? []).find((ip) => {
+		if (target.kind && ip.kind !== target.kind) return false;
+		if (target.uuid && ip.integratable_uuid === target.uuid) return true;
+		if (target.id != null && ip.integratable_id === target.id) return true;
+		return false;
+	});
+}
+//#endregion
+//#region src/commands/show.ts
+/** `fluid mist show <slug>` — single mist detail, including its attached
+*  surfaces (integration points). Surfaces scheduled_destroy_at when state is
+*  pending_destroy. */
+/** Display ref for an attached surface: the uuid echo when present, else id. */
+function surfaceRef(ip) {
+	if (ip.integratable_uuid) return ip.integratable_uuid;
+	if (ip.integratable_id != null) return `#${ip.integratable_id}`;
+	return "(unknown)";
+}
+const showCommand = new Command("show").description("Show one mist by slug").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("--json", "Emit raw API JSON").action((slug, opts) => runAction(async () => {
+	const resolved = resolveSlug(slug);
+	const client = createMistClient();
+	const { mist } = await showMist(client, resolved);
+	const integrationPoints = (await listIntegrationPoints(client, resolved)).integration_points;
+	if (opts.json) return printJson({
+		mist,
+		integration_points: integrationPoints
+	});
+	const lines = [];
+	const label = mistLabel(mist.name, mist.vendor_name);
+	lines.push(`${label}  ${chalk.dim(mist.slug)}`);
+	if (mist.vendor_name && mist.name && mist.name !== mist.vendor_name) lines.push(`  vendor   ${chalk.dim(mist.vendor_name)}`);
+	lines.push(`  state    ${colorState(mist.state)}`);
+	if (mist.kind) lines.push(`  kind     ${mist.kind}`);
+	if (mist.public_url) lines.push(`  url      ${chalk.cyan(mist.public_url)}`);
+	if (integrationPoints.length > 0) {
+		lines.push(`  surfaces ${integrationPoints.length}`);
+		for (const ip of integrationPoints) lines.push(`    ${chalk.dim("·")} ${ip.kind}  ${surfaceRef(ip)}  ${chalk.dim(`integration ${ip.id}`)}`);
+	}
+	if (mist.provisioned_at) lines.push(`  live     ${relativeDate(mist.provisioned_at)}`);
+	lines.push(`  updated  ${relativeDate(mist.updated_at)}`);
+	if (mist.scheduled_destroy_at) lines.push(chalk.magenta(`  destroy  scheduled ${formatAbsolute(mist.scheduled_destroy_at)} (run \`fluid mist restore ${mist.slug}\` to undo)`));
+	console.log(lines.join("\n"));
+}));
+//#endregion
+//#region src/lib/ora-reporter.ts
+/**
+* Spinner-backed `StepReporter` for interactive human runs. Split from
+* `step-reporter.ts` so tests can use the recording reporter without pulling
+* in `ora`'s ESM-only dependency chain.
+*/
+function createOraReporter() {
+	const spinner = ora();
 	return {
-		mist: {
-			id: mist.id,
-			slug: mist.slug,
-			name: mist.name,
-			public_url: mist.public_url,
-			state: mist.state
+		start(text) {
+			spinner.start(text);
 		},
-		kind,
-		surface: {
-			uuid: surfaceUuid,
-			id: surfaceNumericId,
-			name: surfaceName
+		update(text) {
+			spinner.text = text;
 		},
-		integrationPoint: integrationPoint ?? {
-			id: "",
-			integratableUuid: null,
-			created: false
+		succeed(text) {
+			spinner.succeed(text);
 		},
-		surfaceCreated,
-		embedUrlSet,
-		managedEnv
-	};
-}
-/**
-* If the integration-points endpoint rejects the attach identifier (e.g. an
-* older API that predates #19688's attach-by-uuid support), surface an
-* actionable message noting the surface WAS created. Other errors pass through.
-*/
-function normalizeAttachError(err, surfaceRef, kind) {
-	if (err instanceof MistApiError && (err.status === 400 || err.status === 422)) {
-		const blob = `${err.message} ${JSON.stringify(err.details ?? {})}`;
-		if (/integratable_uuid|integratable_id|unpermitted|unknown|param/i.test(blob)) return new MistApiError(`The ${KIND_LABEL$1[kind]} ${surfaceRef} was created, but this API rejected the attach (needs the #19688 integration-points endpoint). Re-run once the API is updated.`, err.status, err.details);
-	}
-	return err instanceof Error ? err : new Error(String(err));
-}
-/**
-* Return the mist's public_url, polling briefly if it isn't ready yet
-* (async-first-deploy). Returns null if it never appears within the window.
-*/
-async function resolvePublicUrl(client, args) {
-	if (args.initial) return args.initial;
-	args.reporter.start("Waiting for the mist's public URL…");
-	const deadline = Date.now() + args.timing.publicUrlTimeoutMs;
-	for (;;) {
-		const url = (await showMist(client, args.slugOrId)).mist.public_url;
-		if (url) {
-			args.reporter.succeed(`Public URL ready: ${url}`);
-			return url;
+		skip(text) {
+			spinner.info(text);
+		},
+		info(text) {
+			spinner.stopAndPersist({
+				symbol: "•",
+				text
+			});
+		},
+		warn(text) {
+			spinner.warn(text);
+		},
+		fail(text) {
+			spinner.fail(text);
 		}
-		if (Date.now() >= deadline) break;
-		await args.sleep(args.timing.publicUrlIntervalMs);
-	}
-	return null;
-}
-/**
-* Poll `GET …/env_vars` until the Mist-managed droplet keys appear with
-* `managed_by: "mist"`. Never fails the flow — a redeploy in progress is a
-* normal, transient state we simply report.
-*/
-async function verifyManagedEnv(client, args) {
-	const required = [...MANAGED_DROPLET_ENV_KEYS];
-	if (!args.enabled) return {
-		ready: false,
-		present: [],
-		missing: required
 	};
-	args.reporter.start("Verifying managed environment…");
-	const deadline = Date.now() + args.timing.envTimeoutMs;
-	let present = [];
-	for (;;) {
-		const envVars = (await listEnvVars(client, args.slugOrId)).env_vars ?? [];
-		const managed = new Set(envVars.filter((e) => e.managed_by === "mist").map((e) => e.key));
-		present = required.filter((k) => managed.has(k));
-		if (present.length === required.length) {
-			args.reporter.succeed("Managed env keys present — droplet is wired up");
-			return {
-				ready: true,
-				present,
-				missing: []
-			};
-		}
-		if (Date.now() >= deadline) break;
-		args.reporter.update(`Verifying managed environment… (${present.length}/${required.length} keys, redeploy in progress)`);
-		await args.sleep(args.timing.envIntervalMs);
-	}
-	const missing = required.filter((k) => !present.includes(k));
-	args.reporter.warn(`Redeploy in progress — managed keys not visible yet (${present.length}/${required.length}). Check later with \`fluid mist env list\`. Missing: ${missing.join(", ")}`);
+}
+//#endregion
+//#region src/lib/step-reporter.ts
+/** No-op reporter for `--json` mode (final payload printed by the command). */
+function createSilentReporter() {
 	return {
-		ready: false,
-		present,
-		missing
+		start() {},
+		update() {},
+		succeed() {},
+		skip() {},
+		info() {},
+		warn() {},
+		fail() {}
 	};
 }
 //#endregion
-//#region src/lib/surface-flags.ts
-const KIND_ALIASES = {
-	droplet: "droplet",
-	droplets: "droplet",
-	"drop-zone": "drop-zone",
-	drop_zone: "drop-zone",
-	dropzone: "drop-zone",
-	zone: "drop-zone",
-	"mobile-embed": "mobile-embed",
-	mobile_embed: "mobile-embed",
-	mobile: "mobile-embed",
-	"mobile-widget": "mobile-embed",
-	mobilewidget: "mobile-embed"
-};
-const SURFACE_KIND_LIST = "droplet, drop-zone, mobile-embed";
-function parseSurfaceKind(raw) {
-	const hit = KIND_ALIASES[raw.trim().toLowerCase()];
-	if (!hit) throw new Error(`Unknown surface kind "${raw}". Use one of: ${SURFACE_KIND_LIST}.`);
-	return hit;
-}
-function parseHeight(raw) {
-	if (raw == null) return void 0;
-	const n = Number(raw);
-	if (!Number.isInteger(n) || n <= 0) throw new Error(`Invalid --height "${raw}". Must be a positive integer (px).`);
-	return n;
-}
+//#region src/api/droplets.ts
+const BASE$3 = "/api/droplets";
 /**
-* Map CLI flags to the kind-specific `provisionSurface` options, enforcing the
-* per-kind requirements the API needs:
-*  - drop-zone requires `--zone <page__zone>` (else it never renders).
-*  - mobile-embed requires `--cover-image <url>` (the API 422s without one; the
-*    CLI has no DAM picker, so the user must supply a url).
+* Full scope set from `Droplet::Installation::VALID_SCOPES`. We request
+* them all by default so a Mist-created droplet's installations carry write
+* access out of the box — matching what Mist Desktop sends. Callers can
+* narrow this via the flow's `requestedScopes` option.
 */
-function surfaceProvisionOptionsFromFlags(kind, flags) {
-	const heightPx = parseHeight(flags.height);
-	if (kind === "drop-zone") {
-		if (!flags.zone?.trim()) throw new Error("A drop-zone needs a slot — pass `--zone <page__zone>` (e.g. --zone checkout__below_total).");
-		return {
-			zone: flags.zone.trim(),
-			heightPx
-		};
-	}
-	if (kind === "mobile-embed") {
-		if (!flags.coverImage?.trim()) throw new Error("A mobile-embed needs a cover image — pass `--cover-image <url>` (the mobile API requires one; the CLI has no image picker).");
-		return {
-			coverImageUrl: flags.coverImage.trim(),
-			heightPx
-		};
-	}
-	return {};
-}
-//#endregion
-//#region src/lib/surface-summary.ts
-/** Shared human-readable summary for a surface provision result. */
-const KIND_LABEL = {
-	droplet: "droplet",
-	"drop-zone": "drop zone",
-	"mobile-embed": "mobile embed"
-};
-function printSurfaceSummary(result) {
-	const ref = result.surface.uuid ?? (result.surface.id != null ? `#${result.surface.id}` : "(unknown)");
-	const state = result.surfaceCreated ? "created" : "existing";
-	console.log(chalk.dim(`  ${KIND_LABEL[result.kind]}: ${ref} (${state}) · integration ${result.integrationPoint.id}`));
-	if (result.kind === "droplet" && result.managedEnv) if (result.managedEnv.ready) console.log(chalk.dim("  env: managed keys provisioned ✓"));
-	else console.log(chalk.yellow("  env: redeploy in progress — run `fluid mist env list` shortly to confirm managed keys"));
+const DEFAULT_DROPLET_SCOPES = [
+	"main",
+	"prospects",
+	"members",
+	"web",
+	"settings",
+	"products",
+	"orders",
+	"users",
+	"website",
+	"header_menus",
+	"payments"
+];
+/** Lifecycle webhook paths a Mist Next app serves (mirrors Mist Desktop). */
+function dropletWebhookUrls(embedUrl) {
+	const base = embedUrl.replace(/\/+$/, "");
+	return {
+		install_webhook_url: `${base}/api/webhooks/installed`,
+		uninstall_webhook_url: `${base}/api/webhooks/uninstalled`
+	};
 }
-//#endregion
-//#region src/commands/create.ts
 /**
-* `fluid mist create` — provision a new mist, optionally creating and attaching
-* a surface in one step. All attach paths go through integration points
-* (hostable is retired — #19684/#19687).
-*
-*   --droplet [name]           Create a NEW droplet and attach it. Bare →
-*                              droplet name defaults to the mist name. The
-*                              "one command that sets everything up" path.
-*   --kind <kind> [flags]      Create + attach a surface of any kind:
-*                              droplet | drop-zone | mobile-embed. Kind flags:
-*                                drop-zone   --zone <page__zone> --height <px>
-*                                mobile-embed --cover-image <url> --height <px>
-*   --hostable droplet:<uuid>  Attach an EXISTING droplet by its drp_… uuid.
-*
-* With none of these, creates a plain standalone mist.
+* Build a droplet create body from a name + (optional) embed URL. When the
+* embed URL is known we also derive the lifecycle webhook URLs from it.
 */
-const createCommand = new Command("create").description("Provision a new mist (optionally create + attach a surface in one step)").option("--droplet [name]", "Create a droplet and attach it. Bare uses the mist name; pass a value to override.").option("--kind <kind>", "Create + attach a surface: droplet | drop-zone | mobile-embed").option("--hostable <ref>", "Attach an existing droplet by uuid: droplet:<uuid> (e.g. droplet:drp_abc123)").option("--name <label>", "Display label for the mist (and the surface)").option("--zone <slot>", "drop-zone slot id: page__zone (e.g. checkout__below_total)").option("--height <px>", "Embed height in px (drop-zone + mobile-embed)").option("--cover-image <url>", "Mobile-embed cover image url (required for mobile-embed)").option("--mist-kind <kind>", "Mist kind (default: next_app)").option("--no-wait", "Don't wait for managed env keys to appear after attach").option("--json", "Emit raw JSON").action((opts) => runAction(async () => {
-	const wantDroplet = opts.droplet !== void 0;
-	const wantKind = !!opts.kind;
-	const wantHostable = !!opts.hostable;
-	if ([
-		wantDroplet,
-		wantKind,
-		wantHostable
-	].filter(Boolean).length > 1) throw new Error("Pass only one of `--droplet`, `--kind`, or `--hostable` — they're mutually exclusive.");
-	let kind;
-	let existingDropletUuid;
-	let nameOverride;
-	if (wantDroplet) {
-		kind = "droplet";
-		nameOverride = typeof opts.droplet === "string" ? opts.droplet.trim() : void 0;
-	} else if (wantKind) kind = parseSurfaceKind(opts.kind);
-	else if (wantHostable) {
-		kind = "droplet";
-		existingDropletUuid = parseDropletRef(opts.hostable);
+function buildDropletCreateInput(opts) {
+	const scopes = [...opts.requestedScopes ?? DEFAULT_DROPLET_SCOPES];
+	const summary = "Created by Fluid Mist";
+	const input = {
+		name: opts.name,
+		requested_scopes: scopes,
+		settings: {
+			marketplace_page: { summary },
+			details_page: { summary }
+		}
+	};
+	if (opts.embedUrl) {
+		input.embed_url = opts.embedUrl;
+		Object.assign(input, dropletWebhookUrls(opts.embedUrl));
 	}
-	const mistBody = { kind: opts.mistKind ?? "next_app" };
-	if (opts.name?.trim()) mistBody.name = opts.name.trim();
-	const client = createMistClient();
-	const reporter = opts.json ? createSilentReporter() : createOraReporter();
-	reporter.start("Setting up your Mist Cloud environment…");
-	let created;
-	try {
-		created = await createMist(client, { mist: mistBody });
-	} catch (err) {
-		reporter.fail("Provisioning failed");
-		throw err;
+	return input;
+}
+function createDroplet(client, body) {
+	return client.post(BASE$3, body);
+}
+/** Page size + runaway guard for walking the page-paginated droplets list. */
+const PER_PAGE$1 = 100;
+const MAX_PAGES$1 = 25;
+/**
+* Recover a droplet's drp_ uuid from its numeric id by paging the company's
+* droplets list (`GET /api/droplets?page=&per_page=` — the list rows carry
+* `id`, unlike the create/show responses). Needed for legacy integration
+* points that only echo `integratable_id`: the show endpoint resolves by
+* uuid, so a numeric id can't be fetched directly. Returns null when no
+* droplet matches within the page cap.
+*/
+async function findDropletUuidByNumericId(client, id) {
+	for (let page = 1; page <= MAX_PAGES$1; page++) {
+		const resp = await client.get(`${BASE$3}?page=${page}&per_page=${PER_PAGE$1}`);
+		const batch = resp.droplets ?? [];
+		const match = batch.find((d) => d.id === id);
+		if (match) return match.uuid ?? null;
+		const totalPages = resp.meta?.pagination?.total_pages;
+		if (totalPages != null ? page >= totalPages : batch.length < PER_PAGE$1) break;
 	}
-	const mist = created.mist;
-	reporter.succeed(`Provisioned ${mist.slug}`);
-	let provision;
-	if (kind) provision = await provisionSurface(client, {
-		slugOrId: mist.slug,
-		kind,
-		name: nameOverride ?? opts.name?.trim(),
-		existingUuid: existingDropletUuid,
-		verifyEnv: opts.wait !== false,
-		reporter,
-		...surfaceProvisionOptionsFromFlags(kind, opts)
+	return null;
+}
+/** PATCH the droplet's embed URL (+ derived webhook URLs) once known. */
+function updateDroplet(client, uuid, input) {
+	return client.patch(`${BASE$3}/${encodeURIComponent(uuid)}`, { droplet: input });
+}
+/** Convenience: set embed URL + derived webhook URLs in one PATCH. */
+function setDropletEmbedUrl(client, uuid, embedUrl) {
+	return updateDroplet(client, uuid, {
+		embed_url: embedUrl,
+		...dropletWebhookUrls(embedUrl)
 	});
-	if (opts.json) return printJson(provision ? {
-		mist,
-		provision
-	} : created);
-	const label = mistLabel(mist.name, mist.vendor_name);
-	console.log();
-	console.log(`${label}  ${chalk.dim(mist.slug)}  ${colorState(mist.state)}`);
-	if (mist.public_url) console.log(`  ${chalk.cyan(mist.public_url)}`);
-	if (provision) printSurfaceSummary(provision);
-	console.log();
-	console.log(chalk.dim(`Clone with: fluid mist clone ${mist.slug}`));
-}));
+}
 //#endregion
-//#region src/commands/attach.ts
+//#region src/api/droplet_installations.ts
+const BASE$2 = "/api/droplet_installations";
+/** Page size + runaway guard for walking the page-paginated list. */
+const PER_PAGE = 100;
+const MAX_PAGES = 25;
 /**
-* `fluid mist attach --kind <kind> [flags] [slug]` — create a surface and wire
-* it to an existing mist. One command for all three kinds:
-*
-*   --kind droplet                       (managed-env-provisioning droplet)
-*   --kind drop-zone --zone page__zone   [--height <px>]
-*   --kind mobile-embed --cover-image <url> [--height <px>]
-*
-* Attach an EXISTING surface instead of creating one with `--existing <ref>`:
-*   droplet/drop-zone → droplet:drp_… / drop-zone:dz_… / bare uuid
-*   mobile-embed      → mobile-embed:<numericId>
-*
-* Idempotent for droplet + attach-existing (skips when already linked).
+* List ALL of the current company's droplet installations, following the
+* endpoint's page-number pagination (`?page=&per_page=` — same shape as
+* fluid-admin's `getCompanyDroplets`). A single-page fetch would miss rows
+* beyond the first page, making the idempotency check (and the duplicate-
+* rejection confirmation) report a false "not installed" forever.
 */
-/** Parse `--existing <ref>` into a uuid or numeric id for the given kind. */
-function parseExisting(kind, raw) {
-	const trimmed = (raw.includes(":") ? raw.slice(raw.lastIndexOf(":") + 1) : raw).trim();
-	if (!trimmed) throw new Error(`Empty --existing reference "${raw}".`);
-	if (kind === "mobile-embed") {
-		const id = Number(trimmed);
-		if (!Number.isInteger(id) || id <= 0) throw new Error(`mobile-embed attaches by numeric id — pass \`--existing <id>\` (got "${raw}").`);
-		return { existingId: id };
+async function listAllDropletInstallations(client) {
+	const rows = [];
+	for (let page = 1; page <= MAX_PAGES; page++) {
+		const resp = await client.get(`${BASE$2}?page=${page}&per_page=${PER_PAGE}`);
+		const batch = resp.droplet_installations ?? [];
+		rows.push(...batch);
+		const totalPages = resp.meta?.pagination?.total_pages;
+		if (totalPages != null ? page >= totalPages : batch.length < PER_PAGE) break;
 	}
-	return { existingUuid: trimmed };
+	return rows;
+}
+/** Install a droplet (by drp_ uuid) for the current company. */
+function createDropletInstallation(client, input) {
+	return client.post(BASE$2, input);
 }
-const attachCommand = new Command("attach").description(`Create a surface (${SURFACE_KIND_LIST}) and wire it to an existing mist`).argument("[slug]", "Mist slug (defaults to the .mist file in CWD)").requiredOption("--kind <kind>", `Surface kind: ${SURFACE_KIND_LIST}`).option("--name <label>", "Surface name (defaults to the mist's name)").option("--zone <slot>", "drop-zone slot id: page__zone (e.g. checkout__below_total)").option("--height <px>", "Embed height in px (drop-zone + mobile-embed)").option("--cover-image <url>", "Mobile-embed cover image url (required for mobile-embed)").option("--existing <ref>", "Attach an existing surface instead of creating one (uuid, or numeric id for mobile-embed)").option("--no-wait", "Don't wait for managed env keys to appear after attach").option("--json", "Emit raw JSON").action((slug, opts) => runAction(async () => {
-	const kind = parseSurfaceKind(opts.kind);
-	const resolved = resolveSlug(slug);
-	const client = createMistClient();
-	const reporter = opts.json ? createSilentReporter() : createOraReporter();
-	const existing = opts.existing ? parseExisting(kind, opts.existing) : void 0;
-	const result = await provisionSurface(client, {
-		slugOrId: resolved,
-		kind,
-		name: opts.name?.trim(),
-		verifyEnv: opts.wait !== false,
-		reporter,
-		...existing,
-		...existing ? {} : surfaceProvisionOptionsFromFlags(kind, opts)
-	});
-	if (opts.json) return printJson(result);
-	console.log();
-	console.log(`${chalk.bold(result.mist.name ?? result.mist.slug)}  ${chalk.dim(result.mist.slug)}`);
-	printSurfaceSummary(result);
-}));
-//#endregion
-//#region src/commands/attach-droplet.ts
 /**
-* `fluid mist attach-droplet [name] [slug]` — droplet shortcut for
-* `fluid mist attach --kind droplet`. Creates a droplet and wires it to an
-* existing standalone mist (provisioning the managed env). Idempotent: if a
-* droplet is already attached, it skips create + attach and just verifies env.
-*
-*   name   Optional droplet name (defaults to the mist's name).
-*   slug   Optional mist slug (defaults to the `.mist` file in CWD).
+* The company's installation row for a droplet drp_ uuid, or undefined.
+* The idempotency key for the install step: an existing row means the
+* droplet is already connected (installed via a previous run, Mist Desktop,
+* or the admin marketplace).
 */
-const attachDropletCommand = new Command("attach-droplet").description("Create a droplet and wire it to an existing standalone mist (idempotent)").argument("[name]", "Droplet name (defaults to the mist's name)").argument("[slug]", "Mist slug (defaults to the .mist file in CWD)").option("--no-wait", "Don't wait for managed env keys to appear after attach").option("--json", "Emit raw JSON").action((name, slug, opts) => runAction(async () => {
-	const resolved = resolveSlug(slug);
-	const client = createMistClient();
-	const reporter = opts.json ? createSilentReporter() : createOraReporter();
-	const result = await provisionSurface(client, {
-		slugOrId: resolved,
-		kind: "droplet",
-		name: name?.trim() || void 0,
-		verifyEnv: opts.wait !== false,
-		reporter
-	});
-	if (opts.json) return printJson(result);
-	console.log();
-	console.log(`${chalk.bold(result.mist.name ?? result.mist.slug)}  ${chalk.dim(result.mist.slug)}`);
-	printSurfaceSummary(result);
-}));
+function findInstallationForDroplet(installations, dropletUuid) {
+	return (installations ?? []).find((i) => i.droplet_uuid === dropletUuid);
+}
 //#endregion
-//#region src/commands/update.ts
+//#region src/api/drop_zones.ts
+const BASE$1 = "/api/drop_zones";
 /**
-* `fluid mist update` — mutate an existing mist. Hostable is retired
-* (#19684/#19687), so attach/detach operate on integration points:
-*
-*   --name <label>            Rename the mist (PATCH /mists/:id).
-*   --hostable droplet:<uuid> Attach a droplet by uuid. No-ops if that same
-*                             droplet is already attached; replaces it if a
-*                             different droplet is attached (droplet is
-*                             1-per-mist — it provisions the managed env).
-*   --detach                  Remove the droplet integration point.
-*
-* The integration-point link is immutable (no update route, no `active`
-* field) — enablement lives on the surface record, so there's no toggle here.
-* All ops re-derive state from the integration-points index (which echoes
-* `integratable_uuid` since #19689) and only make the calls that change it.
+* Build a drop-zone create body. The slot id is `page__zone` (same split the
+* storefront preview uses, e.g. `checkout__below_total`) → `settings.page` +
+* `settings.zone`; height (px) → `settings.height`. Without a slot the zone
+* never renders, so the backend needs it to know WHERE to inject.
 */
-const updateCommand = new Command("update").description("Rename a mist, or attach/detach its droplet").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("--name <label>", "Set the display label").option("--hostable <ref>", "Attach a droplet: droplet:<uuid> (e.g. droplet:drp_abc123)").option("--detach", "Remove the droplet integration point").option("--json", "Emit raw API JSON").action((slug, opts) => runAction(async () => {
-	if (opts.hostable && opts.detach) throw new Error("Pass either `--hostable` OR `--detach`, not both — they're mutually exclusive.");
-	if (!opts.name && !opts.hostable && !opts.detach) throw new Error("Nothing to do — pass `--name`, `--hostable`, or `--detach`.");
-	const resolved = resolveSlug(slug);
-	const client = createMistClient();
-	const notes = [];
-	let renameResp;
-	if (opts.name?.trim()) {
-		renameResp = await updateMist(client, resolved, { mist: { name: opts.name.trim() } });
-		if (!opts.json) {
-			const m = renameResp.mist;
-			console.log(`${mistLabel(m.name, m.vendor_name)}  ${chalk.dim(m.slug)}  ${colorState(m.state)}`);
-		}
-	}
-	if (opts.hostable || opts.detach) {
-		const existing = findDropletIntegrationPoint((await listIntegrationPoints(client, resolved)).integration_points);
-		if (opts.hostable) {
-			const dropletUuid = parseDropletRef(opts.hostable);
-			if (existing && existing.integratable_uuid === dropletUuid) notes.push(`droplet ${dropletUuid} already attached (integration ${existing.id})`);
-			else {
-				if (existing) {
-					await deleteIntegrationPoint(client, resolved, existing.id);
-					notes.push(`replaced integration ${existing.id}`);
-				}
-				const ip = await createIntegrationPoint(client, resolved, {
-					kind: "droplet",
-					integratable_uuid: dropletUuid
-				});
-				notes.push(`attached droplet ${dropletUuid} (integration ${ip.integration_point.id})`);
-			}
-		} else if (opts.detach) if (existing) {
-			await deleteIntegrationPoint(client, resolved, existing.id);
-			notes.push(`detached droplet (removed integration ${existing.id})`);
-		} else notes.push("already standalone (no droplet integration)");
-	}
-	if (opts.json) return printJson(renameResp ? {
-		...renameResp,
-		slug: resolved,
-		notes
-	} : {
-		slug: resolved,
-		notes
-	});
-	for (const note of notes) console.log(chalk.dim(`  ${note}`));
-}));
+function buildDropZoneCreateInput(opts) {
+	const [page, zone] = (opts.zone ?? "").split("__");
+	const settings = {};
+	if (page) settings.page = page;
+	if (zone) settings.zone = zone;
+	if (opts.heightPx != null) settings.height = opts.heightPx;
+	const input = { name: opts.name };
+	if (opts.embedUrl) input.embed_url = opts.embedUrl;
+	if (Object.keys(settings).length > 0) input.settings = settings;
+	return input;
+}
+function createDropZone(client, body) {
+	return client.post(BASE$1, body);
+}
 //#endregion
-//#region src/commands/delete.ts
+//#region src/api/mobile_widgets.ts
+const BASE = "/api/company/mobile_widgets";
 /**
-* `fluid mist delete` — scheduled teardown 15 days out (spec §3 "15-day
-* grace period"). DO NOT poll for completion.
+* Build a mobile-widget create body. `cover_image_url` and `height` are
+* REQUIRED by the API (422 without them); we fall back to the Fluid
+* placeholder + default height when the caller doesn't supply them.
 */
-const deleteCommand = new Command("delete").description("Schedule a mist for destruction (15-day grace window)").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("-y, --yes", "Skip confirmation prompt").option("--json", "Emit raw API JSON").action((slug, opts) => runAction(async () => {
-	const resolved = resolveSlug(slug);
-	const client = createMistClient();
-	if (!opts.yes) {
-		const { mist } = await showMist(client, resolved);
-		const fifteenDaysOut = new Date(Date.now() + 15 * 864e5).toISOString().slice(0, 10);
-		console.log();
-		console.log(`About to schedule ${chalk.bold(mist.name ?? mist.vendor_name ?? mist.slug)} (${chalk.dim(mist.slug)}) for destruction on ${chalk.yellow(fifteenDaysOut)}.`);
-		console.log(chalk.dim(`Vendor resources stay alive until then; run \`fluid mist restore ${mist.slug}\` to undo.`));
-		const { confirmed } = await prompts({
-			type: "confirm",
-			name: "confirmed",
-			message: "Continue?",
-			initial: false
-		}, { onCancel: () => process.exit(130) });
-		if (!confirmed) {
-			console.log(chalk.dim("Aborted."));
-			process.exit(0);
-		}
-	}
-	const { mist } = await deleteMist(client, resolved);
-	if (opts.json) return printJson({ mist });
-	console.log(chalk.magenta(`Scheduled for destruction on ${mist.scheduled_destroy_at ? formatAbsolute(mist.scheduled_destroy_at) : "the 15-day mark"}.`));
-	console.log(chalk.dim(`Vendor resources stay alive until then; run \`fluid mist restore ${mist.slug}\` to undo.`));
-}));
-//#endregion
-//#region src/commands/restore.ts
-/** `fluid mist restore` — un-delete within the 15-day window. Spec §3. */
-const restoreCommand = new Command("restore").description("Cancel a scheduled mist destruction (15-day window)").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("--json", "Emit raw API JSON").action((slug, opts) => runAction(async () => {
-	const resolved = resolveSlug(slug);
-	const { mist } = await restoreMist(createMistClient(), resolved);
-	if (opts.json) return printJson({ mist });
-	console.log(`Restored: ${mist.public_url ? chalk.cyan(mist.public_url) : mist.name ?? mist.vendor_name ?? mist.slug} (${colorState(mist.state)})`);
-}));
+function buildMobileWidgetCreateInput(opts) {
+	return {
+		name: opts.name,
+		embed_url: opts.embedUrl,
+		cover_image_url: opts.coverImageUrl || "https://ik.imagekit.io/fluid/s3/app/image-placeholder.svg",
+		height: opts.heightPx ?? 600,
+		scrollable: true
+	};
+}
+function createMobileWidget(client, body) {
+	return client.post(BASE, body);
+}
 //#endregion
-//#region src/api/git_credential.ts
-async function createGitCredential(client, slug) {
+//#region src/api/env_vars.ts
+function path$1(id, key) {
+	return key ? `/api/v202604/mists/${id}/env_vars/${encodeURIComponent(key)}` : `/api/v202604/mists/${id}/env_vars`;
+}
+async function listEnvVars(client, slug) {
 	const id = await resolveMistId(client, slug);
-	return client.post(`/api/v202604/mists/${id}/git_credential`);
+	return client.get(path$1(id));
+}
+/** Create a new env var (the spec routes `set` to POST for new keys). */
+async function createEnvVar(client, slug, key, value, targets) {
+	const id = await resolveMistId(client, slug);
+	return client.post(path$1(id), { env_var: {
+		key,
+		value,
+		targets
+	} });
+}
+/** Update an existing env var (the spec routes `set` to PATCH for existing keys). */
+async function updateEnvVar(client, slug, key, value, targets) {
+	const id = await resolveMistId(client, slug);
+	return client.patch(path$1(id, key), { env_var: {
+		value,
+		targets
+	} });
+}
+async function deleteEnvVar(client, slug, key) {
+	const id = await resolveMistId(client, slug);
+	return client.delete(path$1(id, key));
 }
 //#endregion
-//#region src/lib/git.ts
+//#region src/types.ts
 /**
-* Git wrapper — shells out to system `git` via execa. Spec §11.1: we
-* deliberately do NOT bundle git or use a pure-JS impl; users are expected
-* to have it installed.
+* Managed env keys the backend writes onto a Mist once a droplet is
+* attached (backfill + redeploy). The CLI VERIFIES these appear with
+* `managed_by: "mist"` — it never sets them (the API 422s on write).
 *
-* Security: token-bearing `remote_url` from POST /git_credential must never
-* be logged, persisted, *or* exposed in the process table. The token is
-* stripped from the URL and handed to git through a GIT_ASKPASS script via
-* env vars (MIST_GIT_USER / MIST_GIT_PASS) — so it never appears in argv
-* (visible to `ps aux` on macOS, `/proc/<pid>/cmdline` on Linux) and is
-* never written to `.git/config`.
+* Source: settled backend contract (#19685 auto-provisions the droplet
+* env on integration-point create).
 */
-var GitError = class extends Error {
-	exitCode;
-	constructor(message, exitCode = 1) {
-		super(message);
-		this.name = "GitError";
-		this.exitCode = exitCode;
-	}
-};
+const MANAGED_DROPLET_ENV_KEYS = [
+	"FLUID_DROPLET_UUID",
+	"FLUID_DROPLET_SECRET",
+	"FLUID_WEBHOOK_AUTH_TOKEN"
+];
+//#endregion
+//#region src/lib/surface-provision.ts
 /**
-* Git author for Mist publish commits. Mist app repos are connected to the
-* we-commerce Vercel team via Vercel's GitHub integration, and Vercel
-* attributes a git-triggered deploy to the *commit author's* GitHub account.
-* If that author is a user's personal GitHub account (not a member of the
-* Vercel team), Vercel blocks the deployment ("… does not have a Vercel
-* account linked to their GitHub account"). Authoring every publish commit as
-* the Mist GitHub App bot — which the Vercel integration recognizes — keeps
-* deploys unblocked regardless of the user's local/global git identity. Human
-* attribution is preserved in the commit *message* (see push.ts), not the
-* author field.
+* Surface provisioning engine — the one place the "create a Fluid surface and
+* wire it to a mist" flow lives, at parity with Mist Desktop's
+* mist-integration-points-api.service.ts. Exposed via `fluid mist create`
+* (create a bare mist first, then run this), `fluid mist attach` (any kind),
+* and `fluid mist attach-droplet` (droplet shortcut).
 *
-* These MUST match the identity set on cloned repos in Mist Desktop
-* (apps/mist-desktop/src/main/ipc.ts) so both paths produce the same author.
+* Three surface kinds, each with its own create endpoint + attach identifier:
+*   - droplet     → POST /api/droplets              → drp_ uuid → integratable_uuid
+*   - drop-zone   → POST /api/drop_zones            → dz_  uuid → integratable_uuid
+*   - mobile-embed→ POST /api/company/mobile_widgets→ numeric id → integratable_id
+*
+* Design tenets (repo philosophy — "server is source of truth"):
+*   - No local progress file. State is re-derived from the API each run.
+*   - Attach-existing is idempotent: if an integration point already links the
+*     target surface (matched via the #19689 integratable_uuid echo, or the
+*     numeric id for mobile), skip. A droplet is 1-per-mist, so creating a new
+*     droplet also skips when one is already attached. Drop-zones/mobile
+*     embeds are additive (a mist can have many).
+*   - Only a droplet attach provisions managed env keys
+*     (FLUID_DROPLET_UUID/_SECRET/_WEBHOOK_AUTH_TOKEN); this flow only
+*     VERIFIES they landed — it never writes them (the API 422s on write).
+*   - A droplet must also be INSTALLED (POST /api/droplet_installations) —
+*     create + link alone leave it not-connected/inactive, so install-scoped
+*     features (dit/dex exchange, admin embeds, install webhooks) don't work.
+*     The install step is idempotent (skips when an installation exists).
 */
-const MIST_GIT_AUTHOR_NAME = "mist-we-commerce[bot]";
-const MIST_GIT_AUTHOR_EMAIL = "293596226+mist-we-commerce[bot]@users.noreply.github.com";
-/** execa throws ENOENT when the git binary itself is missing — the
-*  single most common failure on non-developer machines. Translate it
-*  into an actionable message instead of "git <verb> failed (exit 1)".
-*  Returns null for every other failure so call sites keep their
-*  specific messages. */
-function gitMissingError(err) {
-	if (err?.code !== "ENOENT") return null;
-	return new GitError("Git isn't installed on this machine. In Mist Desktop, use the Install button in the yellow banner at the top of the app. From a terminal: macOS `xcode-select --install`, or download from https://git-scm.com/downloads.", 127);
-}
+const DEFAULT_TIMING = {
+	publicUrlTimeoutMs: 9e4,
+	publicUrlIntervalMs: 3e3,
+	envTimeoutMs: 12e4,
+	envIntervalMs: 5e3
+};
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const KIND_LABEL$1 = {
+	droplet: "droplet",
+	"drop-zone": "drop zone",
+	"mobile-embed": "mobile embed"
+};
 /**
-* Split a token-bearing remote URL into the userless URL + creds. Used
-* to keep the token off git's argv: we pass `cleanUrl` to git and feed
-* `username` / `password` back through GIT_ASKPASS env vars.
-*
-* If the URL has no embedded credentials, returns empty strings — fine
-* for public repos where git won't even invoke askpass.
+* Create (or reuse) a surface of `kind` and wire it to the mist. Idempotent
+* for droplet + attach-existing; additive for new drop-zones/mobile embeds.
 */
-function splitRemoteCredentials(remoteUrl) {
-	const u = new URL(remoteUrl);
-	const username = decodeURIComponent(u.username);
-	const password = decodeURIComponent(u.password);
-	u.username = "";
-	u.password = "";
+async function provisionSurface(client, options) {
+	const { reporter, slugOrId, kind } = options;
+	const timing = {
+		...DEFAULT_TIMING,
+		...options.timing
+	};
+	const sleep = options.sleep ?? defaultSleep;
+	const label = KIND_LABEL$1[kind];
+	reporter.start("Resolving mist…");
+	const mist = (await showMist(client, slugOrId)).mist;
+	reporter.succeed(`Mist ${mist.slug} (${mist.state})`);
+	reporter.start("Checking existing integrations…");
+	const points = (await listIntegrationPoints(client, slugOrId)).integration_points;
+	let surfaceUuid = null;
+	let surfaceNumericId = null;
+	let surfaceName = null;
+	let surfaceCreated = false;
+	let embedUrlSet = false;
+	let integrationPoint;
+	const attachingExisting = options.existingUuid != null || options.existingId != null;
+	const alreadyLinked = attachingExisting ? findIntegrationPointBySurface(points, {
+		kind,
+		uuid: options.existingUuid,
+		id: options.existingId
+	}) : kind === "droplet" ? findDropletIntegrationPoint(points) : void 0;
+	if (alreadyLinked) {
+		reporter.skip(`${label} already attached (integration #${alreadyLinked.id}) — skipping`);
+		surfaceUuid = alreadyLinked.integratable_uuid ?? options.existingUuid ?? null;
+		surfaceNumericId = alreadyLinked.integratable_id ?? options.existingId ?? null;
+		integrationPoint = {
+			id: alreadyLinked.id,
+			integratableUuid: alreadyLinked.integratable_uuid ?? null,
+			created: false
+		};
+	} else {
+		reporter.succeed("No matching integration yet");
+		let attachUuid = options.existingUuid;
+		let attachId = options.existingId;
+		if (!attachingExisting) {
+			const embedUrl = await resolvePublicUrl(client, {
+				slugOrId,
+				initial: mist.public_url,
+				reporter,
+				timing,
+				sleep
+			});
+			const name = options.name?.trim() || mist.name?.trim() || mist.vendor_name || mist.slug;
+			reporter.start(`Creating ${label} "${name}"…`);
+			if (kind === "droplet") {
+				const created = await createDroplet(client, { droplet: buildDropletCreateInput({
+					name,
+					embedUrl,
+					requestedScopes: options.requestedScopes
+				}) });
+				surfaceUuid = created.droplet.uuid;
+				surfaceNumericId = created.droplet.id ?? null;
+				surfaceName = created.droplet.name;
+				attachUuid = created.droplet.uuid;
+				embedUrlSet = Boolean(embedUrl);
+				reporter.succeed(`Created droplet ${surfaceUuid}${embedUrl ? "" : " (embed URL pending)"}`);
+				if (!embedUrl && surfaceUuid) {
+					const laterUrl = await resolvePublicUrl(client, {
+						slugOrId,
+						initial: null,
+						reporter,
+						timing,
+						sleep
+					});
+					if (laterUrl) {
+						reporter.start("Backfilling droplet embed URL…");
+						await setDropletEmbedUrl(client, surfaceUuid, laterUrl);
+						embedUrlSet = true;
+						reporter.succeed("Embed URL set");
+					} else reporter.warn("Mist public_url not ready yet — re-run once the first deploy finishes to set the embed URL");
+				}
+			} else if (kind === "drop-zone") {
+				if (!embedUrl) throw new Error("The mist has no public_url yet — wait for the first deploy, then attach the drop zone.");
+				const created = await createDropZone(client, { drop_zone: buildDropZoneCreateInput({
+					name,
+					embedUrl,
+					zone: options.zone,
+					heightPx: options.heightPx
+				}) });
+				surfaceUuid = created.drop_zone.uuid;
+				surfaceName = created.drop_zone.name;
+				attachUuid = created.drop_zone.uuid;
+				embedUrlSet = true;
+				reporter.succeed(`Created drop zone ${surfaceUuid}`);
+			} else {
+				if (!embedUrl) throw new Error("The mist has no public_url yet — wait for the first deploy, then attach the mobile embed.");
+				const created = await createMobileWidget(client, { mobile_widget: buildMobileWidgetCreateInput({
+					name,
+					embedUrl,
+					coverImageUrl: options.coverImageUrl,
+					heightPx: options.heightPx
+				}) });
+				surfaceNumericId = created.mobile_widget.id;
+				surfaceName = created.mobile_widget.name;
+				attachId = created.mobile_widget.id;
+				embedUrlSet = true;
+				reporter.succeed(`Created mobile embed #${surfaceNumericId}`);
+			}
+			surfaceCreated = true;
+		} else {
+			surfaceUuid = options.existingUuid ?? null;
+			surfaceNumericId = options.existingId ?? null;
+			embedUrlSet = true;
+		}
+		const attachInput = kind === "mobile-embed" ? {
+			kind,
+			integratable_id: attachId
+		} : {
+			kind,
+			integratable_uuid: attachUuid
+		};
+		reporter.start(`Attaching ${label}…`);
+		let ipResp;
+		try {
+			ipResp = await createIntegrationPoint(client, slugOrId, attachInput);
+		} catch (err) {
+			reporter.fail("Attach failed");
+			throw normalizeAttachError(err, attachUuid ?? String(attachId), kind);
+		}
+		integrationPoint = {
+			id: ipResp.integration_point.id,
+			integratableUuid: ipResp.integration_point.integratable_uuid ?? null,
+			created: true
+		};
+		if (!surfaceUuid) surfaceUuid = ipResp.integration_point.integratable_uuid ?? attachUuid ?? null;
+		if (surfaceNumericId == null) surfaceNumericId = ipResp.integration_point.integratable_id ?? null;
+		reporter.succeed(kind === "droplet" ? "Droplet attached — provisioning env + redeploy…" : `${label} attached`);
+	}
+	let installation = null;
+	if (kind === "droplet") {
+		if (!surfaceUuid && surfaceNumericId != null) try {
+			surfaceUuid = await findDropletUuidByNumericId(client, surfaceNumericId);
+		} catch {}
+		if (!surfaceUuid) {
+			reporter.fail("Droplet uuid unknown — cannot install");
+			throw new Error("Couldn't determine the droplet uuid, so the droplet is linked but NOT installed — it stays inactive until an installation exists. Re-run with `--existing <droplet-uuid>`, or install manually: POST /api/droplet_installations with {\"droplet_uuid\":\"<uuid>\"}.");
+		}
+		installation = await ensureDropletInstalled(client, {
+			dropletUuid: surfaceUuid,
+			scopes: options.requestedScopes ?? DEFAULT_DROPLET_SCOPES,
+			reporter
+		});
+	}
+	const managedEnv = kind === "droplet" ? await verifyManagedEnv(client, {
+		slugOrId,
+		reporter,
+		timing,
+		sleep,
+		enabled: options.verifyEnv !== false
+	}) : null;
 	return {
-		cleanUrl: u.toString(),
-		username,
-		password
+		mist: {
+			id: mist.id,
+			slug: mist.slug,
+			name: mist.name,
+			public_url: mist.public_url,
+			state: mist.state
+		},
+		kind,
+		surface: {
+			uuid: surfaceUuid,
+			id: surfaceNumericId,
+			name: surfaceName
+		},
+		integrationPoint: integrationPoint ?? {
+			id: "",
+			integratableUuid: null,
+			created: false
+		},
+		surfaceCreated,
+		embedUrlSet,
+		installation,
+		managedEnv
 	};
 }
 /**
-* Write a stub GIT_ASKPASS shell script to a per-process tmpdir and
-* return its path. The script itself contains no secret — it just
-* echoes back whichever env var (MIST_GIT_USER / MIST_GIT_PASS)
-* matches git's prompt ("Username for …" / "Password for …"). The
-* credentials only live in the spawned git process's env for the
-* duration of the call.
-*
-* One POSIX script for all platforms: Git for Windows executes
-* GIT_ASKPASS through its bundled sh, so a .cmd askpass fails with
-* "unable to read askpass response" (git 2.52.0.windows.1) while a
-* plain sh script works.
-*
-* Idempotent: subsequent calls reuse the same script path.
-*/
-let askpassPath = null;
-function ensureAskpassScript() {
-	if (askpassPath && existsSync(askpassPath)) return askpassPath;
-	const dir = path.join(os.tmpdir(), `mist-cli-askpass-${process.pid}`);
-	if (!existsSync(dir)) mkdirSync(dir, {
-		recursive: true,
-		mode: 448
-	});
-	const p = path.join(dir, "askpass.sh");
-	writeFileSync(p, `#!/bin/sh\ncase "$1" in\n  Username*) printf '%s' "$MIST_GIT_USER" ;;\n  *) printf '%s' "$MIST_GIT_PASS" ;;\nesac\n`, { mode: 448 });
-	chmodSync(p, 448);
-	askpassPath = p;
-	return askpassPath;
-}
-/**
-* Build the spawn env + cleaned URL for a credentialed git invocation.
-* Returns:
-*   - `cleanUrl`: URL with userinfo stripped — safe to pass as argv.
-*   - `env`: parent env plus GIT_ASKPASS + MIST_GIT_USER / MIST_GIT_PASS.
-*            GIT_TERMINAL_PROMPT=0 prevents the TTY-prompt fallback if
-*            the credentials are empty (we want auth to fail fast, not
-*            hang the desktop waiting for interactive input).
+* Install the droplet for the current company (idempotent). Checks the
+* installations list first; treats the API's already-installed rejection as
+* success too, so re-runs and races both converge. A hard failure throws with
+* the droplet uuid + recovery steps — the created droplet and mist link stay
+* in place, so an idempotent re-run finishes the job.
 */
-function gitAuthSpawn(remoteUrl) {
-	const { cleanUrl, username, password } = splitRemoteCredentials(remoteUrl);
-	return {
-		cleanUrl,
-		env: {
-			...process.env,
-			GIT_ASKPASS: ensureAskpassScript(),
-			GIT_TERMINAL_PROMPT: "0",
-			MIST_GIT_USER: username,
-			MIST_GIT_PASS: password
+async function ensureDropletInstalled(client, args) {
+	const { reporter, dropletUuid } = args;
+	reporter.start("Installing droplet…");
+	let existing;
+	try {
+		existing = findInstallationForDroplet(await listAllDropletInstallations(client), dropletUuid);
+	} catch {}
+	if (existing) {
+		reporter.skip(`Droplet already installed${existing.uuid ? ` (${existing.uuid})` : ""} — skipping`);
+		return {
+			uuid: existing.uuid ?? null,
+			created: false
+		};
+	}
+	try {
+		const uuid = (await createDropletInstallation(client, {
+			droplet_uuid: dropletUuid,
+			scopes: [...args.scopes]
+		})).droplet_installation?.uuid ?? null;
+		reporter.succeed(`Droplet installed${uuid ? ` (${uuid})` : ""}`);
+		return {
+			uuid,
+			created: true
+		};
+	} catch (err) {
+		if (isAlreadyInstalledError(err)) {
+			const confirmed = await lookupInstallation(client, dropletUuid);
+			if (confirmed) {
+				reporter.skip("Droplet already installed — skipping");
+				return {
+					uuid: confirmed.uuid ?? null,
+					created: false
+				};
+			}
 		}
-	};
+		reporter.fail("Droplet install failed");
+		throw normalizeInstallError(err, dropletUuid);
+	}
 }
-/** Confirm git is installed. Cheap call once at startup. */
-async function ensureGitAvailable() {
+function isAlreadyInstalledError(err) {
+	return err instanceof MistApiError && (err.status === 409 || err.status === 422) && /already|taken|installed|exists/i.test(`${err.message} ${JSON.stringify(err.details ?? {})}`);
+}
+/** Best-effort installation lookup for a droplet; null when the row can't
+*  be found or the list call fails. */
+async function lookupInstallation(client, dropletUuid) {
 	try {
-		await execa("git", ["--version"]);
+		return findInstallationForDroplet(await listAllDropletInstallations(client), dropletUuid) ?? null;
 	} catch {
-		throw new GitError("`git` is required but not found on your PATH. Install it from https://git-scm.com/downloads or via `brew install git`.");
+		return null;
 	}
 }
 /**
-* `git clone <cleanUrl> <targetDir>`. The original remoteUrl carries a
-* token; gitAuthSpawn strips it from the URL and re-injects it via
-* GIT_ASKPASS so it never appears in argv. `credential.helper=` stops
-* git from caching what askpass returned to any system credential
-* store.
+* Install failures must NOT read as "wired up" — an uninstalled droplet means
+* dit/dex token exchange, admin embeds, and install webhooks silently don't
+* work. Surface the droplet uuid + recovery path; keep the MistApiError
+* status so the error handler exits with the spec'd non-zero code.
 */
-async function gitClone(remoteUrl, targetDir) {
-	const { cleanUrl, env } = gitAuthSpawn(remoteUrl);
-	try {
-		await execa("git", [
-			"-c",
-			"credential.helper=",
-			"clone",
-			"--quiet",
-			cleanUrl,
-			targetDir
-		], {
-			env,
-			stdio: [
-				"ignore",
-				"inherit",
-				"inherit"
-			]
-		});
-	} catch (err) {
-		const missing = gitMissingError(err);
-		if (missing) throw missing;
-		const e = err;
-		throw new GitError(`git clone failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
-	}
-	await ensureBotIdentity(targetDir);
+function normalizeInstallError(err, dropletUuid) {
+	const message = `Droplet ${dropletUuid} was created and linked to the mist, but installing it failed: ${err instanceof Error ? err.message : String(err)}. The droplet and its link were left in place — re-run this command to finish the install, or install manually: POST /api/droplet_installations with {"droplet_uuid":"${dropletUuid}"}.`;
+	return err instanceof MistApiError ? new MistApiError(message, err.status, err.details) : new Error(message);
 }
-/** `git push origin <branch>` — credentials supplied via GIT_ASKPASS,
-*  never in argv. The `.extraheader=` override clears any cached
-*  Authorization header that a CI-style git config might inject. */
-async function gitPush(cwd, remoteUrl, branch = "main") {
-	const { cleanUrl, env } = gitAuthSpawn(remoteUrl);
-	try {
-		await execa("git", [
-			"-c",
-			"credential.helper=",
-			"-c",
-			`http.https://github.com/.extraheader=`,
-			"push",
-			cleanUrl,
-			`HEAD:${branch}`
-		], {
-			cwd,
-			env,
-			stdio: [
-				"ignore",
-				"inherit",
-				"inherit"
-			]
-		});
-	} catch (err) {
-		const missing = gitMissingError(err);
-		if (missing) throw missing;
-		const e = err;
-		throw new GitError(`git push failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
+/**
+* If the integration-points endpoint rejects the attach identifier (e.g. an
+* older API that predates #19688's attach-by-uuid support), surface an
+* actionable message noting the surface WAS created. Other errors pass through.
+*/
+function normalizeAttachError(err, surfaceRef, kind) {
+	if (err instanceof MistApiError && (err.status === 400 || err.status === 422)) {
+		const blob = `${err.message} ${JSON.stringify(err.details ?? {})}`;
+		if (/integratable_uuid|integratable_id|unpermitted|unknown|param/i.test(blob)) return new MistApiError(`The ${KIND_LABEL$1[kind]} ${surfaceRef} was created, but this API rejected the attach (needs the #19688 integration-points endpoint). Re-run once the API is updated.`, err.status, err.details);
 	}
+	return err instanceof Error ? err : new Error(String(err));
 }
-/** `git pull origin <branch>`. Token supplied via GIT_ASKPASS, same as push. */
-async function gitPull(cwd, remoteUrl, branch = "main") {
-	const { cleanUrl, env } = gitAuthSpawn(remoteUrl);
-	try {
-		await execa("git", [
-			"-c",
-			"credential.helper=",
-			"pull",
-			"--ff-only",
-			cleanUrl,
-			branch
-		], {
-			cwd,
-			env,
-			stdio: [
-				"ignore",
-				"inherit",
-				"inherit"
-			]
-		});
-	} catch (err) {
-		const missing = gitMissingError(err);
-		if (missing) throw missing;
-		const e = err;
-		throw new GitError(`git pull failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
+/**
+* Return the mist's public_url, polling briefly if it isn't ready yet
+* (async-first-deploy). Returns null if it never appears within the window.
+*/
+async function resolvePublicUrl(client, args) {
+	if (args.initial) return args.initial;
+	args.reporter.start("Waiting for the mist's public URL…");
+	const deadline = Date.now() + args.timing.publicUrlTimeoutMs;
+	for (;;) {
+		const url = (await showMist(client, args.slugOrId)).mist.public_url;
+		if (url) {
+			args.reporter.succeed(`Public URL ready: ${url}`);
+			return url;
+		}
+		if (Date.now() >= deadline) break;
+		await args.sleep(args.timing.publicUrlIntervalMs);
 	}
+	return null;
 }
 /**
-* Are there uncommitted changes (working tree or index) in this repo?
-* `git status --porcelain` is empty when everything is clean, non-empty
-* otherwise — so the count is just "is the output non-trivial".
+* Poll `GET …/env_vars` until the Mist-managed droplet keys appear with
+* `managed_by: "mist"`. Never fails the flow — a redeploy in progress is a
+* normal, transient state we simply report.
 */
-async function hasUncommittedChanges(cwd) {
-	try {
-		const { stdout } = await execa("git", ["status", "--porcelain"], { cwd });
-		return stdout.trim().length > 0;
-	} catch {
-		return false;
+async function verifyManagedEnv(client, args) {
+	const required = [...MANAGED_DROPLET_ENV_KEYS];
+	if (!args.enabled) return {
+		ready: false,
+		present: [],
+		missing: required
+	};
+	args.reporter.start("Verifying managed environment…");
+	const deadline = Date.now() + args.timing.envTimeoutMs;
+	let present = [];
+	for (;;) {
+		const envVars = (await listEnvVars(client, args.slugOrId)).env_vars ?? [];
+		const managed = new Set(envVars.filter((e) => e.managed_by === "mist").map((e) => e.key));
+		present = required.filter((k) => managed.has(k));
+		if (present.length === required.length) {
+			args.reporter.succeed("Managed env keys present — droplet is wired up");
+			return {
+				ready: true,
+				present,
+				missing: []
+			};
+		}
+		if (Date.now() >= deadline) break;
+		args.reporter.update(`Verifying managed environment… (${present.length}/${required.length} keys, redeploy in progress)`);
+		await args.sleep(args.timing.envIntervalMs);
 	}
+	const missing = required.filter((k) => !present.includes(k));
+	args.reporter.warn(`Redeploy in progress — managed keys not visible yet (${present.length}/${required.length}). Check later with \`fluid mist env list\`. Missing: ${missing.join(", ")}`);
+	return {
+		ready: false,
+		present,
+		missing
+	};
 }
-/**
-* Fetch the given branch from the token-bearing remote URL, writing
-* `FETCH_HEAD` so `git rev-list HEAD...FETCH_HEAD` is meaningful.
-*
-* Same security stance as gitPush — installation token comes through
-* GIT_ASKPASS, never argv or `.git/config`.
-*/
-async function gitFetch(cwd, remoteUrl, branch = "main") {
-	const { cleanUrl, env } = gitAuthSpawn(remoteUrl);
-	try {
-		await execa("git", [
-			"-c",
-			"credential.helper=",
-			"fetch",
-			"--quiet",
-			cleanUrl,
-			branch
-		], {
-			cwd,
-			env
-		});
-	} catch (err) {
-		const missing = gitMissingError(err);
-		if (missing) throw missing;
-		const e = err;
-		throw new GitError(`git fetch failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
-	}
+//#endregion
+//#region src/lib/surface-flags.ts
+const KIND_ALIASES = {
+	droplet: "droplet",
+	droplets: "droplet",
+	"drop-zone": "drop-zone",
+	drop_zone: "drop-zone",
+	dropzone: "drop-zone",
+	zone: "drop-zone",
+	"mobile-embed": "mobile-embed",
+	mobile_embed: "mobile-embed",
+	mobile: "mobile-embed",
+	"mobile-widget": "mobile-embed",
+	mobilewidget: "mobile-embed"
+};
+const SURFACE_KIND_LIST = "droplet, drop-zone, mobile-embed";
+function parseSurfaceKind(raw) {
+	const hit = KIND_ALIASES[raw.trim().toLowerCase()];
+	if (!hit) throw new Error(`Unknown surface kind "${raw}". Use one of: ${SURFACE_KIND_LIST}.`);
+	return hit;
+}
+function parseHeight(raw) {
+	if (raw == null) return void 0;
+	const n = Number(raw);
+	if (!Number.isInteger(n) || n <= 0) throw new Error(`Invalid --height "${raw}". Must be a positive integer (px).`);
+	return n;
 }
 /**
-* Count commits in local HEAD vs `FETCH_HEAD` (after `gitFetch`). Returns
-* `{ahead, behind}`: how many commits HEAD has that the remote doesn't,
-* and vice versa. A `0/0` result means "in sync".
+* Map CLI flags to the kind-specific `provisionSurface` options, enforcing the
+* per-kind requirements the API needs:
+*  - drop-zone requires `--zone <page__zone>` (else it never renders).
+*  - mobile-embed requires `--cover-image <url>` (the API 422s without one; the
+*    CLI has no DAM picker, so the user must supply a url).
 */
-async function gitAheadBehindVsFetchHead(cwd) {
-	try {
-		const { stdout } = await execa("git", [
-			"rev-list",
-			"--left-right",
-			"--count",
-			"HEAD...FETCH_HEAD"
-		], { cwd });
-		const [a, b] = stdout.trim().split(/\s+/);
-		const ahead = Number.parseInt(a ?? "0", 10);
-		const behind = Number.parseInt(b ?? "0", 10);
+function surfaceProvisionOptionsFromFlags(kind, flags) {
+	const heightPx = parseHeight(flags.height);
+	if (kind === "drop-zone") {
+		if (!flags.zone?.trim()) throw new Error("A drop-zone needs a slot — pass `--zone <page__zone>` (e.g. --zone checkout__below_total).");
 		return {
-			ahead: Number.isFinite(ahead) ? ahead : 0,
-			behind: Number.isFinite(behind) ? behind : 0
+			zone: flags.zone.trim(),
+			heightPx
 		};
-	} catch {
+	}
+	if (kind === "mobile-embed") {
+		if (!flags.coverImage?.trim()) throw new Error("A mobile-embed needs a cover image — pass `--cover-image <url>` (the mobile API requires one; the CLI has no image picker).");
 		return {
-			ahead: 0,
-			behind: 0
+			coverImageUrl: flags.coverImage.trim(),
+			heightPx
 		};
 	}
+	return {};
 }
-/** Fast-forward `HEAD` to `FETCH_HEAD`. Fails (non-zero exit) if not
-*  fast-forwardable — caller must check ahead-count first. */
-async function gitMergeFastForward(cwd) {
-	try {
-		await execa("git", [
-			"merge",
-			"--ff-only",
-			"FETCH_HEAD"
-		], { cwd });
-	} catch (err) {
-		const missing = gitMissingError(err);
-		if (missing) throw missing;
-		const e = err;
-		throw new GitError(`git fast-forward merge failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
+//#endregion
+//#region src/lib/surface-summary.ts
+/** Shared human-readable summary for a surface provision result. */
+const KIND_LABEL = {
+	droplet: "droplet",
+	"drop-zone": "drop zone",
+	"mobile-embed": "mobile embed"
+};
+function printSurfaceSummary(result) {
+	const ref = result.surface.uuid ?? (result.surface.id != null ? `#${result.surface.id}` : "(unknown)");
+	const state = result.surfaceCreated ? "created" : "existing";
+	console.log(chalk.dim(`  ${KIND_LABEL[result.kind]}: ${ref} (${state}) · integration ${result.integrationPoint.id}`));
+	if (result.kind === "droplet" && result.installation) {
+		const ref = result.installation.uuid ?? "(uuid unknown)";
+		console.log(chalk.dim(`  installation: ${ref} (${result.installation.created ? "installed" : "already installed"})`));
 	}
+	if (result.kind === "droplet" && result.managedEnv) if (result.managedEnv.ready) console.log(chalk.dim("  env: managed keys provisioned ✓"));
+	else console.log(chalk.yellow("  env: redeploy in progress — run `fluid mist env list` shortly to confirm managed keys"));
 }
+//#endregion
+//#region src/commands/create.ts
 /**
-* Stash working-tree + untracked changes with a Mist-tagged message.
-* Returns the stash ref (`stash@{0}`) we created. Callers should pair
-* this with `gitStashPop` after the dangerous step is done.
+* `fluid mist create` — provision a new mist, optionally creating and attaching
+* a surface in one step. All attach paths go through integration points
+* (hostable is retired — #19684/#19687).
+*
+*   --droplet [name]           Create a NEW droplet and attach it. Bare →
+*                              droplet name defaults to the mist name. The
+*                              "one command that sets everything up" path.
+*   --kind <kind> [flags]      Create + attach a surface of any kind:
+*                              droplet | drop-zone | mobile-embed. Kind flags:
+*                                drop-zone   --zone <page__zone> --height <px>
+*                                mobile-embed --cover-image <url> --height <px>
+*   --hostable droplet:<uuid>  Attach an EXISTING droplet by its drp_… uuid.
+*
+* With none of these, creates a plain standalone mist.
 */
-async function gitStash(cwd, message) {
+const createCommand = new Command("create").description("Provision a new mist (optionally create + attach a surface in one step)").option("--droplet [name]", "Create a droplet and attach it. Bare uses the mist name; pass a value to override.").option("--kind <kind>", "Create + attach a surface: droplet | drop-zone | mobile-embed").option("--hostable <ref>", "Attach an existing droplet by uuid: droplet:<uuid> (e.g. droplet:drp_abc123)").option("--name <label>", "Display label for the mist (and the surface)").option("--zone <slot>", "drop-zone slot id: page__zone (e.g. checkout__below_total)").option("--height <px>", "Embed height in px (drop-zone + mobile-embed)").option("--cover-image <url>", "Mobile-embed cover image url (required for mobile-embed)").option("--mist-kind <kind>", "Mist kind (default: next_app)").option("--no-wait", "Don't wait for managed env keys to appear after attach").option("--json", "Emit raw JSON").action((opts) => runAction(async () => {
+	const wantDroplet = opts.droplet !== void 0;
+	const wantKind = !!opts.kind;
+	const wantHostable = !!opts.hostable;
+	if ([
+		wantDroplet,
+		wantKind,
+		wantHostable
+	].filter(Boolean).length > 1) throw new Error("Pass only one of `--droplet`, `--kind`, or `--hostable` — they're mutually exclusive.");
+	let kind;
+	let existingDropletUuid;
+	let nameOverride;
+	if (wantDroplet) {
+		kind = "droplet";
+		nameOverride = typeof opts.droplet === "string" ? opts.droplet.trim() : void 0;
+	} else if (wantKind) kind = parseSurfaceKind(opts.kind);
+	else if (wantHostable) {
+		kind = "droplet";
+		existingDropletUuid = parseDropletRef(opts.hostable);
+	}
+	const mistBody = { kind: opts.mistKind ?? "next_app" };
+	if (opts.name?.trim()) mistBody.name = opts.name.trim();
+	const client = createMistClient();
+	const reporter = opts.json ? createSilentReporter() : createOraReporter();
+	reporter.start("Setting up your Mist Cloud environment…");
+	let created;
 	try {
-		await execa("git", [
-			"stash",
-			"push",
-			"--include-untracked",
-			"--message",
-			message
-		], { cwd });
+		created = await createMist(client, { mist: mistBody });
 	} catch (err) {
-		const missing = gitMissingError(err);
-		if (missing) throw missing;
-		throw new GitError(`git stash push failed`, err.exitCode ?? 1);
+		reporter.fail("Provisioning failed");
+		throw err;
 	}
-}
+	const mist = created.mist;
+	reporter.succeed(`Provisioned ${mist.slug}`);
+	let provision;
+	if (kind) provision = await provisionSurface(client, {
+		slugOrId: mist.slug,
+		kind,
+		name: nameOverride ?? opts.name?.trim(),
+		existingUuid: existingDropletUuid,
+		verifyEnv: opts.wait !== false,
+		reporter,
+		...surfaceProvisionOptionsFromFlags(kind, opts)
+	});
+	if (opts.json) return printJson(provision ? {
+		mist,
+		provision
+	} : created);
+	const label = mistLabel(mist.name, mist.vendor_name);
+	console.log();
+	console.log(`${label}  ${chalk.dim(mist.slug)}  ${colorState(mist.state)}`);
+	if (mist.public_url) console.log(`  ${chalk.cyan(mist.public_url)}`);
+	if (provision) printSurfaceSummary(provision);
+	console.log();
+	console.log(chalk.dim(`Clone with: fluid mist clone ${mist.slug}`));
+}));
+//#endregion
+//#region src/commands/attach.ts
 /**
-* Pop the most recent stash. Throws on conflict so callers can surface
-* the situation (the working tree will have conflict markers; the user
-* needs to resolve manually).
+* `fluid mist attach --kind <kind> [flags] [slug]` — create a surface and wire
+* it to an existing mist. One command for all three kinds:
+*
+*   --kind droplet                       (managed-env-provisioning droplet)
+*   --kind drop-zone --zone page__zone   [--height <px>]
+*   --kind mobile-embed --cover-image <url> [--height <px>]
+*
+* Attach an EXISTING surface instead of creating one with `--existing <ref>`:
+*   droplet/drop-zone → droplet:drp_… / drop-zone:dz_… / bare uuid
+*   mobile-embed      → mobile-embed:<numericId>
+*
+* Idempotent for droplet + attach-existing (skips when already linked).
 */
-async function gitStashPop(cwd) {
-	try {
-		await execa("git", ["stash", "pop"], { cwd });
-	} catch (err) {
-		const missing = gitMissingError(err);
-		if (missing) throw missing;
-		throw new GitError(`Couldn't restore your local changes after pulling — the file edits collided with a teammate's. Run \`git stash list\` and resolve manually.`, err.exitCode ?? 1);
+/** Parse `--existing <ref>` into a uuid or numeric id for the given kind. */
+function parseExisting(kind, raw) {
+	const trimmed = (raw.includes(":") ? raw.slice(raw.lastIndexOf(":") + 1) : raw).trim();
+	if (!trimmed) throw new Error(`Empty --existing reference "${raw}".`);
+	if (kind === "mobile-embed") {
+		const id = Number(trimmed);
+		if (!Number.isInteger(id) || id <= 0) throw new Error(`mobile-embed attaches by numeric id — pass \`--existing <id>\` (got "${raw}").`);
+		return { existingId: id };
 	}
+	return { existingUuid: trimmed };
 }
+const attachCommand = new Command("attach").description(`Create a surface (${SURFACE_KIND_LIST}) and wire it to an existing mist`).argument("[slug]", "Mist slug (defaults to the .mist file in CWD)").requiredOption("--kind <kind>", `Surface kind: ${SURFACE_KIND_LIST}`).option("--name <label>", "Surface name (defaults to the mist's name)").option("--zone <slot>", "drop-zone slot id: page__zone (e.g. checkout__below_total)").option("--height <px>", "Embed height in px (drop-zone + mobile-embed)").option("--cover-image <url>", "Mobile-embed cover image url (required for mobile-embed)").option("--existing <ref>", "Attach an existing surface instead of creating one (uuid, or numeric id for mobile-embed)").option("--no-wait", "Don't wait for managed env keys to appear after attach").option("--json", "Emit raw JSON").action((slug, opts) => runAction(async () => {
+	const kind = parseSurfaceKind(opts.kind);
+	const resolved = resolveSlug(slug);
+	const client = createMistClient();
+	const reporter = opts.json ? createSilentReporter() : createOraReporter();
+	const existing = opts.existing ? parseExisting(kind, opts.existing) : void 0;
+	const result = await provisionSurface(client, {
+		slugOrId: resolved,
+		kind,
+		name: opts.name?.trim(),
+		verifyEnv: opts.wait !== false,
+		reporter,
+		...existing,
+		...existing ? {} : surfaceProvisionOptionsFromFlags(kind, opts)
+	});
+	if (opts.json) return printJson(result);
+	console.log();
+	console.log(`${chalk.bold(result.mist.name ?? result.mist.slug)}  ${chalk.dim(result.mist.slug)}`);
+	printSurfaceSummary(result);
+}));
+//#endregion
+//#region src/commands/attach-droplet.ts
 /**
-* Persist the Mist bot as the repo's LOCAL git identity
-* (`git config --local user.{name,email}`).
-*
-* `gitAutoCommit` already forces the bot author on the publish commit
-* via `-c`/env, but that only covers commits WE make. Commits made any
-* other way against the same checkout — the Mist chat agent shelling out
-* `git commit` via run_cli, or the user in a terminal — inherit the
-* repo's configured identity, which is the person's personal GitHub
-* account. Vercel rejects a deploy whose commit author isn't a
-* we-commerce team member, so those personal-authored commits silently
-* block the deploy (exactly the www-* "stuck project" case).
+* `fluid mist attach-droplet [name] [slug]` — droplet shortcut for
+* `fluid mist attach --kind droplet`. Creates a droplet and wires it to an
+* existing standalone mist (provisioning the managed env). Idempotent: if a
+* droplet is already attached, it skips create + attach and just verifies env.
 *
-* Setting the identity at the repo level makes EVERY commit path
-* bot-authored, and heals repos cloned before this was in place on their
-* next publish. Best-effort: a config failure must never abort a push —
-* the publish commit is still bot-forced by gitAutoCommit regardless.
+*   name   Optional droplet name (defaults to the mist's name).
+*   slug   Optional mist slug (defaults to the `.mist` file in CWD).
 */
-async function ensureBotIdentity(cwd) {
-	try {
-		await execa("git", [
-			"config",
-			"--local",
-			"user.name",
-			MIST_GIT_AUTHOR_NAME
-		], { cwd });
-		await execa("git", [
-			"config",
-			"--local",
-			"user.email",
-			MIST_GIT_AUTHOR_EMAIL
-		], { cwd });
-	} catch {}
-}
+const attachDropletCommand = new Command("attach-droplet").description("Create a droplet and wire it to an existing standalone mist (idempotent)").argument("[name]", "Droplet name (defaults to the mist's name)").argument("[slug]", "Mist slug (defaults to the .mist file in CWD)").option("--no-wait", "Don't wait for managed env keys to appear after attach").option("--json", "Emit raw JSON").action((name, slug, opts) => runAction(async () => {
+	const resolved = resolveSlug(slug);
+	const client = createMistClient();
+	const reporter = opts.json ? createSilentReporter() : createOraReporter();
+	const result = await provisionSurface(client, {
+		slugOrId: resolved,
+		kind: "droplet",
+		name: name?.trim() || void 0,
+		verifyEnv: opts.wait !== false,
+		reporter
+	});
+	if (opts.json) return printJson(result);
+	console.log();
+	console.log(`${chalk.bold(result.mist.name ?? result.mist.slug)}  ${chalk.dim(result.mist.slug)}`);
+	printSurfaceSummary(result);
+}));
+//#endregion
+//#region src/commands/update.ts
 /**
-* `git add -A && git commit -m <message>` in `cwd`.
+* `fluid mist update` — mutate an existing mist. Hostable is retired
+* (#19684/#19687), so attach/detach operate on integration points:
 *
-* Mist Desktop's "Publish" UX target is non-technical: the user expects
-* "ship my changes" to ship the changes they made, not to know about
-* staging or commit messages. This helper bundles working-tree edits
-* into one commit per publish so push has something to send.
+*   --name <label>            Rename the mist (PATCH /mists/:id).
+*   --hostable droplet:<uuid> Attach a droplet by uuid. No-ops if that same
+*                             droplet is already attached; replaces it if a
+*                             different droplet is attached (droplet is
+*                             1-per-mist — it provisions the managed env).
+*   --detach                  Remove the droplet integration point.
 *
-* The commit author is ALWAYS forced to the Mist GitHub App bot identity
-* (MIST_GIT_AUTHOR_*), overriding whatever local/global git identity the
-* machine has. This is what keeps Vercel from blocking the deploy: a commit
-* authored by a user's personal GitHub account that isn't a we-commerce Vercel
-* team member gets rejected. Passing `-c user.name=… -c user.email=…` beats
-* even a `--local` config, so every publish is bot-authored regardless of how
-* the repo landed on disk (fresh clone, pre-existing clone, or terminal CLI).
-* The real person is still recorded in the commit *message* (see push.ts).
+* The integration-point link is immutable (no update route, no `active`
+* field) — enablement lives on the surface record, so there's no toggle here.
+* All ops re-derive state from the integration-points index (which echoes
+* `integratable_uuid` since #19689) and only make the calls that change it.
 */
-async function gitAutoCommit(cwd, message) {
-	await ensureBotIdentity(cwd);
-	try {
-		await execa("git", ["add", "-A"], { cwd });
-	} catch (err) {
-		const missing = gitMissingError(err);
-		if (missing) throw missing;
-		throw new GitError(`git add failed`, err.exitCode ?? 1);
+const updateCommand = new Command("update").description("Rename a mist, or attach/detach its droplet").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("--name <label>", "Set the display label").option("--hostable <ref>", "Attach a droplet: droplet:<uuid> (e.g. droplet:drp_abc123)").option("--detach", "Remove the droplet integration point").option("--json", "Emit raw API JSON").action((slug, opts) => runAction(async () => {
+	if (opts.hostable && opts.detach) throw new Error("Pass either `--hostable` OR `--detach`, not both — they're mutually exclusive.");
+	if (!opts.name && !opts.hostable && !opts.detach) throw new Error("Nothing to do — pass `--name`, `--hostable`, or `--detach`.");
+	const resolved = resolveSlug(slug);
+	const client = createMistClient();
+	const notes = [];
+	let renameResp;
+	if (opts.name?.trim()) {
+		renameResp = await updateMist(client, resolved, { mist: { name: opts.name.trim() } });
+		if (!opts.json) {
+			const m = renameResp.mist;
+			console.log(`${mistLabel(m.name, m.vendor_name)}  ${chalk.dim(m.slug)}  ${colorState(m.state)}`);
+		}
 	}
-	const identityArgs = [
-		"-c",
-		`user.name=${MIST_GIT_AUTHOR_NAME}`,
-		"-c",
-		`user.email=${MIST_GIT_AUTHOR_EMAIL}`
-	];
-	const identityEnv = {
-		GIT_AUTHOR_NAME: MIST_GIT_AUTHOR_NAME,
-		GIT_AUTHOR_EMAIL: MIST_GIT_AUTHOR_EMAIL,
-		GIT_COMMITTER_NAME: MIST_GIT_AUTHOR_NAME,
-		GIT_COMMITTER_EMAIL: MIST_GIT_AUTHOR_EMAIL
-	};
-	try {
-		await execa("git", [
-			...identityArgs,
-			"commit",
-			"-m",
-			message
-		], {
-			cwd,
-			env: {
-				...process.env,
-				...identityEnv
-			},
-			stdio: [
-				"ignore",
-				"inherit",
-				"inherit"
-			]
-		});
-	} catch (err) {
-		const missing = gitMissingError(err);
-		if (missing) throw missing;
-		const e = err;
-		if (typeof e.stderr === "string" && /nothing to commit/i.test(e.stderr)) return;
-		throw new GitError(`git commit failed${e.exitCode != null ? ` (exit ${e.exitCode})` : ""}`, e.exitCode ?? 1);
+	if (opts.hostable || opts.detach) {
+		const existing = findDropletIntegrationPoint((await listIntegrationPoints(client, resolved)).integration_points);
+		if (opts.hostable) {
+			const dropletUuid = parseDropletRef(opts.hostable);
+			if (existing && existing.integratable_uuid === dropletUuid) notes.push(`droplet ${dropletUuid} already attached (integration ${existing.id})`);
+			else {
+				if (existing) {
+					await deleteIntegrationPoint(client, resolved, existing.id);
+					notes.push(`replaced integration ${existing.id}`);
+				}
+				const ip = await createIntegrationPoint(client, resolved, {
+					kind: "droplet",
+					integratable_uuid: dropletUuid
+				});
+				notes.push(`attached droplet ${dropletUuid} (integration ${ip.integration_point.id})`);
+			}
+		} else if (opts.detach) if (existing) {
+			await deleteIntegrationPoint(client, resolved, existing.id);
+			notes.push(`detached droplet (removed integration ${existing.id})`);
+		} else notes.push("already standalone (no droplet integration)");
+	}
+	if (opts.json) return printJson(renameResp ? {
+		...renameResp,
+		slug: resolved,
+		notes
+	} : {
+		slug: resolved,
+		notes
+	});
+	for (const note of notes) console.log(chalk.dim(`  ${note}`));
+}));
+//#endregion
+//#region src/commands/delete.ts
+/**
+* `fluid mist delete` — scheduled teardown 15 days out (spec §3 "15-day
+* grace period"). DO NOT poll for completion.
+*/
+const deleteCommand = new Command("delete").description("Schedule a mist for destruction (15-day grace window)").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("-y, --yes", "Skip confirmation prompt").option("--json", "Emit raw API JSON").action((slug, opts) => runAction(async () => {
+	const resolved = resolveSlug(slug);
+	const client = createMistClient();
+	if (!opts.yes) {
+		const { mist } = await showMist(client, resolved);
+		const fifteenDaysOut = new Date(Date.now() + 15 * 864e5).toISOString().slice(0, 10);
+		console.log();
+		console.log(`About to schedule ${chalk.bold(mist.name ?? mist.vendor_name ?? mist.slug)} (${chalk.dim(mist.slug)}) for destruction on ${chalk.yellow(fifteenDaysOut)}.`);
+		console.log(chalk.dim(`Vendor resources stay alive until then; run \`fluid mist restore ${mist.slug}\` to undo.`));
+		const { confirmed } = await prompts({
+			type: "confirm",
+			name: "confirmed",
+			message: "Continue?",
+			initial: false
+		}, { onCancel: () => process.exit(130) });
+		if (!confirmed) {
+			console.log(chalk.dim("Aborted."));
+			process.exit(0);
+		}
 	}
+	const { mist } = await deleteMist(client, resolved);
+	if (opts.json) return printJson({ mist });
+	console.log(chalk.magenta(`Scheduled for destruction on ${mist.scheduled_destroy_at ? formatAbsolute(mist.scheduled_destroy_at) : "the 15-day mark"}.`));
+	console.log(chalk.dim(`Vendor resources stay alive until then; run \`fluid mist restore ${mist.slug}\` to undo.`));
+}));
+//#endregion
+//#region src/commands/restore.ts
+/** `fluid mist restore` — un-delete within the 15-day window. Spec §3. */
+const restoreCommand = new Command("restore").description("Cancel a scheduled mist destruction (15-day window)").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("--json", "Emit raw API JSON").action((slug, opts) => runAction(async () => {
+	const resolved = resolveSlug(slug);
+	const { mist } = await restoreMist(createMistClient(), resolved);
+	if (opts.json) return printJson({ mist });
+	console.log(`Restored: ${mist.public_url ? chalk.cyan(mist.public_url) : mist.name ?? mist.vendor_name ?? mist.slug} (${colorState(mist.state)})`);
+}));
+//#endregion
+//#region src/api/git_credential.ts
+async function createGitCredential(client, slug) {
+	const id = await resolveMistId(client, slug);
+	return client.post(`/api/v202604/mists/${id}/git_credential`);
 }
 //#endregion
 //#region src/commands/clone.ts
@@ -2035,12 +2268,67 @@ const logsCommand = new Command("logs").description("Fetch deployment logs (use
 	}
 }));
 //#endregion
+//#region src/lib/encrypted-env.ts
+/**
+* Detects Vercel-encrypted env var ciphertext.
+*
+* `GET /api/v202604/mists/:id/env_vars` is a thin proxy to the Mist's
+* Vercel project env — it returns values ENCRYPTED, never plaintext (see
+* apps/mist-desktop/src/main/services/mist-env-vars.service.ts:25-28,
+* which documents the same server behavior for the desktop app's copy of
+* this API). The ciphertext is a base64-encoded JSON envelope of shape
+* `{"v":"v2","c":"<base64 ciphertext>","k":[<byte array>]}`.
+*
+* `fluid mist env pull` uses this to avoid writing that ciphertext into
+* `.env.local` as if it were a usable value.
+*/
+const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+function looksLikeBase64(value) {
+	return value.length > 0 && value.length % 4 === 0 && BASE64_RE.test(value);
+}
+function hasEncryptedEnvelopeShape(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && "v" in value && "c" in value && "k" in value;
+}
+/**
+* True when `value` is the Vercel encrypted-env envelope: a base64 string
+* that decodes to a JSON object with the `{ v, c, k }` shape. Returns
+* false for empty strings, non-base64 strings, and base64 strings that
+* decode to plaintext or to JSON that doesn't match the envelope shape —
+* so real plaintext secrets that happen to look like base64 are never
+* misclassified as ciphertext.
+*/
+function isVercelEncryptedEnvValue(value) {
+	if (!looksLikeBase64(value)) return false;
+	let decoded;
+	try {
+		decoded = Buffer.from(value, "base64").toString("utf8");
+	} catch {
+		return false;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(decoded);
+	} catch {
+		return false;
+	}
+	return hasEncryptedEnvelopeShape(parsed);
+}
+//#endregion
 //#region src/commands/env/list.ts
 /** `fluid mist env list` — list env vars; mark managed_by entries. Spec §4. */
 function maskValue(value) {
 	if (value.length <= 8) return "•".repeat(value.length);
 	return `${value.slice(0, 4)}${"•".repeat(8)}${value.slice(-2)}`;
 }
+/**
+* Values come back Vercel-encrypted ciphertext (see
+* `../../lib/encrypted-env.ts`) — never show that raw blob, masked or not,
+* since it isn't the real secret and can run to ~1KB of base64.
+*/
+function displayValue(v, showValues) {
+	if (isVercelEncryptedEnvValue(v.value)) return chalk.dim("<encrypted>");
+	return showValues ? v.value : maskValue(v.value);
+}
 const envListCommand = new Command("list").description("List a mist's env vars").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("--show-values", "Print full values instead of masking them").option("--json", "Emit raw API JSON").action((slug, opts) => runAction(async () => {
 	const resolved = resolveSlug(slug);
 	const response = await listEnvVars(createMistClient(), resolved);
@@ -2057,7 +2345,7 @@ const envListCommand = new Command("list").description("List a mist's env vars")
 		chalk.bold("MANAGED")
 	], ...vars.map((v) => [
 		v.key,
-		opts.showValues ? v.value : maskValue(v.value),
+		displayValue(v, opts.showValues),
 		v.targets.join(","),
 		v.managed_by === "mist" ? chalk.magenta("mist") : chalk.dim("user")
 	])]);
@@ -2137,21 +2425,79 @@ const envUnsetCommand = new Command("unset").description("Delete one or more env
 * `fluid mist env pull` — writes `.env.local` with user-managed vars only.
 * Skips `managed_by: "mist"` entries (DATABASE_URL, FLUID_*) since local
 * dev uses PGlite, not the production database. Spec §4 + §5.
+*
+* Also skips user-managed vars whose value comes back as Vercel-encrypted
+* ciphertext (`GET .../env_vars` is a proxy to Vercel's project env, which
+* never returns plaintext — see `../../lib/encrypted-env.ts`). Writing that
+* ciphertext into `.env.local` verbatim would silently produce an unusable
+* file, so those keys are collected and surfaced as a warning instead.
+*
+* The output file is MERGED, not replaced: pulled plaintext values update
+* their existing lines (or are appended), while every other existing line
+* — comments, locally maintained secrets for encrypted/managed keys, and
+* local-only vars — is preserved verbatim. Replacing the file wholesale
+* would delete manually set values for skipped keys, and an all-encrypted
+* response would truncate the file to zero bytes right before telling the
+* user to set those same values locally.
 */
 function escapeValue(v) {
 	if (/[\s#"']/.test(v)) return `"${v.replace(/(["\\$`])/g, "\\$1")}"`;
 	return v;
 }
+/**
+* Splits the raw env-var list into what `env pull` can safely write vs.
+* what it must skip, and why. Pure — no I/O — so it's unit-testable
+* without mocking the API client or the filesystem.
+*/
+function partitionPullEnvVars(envVars) {
+	const plaintext = [];
+	const encrypted = [];
+	const managed = [];
+	for (const v of envVars) if (v.managed_by === "mist") managed.push(v);
+	else if (isVercelEncryptedEnvValue(v.value)) encrypted.push(v);
+	else plaintext.push(v);
+	return {
+		plaintext,
+		encrypted,
+		managed
+	};
+}
+/** Matches a `KEY=` / `export KEY=` assignment line and captures the key. */
+const ENV_ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/**
+* Merges pulled plaintext vars into the existing env-file contents.
+* Existing assignment lines for pulled keys are updated in place; every
+* other line (comments, blank lines, locally maintained values for keys
+* the pull skipped) is preserved verbatim; new keys are appended. Pure —
+* no I/O — so it's unit-testable without touching the filesystem.
+*/
+function mergeEnvContents(existing, plaintext) {
+	const updates = new Map(plaintext.map((v) => [v.key, `${v.key}=${escapeValue(v.value)}`]));
+	const lines = existing.length > 0 ? existing.split("\n") : [];
+	if (lines.at(-1) === "") lines.pop();
+	const out = [];
+	for (const line of lines) {
+		const key = ENV_ASSIGNMENT.exec(line)?.[1];
+		const replacement = key === void 0 ? void 0 : updates.get(key);
+		if (key !== void 0 && replacement !== void 0) {
+			out.push(replacement);
+			updates.delete(key);
+		} else out.push(line);
+	}
+	for (const rendered of updates.values()) out.push(rendered);
+	return out.length > 0 ? out.join("\n") + "\n" : "";
+}
 const envPullCommand = new Command("pull").description("Write user-managed env vars to .env.local in the CWD").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("--out <path>", "Output path (default: .env.local)").action((slug, opts) => runAction(async () => {
 	const resolved = resolveSlug(slug);
 	const { env_vars } = await listEnvVars(createMistClient(), resolved);
-	const user = env_vars.filter((v) => v.managed_by === "user");
-	const skipped = env_vars.filter((v) => v.managed_by === "mist");
-	const target = join(process.cwd(), opts.out ?? ".env.local");
-	const body = user.map((v) => `${v.key}=${escapeValue(v.value)}`).join("\n");
-	writeFileSync(target, body + (body.length ? "\n" : ""), "utf8");
-	console.log(chalk.green(`Wrote ${user.length} var(s) to ${target.replace(process.cwd() + "/", "")}.`));
-	if (skipped.length > 0) console.log(chalk.dim(`Skipped ${skipped.length} Mist-managed var(s): ${skipped.map((v) => v.key).join(", ")} (local dev uses PGlite)`));
+	const { plaintext, encrypted, managed } = partitionPullEnvVars(env_vars);
+	const outName = opts.out ?? ".env.local";
+	const target = join(process.cwd(), outName);
+	const existing = existsSync(target) ? readFileSync(target, "utf8") : "";
+	writeFileSync(target, mergeEnvContents(existing, plaintext), "utf8");
+	console.log(chalk.green(`Wrote ${plaintext.length} var(s) to ${target.replace(process.cwd() + "/", "")}${existing.length > 0 ? " (existing entries for other keys preserved)" : ""}.`));
+	if (managed.length > 0) console.log(chalk.dim(`Skipped ${managed.length} Mist-managed var(s): ${managed.map((v) => v.key).join(", ")} (local dev uses PGlite)`));
+	if (encrypted.length > 0) console.log(chalk.yellow(`Skipped ${encrypted.length} var(s) whose values are stored encrypted and can't be pulled: ${encrypted.map((v) => v.key).join(", ")} — set them locally in ${outName} yourself (values are visible in the Vercel dashboard) or re-set them via \`fluid mist env set\`.`));
 }));
 //#endregion
 //#region src/commands/env/index.ts