@moku-labs/worker 0.6.0 → 0.7.0

package/dist/{cli-DgZv5A0G.mjs → cli-Bb37rYq_.mjs}

@@ -1,10 +1,10 @@
 import { envPlugin, logPlugin } from "@moku-labs/common";
 import { createCoreConfig, createCorePlugin } from "@moku-labs/core";
 import { brandedSink, createBrandConsole, createBrandPrompts } from "@moku-labs/common/cli";
+import { access, readdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, watch } from "node:fs";
-import path from "node:path";
-import { readdir, stat, writeFile } from "node:fs/promises";
 /**
 * stage core plugin — deployment-stage / dev-mode detection, flat-injected on
 * every regular plugin's context as `ctx.stage` (spec/02 §6). No state, no
@@ -158,115 +158,173 @@ const bindingsPlugin = createPlugin("bindings", {
 	api: createBindingsApi
 });
 //#endregion
+//#region src/instances.ts
+/**
+* Resolve the default instance key from a keyed-map config: the sole entry, or the one flagged
+* `default: true`. Throws a branded error when there are no instances, or several without (or with
+* more than one) `default: true`.
+*
+* @param instances - The keyed-map config (`Record<key, instance>`).
+* @param kind - The resource kind, for the error message (e.g. "kv", "d1").
+* @returns The default instance's key.
+* @throws {Error} With a `[moku-worker]` prefix when no single default can be resolved.
+* @example
+* ```ts
+* defaultInstanceKey({ main: { name: "db", binding: "DB" } }, "d1"); // "main"
+* ```
+*/
+const defaultInstanceKey = (instances, kind) => {
+	const keys = Object.keys(instances);
+	if (keys.length === 0) throw new Error(`[moku-worker] No ${kind} instance is configured.`);
+	if (keys.length === 1) return keys[0];
+	const flagged = keys.filter((key) => instances[key]?.default === true);
+	if (flagged.length === 1) return flagged[0];
+	throw new Error(`[moku-worker] ${kind} has ${String(keys.length)} instances — mark exactly one with \`default: true\`.`);
+};
+/**
+* Look up a resource instance by key, with a branded error listing the configured keys when absent.
+*
+* @param instances - The keyed-map config (`Record<key, instance>`).
+* @param key - The instance key to resolve (the `use(key)` selector).
+* @param kind - The resource kind, for the error message.
+* @returns The instance at `key`.
+* @throws {Error} With a `[moku-worker]` prefix when `key` is not configured.
+* @example
+* ```ts
+* pickInstance(cfg, "analytics", "d1");
+* ```
+*/
+const pickInstance = (instances, key, kind) => {
+	const instance = instances[key];
+	if (instance === void 0) {
+		const configured = Object.keys(instances).join(", ") || "(none)";
+		throw new Error(`[moku-worker] No ${kind} instance "${key}". Configured: ${configured}.`);
+	}
+	return instance;
+};
+//#endregion
 //#region src/plugins/d1/api.ts
 /**
-* Create the d1 api. Each method resolves the D1Database off the request
-* `env` via the bindings plugin, then forwards to the native D1 call. The
-* binding is never cached, so concurrent requests stay isolated (SB4).
+* Create the d1 api over a keyed map of database instances. The default-database methods and
+* `use(key)` both resolve the `D1Database` off the REQUEST-SUPPLIED env on every call — env is
+* threaded, never stored (SB4), so concurrent requests stay isolated — and the instance key is
+* resolved lazily by binding-getter so an unconfigured-but-present plugin only errors when actually
+* called.
 *
 * The return is intentionally NOT annotated `: Api`. Annotating it would
 * collapse the per-method call-site generic `<T>` on `query`/`first` to
 * `unknown`; instead the implementation forwards `<T>` to `all<T>()` /
 * `first<T>()` and `types.ts#Api` remains the public-surface source of truth.
 *
-* @param {D1Ctx} ctx - Plugin context (own config + require).
-* @returns {object} The d1 public api (query, first, run, batch, prepare, deployManifest).
+* @param {D1Ctx} ctx - Plugin context (keyed-map config + require).
+* @returns {object} The d1 public api (query, first, run, batch, prepare, use, deployManifest).
 * @example
 * ```typescript
 * const api = createD1Api(ctx);
 * const { results } = await api.query<Product>(env, "SELECT * FROM products");
+* await api.use("analytics").run(env, "INSERT INTO events (name) VALUES (?)", "click");
 * ```
 */
 const createD1Api = (ctx) => {
-	const db = (env) => ctx.require(bindingsPlugin).require(env, ctx.config.binding);
+	const bindings = ctx.require(bindingsPlugin);
+	const surface = (binding) => {
+		const db = (env) => bindings.require(env, binding());
+		return {
+			/**
+			* Run a statement against this database and return all rows.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param sql - SQL with `?` placeholders.
+			* @param params - Bind parameters for the placeholders.
+			* @returns All rows in a D1 result.
+			* @example
+			* ```typescript
+			* const { results } = await api.query<Product>(env, "SELECT * FROM products");
+			* ```
+			*/
+			query: (env, sql, ...params) => db(env).prepare(sql).bind(...params).all(),
+			/**
+			* Run a statement against this database and return the first row, or null when none.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param sql - SQL with `?` placeholders.
+			* @param params - Bind parameters for the placeholders.
+			* @returns The first row, or null if none.
+			* @example
+			* ```typescript
+			* const product = await api.first<Product>(env, "SELECT * FROM products WHERE id = ?", 1);
+			* ```
+			*/
+			first: (env, sql, ...params) => db(env).prepare(sql).bind(...params).first(),
+			/**
+			* Run a write/DDL statement against this database and return its result meta.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param sql - SQL with `?` placeholders.
+			* @param params - Bind parameters for the placeholders.
+			* @returns Result carrying `.meta`.
+			* @example
+			* ```typescript
+			* await api.run(env, "INSERT INTO events (name) VALUES (?)", "click");
+			* ```
+			*/
+			run: (env, sql, ...params) => db(env).prepare(sql).bind(...params).run(),
+			/**
+			* Execute caller-built prepared statements atomically in one round-trip.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param stmts - Caller-built prepared statements.
+			* @returns One result per statement, order preserved.
+			* @example
+			* ```typescript
+			* await api.batch(env, [api.prepare(env).prepare("INSERT INTO t (id) VALUES (1)")]);
+			* ```
+			*/
+			batch: (env, stmts) => db(env).batch(stmts),
+			/**
+			* Resolve the request `D1Database` so callers can build statements for `batch()`.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @returns The request-resolved database handle.
+			* @example
+			* ```typescript
+			* const stmt = api.prepare(env).prepare("SELECT * FROM products");
+			* ```
+			*/
+			prepare: (env) => db(env)
+		};
+	};
+	const defaultBinding = () => pickInstance(ctx.config, defaultInstanceKey(ctx.config, "d1"), "d1").binding;
 	return {
+		...surface(defaultBinding),
 		/**
-		* Run a statement and return all rows. Forwards the call-site generic to
-		* `all<T>()` so the result type is not widened to `unknown`.
-		*
-		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
-		* @param {string} sql - SQL text with `?` placeholders.
-		* @param {unknown[]} params - Bind parameters, in placeholder order.
-		* @returns {Promise<D1Result<T>>} All rows (`.results` is `T[]`).
-		* @example
-		* ```typescript
-		* const { results } = await api.query<Product>(env, "SELECT * FROM products WHERE active = ?", 1);
-		* ```
-		*/
-		query: (env, sql, ...params) => db(env).prepare(sql).bind(...params).all(),
-		/**
-		* Run a statement and return the first row, or `null` if there are none.
-		* Forwards the call-site generic to `first<T>()`.
-		*
-		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
-		* @param {string} sql - SQL text with `?` placeholders.
-		* @param {unknown[]} params - Bind parameters, in placeholder order.
-		* @returns {Promise<T | null>} The first row, or `null` if none matched.
-		* @example
-		* ```typescript
-		* const row = await api.first<Product>(env, "SELECT * FROM products WHERE id = ?", id);
-		* ```
-		*/
-		first: (env, sql, ...params) => db(env).prepare(sql).bind(...params).first(),
-		/**
-		* Run a write/DDL statement (INSERT/UPDATE/DELETE/DDL) and return the
-		* D1 result carrying `.meta` (e.g. `rows_written`, `last_row_id`).
-		*
-		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
-		* @param {string} sql - SQL text with `?` placeholders.
-		* @param {unknown[]} params - Bind parameters, in placeholder order.
-		* @returns {Promise<D1Result>} Result carrying `.meta`.
-		* @example
-		* ```typescript
-		* const res = await api.run(env, "INSERT INTO products (name) VALUES (?)", name);
-		* const id = res.meta.last_row_id;
-		* ```
-		*/
-		run: (env, sql, ...params) => db(env).prepare(sql).bind(...params).run(),
-		/**
-		* Execute caller-built prepared statements atomically in one round-trip,
-		* returning one result per statement in order.
+		* Select a specific D1 database instance by its config key.
 		*
-		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
-		* @param {D1PreparedStatement[]} stmts - Statements built from prepare(env).
-		* @returns {Promise<D1Result[]>} One result per statement, order preserved.
+		* @param key - The instance key (as configured under `pluginConfigs.d1`).
+		* @returns The SQL surface bound to that database.
 		* @example
 		* ```typescript
-		* const handle = api.prepare(env);
-		* await api.batch(env, [handle.prepare("INSERT INTO a VALUES (1)").bind()]);
+		* await api.use("analytics").run(env, "INSERT INTO events (name) VALUES (?)", "click");
 		* ```
 		*/
-		batch: (env, stmts) => db(env).batch(stmts),
+		use: (key) => surface(() => pickInstance(ctx.config, key, "d1").binding),
 		/**
-		* Resolve the request-scoped D1Database so callers can build prepared
-		* statements for batch(). Issues no query itself.
+		* Return this plugin's deploy metadata — one descriptor per configured database.
 		*
-		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
-		* @returns {D1Database} The request-resolved database handle.
+		* @returns One d1 deploy descriptor per instance.
 		* @example
 		* ```typescript
-		* const handle = api.prepare(env);
-		* const stmt = handle.prepare("SELECT * FROM t").bind();
+		* const manifest = api.deployManifest(); // [{ kind: "d1", name: "tracker-db", binding: "DB" }]
 		* ```
 		*/
-		prepare: (env) => db(env),
-		/**
-		* Return this plugin's deploy metadata for the deploy plugin to read.
-		* Build-time only — takes no `env`. The return is typed `DeployManifest`
-		* (from types.ts), which pins `kind` to the literal `"d1"` without an
-		* inline `as` assertion.
-		*
-		* @returns {DeployManifest} Deploy manifest entry `{ kind: "d1", binding, migrations }`.
-		* @example
-		* ```typescript
-		* const m = api.deployManifest();
-		* // => { kind: "d1", binding: "DB", migrations: "./migrations" }
-		* ```
-		*/
-		deployManifest: () => ({
-			kind: "d1",
-			binding: ctx.config.binding,
-			migrations: ctx.config.migrations
+		deployManifest: () => Object.values(ctx.config).map((instance) => {
+			const entry = {
+				kind: "d1",
+				name: instance.name,
+				binding: instance.binding
+			};
+			if (instance.migrations !== void 0) entry.migrations = instance.migrations;
+			return entry;
 		})
 	};
 };
@@ -281,10 +339,7 @@ const createD1Api = (ctx) => {
 */
 const d1Plugin = createPlugin("d1", {
 	depends: [bindingsPlugin],
-	config: {
-		binding: "DB",
-		migrations: ""
-	},
+	config: {},
 	api: (ctx) => createD1Api(ctx)
 });
 //#endregion
@@ -293,59 +348,62 @@ const d1Plugin = createPlugin("d1", {
 * Builds the `app.durableObjects` API surface — `get` and `deployManifest`.
 *
 * All namespace resolution uses the per-call `env` argument: `env` is threaded, never
-* stored (SB4 / design §1a). The config bindings map is frozen and read-only. No state
+* stored (SB4 / design §1a). The keyed-map config is frozen and read-only. No state
 * is held on the plugin between calls (stateless — `Record<string, never>`).
 *
-* @param ctx - Plugin context with `config.bindings`, `require(bindingsPlugin)`, and core APIs.
+* @param ctx - Plugin context with the keyed-map `config`, `require(bindingsPlugin)`, and core APIs.
 * @returns The durableObjects API: `{ get, deployManifest }`.
 * @example
 * ```typescript
 * const api = createDoApi(ctx);
-* const stub = api.get(env, "counter", "room-42");
-* const manifest = api.deployManifest(); // { kind: "do", bindings: { counter: "COUNTER" } }
+* const stub = api.get(env, "board", "room-42");
+* const manifest = api.deployManifest(); // [{ kind: "do", binding: "BOARD", className: "BoardChannel" }]
 * ```
 */
 const createDoApi = (ctx) => ({
 	/**
 	* Resolves a `DurableObjectStub` off the per-request env.
 	*
-	* Maps `logicalName` → `config.bindings[logicalName]` (falling back to `logicalName`
-	* itself when unmapped), derives a deterministic id via `namespace.idFromName(idName)`,
-	* and returns the addressed stub. Synchronous — returns a stub, not a Promise.
-	* Throws (via the bindings resolver) when the binding is not present on `env`.
+	* Selects the configured instance by `logicalName` (the config key) via `pickInstance`, resolves
+	* its `binding` off `env`, derives a deterministic id via `namespace.idFromName(idName)`, and
+	* returns the addressed stub. Synchronous — returns a stub, not a Promise. Throws (branded) when
+	* `logicalName` is not configured, or (via the bindings resolver) when the binding is not present
+	* on `env`.
 	*
 	* @param env - Per-request Cloudflare bindings object (Worker fetch/queue/scheduled env).
-	* @param logicalName - Logical DO name used in code (e.g. `"counter"`).
+	* @param logicalName - Logical DO key (selects the configured instance, e.g. `"board"`).
 	* @param idName - Stable id name passed to `idFromName` (e.g. `"room-42"`).
 	* @returns The addressed `DurableObjectStub`.
-	* @throws {Error} With `[moku-worker]` prefix when the binding is not bound on `env`.
+	* @throws {Error} With `[moku-worker]` prefix when `logicalName` is not configured, or when the
+	*   binding is not bound on `env`.
 	* @example
 	* ```typescript
-	* const stub = app.durableObjects.get(env, "counter", "room-42");
+	* const stub = app.durableObjects.get(env, "board", "room-42");
 	* const res = await stub.fetch("https://do/increment");
 	* ```
 	*/
 	get: (env, logicalName, idName) => {
-		const binding = ctx.config.bindings[logicalName] ?? logicalName;
+		const binding = pickInstance(ctx.config, logicalName, "durableObjects").binding;
 		const ns = ctx.require(bindingsPlugin).require(env, binding);
 		return ns.get(ns.idFromName(idName));
 	},
 	/**
-	* Returns this plugin's deploy metadata — read by the `deploy` plugin via
-	* `ctx.require(durableObjectsPlugin)`. Never reads sibling `pluginConfigs` (F6;
-	* spec/08 §5, §7). Pure synchronous read of `ctx.config.bindings`.
+	* Returns this plugin's deploy metadata — one entry per configured instance, read by the `deploy`
+	* plugin via `ctx.require(durableObjectsPlugin)`. Never reads sibling `pluginConfigs` (F6;
+	* spec/08 §5, §7). Pure synchronous read of `ctx.config`.
 	*
-	* @returns `{ kind: "do", bindings }` reflecting the frozen plugin config.
+	* @returns One `{ kind: "do", binding, className }` per configured instance.
 	* @example
 	* ```typescript
 	* const manifest = app.durableObjects.deployManifest();
-	* // → { kind: "do", bindings: { counter: "COUNTER" } }
+	* // → [{ kind: "do", binding: "BOARD", className: "BoardChannel" }]
 	* ```
 	*/
-	deployManifest: () => ({
+	deployManifest: () => Object.values(ctx.config).map((instance) => ({
 		kind: "do",
-		bindings: ctx.config.bindings
-	})
+		binding: instance.binding,
+		className: instance.className
+	}))
 });
 //#endregion
 //#region src/plugins/durable-objects/helpers.ts
@@ -418,17 +476,17 @@ const defineDurableObject = (name) => {
 * Cloudflare Durable Objects plugin — Standard tier.
 *
 * Exposes `get(env, logicalName, idName)` (synchronous stub accessor, threaded env) and
-* `deployManifest()` (build-time metadata). Depends on `bindingsPlugin` for namespace
-* resolution. The `defineDurableObject` helper is mounted under `helpers` and re-exported
-* at the top level for consumer use.
+* `deployManifest()` (build-time metadata, one entry per configured instance). Depends on
+* `bindingsPlugin` for namespace resolution. The `defineDurableObject` helper is mounted under
+* `helpers` and re-exported at the top level for consumer use.
 *
 * @example
 * ```typescript
 * // Consumer endpoint handler:
-* const stub = app.durableObjects.get(env, "counter", params.room!);
+* const stub = app.durableObjects.get(env, "board", params.room!);
 * const res = await stub.fetch("https://do/increment");
-* // Consumer DO class:
-* export class Counter extends defineDurableObject("Counter") {
+* // Consumer DO class (the EXPORTED className referenced by the "board" instance):
+* export class BoardChannel extends defineDurableObject("BoardChannel") {
 *   async fetch(): Promise<Response> { return new Response("ok"); }
 * }
 * ```
@@ -436,91 +494,112 @@ const defineDurableObject = (name) => {
 */
 const durableObjectsPlugin = createPlugin("durableObjects", {
 	depends: [bindingsPlugin],
-	config: { bindings: {} },
+	config: {},
 	api: createDoApi,
 	helpers: { defineDurableObject }
 });
 //#endregion
 //#region src/plugins/kv/api.ts
 /**
-* Builds the app.kv.* api. Resolves the KV namespace off the REQUEST-SUPPLIED env
-* on every call — env is threaded, never stored (design §1a / SB4).
+* Builds the app.kv.* api over a keyed map of namespace instances. The default-namespace methods and
+* `use(key)` both resolve the namespace off the REQUEST-SUPPLIED env on every call — env is threaded,
+* never stored (design §1a / SB4) — and the instance key is resolved lazily so an unconfigured-but-
+* present plugin only errors when actually called.
 *
-* @param ctx - The kv plugin context (own config + merged events).
-* @returns The app.kv api: get / put / delete / list / deployManifest.
+* @param ctx - The kv plugin context (keyed-map config + merged events).
+* @returns The app.kv api: get / put / delete / list / use / deployManifest.
 * @example
 * ```typescript
 * const api = createKvApi(ctx);
 * const value = await api.get(env, "key");
+* await api.use("sessions").put(env, "s:1", "data");
 * ```
 */
 const createKvApi = (ctx) => {
-	const ns = (env) => ctx.require(bindingsPlugin).require(env, ctx.config.binding);
+	const bindings = ctx.require(bindingsPlugin);
+	const surface = (binding) => {
+		const ns = (env) => bindings.require(env, binding());
+		return {
+			/**
+			* Read a value by key from this namespace. Returns null when absent.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The key to read.
+			* @returns The stored value, or null when absent.
+			* @example
+			* ```typescript
+			* const value = await api.get(env, "feature-flags");
+			* ```
+			*/
+			get: async (env, key) => ns(env).get(key),
+			/**
+			* Write a string value under a key, optionally with KV put options.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The key to write.
+			* @param value - The string value to store.
+			* @param opts - Optional expiration / metadata.
+			* @returns Resolves once the write is acknowledged.
+			* @example
+			* ```typescript
+			* await api.put(env, "session:1", "data", { expirationTtl: 3600 });
+			* ```
+			*/
+			put: async (env, key, value, opts) => ns(env).put(key, value, opts),
+			/**
+			* Remove a key from this namespace (no-op if absent).
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The key to delete.
+			* @returns Resolves once the delete is acknowledged.
+			* @example
+			* ```typescript
+			* await api.delete(env, "session:expired");
+			* ```
+			*/
+			delete: async (env, key) => ns(env).delete(key),
+			/**
+			* List keys in this namespace, optionally filtered/paginated.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param opts - Optional prefix / cursor / limit.
+			* @returns The list result.
+			* @example
+			* ```typescript
+			* const { keys } = await api.list(env, { prefix: "session:" });
+			* ```
+			*/
+			list: async (env, opts) => ns(env).list(opts)
+		};
+	};
+	const defaultBinding = () => pickInstance(ctx.config, defaultInstanceKey(ctx.config, "kv"), "kv").binding;
 	return {
+		...surface(defaultBinding),
 		/**
-		* Reads a value by key from the KV namespace. Returns null when absent.
-		*
-		* @param env - The per-request Cloudflare env (threaded, never stored).
-		* @param key - The key to read.
-		* @returns The stored value, or null when absent.
-		* @example
-		* ```typescript
-		* const value = await api.get(env, "feature-flags");
-		* ```
-		*/
-		get: async (env, key) => ns(env).get(key),
-		/**
-		* Writes a string value under a key, optionally with KV put options.
+		* Select a specific KV namespace instance by its config key.
 		*
-		* @param env - The per-request Cloudflare env.
-		* @param key - The key to write.
-		* @param value - The string value to store.
-		* @param opts - Optional expiration / metadata.
-		* @returns Resolves once the write is acknowledged.
+		* @param key - The instance key (as configured under `pluginConfigs.kv`).
+		* @returns The key/value surface bound to that namespace.
 		* @example
 		* ```typescript
-		* await api.put(env, "session:1", "data", { expirationTtl: 3600 });
+		* await api.use("sessions").get(env, "s:1");
 		* ```
 		*/
-		put: async (env, key, value, opts) => ns(env).put(key, value, opts),
+		use: (key) => surface(() => pickInstance(ctx.config, key, "kv").binding),
 		/**
-		* Removes a key from the namespace (no-op if absent).
+		* Return this plugin's deploy metadata — one descriptor per configured namespace.
 		*
-		* @param env - The per-request Cloudflare env.
-		* @param key - The key to delete.
-		* @returns Resolves once the delete is acknowledged.
+		* @returns One kv deploy descriptor per instance.
 		* @example
 		* ```typescript
-		* await api.delete(env, "session:expired");
+		* const manifest = api.deployManifest(); // [{ kind: "kv", name: "tracker-cache", binding: "CACHE" }]
 		* ```
 		*/
-		delete: async (env, key) => ns(env).delete(key),
-		/**
-		* Lists keys in the namespace, optionally filtered/paginated via opts.
-		*
-		* @param env - The per-request Cloudflare env.
-		* @param opts - Optional prefix / cursor / limit.
-		* @returns The list result from the KV namespace.
-		* @example
-		* ```typescript
-		* const { keys } = await api.list(env, { prefix: "session:" });
-		* ```
-		*/
-		list: async (env, opts) => ns(env).list(opts),
-		/**
-		* Returns this plugin's own deploy metadata, read by the deploy plugin via
-		* require (design §6 / F6). Build-time only — takes no env.
-		*
-		* @returns The kv deploy descriptor with kind literal and binding name.
-		* @example
-		* ```typescript
-		* const manifest = api.deployManifest(); // { kind: "kv", binding: "KV" }
-		* ```
-		*/
-		deployManifest: () => ({
+		deployManifest: () => Object.values(ctx.config).map((instance) => ({
 			kind: "kv",
-			binding: ctx.config.binding
-		})
+			name: instance.name,
+			binding: instance.binding
+		}))
 	};
 };
 /**
@@ -534,109 +613,113 @@ const createKvApi = (ctx) => {
 */
 const kvPlugin = createPlugin("kv", {
 	depends: [bindingsPlugin],
-	config: { binding: "KV" },
+	config: {},
 	api: createKvApi
 });
 //#endregion
 //#region src/plugins/queues/api.ts
 /**
-* @file queues plugin — API factory (send, sendBatch, consume, deployManifest).
+* Resolve the instance a consumed batch belongs to. With a single instance, that instance always
+* matches. With several, match the instance whose `name` equals `batch.queue` OR whose stage-suffixed
+* form (`${name}-`) prefixes it (tolerant of the deploy stage suffix, e.g. `tracker-activity-dev`);
+* fall back to the default instance when nothing matches.
 *
-* All binding-resolving methods take the per-request `env` as the first argument
-* and resolve the `Queue` via `ctx.require(bindingsPlugin).require<Queue>(env, name)`.
-* The `env` is never stored (SB4 / design §1a) — resolved fresh on every call.
+* @param config - The keyed-map queues config.
+* @param queueName - The CF queue name from `batch.queue`.
+* @returns The matched `QueueInstance` (its `onMessage` is what `consume` awaits).
+* @example
+* ```ts
+* routeInstance(cfg, "tracker-activity-dev"); // → the `activity` instance
+* ```
 */
+const routeInstance = (config, queueName) => {
+	const keys = Object.keys(config);
+	if (keys.length === 1) return pickInstance(config, keys[0], "queues");
+	return Object.values(config).find((instance) => instance.name === queueName || queueName.startsWith(`${instance.name}-`)) ?? pickInstance(config, defaultInstanceKey(config, "queues"), "queues");
+};
 /**
-* Builds app.queues.* — read by worker.ts queue() delegation (design §1d; spec/02 §7).
+* Builds app.queues.* over a keyed map of Queue instances — read by worker.ts queue() delegation
+* (design §1d; spec/02 §7). The default-instance producer methods and `use(key)` both resolve the
+* Queue off the REQUEST-SUPPLIED env on every call (env is threaded, never stored — SB4); the
+* instance key is resolved lazily. Emits `queue:message` for observability after each consumed
+* message (F8).
 *
-* Resolves Queue bindings off the request env per call (never stored — SB4).
-* Emits `queue:message` for observability after each consumed message (F8).
-*
-* @param ctx - Plugin context (own config + require + emit).
-* @returns The queues API surface: send, sendBatch, consume, deployManifest.
+* @param ctx - Plugin context (keyed-map config + require + emit).
+* @returns The queues API surface: send, sendBatch, use, consume, deployManifest.
 * @example
 * ```ts
-* // Worker entry (design §1d)
-* export default {
-*   queue: (b, e, c) => app.queues.consume(b, e, c),
-* };
+* const api = createQueuesApi(ctx);
+* await api.send(env, { orderId: "1" });            // default instance
+* await api.use("activity").send(env, { id: 2 });   // a named instance
+* // Worker entry (design §1d): queue: (b, e, c) => app.queues.consume(b, e, c)
 * ```
 */
 const createQueuesApi = (ctx) => {
-	/**
-	* Resolves a named Queue binding from the per-request env.
-	* Throws a [moku-worker]-prefixed error when the binding is absent.
-	*
-	* @param env - Per-request Cloudflare bindings.
-	* @param name - Queue binding name.
-	* @returns The resolved Queue instance.
-	* @example
-	* ```ts
-	* const q = queue(env, "ORDERS");
-	* ```
-	*/
-	const queue = (env, name) => ctx.require(bindingsPlugin).require(env, name);
+	const bindings = ctx.require(bindingsPlugin);
+	const surface = (binding) => {
+		const queue = (env) => bindings.require(env, binding());
+		return {
+			/**
+			* Enqueue a single message onto this instance's queue.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param body - The message body to enqueue.
+			* @returns Resolves once the message is enqueued.
+			* @example
+			* ```typescript
+			* await api.send(env, { userId: "u1" });
+			* ```
+			*/
+			send: async (env, body) => {
+				await queue(env).send(body);
+			},
+			/**
+			* Enqueue many messages onto this instance's queue; each element becomes one message.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param bodies - Array of message bodies; each becomes one message.
+			* @returns Resolves once all messages are enqueued.
+			* @example
+			* ```typescript
+			* await api.sendBatch(env, [{ id: 1 }, { id: 2 }]);
+			* ```
+			*/
+			sendBatch: async (env, bodies) => {
+				await queue(env).sendBatch(bodies.map((body) => ({ body })));
+			}
+		};
+	};
+	const defaultBinding = () => pickInstance(ctx.config, defaultInstanceKey(ctx.config, "queues"), "queues").binding;
 	return {
+		...surface(defaultBinding),
 		/**
-		* Enqueue a single message onto the named queue.
+		* Select a specific Queue instance by its config key.
 		*
-		* Resolves the Queue binding fresh from `env` on every call (SB4).
-		* Request/response work → api method, never emit (F8).
-		*
-		* @param env - Per-request Cloudflare bindings object.
-		* @param q - Target queue binding name in `env`.
-		* @param body - Message body to enqueue.
-		* @returns Resolves once the message is enqueued.
-		* @throws {Error} With a `[moku-worker]` prefix if the binding is missing.
+		* @param key - The instance key (as configured under `pluginConfigs.queues`).
+		* @returns The producer surface bound to that instance.
 		* @example
-		* ```ts
-		* await app.queues.send(env, "ORDERS", { orderId: "123" });
-		* ```
-		*/
-		send: async (env, q, body) => {
-			await queue(env, q).send(body);
-		},
-		/**
-		* Enqueue many messages in one call; each element becomes one message.
-		*
-		* Maps each body to `{ body }` before calling `Queue.sendBatch` (design §4.3).
-		*
-		* @param env - Per-request Cloudflare bindings object.
-		* @param q - Target queue binding name in `env`.
-		* @param bodies - Array of message bodies; each becomes one message.
-		* @returns Resolves once all messages are enqueued.
-		* @throws {Error} With a `[moku-worker]` prefix if the binding is missing.
-		* @example
-		* ```ts
-		* await app.queues.sendBatch(env, "ORDERS", orders);
+		* ```typescript
+		* await api.use("activity").send(env, { id: 2 });
 		* ```
 		*/
-		sendBatch: async (env, q, bodies) => {
-			await queue(env, q).sendBatch(bodies.map((body) => ({ body })));
-		},
+		use: (key) => surface(() => pickInstance(ctx.config, key, "queues").binding),
 		/**
-		* Consumer dispatch — the Worker's `queue()` export delegates here.
+		* Consumer dispatch — the Worker's `queue()` export delegates here. Routes the batch to the
+		* matching instance's `onMessage` and emits `queue:message` per message.
 		*
-		* Iterates `batch.messages`, **awaits** `config.onMessage(message, env)` per message
-		* (so Cloudflare gets a settled promise and the handler controls ack/retry; F8,
-		* spec/07 §3 — never emit for awaited work), then fire-and-forget emits `queue:message`
-		* for observability. Returns a promise the Worker **must** await so the isolate is not
-		* killed mid-batch.
-		*
-		* @param batch - The incoming message batch from Cloudflare.
-		* @param env - Per-request Cloudflare bindings object.
-		* @param _exec - waitUntil / passThroughOnException (reserved for future use).
-		* @returns Resolves after all messages in the batch are processed.
-		* @throws {Error} Re-throws any error from `config.onMessage` so Cloudflare can retry.
+		* @param batch - The incoming message batch.
+		* @param env - The per-request Cloudflare env.
+		* @param _ctx - The execution context (waitUntil / passThroughOnException); unused.
+		* @returns Resolves after all messages settle.
 		* @example
-		* ```ts
-		* // Worker entry
-		* queue: (b, e, c) => app.queues.consume(b, e, c),
+		* ```typescript
+		* // Worker entry (design §1d): queue: (b, e, c) => app.queues.consume(b, e, c)
 		* ```
 		*/
-		consume: async (batch, env, _exec) => {
+		consume: async (batch, env, _ctx) => {
+			const instance = routeInstance(ctx.config, batch.queue);
 			for (const m of batch.messages) {
-				await ctx.config.onMessage(m, env);
+				if (instance.onMessage) await instance.onMessage(m, env);
 				ctx.emit("queue:message", {
 					queue: batch.queue,
 					messageId: m.id
@@ -644,24 +727,24 @@ const createQueuesApi = (ctx) => {
 			}
 		},
 		/**
-		* Returns this plugin's deploy metadata, read by the deploy plugin via
-		* `ctx.require(queuesPlugin).deployManifest()` (F6 — never reads sibling config).
+		* Return this plugin's deploy metadata — one descriptor per configured instance.
 		*
-		* @returns Deploy manifest entry `{ kind: "queue", producers }`.
+		* @returns One queue deploy descriptor per instance.
 		* @example
-		* ```ts
-		* const manifest = ctx.require(queuesPlugin).deployManifest();
-		* // → { kind: "queue", producers: ["orders"] }
+		* ```typescript
+		* const manifest = api.deployManifest(); // [{ kind: "queue", name: "tracker-activity", binding: "ACTIVITY" }]
 		* ```
 		*/
-		deployManifest: () => ({
+		deployManifest: () => Object.values(ctx.config).map((instance) => ({
 			kind: "queue",
-			producers: ctx.config.producers
-		})
+			name: instance.name,
+			binding: instance.binding
+		}))
 	};
 };
 /**
-* Standard tier — Cloudflare Queues producer + consumer dispatch.
+* Standard tier — Cloudflare Queues producer + per-instance consumer dispatch over a keyed map of
+* instances.
 *
 * `events` is declared first and via `register.map<QueueEvents>` so the plugin's own events infer
 * into the factory context; the api wiring is therefore arrow-wrapped (contextually typed).
@@ -673,10 +756,7 @@ const createQueuesApi = (ctx) => {
 const queuesPlugin = createPlugin("queues", {
 	events: (register) => register.map({ "queue:message": "A queue message was processed" }),
 	depends: [bindingsPlugin],
-	config: {
-		producers: [],
-		onMessage: async () => {}
-	},
+	config: {},
 	api: (ctx) => createQueuesApi(ctx)
 });
 //#endregion
@@ -771,101 +851,108 @@ const resolveR2Provider = (bindings, env, bucket) => {
 //#endregion
 //#region src/plugins/storage/api.ts
 /**
-* Build the env-first storage API. Each runtime method resolves the bucket
-* provider fresh from the per-request `env` — nothing is stored, so concurrent
-* requests stay isolated (worker-api-design SB4; spec/08 §6,§7).
+* Build the app.storage.* api over a keyed map of R2 bucket instances. The default-bucket methods and
+* `use(key)` both resolve the bucket off the REQUEST-SUPPLIED env on every call — env is threaded,
+* never stored (worker-api-design SB4; spec/08 §6,§7) — and the instance key is resolved lazily so an
+* unconfigured-but-present plugin only errors when actually called.
 *
 * The `deployManifest()` method is build-time only: it reads from `ctx.config`
 * and never touches `env` or R2.
 *
-* @param ctx - Plugin context (config + require for bindings resolution).
-* @returns {StorageApi} The env-first storage API surface.
+* @param ctx - Plugin context (keyed-map config + require for bindings resolution).
+* @returns {StorageApi} The app.storage api: get / put / delete / list / use / deployManifest.
 * @example
 * ```typescript
 * const api = createStorageApi(ctx);
 * const body = await api.get(env, "my-object");
+* await api.use("uploads").put(env, "avatar.png", buffer);
 * ```
 */
 const createStorageApi = (ctx) => {
-	/**
-	* Resolve the StorageProvider for the given per-request env. Called on every
-	* method invocation — the bucket binding is never cached across calls.
-	*
-	* @param env - The per-request Cloudflare bindings object.
-	* @returns {StorageProvider} A StorageProvider delegating to the resolved R2Bucket.
-	* @example
-	* ```typescript
-	* const p = provider(env);
-	* const body = await p.get("key");
-	* ```
-	*/
-	const provider = (env) => resolveR2Provider(ctx.require(bindingsPlugin), env, ctx.config.bucket);
+	const bindings = ctx.require(bindingsPlugin);
+	const surface = (binding) => {
+		const provider = (env) => resolveR2Provider(bindings, env, binding());
+		return {
+			/**
+			* Read an object from this bucket; resolves null when the key is absent.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The object key to read.
+			* @returns The object body, or null.
+			* @example
+			* ```typescript
+			* const body = await api.get(env, "assets/logo.png");
+			* ```
+			*/
+			get: (env, key) => provider(env).get(key),
+			/**
+			* Write an object to this bucket.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The object key to write.
+			* @param value - The object contents.
+			* @returns The written object metadata.
+			* @example
+			* ```typescript
+			* await api.put(env, "avatar.png", buffer);
+			* ```
+			*/
+			put: (env, key, value) => provider(env).put(key, value),
+			/**
+			* Remove an object (or keys) from this bucket. No-op when absent.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The object key or keys to delete.
+			* @returns Resolves once removed.
+			* @example
+			* ```typescript
+			* await api.delete(env, "assets/old-logo.png");
+			* ```
+			*/
+			delete: (env, key) => provider(env).delete(key),
+			/**
+			* List objects in this bucket, optionally filtered by R2ListOptions.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param opts - Optional prefix / limit / cursor / delimiter.
+			* @returns The list result.
+			* @example
+			* ```typescript
+			* const { objects } = await api.list(env, { prefix: "assets/" });
+			* ```
+			*/
+			list: (env, opts) => provider(env).list(opts)
+		};
+	};
+	const defaultBinding = () => pickInstance(ctx.config, defaultInstanceKey(ctx.config, "r2"), "r2").binding;
 	return {
+		...surface(defaultBinding),
 		/**
-		* Read an object from the bucket; resolves null when the key is absent.
+		* Select a specific R2 bucket instance by its config key.
 		*
-		* @param env - Per-request Cloudflare bindings.
-		* @param key - Object key.
-		* @returns {Promise<R2ObjectBody | null>} The R2ObjectBody, or null.
+		* @param key - The instance key (as configured under `pluginConfigs.storage`).
+		* @returns The object surface bound to that bucket.
 		* @example
 		* ```typescript
-		* const body = await api.get(env, "assets/logo.png");
+		* await api.use("uploads").put(env, "avatar.png", buffer);
 		* ```
 		*/
-		get: (env, key) => provider(env).get(key),
+		use: (key) => surface(() => pickInstance(ctx.config, key, "r2").binding),
 		/**
-		* Write an object to the bucket.
+		* Return this plugin's deploy metadata — one descriptor per configured bucket.
 		*
-		* @param env - Per-request Cloudflare bindings.
-		* @param key - Object key.
-		* @param value - Object contents (ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null).
-		* @returns {Promise<R2Object>} The R2Object metadata for the written object.
+		* @returns One r2 deploy descriptor per instance.
 		* @example
 		* ```typescript
-		* const obj = await api.put(env, "assets/logo.png", buffer);
+		* const manifest = api.deployManifest(); // [{ kind: "r2", name: "tracker-files", binding: "FILES" }]
 		* ```
 		*/
-		put: (env, key, value) => provider(env).put(key, value),
-		/**
-		* Remove an object (or array of keys) from the bucket. No-op when absent.
-		*
-		* @param env - Per-request Cloudflare bindings.
-		* @param key - Object key or array of keys.
-		* @returns {Promise<void>} Resolves once removed.
-		* @example
-		* ```typescript
-		* await api.delete(env, "assets/old.png");
-		* ```
-		*/
-		delete: (env, key) => provider(env).delete(key),
-		/**
-		* List objects, optionally filtered by R2ListOptions.
-		*
-		* @param env - Per-request Cloudflare bindings.
-		* @param opts - Optional R2ListOptions (prefix, limit, cursor, delimiter).
-		* @returns {Promise<R2Objects>} The R2Objects list result.
-		* @example
-		* ```typescript
-		* const { objects } = await api.list(env, { prefix: "images/" });
-		* ```
-		*/
-		list: (env, opts) => provider(env).list(opts),
-		/**
-		* Return this plugin's deploy metadata. Build-time only — does not touch
-		* `env` or R2. The deploy plugin reads this via `ctx.require(storagePlugin).deployManifest()`.
-		*
-		* @returns {StorageManifest} Deploy manifest entry `{ kind: "r2", bucket, upload }`.
-		* @example
-		* ```typescript
-		* const manifest = api.deployManifest();
-		* // { kind: "r2", bucket: "ASSETS", upload: "./public" }
-		* ```
-		*/
-		deployManifest: () => ({
+		deployManifest: () => Object.values(ctx.config).map((instance) => ({
 			kind: "r2",
-			bucket: ctx.config.bucket,
-			upload: ctx.config.upload
-		})
+			name: instance.name,
+			binding: instance.binding,
+			...instance.upload === void 0 ? {} : { upload: instance.upload }
+		}))
 	};
 };
 /**
@@ -879,13 +966,47 @@ const createStorageApi = (ctx) => {
 */
 const storagePlugin = createPlugin("storage", {
 	depends: [bindingsPlugin],
-	config: {
-		upload: "",
-		bucket: "ASSETS"
-	},
+	config: {},
 	api: createStorageApi
 });
 //#endregion
+//#region src/plugins/deploy/auth/env-file.ts
+/**
+* @file deploy plugin — `.env.local` scaffolder (node:fs).
+*
+* Writes a ready-to-fill `.env.local` so the guided deploy can hand the user a real file to paste
+* their Cloudflare token into — NEVER clobbering an existing one (it may already hold real secrets).
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Create `<dir>/.env.local` with the given contents, unless it already exists. Existing files are
+* left untouched (they may hold real secrets) — the caller tells the user to fill that one in.
+*
+* @param dir - Directory to create the file in (usually `process.cwd()`).
+* @param content - The file contents to write when absent (e.g. `envLocalScaffold(manifest)`).
+* @returns Whether the file was created (false when it already existed) and its path.
+* @example
+* ```ts
+* const { created, path } = await ensureEnvLocal(process.cwd(), envLocalScaffold(manifest));
+* ```
+*/
+const ensureEnvLocal = async (dir, content) => {
+	const filePath = path.join(dir, ".env.local");
+	try {
+		await access(filePath);
+		return {
+			created: false,
+			path: filePath
+		};
+	} catch {
+		await writeFile(filePath, content, "utf8");
+		return {
+			created: true,
+			path: filePath
+		};
+	}
+};
+//#endregion
 //#region src/plugins/deploy/auth/permissions.ts
 /** Permission groups every deploy needs, regardless of resources. */
 const ALWAYS = [{
@@ -1024,6 +1145,104 @@ const ciToken = (manifest) => {
 	return groups;
 };
 //#endregion
+//#region src/plugins/deploy/auth/render.ts
+/** Cloudflare's dashboard path for creating API tokens. */
+const TOKENS_URL$1 = "https://dash.cloudflare.com/profile/api-tokens";
+/**
+* Render one permission as a framed row. With the template flag on (the LOCAL panel) a green `✓`
+* marks a permission the stock template already includes and a pink `+ ← add to template` marks one
+* the user must add; with it off (the CI panel) every row is a neutral bullet. Scope bold, reason dim.
+*
+* @param ui - The branded console (for its palette).
+* @param permission - The permission group to render.
+* @param showTemplateFlag - Whether to mark template-vs-add (LOCAL) or use a neutral bullet (CI).
+* @returns The rendered (colorized) row, ready to drop into a box.
+* @example
+* ```ts
+* permissionRow(ui, { group: "Account · D1", scope: "Edit", reason: "d1", inBaseTemplate: false }, true);
+* ```
+*/
+const permissionRow = (ui, permission, showTemplateFlag) => {
+	const { palette } = ui;
+	const templateMark = permission.inBaseTemplate ? palette.green("✓") : palette.pink("+");
+	const mark = showTemplateFlag ? templateMark : palette.dim("•");
+	const flag = showTemplateFlag && !permission.inBaseTemplate ? palette.pink("  ← add to template") : "";
+	const reason = palette.dim(`(${permission.reason})`);
+	return `${mark} ${permission.group} : ${palette.bold(permission.scope)}  ${reason}${flag}`;
+};
+/**
+* Render the LOCAL (first deploy) token panel: the full permission set with template/add markers,
+* then the numbered create-token steps (URL cyan, template + `.env.local` bold).
+*
+* @param ui - The branded console to render through.
+* @param requirement - The LOCAL token requirement (from requiredToken()).
+* @example
+* ```ts
+* localPanel(ui, requiredToken(manifest));
+* ```
+*/
+const localPanel = (ui, requirement) => {
+	const { palette } = ui;
+	const adds = requirement.toAdd.map((permission) => `${permission.group.replace("Account · ", "")} → ${permission.scope}`).join(", ");
+	const coversAll = palette.dim(`The "${requirement.base}" template covers everything.`);
+	const addStep = requirement.toAdd.length > 0 ? `  3. ADD ${palette.pink(adds)}` : `  3. ${coversAll}`;
+	const template = palette.bold(`"${requirement.base}"`);
+	ui.box([
+		palette.bold("LOCAL — first deploy (creates your infra)"),
+		"",
+		...requirement.required.map((permission) => permissionRow(ui, permission, true)),
+		"",
+		`  1. ${palette.cyan(TOKENS_URL$1)}`,
+		`  2. Create Token → start from the ${template} template.`,
+		addStep,
+		"  4. Account Resources → Include → your account.",
+		`  5. Create it, copy it, then paste into ${palette.bold(".env.local")} (below).`
+	]);
+};
+/**
+* Render the compact CI (automation redeploy) token panel: the reduced, read-mostly permission set
+* for a later Custom Token. No template markers — CI builds a token from scratch, not the template.
+*
+* @param ui - The branded console to render through.
+* @param groups - The CI token permission groups (from ciToken()).
+* @example
+* ```ts
+* ciPanel(ui, ciToken(manifest));
+* ```
+*/
+const ciPanel = (ui, groups) => {
+	const { palette } = ui;
+	ui.box([
+		palette.bold("CI — automation redeploy (optional, later)"),
+		"",
+		...groups.map((permission) => permissionRow(ui, permission, false)),
+		"",
+		palette.dim("Create a Custom Token with exactly these (Read, not Edit, on data)."),
+		palette.dim("Store as the CLOUDFLARE_API_TOKEN secret; pin CLOUDFLARE_ACCOUNT_ID.")
+	]);
+};
+/**
+* Render the full branded `auth setup` guidance: a heading, the LOCAL token panel (what to create
+* now), and — when `opts.ci` is supplied — the compact CI panel; otherwise a one-line pointer to
+* `auth setup` for the CI token (so the guided deploy stays focused on the immediate next step).
+*
+* @param ui - The branded console to render through.
+* @param requirement - The LOCAL token requirement (from requiredToken()).
+* @param opts - Optional rendering options.
+* @param opts.ci - The CI token permission groups (from ciToken()); omit to show a pointer instead.
+* @example
+* ```ts
+* renderAuthSetup(ui, requiredToken(manifest));                     // guided deploy (LOCAL only)
+* renderAuthSetup(ui, requiredToken(manifest), { ci: ciToken(m) }); // `auth setup` (LOCAL + CI)
+* ```
+*/
+const renderAuthSetup = (ui, requirement, opts) => {
+	ui.heading("Cloudflare API token");
+	localPanel(ui, requirement);
+	if (opts?.ci) ciPanel(ui, opts.ci);
+	else ui.line(ui.palette.dim("  Need a CI token later? Run `auth setup` for the reduced set."));
+};
+//#endregion
 //#region src/plugins/deploy/auth/setup.ts
 /** Cloudflare's dashboard path for creating API tokens. */
 const TOKENS_URL = "https://dash.cloudflare.com/profile/api-tokens";
@@ -1103,6 +1322,41 @@ const tokenInstructions = (manifest) => [
 	"",
 	...ciSection(ciToken(manifest))
 ].join("\n");
+/**
+* Render a ready-to-fill `.env.local` for the guided deploy: the two Cloudflare credential keys
+* (left blank to paste into) preceded by a comment block derived from the manifest — where to
+* create the token, which template to start from, exactly which permissions to add, and how to find
+* the account id. The same guidance {@link tokenInstructions} prints, but PERSISTED in the file the
+* user edits (so it survives the terminal scrolling away). Pure: no fs, no network.
+*
+* @param manifest - The assembled deploy manifest.
+* @returns The `.env.local` file contents (trailing newline included).
+* @example
+* ```ts
+* await writeFile(".env.local", envLocalScaffold(manifest));
+* ```
+*/
+const envLocalScaffold = (manifest) => {
+	const requirement = requiredToken(manifest);
+	const addStep = requirement.toAdd.length > 0 ? `#   3. Under Permissions, ADD: ${requirement.toAdd.map((permission) => `${permission.group.replace("Account · ", "")} -> ${permission.scope}`).join(", ")}` : `#   3. The "${requirement.base}" template covers everything — no changes needed.`;
+	return `${[
+		"# Cloudflare credentials for the moku deploy — fill in the two values below, then re-run deploy.",
+		"# Local-only: keep this file out of git (.env.local is gitignored by convention).",
+		"#",
+		"# Create the API token:",
+		`#   1. ${TOKENS_URL}  ->  Create Token`,
+		`#   2. Start from the "${requirement.base}" template.`,
+		addStep,
+		"#   4. Account Resources -> Include -> your account.",
+		"#   5. Create the token, copy it, and paste it after CLOUDFLARE_API_TOKEN= below.",
+		"#",
+		"# Account id: open https://dash.cloudflare.com — it is the id in the URL",
+		"# (dash.cloudflare.com/<account-id>) or in the right sidebar of any domain's overview.",
+		"",
+		"CLOUDFLARE_API_TOKEN=",
+		"CLOUDFLARE_ACCOUNT_ID="
+	].join("\n")}\n`;
+};
 //#endregion
 //#region src/plugins/deploy/infra/cloudflare.ts
 /**
@@ -1606,16 +1860,17 @@ const realDevDeps = () => ({
 	now: nowMs
 });
 /**
-* The d1 binding to migrate locally, when a d1 plugin is present in the app.
+* The d1 bindings to migrate locally — one per configured d1 instance that declares a migrations
+* directory (empty when no d1 plugin is present, or none declares migrations).
 *
 * @param ctx - The deploy plugin context.
-* @returns The d1 binding name, or undefined when no d1 plugin is present.
+* @returns The d1 binding names with migrations (e.g. `["DB"]`).
 * @example
 * ```ts
-* const binding = d1Binding(ctx); // "DB" | undefined
+* const bindings = d1MigrationBindings(ctx); // ["DB"]
 * ```
 */
-const d1Binding = (ctx) => ctx.has("d1") ? ctx.require(d1Plugin).deployManifest().binding : void 0;
+const d1MigrationBindings = (ctx) => ctx.has("d1") ? ctx.require(d1Plugin).deployManifest().filter((manifest) => manifest.migrations !== void 0).map((manifest) => manifest.binding) : [];
 /**
 * Rebuild the site once and announce the result. A failed build keeps the session alive (it just
 * emits dev:error and serves the last good build).
@@ -1669,13 +1924,13 @@ const runDev = async (ctx, opts, deps) => {
 		detail: "site"
 	});
 	await deps.build(ctx, webBuild);
-	const binding = d1Binding(ctx);
-	if (ctx.config.migrateLocal && binding !== void 0) {
+	const migrationBindings = ctx.config.migrateLocal ? d1MigrationBindings(ctx) : [];
+	if (migrationBindings.length > 0) {
 		ctx.emit("dev:phase", {
 			phase: "migrate",
 			detail: "d1 (local)"
 		});
-		await deps.runWrangler([
+		for (const binding of migrationBindings) await deps.runWrangler([
 			"d1",
 			"migrations",
 			"apply",
@@ -1719,21 +1974,21 @@ const runDev = async (ctx, opts, deps) => {
 const checkExisting = (resource, existing) => {
 	switch (resource.kind) {
 		case "kv": {
-			const id = existing.kv.get(resource.binding);
+			const id = existing.kv.get(resource.name);
 			return id === void 0 ? { exists: false } : {
 				exists: true,
 				id
 			};
 		}
 		case "d1": {
-			const id = existing.d1.get(resource.binding);
+			const id = existing.d1.get(resource.name);
 			return id === void 0 ? { exists: false } : {
 				exists: true,
 				id
 			};
 		}
-		case "r2": return { exists: existing.r2.has(resource.bucket) };
-		case "queue": return { exists: resource.producers.every((producer) => existing.queue.has(producer)) };
+		case "r2": return { exists: existing.r2.has(resource.name) };
+		case "queue": return { exists: existing.queue.has(resource.name) };
 		case "do": return { exists: false };
 	}
 };
@@ -1783,6 +2038,177 @@ const planInfra = async (ctx, manifest) => {
 	};
 };
 //#endregion
+//#region src/plugins/deploy/infra/render.ts
+/**
+* Derive a human-readable name from a resource descriptor: the Cloudflare resource `name` for the
+* provisioned kinds (kv/r2/d1/queue), or the exported `className` for a Durable Object (which has no
+* provisioned name). Used in both the provision events and the branded panels so the two agree.
+*
+* @param resource - The resource descriptor.
+* @returns A short name identifying the resource.
+* @example
+* ```ts
+* resourceName({ kind: "kv", name: "tracker-cache", binding: "CACHE" }); // "tracker-cache"
+* ```
+*/
+const resourceName = (resource) => resource.kind === "do" ? resource.className : resource.name;
+/**
+* Format a `kind name` cell, padding the kind so the names line up in a column.
+*
+* @param kind - The resource kind (kv / r2 / d1 / queue / do).
+* @param name - The resource name.
+* @returns The aligned `kind  name` cell.
+* @example
+* ```ts
+* cell("kv", "CACHE"); // "kv     CACHE"
+* ```
+*/
+const cell = (kind, name) => `${kind.padEnd(6)}${name}`;
+/**
+* ANSI SGR matcher — built from `String.fromCharCode(27)` (the ESC byte) so no control character
+* appears in a regex literal (which both linters reject).
+*/
+const ANSI_SGR = new RegExp(String.raw`${String.fromCodePoint(27)}\[[0-9;]*m`, "gu");
+/**
+* Strip ANSI SGR escape sequences so a captured (colorized) error renders as plain, readable text.
+*
+* @param text - The (possibly colorized) text.
+* @returns The text with ANSI color codes removed.
+* @example
+* ```ts
+* stripAnsi(`${String.fromCharCode(27)}[31mX${String.fromCharCode(27)}[0m`); // "X"
+* ```
+*/
+const stripAnsi = (text) => text.replaceAll(ANSI_SGR, "");
+/**
+* Clean a captured (colorized, multi-line, wrapper-wrapped) provision error down to its meaningful
+* text: strip ANSI, drop the wrapper lines (the branded prefix, wrangler's log-file pointer), strip
+* each `✘ [ERROR]` marker, and join what's left. Returns the FULL message (the caller word-wraps it)
+* so the user reads the actual reason — never a truncated `…`.
+*
+* @param message - The captured error message.
+* @returns The full, plain failure reason.
+* @example
+* ```ts
+* cleanError("[moku-worker] wrangler exited…\n  ✘ [ERROR] The bucket name is invalid.");
+* // "The bucket name is invalid."
+* ```
+*/
+const cleanError = (message) => {
+	const cleaned = stripAnsi(message).split("\n").map((line) => line.trim()).filter((line) => line.length > 0).filter((line) => !/^\[moku-worker\]/u.test(line)).filter((line) => !/logs were written to/iu.test(line)).map((line) => line.replace(/^✘\s*/u, "").replace(/^\[error\]\s*/iu, "")).join(" ");
+	return cleaned.length > 0 ? cleaned : stripAnsi(message).trim();
+};
+/**
+* Word-wrap text to `width` columns (never splitting inside a word), so a long failure reason reads
+* as a tidy indented block instead of forcing the box wide or scrolling off the edge.
+*
+* @param text - The text to wrap.
+* @param width - The maximum column width per line.
+* @returns The wrapped lines.
+* @example
+* ```ts
+* wrapText("a long sentence to wrap", 10); // ["a long", "sentence", "to wrap"]
+* ```
+*/
+const wrapText = (text, width) => {
+	const lines = [];
+	let line = "";
+	for (const word of text.split(/\s+/u).filter(Boolean)) if (line.length === 0) line = word;
+	else if (line.length + 1 + word.length <= width) line += ` ${word}`;
+	else {
+		lines.push(line);
+		line = word;
+	}
+	if (line.length > 0) lines.push(line);
+	return lines;
+};
+/**
+* Render the infra preflight plan as a branded panel: a dim summary line (counts + account) then one
+* row per declared resource — a pink `+` for those to create, a dim `~ (exists)` for those already
+* present. When nothing needs creating it still renders, so the user sees the full picture.
+*
+* @param ui - The branded console to render through.
+* @param plan - The infra plan (existing vs missing) from checkInfra()/planInfra().
+* @example
+* ```ts
+* renderPlan(ui, await planInfra(ctx, manifest));
+* ```
+*/
+const renderPlan = (ui, plan) => {
+	const { palette } = ui;
+	const summary = palette.dim(`${String(plan.missing.length)} to create · ${String(plan.exists.length)} exist · ${plan.account}`);
+	const existsRows = plan.exists.map((ref) => `${palette.dim("~")} ${cell(ref.resource.kind, resourceName(ref.resource))} ${palette.dim("(exists)")}`);
+	const createRows = plan.missing.map((resource) => `${palette.pink("+")} ${cell(resource.kind, resourceName(resource))}`);
+	ui.heading("Infra plan");
+	ui.box([
+		summary,
+		"",
+		...createRows,
+		...existsRows
+	]);
+};
+/**
+* Render the provision result as a branded panel — a green `✓` per created resource, a dim `~` per
+* skipped, a red `✗` per failure, then a summary line (failed count red when non-zero) — followed,
+* when anything failed, by a detail block printing each failure's FULL reason (ANSI-stripped and
+* word-wrapped) so it is actually readable instead of truncated inside the box.
+*
+* @param ui - The branded console to render through.
+* @param result - The provision result from provisionInfra()/the deploy pipeline.
+* @example
+* ```ts
+* renderProvisionResult(ui, await provisionInfra(plan));
+* ```
+*/
+const renderProvisionResult = (ui, result) => {
+	const { palette } = ui;
+	const createdRows = result.created.map((ref) => `${palette.green("✓")} ${cell(ref.resource.kind, resourceName(ref.resource))}`);
+	const skippedRows = result.skipped.map((ref) => `${palette.dim("~")} ${cell(ref.resource.kind, resourceName(ref.resource))} ${palette.dim("(exists)")}`);
+	const failedRows = result.failed.map((failure) => `${palette.red("✗")} ${cell(failure.resource.kind, resourceName(failure.resource))}`);
+	const failedCount = result.failed.length > 0 ? palette.red(`${String(result.failed.length)} failed`) : "0 failed";
+	const summary = `${String(result.created.length)} created · ${String(result.skipped.length)} exist · ${failedCount}`;
+	ui.heading("Provisioned");
+	ui.box([
+		...createdRows,
+		...skippedRows,
+		...failedRows,
+		"",
+		summary
+	]);
+	if (result.failed.length > 0) {
+		ui.line();
+		for (const failure of result.failed) {
+			ui.line(`  ${palette.red("✗")} ${cell(failure.resource.kind, resourceName(failure.resource))}`);
+			for (const wrapped of wrapText(cleanError(failure.error), ui.width - 4)) ui.line(palette.dim(`    ${wrapped}`));
+		}
+	}
+};
+//#endregion
+//#region src/plugins/deploy/naming.ts
+/**
+* @file deploy plugin — stage-aware resource naming.
+*
+* One source of truth for turning a base Cloudflare resource name into its stage variant, so the
+* worker name, the provisioners, the infra existence diff, and the generated wrangler config all
+* agree. Production keeps the base name; every other stage gets a `-${stage}` suffix. Node-only;
+* never imported by the runtime Worker bundle.
+*/
+/**
+* Apply the deploy stage to a base Cloudflare resource name: the base name in `production`, else
+* `${base}-${stage}` (e.g. dev → `tracker-db-dev`). Env bindings + DO class names never get the
+* suffix — only provisioned resource names (and the worker name) are stage-qualified.
+*
+* @param base - The base resource name (e.g. "tracker-db").
+* @param stage - The deploy stage (e.g. "production", "development", "dev").
+* @returns The stage-qualified name.
+* @example
+* ```ts
+* stageName("tracker-db", "production"); // "tracker-db"
+* stageName("tracker-db", "dev");        // "tracker-db-dev"
+* ```
+*/
+const stageName = (base, stage) => stage === "production" ? base : `${base}-${stage}`;
+//#endregion
 //#region src/plugins/deploy/providers/d1.ts
 /**
 * @file deploy plugin — D1 provisioning adapter.
@@ -1822,13 +2248,13 @@ const provisionD1 = async (manifest, _ci) => {
 	const id = parseD1DatabaseId(await runWrangler([
 		"d1",
 		"create",
-		manifest.binding
+		manifest.name
 	]));
 	if (manifest.migrations) await runWrangler([
 		"d1",
 		"migrations",
 		"apply",
-		manifest.binding,
+		manifest.name,
 		"--local"
 	]);
 	return id ? { id } : {};
@@ -1891,7 +2317,7 @@ const provisionKv = async (manifest, _ci) => {
 		"kv",
 		"namespace",
 		"create",
-		manifest.binding
+		manifest.name
 	]));
 	return id ? { id } : {};
 };
@@ -1900,25 +2326,25 @@ const provisionKv = async (manifest, _ci) => {
 /**
 * @file deploy plugin — Queues provisioning adapter.
 *
-* Creates Cloudflare Queues via `wrangler queues create <name>` for each producer.
+* Creates one Cloudflare Queue via `wrangler queues create <name>` per queue instance.
 * Node-only; never imported by the runtime Worker bundle.
 */
 /**
-* Provision queues via `wrangler queues create` for each declared producer.
+* Provision the queue via `wrangler queues create <name>`.
 *
 * @param manifest - The queue resource descriptor.
 * @param _ci - Whether running non-interactively.
-* @returns Resolves once all queues are created.
+* @returns Resolves once the queue is created.
 * @example
 * ```ts
-* await provisionQueue({ kind: "queue", producers: ["orders"] }, false);
+* await provisionQueue({ kind: "queue", name: "tracker-activity", binding: "ACTIVITY" }, false);
 * ```
 */
 const provisionQueue = async (manifest, _ci) => {
-	for (const producer of manifest.producers) await runWrangler([
+	await runWrangler([
 		"queues",
 		"create",
-		producer
+		manifest.name
 	]);
 };
 //#endregion
@@ -1941,7 +2367,7 @@ const provisionQueue = async (manifest, _ci) => {
 * @returns Resolves once the bucket is created.
 * @example
 * ```ts
-* await provisionR2({ kind: "r2", bucket: "ASSETS" }, false);
+* await provisionR2({ kind: "r2", name: "tracker-files", binding: "FILES" }, false);
 * ```
 */
 const provisionR2 = async (manifest, _ci) => {
@@ -1949,7 +2375,7 @@ const provisionR2 = async (manifest, _ci) => {
 		"r2",
 		"bucket",
 		"create",
-		manifest.bucket
+		manifest.name
 	]);
 };
 /**
@@ -2095,12 +2521,12 @@ const buildKvNamespaces = (resources, ids) => resources.filter((resource) => res
 * @returns One wrangler R2 bucket entry per r2 resource.
 * @example
 * ```ts
-* const r2 = buildR2Buckets([{ kind: "r2", bucket: "ASSETS" }]);
+* const r2 = buildR2Buckets([{ kind: "r2", name: "tracker-files", binding: "FILES" }]);
 * ```
 */
 const buildR2Buckets = (resources) => resources.filter((resource) => resource.kind === "r2").map((resource) => ({
-	binding: resource.bucket,
-	bucket_name: resource.bucket.toLowerCase()
+	binding: resource.binding,
+	bucket_name: resource.name
 }));
 /**
 * Build the wrangler `d1_databases` array from the manifest's d1 resources.
@@ -2110,13 +2536,13 @@ const buildR2Buckets = (resources) => resources.filter((resource) => resource.ki
 * @returns One wrangler D1 database entry per d1 resource (migrations_dir set when present).
 * @example
 * ```ts
-* const d1 = buildD1Databases([{ kind: "d1", binding: "DB" }], { DB: "uuid-1234" });
+* const d1 = buildD1Databases([{ kind: "d1", name: "tracker-db", binding: "DB" }], { DB: "uuid-1234" });
 * ```
 */
 const buildD1Databases = (resources, ids) => resources.filter((resource) => resource.kind === "d1").map((resource) => {
 	const entry = {
 		binding: resource.binding,
-		database_name: resource.binding.toLowerCase(),
+		database_name: resource.name,
 		database_id: ids[resource.binding] ?? ""
 	};
 	if (resource.migrations) entry.migrations_dir = resource.migrations;
@@ -2129,16 +2555,16 @@ const buildD1Databases = (resources, ids) => resources.filter((resource) => reso
 * @returns The queues section, or undefined when there are no queue resources.
 * @example
 * ```ts
-* const q = buildQueues([{ kind: "queue", producers: ["jobs"] }]);
+* const q = buildQueues([{ kind: "queue", name: "tracker-activity", binding: "ACTIVITY" }]);
 * ```
 */
 const buildQueues = (resources) => {
 	const queueResources = resources.filter((resource) => resource.kind === "queue");
 	if (queueResources.length === 0) return void 0;
-	return { producers: queueResources.flatMap((resource) => resource.producers.map((producer) => ({
-		queue: producer,
-		binding: producer.toUpperCase()
-	}))) };
+	return { producers: queueResources.map((resource) => ({
+		queue: resource.name,
+		binding: resource.binding
+	})) };
 };
 /**
 * Build the wrangler `durable_objects` bindings section from the manifest's do resources.
@@ -2147,47 +2573,136 @@ const buildQueues = (resources) => {
 * @returns The durable_objects section, or undefined when there are no do resources.
 * @example
 * ```ts
-* const dobj = buildDurableObjects([{ kind: "do", bindings: { Counter: "COUNTER" } }]);
+* const dobj = buildDurableObjects([{ kind: "do", binding: "COUNTER", className: "Counter" }]);
 * ```
 */
 const buildDurableObjects = (resources) => {
 	const doResources = resources.filter((resource) => resource.kind === "do");
 	if (doResources.length === 0) return void 0;
-	return { bindings: doResources.flatMap((resource) => Object.entries(resource.bindings).map(([className, bindingName]) => ({
-		name: bindingName,
-		class_name: className
-	}))) };
+	return { bindings: doResources.map((resource) => ({
+		name: resource.binding,
+		class_name: resource.className
+	})) };
+};
+/**
+* Build the auto Durable Object `migrations` from the manifest's do classes. wrangler REQUIRES a
+* migration for every DO class, so this derives a single `v1` migration registering each class as
+* SQLite-backed (the modern default) — the exact section wrangler prompts for when it is missing.
+*
+* @param resources - All resource descriptors from the manifest.
+* @returns A single-entry migrations array, or undefined when there are no do resources.
+* @example
+* ```ts
+* buildMigrations([{ kind: "do", binding: "BOARD", className: "BoardChannel" }]);
+* // [{ tag: "v1", new_sqlite_classes: ["BoardChannel"] }]
+* ```
+*/
+const buildMigrations = (resources) => {
+	const classes = resources.filter((resource) => resource.kind === "do").map((resource) => resource.className);
+	return classes.length > 0 ? [{
+		tag: "v1",
+		new_sqlite_classes: classes
+	}] : void 0;
+};
+/**
+* Extract the already-captured Cloudflare ids (kv namespace `id`, d1 `database_id`) from an existing
+* parsed wrangler config, keyed by binding — so a regeneration (e.g. on `dev`) can preserve ids it
+* isn't handed. Tolerant of a malformed/hand-edited file (skips non-object / non-string entries).
+*
+* @param existing - The parsed existing wrangler config (or `{}`).
+* @returns A binding → id map (empty when the file has none).
+* @example
+* ```ts
+* extractExistingIds({ kv_namespaces: [{ binding: "CACHE", id: "ns1" }] }); // { CACHE: "ns1" }
+* ```
+*/
+const extractExistingIds = (existing) => {
+	const ids = {};
+	const collect = (list, idKey) => {
+		if (!Array.isArray(list)) return;
+		for (const raw of list) {
+			if (raw === null || typeof raw !== "object") continue;
+			const entry = raw;
+			const binding = entry.binding;
+			const id = entry[idKey];
+			if (typeof binding === "string" && typeof id === "string" && id.length > 0) ids[binding] = id;
+		}
+	};
+	collect(existing.kv_namespaces, "id");
+	collect(existing.d1_databases, "database_id");
+	return ids;
+};
+/**
+* Build the extra top-level wrangler keys from the typed deploy config: `entry` → `main`,
+* `nodeCompat` → `compatibility_flags: ["nodejs_compat"]`, `assets` → the wrangler `assets` block
+* (SPA fallback when `spa`), then the raw `wrangler` passthrough last (the escape hatch wins / adds
+* anything else). Pass the result as the `extra` argument to {@link writeWranglerConfig}.
+*
+* @param config - The deploy plugin config.
+* @returns The merged extra wrangler keys.
+* @example
+* ```ts
+* await writeWranglerConfig(file, manifest, ids, wranglerExtra(ctx.config));
+* ```
+*/
+const wranglerExtra = (config) => {
+	const extra = {};
+	if (config.entry !== void 0) extra.main = config.entry;
+	if (config.nodeCompat === true) extra.compatibility_flags = ["nodejs_compat"];
+	if (config.assets !== void 0) extra.assets = {
+		directory: config.assets.directory,
+		binding: config.assets.binding,
+		...config.assets.spa === true ? { not_found_handling: "single-page-application" } : {}
+	};
+	return {
+		...extra,
+		...config.wrangler
+	};
 };
 /**
 * Generate/update the wrangler config file from a manifest (non-destructive merge).
-* If the file exists, its top-level keys are preserved and only deploy-managed keys
-* (name, compatibility_date, kv_namespaces, r2_buckets, d1_databases, queues,
-* durable_objects) are updated.
+*
+* Layering (last wins): existing file keys → the `extra` passthrough (the app's `wrangler` config:
+* `main`, `compatibility_flags`, `assets`, `vars`, …) → the deploy-managed keys (name,
+* compatibility_date, kv_namespaces, r2_buckets, d1_databases, queues, durable_objects). So the
+* framework always owns the resource sections, the app supplies what the manifest can't derive, and
+* any other hand-written keys survive. Durable Object `migrations` are auto-derived for every DO
+* class (the section wrangler requires) UNLESS the file/passthrough already defines `migrations`.
 *
 * @param configFile - Path to the wrangler config file.
 * @param manifest - The assembled deploy manifest.
 * @param ids - Captured Cloudflare ids keyed by binding (kv namespace id, d1 database id). Defaults
 *   to an empty map, in which case `id`/`database_id` are written as "" (e.g. the universal path).
+* @param extra - Extra top-level wrangler keys to merge in (the app's `deploy.wrangler` config).
 * @returns Resolves once the file is written.
 * @example
 * ```ts
-* await writeWranglerConfig("wrangler.jsonc", manifest, { CACHE: "ns123", DB: "uuid-1234" });
+* await writeWranglerConfig("wrangler.jsonc", manifest, { CACHE: "ns123" }, {
+*   main: "src/cloudflare/worker.ts",
+*   compatibility_flags: ["nodejs_compat"],
+*   assets: { directory: "dist/client", binding: "ASSETS" }
+* });
 * ```
 */
-const writeWranglerConfig = async (configFile, manifest, ids = {}) => {
+const writeWranglerConfig = async (configFile, manifest, ids = {}, extra = {}) => {
 	let existing = {};
 	if (existsSync(configFile)) try {
 		existing = parseJsonc(readFileSync(configFile, "utf8"));
 	} catch {
 		existing = {};
 	}
-	const kvNamespaces = buildKvNamespaces(manifest.resources, ids);
+	const effectiveIds = {
+		...extractExistingIds(existing),
+		...ids
+	};
+	const kvNamespaces = buildKvNamespaces(manifest.resources, effectiveIds);
 	const r2Buckets = buildR2Buckets(manifest.resources);
-	const d1Databases = buildD1Databases(manifest.resources, ids);
+	const d1Databases = buildD1Databases(manifest.resources, effectiveIds);
 	const queues = buildQueues(manifest.resources);
 	const durableObjects = buildDurableObjects(manifest.resources);
 	const updated = {
 		...existing,
+		...extra,
 		name: manifest.name,
 		compatibility_date: manifest.compatibilityDate
 	};
@@ -2196,6 +2711,8 @@ const writeWranglerConfig = async (configFile, manifest, ids = {}) => {
 	if (d1Databases.length > 0) updated.d1_databases = d1Databases;
 	if (queues !== void 0) updated.queues = queues;
 	if (durableObjects !== void 0) updated.durable_objects = durableObjects;
+	const migrations = buildMigrations(manifest.resources);
+	if (migrations !== void 0 && updated.migrations === void 0) updated.migrations = migrations;
 	await writeFile(configFile, JSON.stringify(updated, void 0, 2));
 };
 /**
@@ -2234,56 +2751,50 @@ const scaffoldWranglerAndCi = async (configFile, _ci) => {
 * Cloudflare REST API (via infra/). Never called in the deployed Worker runtime.
 */
 /**
-* Derive a human-readable name string from a resource descriptor (used in provision events).
-*
-* @param resource - The resource descriptor.
-* @returns A name suitable for the provision:resource / provision:skip event payload.
-* @example
-* ```ts
-* resourceName({ kind: "kv", binding: "CACHE" }); // "CACHE"
-* ```
-*/
-const resourceName = (resource) => {
-	switch (resource.kind) {
-		case "r2": return resource.bucket;
-		case "do": return Object.values(resource.bindings).join(",");
-		case "queue": return resource.producers.join(",");
-		default: return resource.binding;
-	}
-};
-/**
-* Assemble the deploy manifest from each present resource plugin's OWN deployManifest() api,
-* gated by ctx.has(name) so absent plugins are skipped — never sibling pluginConfigs (F6).
+* Assemble the deploy manifest from each present resource plugin's OWN deployManifest() api (each
+* returns one entry PER configured instance), gated by ctx.has(name) so absent plugins are skipped —
+* never sibling pluginConfigs (F6). The single place the deploy stage is baked into names: the worker
+* name and every provisioned resource `name` are run through {@link stageName} (bindings/DO class
+* names are never suffixed), so provisioning, the existence diff, and the generated config all agree.
 *
 * @param ctx - The deploy plugin context.
-* @returns The assembled manifest (name, compatibilityDate, resources).
+* @param stage - The deploy stage (e.g. "production", "dev") applied to every resource name.
+* @returns The assembled manifest (stage-qualified name, compatibilityDate, per-instance resources).
 * @example
 * ```ts
-* const manifest = assembleManifest(ctx);
+* const manifest = assembleManifest(ctx, "production");
 * ```
 */
-const assembleManifest = (ctx) => ({
-	name: ctx.global.name,
-	compatibilityDate: ctx.global.compatibilityDate,
-	resources: [
-		ctx.has("storage") ? ctx.require(storagePlugin).deployManifest() : void 0,
-		ctx.has("kv") ? ctx.require(kvPlugin).deployManifest() : void 0,
-		ctx.has("d1") ? ctx.require(d1Plugin).deployManifest() : void 0,
-		ctx.has("queues") ? ctx.require(queuesPlugin).deployManifest() : void 0,
-		ctx.has("durableObjects") ? ctx.require(durableObjectsPlugin).deployManifest() : void 0
-	].filter((resource) => resource !== void 0)
-});
+const assembleManifest = (ctx, stage) => {
+	const resources = [
+		ctx.has("storage") ? ctx.require(storagePlugin).deployManifest() : [],
+		ctx.has("kv") ? ctx.require(kvPlugin).deployManifest() : [],
+		ctx.has("d1") ? ctx.require(d1Plugin).deployManifest() : [],
+		ctx.has("queues") ? ctx.require(queuesPlugin).deployManifest() : [],
+		ctx.has("durableObjects") ? ctx.require(durableObjectsPlugin).deployManifest() : []
+	].flat();
+	return {
+		name: stageName(ctx.global.name, stage),
+		compatibilityDate: ctx.global.compatibilityDate,
+		resources: resources.map((resource) => "name" in resource ? {
+			...resource,
+			name: stageName(resource.name, stage)
+		} : resource)
+	};
+};
 /**
-* Act on an infra plan: skip the resources that already exist (reusing their ids), create only
-* the missing ones (capturing each new id), and announce each via provision:skip / :resource.
+* Act on an infra plan: skip the resources that already exist (reusing their ids), create the
+* missing ones (capturing each new id), and announce each via provision:skip / :resource. Resilient
+* — a single resource that fails to create is CAPTURED in `failed` (not thrown), so one bad resource
+* (e.g. an invalid bucket name) never aborts the whole run and the caller can report a clear result.
 *
 * @param ctx - The deploy plugin context.
 * @param plan - The infra plan from planInfra (existing vs missing).
 * @param ci - Whether provisioning runs non-interactively (forwarded to each provider).
-* @returns The provisioning result: created, skipped, and the merged binding → id map.
+* @returns The provisioning result: created, skipped, failed, and the merged binding → id map.
 * @example
 * ```ts
-* const { ids } = await applyPlan(ctx, plan, false);
+* const { created, failed } = await applyPlan(ctx, plan, false);
 * ```
 */
 const applyPlan = async (ctx, plan, ci) => {
@@ -2296,7 +2807,8 @@ const applyPlan = async (ctx, plan, ci) => {
 		});
 	}
 	const created = [];
-	for (const resource of plan.missing) {
+	const failed = [];
+	for (const resource of plan.missing) try {
 		const { id } = await provisionResource(resource, ci);
 		if (id !== void 0 && (resource.kind === "kv" || resource.kind === "d1")) ids[resource.binding] = id;
 		created.push(id === void 0 ? { resource } : {
@@ -2307,14 +2819,234 @@ const applyPlan = async (ctx, plan, ci) => {
 			kind: resource.kind,
 			name: resourceName(resource)
 		});
+	} catch (error) {
+		failed.push({
+			resource,
+			error: error instanceof Error ? error.message : String(error)
+		});
 	}
 	return {
 		created,
 		skipped: plan.exists,
+		failed,
 		ids
 	};
 };
 /**
+* Sentinel a guided helper resolves to when the user declined recovery — a clean abort the caller
+* turns into a `deploy:phase aborted` + early return, never a thrown (and re-rendered) error.
+*/
+const ABORTED = Symbol("deploy:aborted");
+/** Retry guidance shown beneath each step's failure, before the "Retry?" prompt. */
+const HINTS = {
+	build: "Web build failed — fix the error above, then retry.",
+	provision: "Verify your token's account scopes and Cloudflare's status, then retry.",
+	upload: "R2 upload failed — check the bucket and your token's R2 scope, then retry.",
+	deploy: "wrangler deploy failed — review the output above, then retry."
+};
+/**
+* Emit the terminal `aborted` phase — the single exit every guided gate/retry funnels through when
+* the user stops the deploy. Factored out so each abort path renders one consistent line.
+*
+* @param ctx - The deploy plugin context.
+* @returns Nothing.
+* @example
+* ```ts
+* if (declined) return emitAborted(ctx);
+* ```
+*/
+const emitAborted = (ctx) => ctx.emit("deploy:phase", { phase: "aborted" });
+/**
+* The full guided token setup shown after an auth failure on a TTY. Offers to walk the user through
+* it, and when accepted: prints WHERE to create the Cloudflare token (dashboard URL, which template,
+* the exact permissions to add) AND scaffolds a ready-to-fill `.env.local` — the same guidance baked
+* in as comments — for the user to paste the token + account id into (never clobbering an existing
+* file). Always ends pointing at the re-run.
+*
+* @param ctx - The deploy plugin context.
+* @param ui - The branded console to render the guidance through.
+* @param confirm - The yes/no prompt.
+* @returns Resolves once the guidance (and optional `.env.local` scaffold) has been rendered.
+* @example
+* ```ts
+* await guidedTokenSetup(ctx, createBrandConsole(), confirm);
+* ```
+*/
+const guidedTokenSetup = async (ctx, ui, confirm) => {
+	if (!await confirm("Set up Cloudflare credentials now? (guided)")) {
+		ui.info("Set CLOUDFLARE_API_TOKEN in .env.local, then run `deploy` again.");
+		return;
+	}
+	const manifest = assembleManifest(ctx, ctx.global.stage);
+	renderAuthSetup(ui, requiredToken(manifest));
+	const { created, path } = await ensureEnvLocal(process.cwd(), envLocalScaffold(manifest));
+	ui.info(created ? `Created ${path} — paste your token + account id there, then run \`deploy\` again.` : `${path} already exists — fill in CLOUDFLARE_API_TOKEN there, then run \`deploy\` again.`);
+};
+/**
+* Verify the `.env` token, turning a missing/invalid token into a guided recovery on a TTY: surface
+* WHY auth failed, then walk the user through {@link guidedTokenSetup} (where to create the token +
+* scaffold a `.env.local`). The env is snapshotted at app start, so a freshly-pasted token only
+* takes effect on a NEW run. In CI/pipes the branded error re-throws (fail-fast).
+*
+* @param ctx - The deploy plugin context.
+* @param deps - Interactivity + the confirm prompt.
+* @returns True when the token verified; false when the user must set it up and re-run.
+* @throws {Error} Re-throws the branded auth error in CI / non-interactive runs.
+* @example
+* ```ts
+* if (!(await guidedAuth(ctx, { interactive, confirm }))) return;
+* ```
+*/
+const guidedAuth = async (ctx, deps) => {
+	try {
+		await verifyAuth(ctx);
+		return true;
+	} catch (error) {
+		if (!deps.interactive) throw error;
+		const ui = createBrandConsole();
+		ui.error(error instanceof Error ? error.message : String(error));
+		await guidedTokenSetup(ctx, ui, deps.confirm);
+		return false;
+	}
+};
+/**
+* Run one external pipeline step with interactive recovery: on failure, render the branded error +
+* an actionable hint, then offer to retry — looping until the step succeeds or the user declines.
+* A decline resolves to {@link ABORTED} (a clean abort the caller surfaces), so the error is shown
+* once, not re-rendered downstream. In CI/pipes the first failure re-throws (fail-fast). The step
+* MUST be safe to re-run (idempotent).
+*
+* @param step - The async step to run (e.g. the web build, the R2 upload, `wrangler deploy`).
+* @param hint - One-line guidance shown beneath the error before the retry prompt.
+* @param deps - Interactivity + the confirm prompt.
+* @returns The step's resolved value once it succeeds, or {@link ABORTED} when a retry is declined.
+* @throws {Error} Re-throws the step's error in CI / non-interactive runs.
+* @example
+* ```ts
+* const url = await guidedStep(() => runWrangler(args), "wrangler deploy failed …", deps);
+* if (url === ABORTED) return;
+* ```
+*/
+const guidedStep = async (step, hint, deps) => {
+	for (;;) try {
+		return await step();
+	} catch (error) {
+		if (!deps.interactive) throw error;
+		const ui = createBrandConsole();
+		ui.error(error instanceof Error ? error.message : String(error));
+		ui.info(hint);
+		if (!await deps.confirm("Retry?")) return ABORTED;
+	}
+};
+/**
+* Run the read-only infra preflight with interactive recovery: a network/scope failure fails fast in
+* CI, or (on a TTY) renders the error + hint and offers a retry. Resolves the plan, or {@link ABORTED}
+* when the user declines the retry.
+*
+* @param ctx - The deploy plugin context.
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @param deps - Interactivity + the confirm prompt.
+* @returns The infra plan, or {@link ABORTED} when a preflight retry is declined.
+* @throws {Error} Re-throws the preflight error in CI / non-interactive runs.
+* @example
+* ```ts
+* const plan = await guidedPlan(ctx, manifest, deps);
+* if (plan === ABORTED) return;
+* ```
+*/
+const guidedPlan = async (ctx, manifest, deps) => {
+	for (;;) try {
+		return await planInfra(ctx, manifest);
+	} catch (error) {
+		if (!deps.interactive) throw error;
+		const ui = createBrandConsole();
+		ui.error(error instanceof Error ? error.message : String(error));
+		ui.info(HINTS.provision);
+		if (!await deps.confirm("Retry?")) return ABORTED;
+	}
+};
+/**
+* Plan + provision the infra with branded panels and interactive recovery. Each attempt RE-PLANS
+* (a resource created by a prior attempt is seen as existing and skipped — retries stay idempotent),
+* renders the plan panel (what will be created vs already exists), confirms the create gate, creates
+* the resources, then renders the result panel (created / skipped / failed). When some resources
+* FAIL it offers to retry just those (interactive) or fails fast (CI). Resolves to {@link ABORTED}
+* when the user declines the gate or a retry.
+*
+* @param ctx - The deploy plugin context.
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @param ci - Whether provisioning runs non-interactively (forwarded to each provider).
+* @param deps - Interactivity + the confirm prompt.
+* @returns The provisioning result (all created/skipped), or {@link ABORTED} when the user declined.
+* @throws {Error} Re-throws a plan error, or throws on a provision failure, in CI / non-interactive runs.
+* @example
+* ```ts
+* const provisioned = await guidedProvision(ctx, manifest, ci, deps);
+* if (provisioned === ABORTED) return;
+* ```
+*/
+const guidedProvision = async (ctx, manifest, ci, deps) => {
+	for (;;) {
+		const plan = await guidedPlan(ctx, manifest, deps);
+		if (plan === ABORTED) return ABORTED;
+		const ui = createBrandConsole();
+		renderPlan(ui, plan);
+		if (plan.missing.length > 0 && !await deps.confirm(`Create ${String(plan.missing.length)} missing resource(s) in "${plan.account}"?`)) return ABORTED;
+		const result = await applyPlan(ctx, plan, ci);
+		renderProvisionResult(ui, result);
+		if (result.failed.length === 0) return result;
+		if (!deps.interactive) throw new Error(`[moku-worker] ${String(result.failed.length)} resource(s) failed to provision.`);
+		if (!await deps.confirm("Retry the failed resource(s)?")) return ABORTED;
+	}
+};
+/**
+* Build the web site first (when a hook is wired in), so its assets exist before the R2 upload and
+* `wrangler deploy`. Emits the `build · web` phase, then runs the build with interactive retry.
+*
+* @param ctx - The deploy plugin context.
+* @param webBuild - The web build hook, or undefined when none is wired (then this is a no-op).
+* @param deps - Interactivity + the confirm prompt.
+* @returns True to continue the pipeline; false when the user declined a build retry (abort).
+* @example
+* ```ts
+* if (!(await guidedWebBuild(ctx, webBuild, deps))) return emitAborted(ctx);
+* ```
+*/
+const guidedWebBuild = async (ctx, webBuild, deps) => {
+	if (webBuild === void 0) return true;
+	ctx.emit("deploy:phase", {
+		phase: "build",
+		detail: "web"
+	});
+	return await guidedStep(() => webBuild(), HINTS.build, deps) !== ABORTED;
+};
+/**
+* Upload the R2 directory when a bucket declares an upload source, with interactive retry. Emits the
+* `upload · N files` phase on success; a no-op (and emits nothing) when no bucket declares an upload.
+*
+* @param ctx - The deploy plugin context.
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @param deps - Interactivity + the confirm prompt.
+* @returns True to continue the pipeline; false when the user declined an upload retry (abort).
+* @example
+* ```ts
+* if (!(await guidedUpload(ctx, manifest, deps))) return emitAborted(ctx);
+* ```
+*/
+const guidedUpload = async (ctx, manifest, deps) => {
+	const r2 = manifest.resources.find((resource) => resource.kind === "r2");
+	if (!r2?.upload) return true;
+	const bucket = r2.name;
+	const uploadDir = r2.upload;
+	const count = await guidedStep(() => uploadDirToR2(bucket, uploadDir), HINTS.upload, deps);
+	if (count === ABORTED) return false;
+	ctx.emit("deploy:phase", {
+		phase: "upload",
+		detail: `${String(count)} files`
+	});
+	return true;
+};
+/**
 * Create the deploy api. Assembles the manifest from each resource plugin's own deployManifest(),
 * runs an infra preflight (check-before-create + id capture), generates config, uploads, and runs
 * `wrangler deploy`, emitting global deploy events along the way.
@@ -2333,10 +3065,16 @@ const createDeployApi = (ctx) => ({
 	* missing) → wrangler-config (with real ids) → upload → deploy. When opts.manifest is supplied
 	* it is used verbatim (universal path).
 	*
+	* On a TTY the run is GUIDED end to end: each gate is confirmed, and every failure is recovered
+	* interactively rather than thrown — a missing/invalid token offers `auth setup`, and the build,
+	* infra, upload, and `wrangler deploy` steps offer a retry. In CI/pipes it fails fast (no prompt,
+	* the first error propagates to the branded CLI handler).
+	*
 	* @param opts - Optional run options.
-	* @param opts.ci - CI/automated mode: never prompts, auto-confirms every gate. When false (the
-	*   default) and stdout is a TTY, the deploy is guided — each gate is confirmed interactively.
-	*   Falls back to ctx.config.ci when omitted.
+	* @param opts.ci - CI/automated mode: never prompts, auto-confirms every gate, fails fast. When
+	*   false (the default) and stdout is a TTY, the deploy is guided — each gate is confirmed and
+	*   failures are recovered interactively. Falls back to ctx.config.ci when omitted.
+	* @param opts.stage - Target stage; suffixes resource names (`production` = bare). Falls back to the app stage.
 	* @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
 	* @param opts.manifest - Caller-supplied manifest (bypasses deployManifest() assembly).
 	* @returns Resolves once the deploy completes.
@@ -2348,46 +3086,32 @@ const createDeployApi = (ctx) => ({
 	*/
 	async run(opts) {
 		const ci = opts?.ci ?? ctx.config.ci;
-		const confirm = !ci && stdoutIsTty() ? createBrandPrompts().confirm : async (_question) => true;
+		const stage = opts?.stage ?? ctx.global.stage;
+		const interactive = !ci && stdoutIsTty();
+		const confirm = interactive ? createBrandPrompts().confirm : async (_question) => true;
+		const deps = {
+			interactive,
+			confirm
+		};
 		ctx.emit("deploy:phase", { phase: "auth" });
-		await verifyAuth(ctx);
-		const webBuild = opts?.webBuild ?? ctx.config.webBuild;
-		if (webBuild !== void 0) {
-			ctx.emit("deploy:phase", {
-				phase: "build",
-				detail: "web"
-			});
-			await webBuild();
-		}
+		if (!await guidedAuth(ctx, deps)) return emitAborted(ctx);
+		if (!await guidedWebBuild(ctx, opts?.webBuild ?? ctx.config.webBuild, deps)) return emitAborted(ctx);
 		ctx.emit("deploy:phase", { phase: "detect" });
-		const manifest = opts?.manifest ?? assembleManifest(ctx);
+		const manifest = opts?.manifest ?? assembleManifest(ctx, stage);
 		ctx.emit("deploy:phase", { phase: "provision" });
-		const plan = await planInfra(ctx, manifest);
-		if (plan.missing.length > 0 && !await confirm(`Create ${plan.missing.length} missing resource(s) in "${plan.account}"?`)) {
-			ctx.emit("deploy:phase", { phase: "aborted" });
-			return;
-		}
-		const { ids } = await applyPlan(ctx, plan, ci);
+		const provisioned = await guidedProvision(ctx, manifest, ci, deps);
+		if (provisioned === ABORTED) return emitAborted(ctx);
 		ctx.emit("deploy:phase", { phase: "wrangler-config" });
-		await writeWranglerConfig(ctx.config.configFile, manifest, ids);
-		const r2Resource = manifest.resources.find((resource) => resource.kind === "r2");
-		if (r2Resource?.upload) {
-			const count = await uploadDirToR2(r2Resource.bucket, r2Resource.upload);
-			ctx.emit("deploy:phase", {
-				phase: "upload",
-				detail: `${String(count)} files`
-			});
-		}
-		if (!await confirm(`Deploy "${manifest.name}" to ${ctx.global.stage}?`)) {
-			ctx.emit("deploy:phase", { phase: "aborted" });
-			return;
-		}
+		await writeWranglerConfig(ctx.config.configFile, manifest, provisioned.ids, wranglerExtra(ctx.config));
+		if (!await guidedUpload(ctx, manifest, deps)) return emitAborted(ctx);
+		if (!await confirm(`Deploy "${manifest.name}" to ${stage}?`)) return emitAborted(ctx);
 		ctx.emit("deploy:phase", { phase: "deploy" });
-		const url = await runWrangler([
+		const url = await guidedStep(() => runWrangler([
 			"deploy",
 			"--config",
 			ctx.config.configFile
-		]);
+		]), HINTS.deploy, deps);
+		if (url === ABORTED) return emitAborted(ctx);
 		ctx.emit("deploy:complete", { url });
 	},
 	/**
@@ -2397,6 +3121,7 @@ const createDeployApi = (ctx) => ({
 	*
 	* @param opts - Optional options.
 	* @param opts.port - Local dev port (default 8787).
+	* @param opts.stage - Stage for the generated config's resource names (defaults to the app stage).
 	* @param opts.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
 	* @returns Resolves when the dev session ends.
 	* @example
@@ -2404,7 +3129,11 @@ const createDeployApi = (ctx) => ({
 	* await api.dev({ port: 8787, webBuild: () => web.cli.build() });
 	* ```
 	*/
-	dev: (opts) => runDev(ctx, opts, realDevDeps()),
+	async dev(opts) {
+		const manifest = assembleManifest(ctx, opts?.stage ?? ctx.global.stage);
+		await writeWranglerConfig(ctx.config.configFile, manifest, {}, wranglerExtra(ctx.config));
+		await runDev(ctx, opts, realDevDeps());
+	},
 	/**
 	* Scaffold a starting wrangler config (and CI files when ci is set).
 	* Idempotent: an existing config file is left untouched.
@@ -2430,7 +3159,7 @@ const createDeployApi = (ctx) => ({
 	* const plan = await api.checkInfra();
 	* ```
 	*/
-	checkInfra: () => planInfra(ctx, assembleManifest(ctx)),
+	checkInfra: () => planInfra(ctx, assembleManifest(ctx, ctx.global.stage)),
 	/**
 	* Create only the resources missing from the plan (skipping existing), capturing each id.
 	*
@@ -2462,7 +3191,19 @@ const createDeployApi = (ctx) => ({
 	* const { toAdd } = api.requiredToken();
 	* ```
 	*/
-	requiredToken: () => requiredToken(assembleManifest(ctx)),
+	requiredToken: () => requiredToken(assembleManifest(ctx, ctx.global.stage)),
+	/**
+	* Derive the REDUCED CI/automation redeploy token permission groups from the manifest (pure, no
+	* network). Used by the branded `auth setup` renderer to show the scoped CI token alongside the
+	* full LOCAL one.
+	*
+	* @returns The CI token permission groups (read-mostly, manifest-scoped).
+	* @example
+	* ```ts
+	* const groups = api.ciToken();
+	* ```
+	*/
+	ciToken: () => ciToken(assembleManifest(ctx, ctx.global.stage)),
 	/**
 	* Render the `auth setup` guidance from the derived token requirement (pure, no network).
 	*
@@ -2472,7 +3213,7 @@ const createDeployApi = (ctx) => ({
 	* const text = api.tokenInstructions();
 	* ```
 	*/
-	tokenInstructions: () => tokenInstructions(assembleManifest(ctx)),
+	tokenInstructions: () => tokenInstructions(assembleManifest(ctx, ctx.global.stage)),
 	/**
 	* Run an arbitrary wrangler command, streaming its output (the branded CLI escape hatch).
 	*
@@ -2568,6 +3309,45 @@ const parsePortArg = (argv) => {
 		if (Number.isInteger(port) && port > 0 && port <= MAX_PORT) return port;
 	}
 };
+/**
+* Extract a `--stage` value from a single token (and the token after it, for the spaced form).
+*
+* @param token - The current argv token.
+* @param next - The following argv token (the value, for the `--stage dev` spaced form).
+* @returns The raw string value when this token is a stage flag, else undefined.
+* @example
+* ```ts
+* stageValueFrom("--stage=dev", undefined); // "dev"
+* stageValueFrom("--stage", "dev");         // "dev"
+* stageValueFrom("--port", "3000");         // undefined
+* ```
+*/
+const stageValueFrom = (token, next) => {
+	const inline = /^--stage=(.+)$/u.exec(token);
+	if (inline) return inline[1];
+	if (token === "--stage") return next;
+};
+/**
+* Parse a `--stage <name>` / `--stage=<name>` flag out of an argv array — the deploy/dev stage that
+* drives the resource-name suffix (e.g. `tracker-db-dev`). Returns the first non-empty value, or
+* undefined so the caller can fall back to the app's configured stage.
+*
+* @param argv - The argv array to scan (the caller passes the process argv).
+* @returns The parsed stage string, or undefined when no `--stage` flag is present.
+* @example
+* ```ts
+* parseStageArg(["bun", "scripts/deploy.ts", "--stage", "dev"]); // "dev"
+* parseStageArg(["bun", "scripts/deploy.ts"]);                    // undefined
+* ```
+*/
+const parseStageArg = (argv) => {
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index];
+		if (token === void 0) continue;
+		const raw = stageValueFrom(token, argv[index + 1]);
+		if (raw !== void 0 && raw.length > 0) return raw;
+	}
+};
 //#endregion
 //#region src/plugins/cli/api.ts
 /**
@@ -2596,6 +3376,7 @@ const createCliApi = (ctx) => ({
 	*
 	* @param opts - Optional local dev options.
 	* @param opts.port - Local dev port to bind. Overrides the `--port` flag and the default.
+	* @param opts.stage - Stage for the generated wrangler config; falls back to `--stage` then the app stage.
 	* @param opts.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
 	* @returns Resolves when the dev session ends.
 	* @example
@@ -2610,11 +3391,13 @@ const createCliApi = (ctx) => ({
 			label: "dev session"
 		});
 		const port = opts?.port ?? parsePortArg(process.argv) ?? ctx.config.port;
+		const stage = opts?.stage ?? parseStageArg(process.argv);
 		try {
-			await ctx.require(deployPlugin).dev(opts?.webBuild ? {
+			await ctx.require(deployPlugin).dev({
 				port,
-				webBuild: opts.webBuild
-			} : { port });
+				...stage === void 0 ? {} : { stage },
+				...opts?.webBuild ? { webBuild: opts.webBuild } : {}
+			});
 			ui.check(true, "dev session stopped cleanly");
 		} catch (error) {
 			ui.error(error instanceof Error ? error.message : String(error));
@@ -2629,17 +3412,22 @@ const createCliApi = (ctx) => ({
 	*
 	* @param opts - Optional deploy options.
 	* @param opts.ci - Automated mode: never prompts, auto-confirms. Omit/false → guided on a TTY.
+	* @param opts.stage - Target stage (resource-name suffix); falls back to `--stage` then the app stage.
 	* @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
 	* @returns Resolves once the deploy completes (or after a failure is rendered).
 	* @example
 	* ```ts
-	* await api.deploy({ webBuild: () => web.cli.build() });           // guided
-	* await api.deploy({ ci: true, webBuild: () => web.cli.build() }); // CI
+	* await api.deploy({ webBuild: () => web.cli.build() });            // guided, app stage
+	* await api.deploy({ ci: true, webBuild: () => web.cli.build() });  // CI; `--stage dev` honored
 	* ```
 	*/
 	async deploy(opts) {
+		const stage = opts?.stage ?? parseStageArg(process.argv);
 		try {
-			await ctx.require(deployPlugin).run(opts);
+			await ctx.require(deployPlugin).run({
+				...opts,
+				...stage === void 0 ? {} : { stage }
+			});
 		} catch (error) {
 			createBrandConsole().error(error instanceof Error ? error.message : String(error));
 			process.exitCode = 1;
@@ -2661,7 +3449,7 @@ const createCliApi = (ctx) => ({
 		const deploy = ctx.require(deployPlugin);
 		const ui = createBrandConsole();
 		if (sub === "setup") {
-			for (const line of deploy.tokenInstructions().split("\n")) ui.line(line);
+			renderAuthSetup(ui, deploy.requiredToken(), { ci: deploy.ciToken() });
 			return;
 		}
 		try {
@@ -2749,12 +3537,12 @@ const WRANGLER_DIVIDER = `  ── wrangler ${"─".repeat(48)}`;
 * never block the deploy pipeline (fire-and-forget, spec/07 §3,§4).
 *
 * @param ctx - CLI plugin context with injected log core API.
-* @returns Hook map for the three global deploy events.
+* @returns Hook map for the deploy/dev phase + completion events (provision detail is panel-rendered).
 * @example
 * ```ts
 * const hooks = createCliHooks(ctx);
 * hooks["deploy:phase"]({ phase: "detect" }); // logs "detect" → renders "  › detect"
-* hooks["provision:resource"]({ kind: "kv", name: "KV" }); // logs "kv KV" → "  › kv KV"
+* hooks["dev:phase"]({ phase: "serve", detail: "http://localhost:8787" }); // "serve · …"
 * hooks["deploy:complete"]({ url: "https://x.workers.dev" }); // "deployed → https://x.workers.dev"
 * ```
 */
@@ -2775,42 +3563,6 @@ const createCliHooks = (ctx) => {
 			ctx.log.info(p.detail ? `${p.phase} · ${p.detail}` : p.phase);
 		},
 		/**
-		* Log the infra preflight summary: "infra · N exist, M to create · account".
-		*
-		* @param p - The provision:plan event payload.
-		* @example
-		* ```ts
-		* handler({ exists: 2, missing: 1, account: "Play Co" }); // "infra · 2 exist, 1 to create · Play Co"
-		* ```
-		*/
-		"provision:plan"(p) {
-			ctx.log.info(`infra · ${p.exists} exist, ${p.missing} to create · ${p.account}`);
-		},
-		/**
-		* Log one clean line per provisioned resource: "kind name".
-		*
-		* @param p - The provision:resource event payload.
-		* @example
-		* ```ts
-		* handler({ kind: "kv", name: "KV" }); // "kv KV"
-		* ```
-		*/
-		"provision:resource"(p) {
-			ctx.log.info(`${p.kind} ${p.name}`);
-		},
-		/**
-		* Log one clean line per already-existing resource (skipped): "kind name (exists)".
-		*
-		* @param p - The provision:skip event payload.
-		* @example
-		* ```ts
-		* handler({ kind: "kv", name: "KV" }); // "kv KV (exists)"
-		* ```
-		*/
-		"provision:skip"(p) {
-			ctx.log.info(`${p.kind} ${p.name} (exists)`);
-		},
-		/**
 		* Log one dev-session phase: "phase" or "phase · detail".
 		*
 		* @param p - The dev:phase event payload.