makefx 1.0.5 → 1.0.7

package/makefx.mjs

@@ -844,7 +844,7 @@ function validateProjectConfig(config, configPath) {
 *   makefx spaces inspect-deleted <space_id>  Inspect a soft-deleted space
 *   makefx spaces restore <space_id> Restore a soft-deleted space
 */
-var defaultDeps$9 = {
+var defaultDeps$10 = {
 	loadConfig: loadStoredConfig,
 	resolveBaseUrl,
 	saveProjectConfig,
@@ -859,7 +859,7 @@ async function handleSpaces(parsed) {
 		process$1.exitCode = 1;
 	}
 }
-async function executeSpaces(parsed, deps = defaultDeps$9) {
+async function executeSpaces(parsed, deps = defaultDeps$10) {
 	const env = resolveCommandEnvironment(parsed);
 	const showDetails = parsed.options.details === "true";
 	const spaceId = parsed.options.id;
@@ -5386,7 +5386,7 @@ function isMirrorEntry(value) {
 *   makefx upload <file> --space <id> --name <name>    Upload as new asset
 *   makefx upload <file> --space <id> --name <name> --type <type>
 */
-var defaultDeps$8 = {
+var defaultDeps$9 = {
 	loadConfig: loadStoredConfig,
 	loadProjectConfig,
 	resolveBaseUrl,
@@ -5415,11 +5415,11 @@ async function handleUpload(parsed) {
 		await executeUpload(parsed);
 	} catch (error) {
 		console.error(error instanceof Error ? `Error: ${error.message}` : "Error: Upload failed");
-		if (error instanceof UploadUsageError) printUsage$8();
+		if (error instanceof UploadUsageError) printUsage$9();
 		process$1.exitCode = 1;
 	}
 }
-async function executeUpload(parsed, deps = defaultDeps$8) {
+async function executeUpload(parsed, deps = defaultDeps$9) {
 	const filePath = parsed.positionals[0];
 	if (!filePath) throw new UploadUsageError("File path is required");
 	rejectRetiredUploadOrganizationOptions(parsed);
@@ -5454,17 +5454,11 @@ async function executeUpload(parsed, deps = defaultDeps$8) {
 	if (config.token.expiresAt < Date.now()) throw new Error(`Token expired for ${env} environment. Run: ${loginCommandForEnvironment(env)}`);
 	const baseUrl = deps.resolveBaseUrl(env);
 	const accessToken = config.token.accessToken;
-	const ctx = {
-		spaceId,
-		baseUrl,
-		accessToken
-	};
 	if (env === "local") process$1.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
 	try {
 		const fileStat = await deps.stat(filePath);
 		if (!fileStat.isFile()) throw new Error(`"${filePath}" is not a file`);
 		if (fileStat.size > 10485760) throw new Error(`File too large (${(fileStat.size / 1024 / 1024).toFixed(2)}MB). Maximum size: 10MB`);
-		await preflightSourceVariants(ctx, deps, sourceVariantIds);
 		const fileBuffer = await deps.readFile(filePath);
 		const fileName = path.basename(filePath);
 		const formData = new FormData();
@@ -5605,30 +5599,7 @@ function parseCsvOption(value, optionName) {
 	if (value === "true") throw new UploadUsageError(`${optionName} requires a value`);
 	return value.split(",").map((entry) => entry.trim()).filter(Boolean);
 }
-async function preflightSourceVariants(ctx, deps, sourceVariantIds) {
-	if (sourceVariantIds.length === 0) return;
-	const state = await fetchVariantState(ctx, deps);
-	for (const sourceVariantId of sourceVariantIds) if (!state.variantsById.has(sourceVariantId)) throw new Error(`Source variant not found in space: ${sourceVariantId}`);
-}
-async function fetchVariantState(ctx, deps) {
-	const assets = (await fetchJson$1(ctx, deps, `/api/spaces/${ctx.spaceId}/assets`)).assets ?? [];
-	const variantsById = /* @__PURE__ */ new Map();
-	await Promise.all(assets.map(async (asset) => {
-		const details = await fetchJson$1(ctx, deps, `/api/spaces/${ctx.spaceId}/assets/${encodeURIComponent(asset.id)}`);
-		for (const variant of details.variants ?? []) variantsById.set(variant.id, variant);
-	}));
-	return { variantsById };
-}
-async function fetchJson$1(ctx, deps, requestPath) {
-	const response = await deps.fetch(`${ctx.baseUrl}${requestPath}`, { headers: {
-		Authorization: `Bearer ${ctx.accessToken}`,
-		Accept: "application/json"
-	} });
-	const data = await response.json().catch(() => ({}));
-	if (!response.ok) throw new Error("error" in data ? data.error : `Request failed: ${response.status}`);
-	return data;
-}
-function printUsage$8() {
+function printUsage$9() {
 	console.log(`
 Usage:
   makefx upload <file> --asset <id> [--space <id>]     Upload media to existing asset
@@ -5945,6 +5916,15 @@ var ServerConfirmationTimeoutError = class extends Error {
 		this.name = "ServerConfirmationTimeoutError";
 	}
 };
+function collectionItemMatchesInput(item, input) {
+	if (item.subject_type !== input.subjectType) return false;
+	if (input.subjectType === "asset" && item.asset_id !== input.assetId) return false;
+	if (input.subjectType === "variant" && item.variant_id !== input.variantId) return false;
+	if (input.role !== void 0 && item.role !== input.role) return false;
+	if (input.pinnedVariantId !== void 0 && item.pinned_variant_id !== input.pinnedVariantId) return false;
+	if (input.sortIndex !== void 0 && item.sort_index !== input.sortIndex) return false;
+	return true;
+}
 var WebSocketClient = class WebSocketClient {
 	ws = null;
 	baseUrl;
@@ -6248,9 +6228,9 @@ var WebSocketClient = class WebSocketClient {
 			case "error": {
 				const errorMsg = message;
 				const error = /* @__PURE__ */ new Error(`${errorMsg.code}: ${errorMsg.message}`);
-				const mutationConsumed = this.failMutationWaiters(error);
-				const estimateConsumed = this.failEstimateHandlers(error);
-				if (!(mutationConsumed || estimateConsumed)) {
+				const requestConsumed = errorMsg.requestId ? this.failRequestHandler(errorMsg.requestId, error) : false;
+				const mutationConsumed = requestConsumed ? false : this.failMutationWaiters(error);
+				if (!requestConsumed && !mutationConsumed) {
 					console.error(`Server error: ${formatServerErrorMessage(errorMsg.code, errorMsg.message)}`);
 					this.onError?.(new Error(errorMsg.message));
 				}
@@ -6315,14 +6295,36 @@ var WebSocketClient = class WebSocketClient {
 		}
 		return true;
 	}
-	failEstimateHandlers(error) {
-		if (this.estimateHandlers.size === 0) return false;
-		for (const [requestId, handler] of this.estimateHandlers) {
-			clearTimeout(handler.timeout);
+	failRequestHandler(requestId, error) {
+		const estimateHandler = this.estimateHandlers.get(requestId);
+		if (estimateHandler) {
 			this.estimateHandlers.delete(requestId);
+			clearTimeout(estimateHandler.timeout);
+			estimateHandler.reject(error);
+			return true;
+		}
+		const generateHandler = this.generateHandlers.get(requestId);
+		if (generateHandler) {
+			this.generateHandlers.delete(requestId);
+			clearTimeout(generateHandler.timeout);
+			generateHandler.reject(error);
+			return true;
+		}
+		const batchHandler = this.batchHandlers.get(requestId);
+		if (batchHandler) {
+			this.batchHandlers.delete(requestId);
+			clearTimeout(batchHandler.timeout);
+			for (const variantId of batchHandler.pending) this.batchVariantToRequestId.delete(variantId);
+			batchHandler.reject(error);
+			return true;
+		}
+		for (const [variantId, handler] of this.variantCompletionHandlers) if (handler.requestId === requestId) {
+			this.variantCompletionHandlers.delete(variantId);
+			clearTimeout(handler.timeout);
 			handler.reject(error);
+			return true;
 		}
-		return true;
+		return false;
 	}
 	/**
 	* Send a mutation message and resolve when a matching broadcast arrives, or
@@ -6407,6 +6409,42 @@ var WebSocketClient = class WebSocketClient {
 			rating
 		}, (msg) => msg.type === "variant:updated" && msg.variant.id === variantId && msg.variant.quality_rating === rating)).variant;
 	}
+	async createCollection(input) {
+		const id = input.id ?? crypto.randomUUID();
+		return (await this.awaitServerMessage({
+			type: "collection:create",
+			...input,
+			id
+		}, (msg) => msg.type === "collection:created" && msg.collection.id === id)).collection;
+	}
+	async deleteCollection(collectionId) {
+		await this.awaitServerMessage({
+			type: "collection:delete",
+			collectionId
+		}, (msg) => msg.type === "collection:deleted" && msg.collectionId === collectionId);
+	}
+	async createCollectionItem(input) {
+		const id = input.id ?? crypto.randomUUID();
+		return (await this.awaitServerMessage({
+			type: "collection_item:create",
+			...input,
+			id
+		}, (msg) => msg.type === "collection_item:created" && msg.item.collection_id === input.collectionId && msg.item.id === id && collectionItemMatchesInput(msg.item, input))).item;
+	}
+	async deleteCollectionItem(collectionId, itemId) {
+		await this.awaitServerMessage({
+			type: "collection_item:delete",
+			collectionId,
+			itemId
+		}, (msg) => msg.type === "collection_item:deleted" && msg.collectionId === collectionId && msg.itemId === itemId);
+	}
+	async reorderCollectionItems(collectionId, itemIds) {
+		return (await this.awaitServerMessage({
+			type: "collection_items:reorder",
+			collectionId,
+			itemIds
+		}, (msg) => msg.type === "collection_items:reordered" && msg.collectionId === collectionId && itemIds.every((itemId, index) => msg.items[index]?.id === itemId))).items;
+	}
 	/**
 	* Send a message through the WebSocket
 	*/
@@ -6990,7 +7028,7 @@ var MEDIA_OPERATION_MATRIX = [
 		assetType: "speech",
 		promptNoun: "speech clip",
 		inheritsReferenceAssetType: false,
-		compatibleSlotMediaKinds: ["audio"],
+		compatibleSlotMediaKinds: [],
 		supportsBatch: true,
 		cliNamespace: "audio",
 		cliCommands: ["generate", "batch"],
@@ -7005,7 +7043,7 @@ var MEDIA_OPERATION_MATRIX = [
 		assetType: "dialogue",
 		promptNoun: "dialogue clip",
 		inheritsReferenceAssetType: false,
-		compatibleSlotMediaKinds: ["audio"],
+		compatibleSlotMediaKinds: [],
 		supportsBatch: true,
 		cliNamespace: "audio",
 		cliCommands: ["generate", "batch"],
@@ -7020,7 +7058,7 @@ var MEDIA_OPERATION_MATRIX = [
 		assetType: "music",
 		promptNoun: "music cue",
 		inheritsReferenceAssetType: false,
-		compatibleSlotMediaKinds: ["audio"],
+		compatibleSlotMediaKinds: [],
 		supportsBatch: true,
 		cliNamespace: "audio",
 		cliCommands: ["generate", "batch"],
@@ -7035,7 +7073,7 @@ var MEDIA_OPERATION_MATRIX = [
 		assetType: "sfx",
 		promptNoun: "sound effect",
 		inheritsReferenceAssetType: false,
-		compatibleSlotMediaKinds: ["audio"],
+		compatibleSlotMediaKinds: [],
 		supportsBatch: true,
 		cliNamespace: "audio",
 		cliCommands: ["generate", "batch"],
@@ -7101,7 +7139,7 @@ function cliGenerationSupportsRefs(namespace) {
 //#endregion
 //#region src/cli/commands/forge.ts
 var CLI_GENERATION_MEDIA_KIND = getCliGenerationMediaKind("top-level");
-var defaultDeps$7 = {
+var defaultDeps$8 = {
 	loadConfig: loadStoredConfig,
 	loadProjectConfig,
 	resolveBaseUrl,
@@ -7175,10 +7213,10 @@ async function handleBatch(parsed) {
 }
 async function handleForgeCommand(command, parsed) {
 	try {
-		await executeForgeCommand(command, parsed, defaultDeps$7);
+		await executeForgeCommand(command, parsed, defaultDeps$8);
 	} catch (error) {
 		console.error("Error:", error instanceof Error ? error.message : error);
-		if (shouldPrintUsageForForgeError(error)) printUsage$7(command);
+		if (shouldPrintUsageForForgeError(error)) printUsage$8(command);
 		process$1.exitCode = 1;
 	}
 }
@@ -7187,11 +7225,11 @@ function shouldPrintUsageForForgeError(error) {
 	const message = error.message;
 	return message.startsWith("--") || message.startsWith("Output path is required") || message.startsWith("Output directory is required") || message.startsWith("Pass either prompt text") || message.startsWith("Speech generation requires") || message.startsWith("Dialogue generation requires") || message.startsWith("Prompt is required");
 }
-async function executeForgeCommand(command, parsed, deps = defaultDeps$7, options = {}) {
+async function executeForgeCommand(command, parsed, deps = defaultDeps$8, options = {}) {
 	const mediaKind = options.mediaKind || CLI_GENERATION_MEDIA_KIND;
 	if (parsed.options.follow) {
 		if (command === "batch") throw new Error("--follow is only supported for single-output generation commands");
-		const ctx = await buildContext$4(parsed, deps);
+		const ctx = await buildContext$5(parsed, deps);
 		const client = await deps.createClient(ctx.env, ctx.spaceId);
 		try {
 			await client.connect();
@@ -7205,7 +7243,7 @@ async function executeForgeCommand(command, parsed, deps = defaultDeps$7, option
 	validateVideoAudioOptions(parsed, mediaKind);
 	parseVideoGenerationOptions(parsed, mediaKind);
 	validateVideoFrameReferenceOptions(command, parsed, mediaKind);
-	const ctx = await buildContext$4(parsed, deps);
+	const ctx = await buildContext$5(parsed, deps);
 	const client = await deps.createClient(ctx.env, ctx.spaceId);
 	try {
 		await client.connect();
@@ -7219,7 +7257,7 @@ async function executeForgeCommand(command, parsed, deps = defaultDeps$7, option
 		client.disconnect();
 	}
 }
-async function executeAudioCommand(command, parsed, deps = defaultDeps$7, options = {}) {
+async function executeAudioCommand(command, parsed, deps = defaultDeps$8, options = {}) {
 	const audioProfile = getCliGenerationProfile("audio");
 	if (!audioProfile.commands.includes(command)) throw new Error(`Audio generation does not support ${command}`);
 	const modeEntry = options.mode ? getMediaOperationEntry(options.mode) : void 0;
@@ -7232,7 +7270,7 @@ async function executeAudioCommand(command, parsed, deps = defaultDeps$7, option
 		audioMode: options.mode
 	});
 }
-async function executeVideoCommand(command, parsed, deps = defaultDeps$7) {
+async function executeVideoCommand(command, parsed, deps = defaultDeps$8) {
 	const videoProfile = getCliGenerationProfile("video");
 	if (!videoProfile.commands.includes(command)) throw new Error(`Video generation does not support ${command}`);
 	return executeForgeCommand(command, parsed, deps, {
@@ -7271,12 +7309,17 @@ async function executeGenerate(parsed, ctx, client, deps, mediaKind, followOptio
 	const musicProvider = parseMusicProviderOption(parsed, mediaKind, assetType);
 	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 	const videoFrameRefs = parseVideoFrameReferenceOptions(parsed, "generate", mediaKind).refs;
-	const state = videoFrameRefs.length > 0 ? await requestSpaceState(client) : void 0;
+	const state = videoFrameRefs.length > 0 ? await requestSpaceState$1(client) : void 0;
 	const referenceVariantIds = videoFrameRefs.length > 0 ? await resolveReferenceVariantIds(videoFrameRefs, ctx, deps, state?.variants, CLI_GENERATION_MEDIA_KIND) : [];
 	const imageOptions = parseImageGenerationOptions(parsed, mediaKind);
 	const audioModelOptions = parseAudioGenerationOptions(parsed, mediaKind);
 	const videoAudioOptions = parseVideoAudioOptions(parsed, mediaKind);
 	const videoOptions = parseVideoGenerationOptions(parsed, mediaKind);
+	const collectionPlacement = parseCollectionPlacementOptions(parsed);
+	const followCommandOptions = {
+		...followOptions,
+		...collectionPlacement
+	};
 	await printPreflightEstimate(client, {
 		operation: "generate",
 		assetType,
@@ -7309,7 +7352,7 @@ async function executeGenerate(parsed, ctx, client, deps, mediaKind, followOptio
 			...videoOptions,
 			onStarted: (started) => {
 				startedVariantId = started.jobId;
-				printFollowHint(started, ctx, outputPath, "generate", mediaKind, followOptions);
+				printFollowHint(started, ctx, outputPath, "generate", mediaKind, followCommandOptions);
 			}
 		});
 	} catch (error) {
@@ -7319,7 +7362,7 @@ async function executeGenerate(parsed, ctx, client, deps, mediaKind, followOptio
 			ctx,
 			command: "generate",
 			mediaKind,
-			followOptions
+			followOptions: followCommandOptions
 		});
 	}
 	const manifestPath = await saveGenerationManifest({
@@ -7336,6 +7379,7 @@ async function executeGenerate(parsed, ctx, client, deps, mediaKind, followOptio
 		refs: videoFrameRefs,
 		referenceVariantIds
 	});
+	await placeGeneratedAssetInCollection(result, ctx, deps, collectionPlacement);
 	await downloadResult(result, outputPath, ctx, deps);
 	printResult(result, outputPath, ctx, manifestPath);
 	return result;
@@ -7363,7 +7407,7 @@ async function executeRefine(parsed, ctx, client, deps, mediaKind) {
 	const prompt = getPrompt(parsed, "refine");
 	const outputPath = getOutputPath$1(parsed);
 	const sourceVariantId = requireOption$1(parsed, "variant");
-	const state = await requestSpaceState(client);
+	const state = await requestSpaceState$1(client);
 	const sourceVariant = state.variants.find((variant) => variant.id === sourceVariantId);
 	if (!sourceVariant) throw new Error(`Variant not found in space sync state: ${sourceVariantId}`);
 	const sourceAsset = state.assets.find((asset) => asset.id === sourceVariant.asset_id);
@@ -7371,6 +7415,8 @@ async function executeRefine(parsed, ctx, client, deps, mediaKind) {
 	const imageOptions = parseImageGenerationOptions(parsed, mediaKind);
 	const videoAudioOptions = parseVideoAudioOptions(parsed, mediaKind);
 	const videoOptions = parseVideoGenerationOptions(parsed, mediaKind);
+	const collectionPlacement = parseCollectionPlacementOptions(parsed);
+	const followCommandOptions = { ...collectionPlacement };
 	await printPreflightEstimate(client, {
 		operation: "refine",
 		assetId: sourceVariant.asset_id,
@@ -7398,7 +7444,7 @@ async function executeRefine(parsed, ctx, client, deps, mediaKind) {
 			...videoOptions,
 			onStarted: (started) => {
 				startedVariantId = started.jobId;
-				printFollowHint(started, ctx, outputPath, "refine", mediaKind);
+				printFollowHint(started, ctx, outputPath, "refine", mediaKind, followCommandOptions);
 			}
 		});
 	} catch (error) {
@@ -7407,7 +7453,8 @@ async function executeRefine(parsed, ctx, client, deps, mediaKind) {
 			outputPath,
 			ctx,
 			command: "refine",
-			mediaKind
+			mediaKind,
+			followOptions: followCommandOptions
 		});
 	}
 	const manifestPath = await saveGenerationManifest({
@@ -7424,6 +7471,7 @@ async function executeRefine(parsed, ctx, client, deps, mediaKind) {
 		refs: [sourceVariantId],
 		referenceVariantIds: [sourceVariantId]
 	});
+	await placeGeneratedAssetInCollection(result, ctx, deps, collectionPlacement);
 	await downloadResult(result, outputPath, ctx, deps);
 	printResult(result, outputPath, ctx, manifestPath);
 	return result;
@@ -7439,10 +7487,15 @@ async function executeDerive(parsed, ctx, client, deps, mediaKind, followOptions
 	if (referenceRefs.length === 0) throw new Error("--refs is required");
 	const imageOptions = parseImageGenerationOptions(parsed, mediaKind);
 	if (mediaKind === "image") validateImageReferenceCount(imageOptions.model, referenceRefs.length);
-	const referenceVariantIds = await resolveReferenceVariantIds(referenceRefs, ctx, deps, (await requestSpaceState(client)).variants, videoFrameRefs.length > 0 ? CLI_GENERATION_MEDIA_KIND : mediaKind);
+	const referenceVariantIds = await resolveReferenceVariantIds(referenceRefs, ctx, deps, (await requestSpaceState$1(client)).variants, videoFrameRefs.length > 0 ? CLI_GENERATION_MEDIA_KIND : mediaKind);
 	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 	const videoAudioOptions = parseVideoAudioOptions(parsed, mediaKind);
 	const videoOptions = parseVideoGenerationOptions(parsed, mediaKind);
+	const collectionPlacement = parseCollectionPlacementOptions(parsed);
+	const followCommandOptions = {
+		...followOptions,
+		...collectionPlacement
+	};
 	await printPreflightEstimate(client, {
 		operation: "derive",
 		assetType,
@@ -7470,7 +7523,7 @@ async function executeDerive(parsed, ctx, client, deps, mediaKind, followOptions
 			...videoOptions,
 			onStarted: (started) => {
 				startedVariantId = started.jobId;
-				printFollowHint(started, ctx, outputPath, "derive", mediaKind, followOptions);
+				printFollowHint(started, ctx, outputPath, "derive", mediaKind, followCommandOptions);
 			}
 		});
 	} catch (error) {
@@ -7480,7 +7533,7 @@ async function executeDerive(parsed, ctx, client, deps, mediaKind, followOptions
 			ctx,
 			command: "derive",
 			mediaKind,
-			followOptions
+			followOptions: followCommandOptions
 		});
 	}
 	const manifestPath = await saveGenerationManifest({
@@ -7497,6 +7550,7 @@ async function executeDerive(parsed, ctx, client, deps, mediaKind, followOptions
 		refs: referenceRefs,
 		referenceVariantIds
 	});
+	await placeGeneratedAssetInCollection(result, ctx, deps, collectionPlacement);
 	await downloadResult(result, outputPath, ctx, deps);
 	printResult(result, outputPath, ctx, manifestPath);
 	return result;
@@ -7506,8 +7560,13 @@ async function executeFollow(parsed, ctx, client, deps, command, mediaKind, foll
 	if (!variantId) throw new Error("--follow requires a variant ID");
 	const outputPath = getOutputPath$1(parsed);
 	const timeoutMs = parseFollowTimeoutMs(parsed, mediaKind);
+	const collectionPlacement = parseCollectionPlacementOptions(parsed);
+	const followCommandOptions = {
+		...followOptions,
+		...collectionPlacement
+	};
 	console.log(`Following variant ${variantId} in space ${ctx.spaceId}...`);
-	const state = await requestSpaceState(client);
+	const state = await requestSpaceState$1(client);
 	const initialVariant = state.variants.find((variant) => variant.id === variantId);
 	if (!initialVariant) throw new Error(`Variant not found in space sync state: ${variantId}`);
 	const initialStatus = initialVariant.status;
@@ -7527,7 +7586,7 @@ async function executeFollow(parsed, ctx, client, deps, command, mediaKind, foll
 				}
 			}
 		});
-		const refreshedVariant = (await requestSpaceState(client)).variants.find((variant) => variant.id === variantId);
+		const refreshedVariant = (await requestSpaceState$1(client)).variants.find((variant) => variant.id === variantId);
 		result = refreshedVariant ? resultFromTerminalVariant(refreshedVariant, requestId) : void 0;
 		if (result) client.cancelFollowVariant?.(variantId, requestId);
 		else try {
@@ -7539,7 +7598,7 @@ async function executeFollow(parsed, ctx, client, deps, command, mediaKind, foll
 				ctx,
 				command,
 				mediaKind,
-				followOptions
+				followOptions: followCommandOptions
 			});
 		}
 	}
@@ -7562,6 +7621,7 @@ async function executeFollow(parsed, ctx, client, deps, command, mediaKind, foll
 		referenceVariantIds
 	});
 	await downloadResult(result, outputPath, ctx, deps);
+	await placeGeneratedAssetInCollection(result, ctx, deps, collectionPlacement);
 	printResult(result, outputPath, ctx, manifestPath);
 	return result;
 }
@@ -7654,10 +7714,11 @@ async function executeBatch(parsed, ctx, client, deps, mediaKind, saveBatchManif
 	const imageOptions = parseImageGenerationOptions(parsed, mediaKind);
 	const audioModelOptions = parseAudioGenerationOptions(parsed, mediaKind);
 	if (mediaKind === "image") validateImageReferenceCount(imageOptions.model, refs.length);
-	const state = await requestSpaceState(client);
+	const state = await requestSpaceState$1(client);
 	const referenceVariantIds = refs.length > 0 ? await resolveReferenceVariantIds(refs, ctx, deps, state.variants, mediaKind) : void 0;
 	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 	const runId = deps.createRunId();
+	const collectionPlacement = parseCollectionPlacementOptions(parsed);
 	await printPreflightEstimate(client, {
 		operation: "batch",
 		assetType,
@@ -7696,6 +7757,7 @@ async function executeBatch(parsed, ctx, client, deps, mediaKind, saveBatchManif
 	}
 	const sortedVariants = [...result.variants].sort((a, b) => a.created_at - b.created_at);
 	const media = [];
+	await placeGeneratedBatchAssetsInCollection(result, ctx, deps, collectionPlacement);
 	for (let index = 0; index < sortedVariants.length; index += 1) {
 		const variant = sortedVariants[index];
 		const outputPath = path.join(outputDir, `${slugify(name)}-${String(index + 1).padStart(2, "0")}.${getOutputExtension(variant, mediaKind)}`);
@@ -7781,7 +7843,69 @@ async function saveGenerationManifest(input) {
 		failed: []
 	}, ctx.projectRoot);
 }
-async function buildContext$4(parsed, deps) {
+function parseCollectionPlacementOptions(parsed) {
+	const collectionId = normalizeCliOption(readOptionalOption(parsed, "collection", "collection") ?? readOptionalOption(parsed, "collection-id", "collectionId"));
+	if (parsed.options.collection !== void 0 || parsed.options.collectionId !== void 0 || parsed.options["collection-id"] !== void 0) {
+		if (!collectionId) throw new Error("--collection requires a collection ID");
+	}
+	return collectionId ? { collectionId } : {};
+}
+async function placeGeneratedAssetInCollection(result, ctx, deps, options) {
+	if (!options.collectionId || !result.success || !result.variant) return;
+	await createCollectionAssetItem({
+		ctx,
+		deps,
+		collectionId: options.collectionId,
+		assetId: result.variant.asset_id,
+		pinnedVariantId: result.variant.id
+	});
+}
+async function placeGeneratedBatchAssetsInCollection(result, ctx, deps, options) {
+	if (!options.collectionId || !result.success) return;
+	const firstVariantByAsset = /* @__PURE__ */ new Map();
+	for (const variant of [...result.variants].sort((a, b) => a.created_at - b.created_at)) if (!firstVariantByAsset.has(variant.asset_id)) firstVariantByAsset.set(variant.asset_id, variant);
+	for (const variant of firstVariantByAsset.values()) await createCollectionAssetItem({
+		ctx,
+		deps,
+		collectionId: options.collectionId,
+		assetId: variant.asset_id,
+		pinnedVariantId: variant.id
+	});
+}
+async function createCollectionAssetItem(input) {
+	const fetchImpl = input.deps.fetch ?? fetch;
+	const itemsUrl = `${input.ctx.baseUrl}/api/spaces/${encodeURIComponent(input.ctx.spaceId)}/collections/${encodeURIComponent(input.collectionId)}/items`;
+	const listResponse = await fetchImpl(itemsUrl, { headers: {
+		"Authorization": `Bearer ${input.ctx.accessToken}`,
+		"Accept": "application/json"
+	} });
+	if (!listResponse.ok) {
+		const errorText = await listResponse.text();
+		throw new Error(`Failed to inspect collection ${input.collectionId} (${listResponse.status}): ${errorText || listResponse.statusText}`);
+	}
+	const existing = await listResponse.json();
+	if (existing.items?.some((item) => item.asset_id === input.assetId)) return;
+	const sortIndex = Math.max(-1, ...(existing.items ?? []).map((item) => typeof item.sort_index === "number" && Number.isFinite(item.sort_index) ? item.sort_index : -1)) + 1;
+	const response = await fetchImpl(itemsUrl, {
+		method: "POST",
+		headers: {
+			"Authorization": `Bearer ${input.ctx.accessToken}`,
+			"Content-Type": "application/json",
+			"Accept": "application/json"
+		},
+		body: JSON.stringify({
+			subjectType: "asset",
+			assetId: input.assetId,
+			pinnedVariantId: input.pinnedVariantId,
+			sortIndex
+		})
+	});
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Failed to place asset ${input.assetId} in collection ${input.collectionId} (${response.status}): ${errorText || response.statusText}`);
+	}
+}
+async function buildContext$5(parsed, deps) {
 	const projectConfig = await deps.loadProjectConfig();
 	const env = resolveCommandEnvironment(parsed, projectConfig);
 	const spaceId = resolveCommandSpace(parsed, projectConfig);
@@ -7898,7 +8022,7 @@ function validateReferenceVariant(ref, variants, mediaKind) {
 		if (!variant.image_key && !variant.media_key) throw new Error(`Reference variant has no image or video media: ${ref}`);
 	}
 }
-function requestSpaceState(client) {
+function requestSpaceState$1(client) {
 	return new Promise((resolve, reject) => {
 		const timer = setTimeout(() => {
 			reject(/* @__PURE__ */ new Error("Timed out waiting for space sync state"));
@@ -7951,12 +8075,13 @@ function printFollowHint(started, ctx, outputPath, command, mediaKind, options =
 }
 function throwGenerationWaitErrorIfNeeded(input, params) {
 	if (!isGenerationWaitTimeout(input)) throw input;
-	if (!params.variantId) throw new Error(["Make Effects did not confirm the generation start before the CLI stopped waiting.", "Check the Space in the web app before retrying, so you do not create a duplicate."].join("\n"));
+	if (!params.variantId) throw new Error(["The CLI timed out before Make Effects returned a variant ID.", "The generation may still have started. Check the Space in the web app before retrying, so you do not create a duplicate."].join("\n"));
 	const followCommand = formatFollowCommand(params.variantId, params.outputPath, params.ctx, params.command, params.mediaKind, params.followOptions);
 	throw new Error([
-		"Still generating in Make Effects.",
+		"The CLI stopped waiting, but the Make Effects generation job is still running.",
+		"Do not retry this generation unless you want a duplicate asset.",
 		"",
-		"Resume the download when the variant is ready:",
+		"Resume the same job and download the variant when it is ready:",
 		`  ${followCommand}`,
 		"",
 		`Variant: ${params.variantId}`
@@ -7964,7 +8089,7 @@ function throwGenerationWaitErrorIfNeeded(input, params) {
 }
 function throwBatchWaitErrorIfNeeded(input, started, ctx) {
 	if (!isBatchWaitTimeout(input)) throw input;
-	if (!started) throw new Error(["Make Effects did not confirm the batch start before the CLI stopped waiting.", "Check the Space in the web app before retrying, so you do not create duplicate assets."].join("\n"));
+	if (!started) throw new Error(["The CLI timed out before Make Effects returned batch variant IDs.", "The batch may still have started. Check the Space in the web app before retrying, so you do not create duplicate assets."].join("\n"));
 	const downloadExample = [
 		"makefx assets download <variant_id> -o <file>",
 		...ctx.env === "local" ? ["--local"] : ["--env", ctx.env],
@@ -7972,7 +8097,8 @@ function throwBatchWaitErrorIfNeeded(input, started, ctx) {
 		ctx.spaceId
 	].join(" ");
 	throw new Error([
-		"Batch generation is still running in Make Effects.",
+		"The CLI stopped waiting, but the Make Effects batch jobs are still running.",
+		"Do not retry this batch unless you want duplicate assets.",
 		"",
 		`Started variants: ${started.jobIds.join(", ")}`,
 		"",
@@ -7999,6 +8125,7 @@ function formatFollowCommand(variantId, outputPath, ctx, command, mediaKind, opt
 		command
 	] : ["makefx", command];
 	const envArgs = ctx.env === "local" ? ["--local"] : ["--env", ctx.env];
+	const collectionArgs = options.collectionId ? ["--collection", options.collectionId] : [];
 	return [
 		...baseCommand,
 		"--follow",
@@ -8007,7 +8134,8 @@ function formatFollowCommand(variantId, outputPath, ctx, command, mediaKind, opt
 		outputPath,
 		...envArgs,
 		"--space",
-		ctx.spaceId
+		ctx.spaceId,
+		...collectionArgs
 	].map(shellQuote).join(" ");
 }
 function shellQuote(value) {
@@ -8250,34 +8378,34 @@ function cliImageSizeValues() {
 function cliImageAspectValues() {
 	return cliOptionValues(getImageModelCapabilities().supportedAspectRatios);
 }
-function printUsage$7(command) {
+function printUsage$8(command) {
 	if (command === "generate") {
 		console.log(`
 Usage:
-  makefx generate "prompt" --name <name> --type <type> -o <file> [--model pro|flash] [--size ${cliImageSizeValues()}] [--aspect ${cliImageAspectValues()}] [--space <id>]
-  makefx generate --follow <variant_id> -o <file> [--space <id>]
+  makefx generate "prompt" --name <name> --type <type> -o <file> [--model pro|flash] [--size ${cliImageSizeValues()}] [--aspect ${cliImageAspectValues()}] [--collection <id>] [--space <id>]
+  makefx generate --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
 `);
 		return;
 	}
 	if (command === "refine") {
 		console.log(`
 Usage:
-  makefx refine --variant <variant_id> "prompt" -o <file> [--model pro|flash] [--size ${cliImageSizeValues()}] [--aspect ${cliImageAspectValues()}] [--space <id>]
-  makefx refine --follow <variant_id> -o <file> [--space <id>]
+  makefx refine --variant <variant_id> "prompt" -o <file> [--model pro|flash] [--size ${cliImageSizeValues()}] [--aspect ${cliImageAspectValues()}] [--collection <id>] [--space <id>]
+  makefx refine --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
 `);
 		return;
 	}
 	if (command === "batch") {
 		console.log(`
 Usage:
-  makefx batch "prompt" --name <name> --type <type> --count <2-8> --output-dir <dir> [--model pro|flash] [--size ${cliImageSizeValues()}] [--aspect ${cliImageAspectValues()}]
+  makefx batch "prompt" --name <name> --type <type> --count <2-8> --output-dir <dir> [--model pro|flash] [--size ${cliImageSizeValues()}] [--aspect ${cliImageAspectValues()}] [--collection <id>]
 `);
 		return;
 	}
 	console.log(`
 Usage:
-  makefx derive --refs <variant_or_file,variant_or_file> --name <name> --type <type> "prompt" -o <file> [--model pro|flash] [--size ${cliImageSizeValues()}] [--aspect ${cliImageAspectValues()}] [--space <id>]
-  makefx derive --follow <variant_id> -o <file> [--space <id>]
+  makefx derive --refs <variant_or_file,variant_or_file> --name <name> --type <type> "prompt" -o <file> [--model pro|flash] [--size ${cliImageSizeValues()}] [--aspect ${cliImageAspectValues()}] [--collection <id>] [--space <id>]
+  makefx derive --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
 `);
 }
 function printBatchResult(result, outputDir, manifestPath, ctx, mediaKind) {
@@ -8291,7 +8419,7 @@ function printBatchResult(result, outputDir, manifestPath, ctx, mediaKind) {
 }
 //#endregion
 //#region src/cli/commands/audio.ts
-var defaultDeps$6 = {
+var defaultDeps$7 = {
 	loadConfig: loadStoredConfig,
 	loadProjectConfig,
 	resolveBaseUrl,
@@ -8304,11 +8432,11 @@ async function handleAudio(parsed) {
 		await executeAudio(parsed);
 	} catch (error) {
 		console.error("Error:", error instanceof Error ? error.message : error);
-		printUsage$6();
+		printUsage$7();
 		process$1.exitCode = 1;
 	}
 }
-async function executeAudio(parsed, deps = defaultDeps$6) {
+async function executeAudio(parsed, deps = defaultDeps$7) {
 	const invocation = parseAudioInvocation(parsed.positionals);
 	if (invocation.command === "voices") return executeAudioVoices({
 		...parsed,
@@ -8381,7 +8509,7 @@ function printVoices(response, print) {
 function formatLabels(labels) {
 	return Object.entries(labels).map(([key, value]) => `${key}:${value}`).join(", ");
 }
-function printUsage$6() {
+function printUsage$7() {
 	const modes = AUDIO_FORGE_MEDIA_MODES.join("|");
 	console.log(`
 Usage:
@@ -8410,7 +8538,7 @@ async function handleVideo(parsed) {
 		});
 	} catch (error) {
 		console.error("Error:", error instanceof Error ? error.message : error);
-		printUsage$5();
+		printUsage$6();
 		process$1.exitCode = 1;
 	}
 }
@@ -8419,7 +8547,7 @@ function parseVideoCommand(value) {
 	if (value && commands.includes(value)) return value;
 	throw new Error("Video command is required: generate, refine, or derive");
 }
-function printUsage$5() {
+function printUsage$6() {
 	const aspectValues = VIDEO_GENERATION_ASPECT_RATIOS.join("|");
 	const resolutionValues = Array.from(new Set(VIDEO_GENERATION_TIERS.flatMap((tier) => getVideoGenerationResolutionsForTier(tier)))).join("|");
 	const durationValues = VIDEO_GENERATION_DURATION_SECONDS.join("|");
@@ -8458,17 +8586,17 @@ Audio:
 }
 //#endregion
 //#region src/cli/commands/init.ts
-var defaultDeps$5 = { saveProjectConfig };
+var defaultDeps$6 = { saveProjectConfig };
 async function handleInit(parsed) {
 	try {
 		await executeInit(parsed);
 	} catch (error) {
 		console.error("Error:", error instanceof Error ? error.message : error);
-		printUsage$4();
+		printUsage$5();
 		process$1.exitCode = 1;
 	}
 }
-async function executeInit(parsed, deps = defaultDeps$5) {
+async function executeInit(parsed, deps = defaultDeps$6) {
 	const environment = resolveCommandEnvironment(parsed);
 	const spaceId = resolveCommandSpace(parsed);
 	if (!spaceId) throw new Error("--space is required");
@@ -8494,7 +8622,7 @@ async function executeInit(parsed, deps = defaultDeps$5) {
 		spaceId
 	};
 }
-function printUsage$4() {
+function printUsage$5() {
 	console.log(`
 Usage:
   makefx init --space <id> [--env production|stage|local]
@@ -8503,7 +8631,7 @@ Usage:
 }
 //#endregion
 //#region src/cli/commands/runs.ts
-var defaultDeps$4 = {
+var defaultDeps$5 = {
 	loadProjectConfig,
 	listRunManifests,
 	readRunManifest,
@@ -8516,11 +8644,11 @@ async function handleRuns(parsed) {
 		await executeRuns(parsed);
 	} catch (error) {
 		console.error("Error:", error instanceof Error ? error.message : error);
-		printUsage$3();
+		printUsage$4();
 		process$1.exitCode = 1;
 	}
 }
-async function executeRuns(parsed, deps = defaultDeps$4) {
+async function executeRuns(parsed, deps = defaultDeps$5) {
 	const projectConfig = await deps.loadProjectConfig();
 	if (!projectConfig?.projectRoot) throw new Error("Make Effects project config not found. Run: makefx init --space <id>");
 	requireDebugAcknowledgement(parsed);
@@ -8638,7 +8766,7 @@ function formatCreated(value) {
 	if (Number.isNaN(date.getTime())) return value;
 	return value.replace("T", " ").replace(/\.\d{3}Z$/, "Z").slice(0, 20);
 }
-function printUsage$3() {
+function printUsage$4() {
 	console.log(`
 Usage:
   makefx runs --debug
@@ -8653,7 +8781,7 @@ Local run manifests are debug-only artifacts, not a source of truth.
 }
 //#endregion
 //#region src/cli/commands/assets.ts
-var defaultDeps$3 = {
+var defaultDeps$4 = {
 	loadConfig: loadStoredConfig,
 	loadProjectConfig,
 	resolveBaseUrl,
@@ -8677,15 +8805,15 @@ async function handleAssets(parsed) {
 		await executeAssets(parsed);
 	} catch (error) {
 		console.error("Error:", error instanceof Error ? error.message : error);
-		printUsage$2();
+		printUsage$3();
 		process$1.exitCode = 1;
 	}
 }
-async function executeAssets(parsed, deps = defaultDeps$3) {
+async function executeAssets(parsed, deps = defaultDeps$4) {
 	const subcommand = parsed.positionals[0] || "list";
 	if (subcommand === "search") return searchAssets(parsed, deps);
 	if (subcommand === "clone") return cloneAsset(parsed, deps);
-	const ctx = await buildContext$3(parsed, deps);
+	const ctx = await buildContext$4(parsed, deps);
 	if (subcommand === "list") {
 		const assets = await listAssets(ctx, deps);
 		if (parsed.options.json === "true") deps.print(JSON.stringify(assets.map(toAssetJson), null, 2));
@@ -8711,13 +8839,21 @@ async function executeAssets(parsed, deps = defaultDeps$3) {
 		if (!ref) throw new Error("Variant ID or legacy image key is required: makefx assets download <variant-id-or-legacy-image-key> -o <file>");
 		const outputPath = getOutputPath(parsed);
 		const resolved = resolveDownloadRef(ref, ctx);
-		const metadata = getDownloadedVariantMetadata(resolved, await deps.downloadFile({
-			baseUrl: ctx.baseUrl,
-			accessToken: ctx.accessToken,
-			requestPath: resolved.requestPath,
-			outputPath,
-			force: ctx.force
-		}));
+		let download;
+		try {
+			download = await deps.downloadFile({
+				baseUrl: ctx.baseUrl,
+				accessToken: ctx.accessToken,
+				requestPath: resolved.requestPath,
+				outputPath,
+				force: ctx.force
+			});
+		} catch (error) {
+			const failedVariantMessage = await getFailedDownloadVariantMessage(error, resolved, ctx, deps);
+			if (failedVariantMessage) throw new Error(failedVariantMessage);
+			throw error;
+		}
+		const metadata = getDownloadedVariantMetadata(resolved, download);
 		await recordDownloadedMirror({
 			ctx,
 			deps,
@@ -8755,7 +8891,7 @@ async function executeAssets(parsed, deps = defaultDeps$3) {
 	}
 	if (subcommand === "set-active") {
 		const assetId = parsed.positionals[1];
-		const variantId = parsed.positionals[2] || normalizeOption(parsed.options.variant);
+		const variantId = parsed.positionals[2] || normalizeOption$1(parsed.options.variant);
 		if (!assetId || !variantId) throw new Error("Usage: makefx assets set-active <asset-id> <variant-id>");
 		const asset = await setActiveVariant(ctx, deps, assetId, variantId);
 		deps.print(`Set active variant of asset ${assetId} to ${asset.active_variant_id}`);
@@ -8766,10 +8902,10 @@ async function executeAssets(parsed, deps = defaultDeps$3) {
 	}
 	throw new Error(`Unknown assets command: ${subcommand}`);
 }
-function normalizeOption(value) {
+function normalizeOption$1(value) {
 	return !value || value === "true" ? void 0 : value;
 }
-async function buildContext$3(parsed, deps) {
+async function buildContext$4(parsed, deps) {
 	const projectConfig = await deps.loadProjectConfig();
 	const env = resolveCommandEnvironment(parsed, projectConfig);
 	const spaceId = resolveCommandSpace(parsed, projectConfig);
@@ -8801,7 +8937,7 @@ async function buildAuthContext(parsed, deps) {
 }
 function requireOption(parsed, names, usage) {
 	for (const name of names) {
-		const value = normalizeOption(parsed.options[name]);
+		const value = normalizeOption$1(parsed.options[name]);
 		if (value) return value;
 	}
 	throw new Error(usage);
@@ -8811,9 +8947,9 @@ async function searchAssets(parsed, deps) {
 	const query = parsed.positionals.slice(1).join(" ").trim();
 	const params = new URLSearchParams();
 	if (query) params.set("q", query);
-	const mediaKind = normalizeOption(parsed.options.media) ?? normalizeOption(parsed.options["media-kind"]);
-	const assetType = normalizeOption(parsed.options.type);
-	const limit = normalizeOption(parsed.options.limit);
+	const mediaKind = normalizeOption$1(parsed.options.media) ?? normalizeOption$1(parsed.options["media-kind"]);
+	const assetType = normalizeOption$1(parsed.options.type);
+	const limit = normalizeOption$1(parsed.options.limit);
 	if (mediaKind) params.set("media_kind", mediaKind);
 	if (assetType) params.set("type", assetType);
 	if (limit) params.set("limit", limit);
@@ -8829,7 +8965,7 @@ async function searchAssets(parsed, deps) {
 }
 async function cloneAsset(parsed, deps) {
 	const ctx = await buildAuthContext(parsed, deps);
-	const sourceVariantId = parsed.positionals[1] ?? normalizeOption(parsed.options.variant);
+	const sourceVariantId = parsed.positionals[1] ?? normalizeOption$1(parsed.options.variant);
 	if (!sourceVariantId) throw new Error("Usage: makefx assets clone <variant-id> --from-space <source-space-id> --to-space <target-space-id>");
 	const sourceSpaceId = requireOption(parsed, ["from-space", "source-space"], "Usage: makefx assets clone <variant-id> --from-space <source-space-id> --to-space <target-space-id>");
 	const targetSpaceId = requireOption(parsed, ["to-space", "target-space"], "Usage: makefx assets clone <variant-id> --from-space <source-space-id> --to-space <target-space-id>");
@@ -8837,8 +8973,8 @@ async function cloneAsset(parsed, deps) {
 		sourceSpaceId,
 		sourceVariantId
 	};
-	const name = normalizeOption(parsed.options.name);
-	const type = normalizeOption(parsed.options.type);
+	const name = normalizeOption$1(parsed.options.name);
+	const type = normalizeOption$1(parsed.options.type);
 	if (name) body.name = name;
 	if (type) body.type = type;
 	const response = await deps.fetch(`${ctx.baseUrl}/api/spaces/${encodeURIComponent(targetSpaceId)}/assets/clone`, {
@@ -8886,10 +9022,10 @@ async function recordDownloadedMirror(input) {
 	}
 }
 async function listAssets(ctx, deps) {
-	return (await fetchJson(ctx, deps, `/api/spaces/${ctx.spaceId}/assets`)).assets || [];
+	return (await fetchJson$1(ctx, deps, `/api/spaces/${ctx.spaceId}/assets`)).assets || [];
 }
 async function getAssetDetails(ctx, deps, assetId) {
-	return fetchJson(ctx, deps, `/api/spaces/${ctx.spaceId}/assets/${assetId}`);
+	return fetchJson$1(ctx, deps, `/api/spaces/${ctx.spaceId}/assets/${assetId}`);
 }
 async function setActiveVariant(ctx, deps, assetId, variantId) {
 	try {
@@ -8901,7 +9037,63 @@ async function setActiveVariant(ctx, deps, assetId, variantId) {
 		throw error;
 	}
 }
-async function fetchJson(ctx, deps, apiPath) {
+async function getFailedDownloadVariantMessage(error, resolved, ctx, deps) {
+	if (resolved.variant || !resolved.requestPath.includes("/variants/")) return null;
+	if (!isVariantMediaUnavailableError(error)) return null;
+	const variantId = resolved.mediaKey;
+	let state;
+	try {
+		state = await requestSpaceState(ctx, deps);
+	} catch {
+		return null;
+	}
+	const variant = state.variants.find((candidate) => {
+		return isVariantRecord(candidate) && candidate.id === variantId;
+	});
+	if (!variant || variant.status !== "failed") return null;
+	const reason = formatGenerationFailureMessage(variant.error_message, variant.provider_metadata);
+	return `Variant ${variant.id} failed and has no downloadable media${reason ? `: ${reason}` : "."}`;
+}
+function isVariantMediaUnavailableError(error) {
+	return error instanceof Error && error.message.includes("Variant media not available");
+}
+function isVariantRecord(value) {
+	return Boolean(value && typeof value === "object" && typeof value.id === "string");
+}
+async function requestSpaceState(ctx, deps) {
+	const client = await deps.createMutationClient(ctx.env, ctx.spaceId);
+	await client.connect();
+	try {
+		return await new Promise((resolve, reject) => {
+			const syncClient = client;
+			if (typeof syncClient.setOnSyncState !== "function" || typeof syncClient.requestSync !== "function") {
+				reject(/* @__PURE__ */ new Error("Space sync is not available"));
+				return;
+			}
+			let settled = false;
+			const finish = (callback) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				callback();
+			};
+			const timer = setTimeout(() => {
+				finish(() => reject(/* @__PURE__ */ new Error("Timed out waiting for space sync state")));
+			}, 3e4);
+			syncClient.setOnSyncState((state) => {
+				finish(() => resolve(state));
+			});
+			try {
+				syncClient.requestSync();
+			} catch (error) {
+				finish(() => reject(error));
+			}
+		});
+	} finally {
+		client.disconnect();
+	}
+}
+async function fetchJson$1(ctx, deps, apiPath) {
 	const response = await deps.fetch(`${ctx.baseUrl}${apiPath}`, { headers: {
 		"Authorization": `Bearer ${ctx.accessToken}`,
 		"Accept": "application/json"
@@ -9083,7 +9275,7 @@ function formatTimestamp(value) {
 	if (Number.isNaN(date.getTime())) return String(value);
 	return date.toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "Z").slice(0, 20);
 }
-function printUsage$2() {
+function printUsage$3() {
 	console.log(`
 Usage:
   makefx assets
@@ -9100,7 +9292,7 @@ Usage:
 }
 //#endregion
 //#region src/cli/commands/variants.ts
-var defaultDeps$2 = {
+var defaultDeps$3 = {
 	loadConfig: loadStoredConfig,
 	loadProjectConfig,
 	resolveBaseUrl,
@@ -9112,12 +9304,12 @@ async function handleVariants(parsed) {
 		await executeVariants(parsed);
 	} catch (error) {
 		console.error("Error:", error instanceof Error ? error.message : error);
-		printUsage$1();
+		printUsage$2();
 		process$1.exitCode = 1;
 	}
 }
-async function executeVariants(parsed, deps = defaultDeps$2) {
-	const ctx = await buildContext$2(parsed, deps);
+async function executeVariants(parsed, deps = defaultDeps$3) {
+	const ctx = await buildContext$3(parsed, deps);
 	const subcommand = parsed.positionals[0];
 	if (subcommand === "delete") {
 		const variantId = requireVariantId(parsed, "delete");
@@ -9165,7 +9357,7 @@ function requireVariantId(parsed, verb) {
 	if (!variantId) throw new Error(`Variant ID is required: makefx variants ${verb} <variant-id>`);
 	return variantId;
 }
-async function buildContext$2(parsed, deps) {
+async function buildContext$3(parsed, deps) {
 	const projectConfig = await deps.loadProjectConfig();
 	const env = resolveCommandEnvironment(parsed, projectConfig);
 	const spaceId = resolveCommandSpace(parsed, projectConfig);
@@ -9188,7 +9380,7 @@ async function withVariantClient(ctx, deps, run) {
 		client.disconnect();
 	}
 }
-function printUsage$1() {
+function printUsage$2() {
 	console.log(`
 Usage:
   makefx variants delete <variant-id>
@@ -9204,6 +9396,251 @@ Options:
 `);
 }
 //#endregion
+//#region src/cli/commands/collections.ts
+var COLLECTION_KINDS = new Set([
+	"cast",
+	"backgrounds",
+	"scenes",
+	"thumbnails",
+	"maps",
+	"deliverables",
+	"custom"
+]);
+var defaultDeps$2 = {
+	loadConfig: loadStoredConfig,
+	loadProjectConfig,
+	resolveBaseUrl,
+	fetch,
+	createMutationClient: (env, spaceId) => WebSocketClient.create(env, spaceId),
+	print: console.log
+};
+async function handleCollections(parsed) {
+	try {
+		await executeCollections(parsed);
+	} catch (error) {
+		console.error("Error:", error instanceof Error ? error.message : error);
+		printUsage$1();
+		process$1.exitCode = 1;
+	}
+}
+async function executeCollections(parsed, deps = defaultDeps$2) {
+	const subcommand = parsed.positionals[0] || "list";
+	const ctx = await buildContext$2(parsed, deps);
+	if (subcommand === "list") {
+		const collections = await listCollections(ctx, deps);
+		if (parsed.options.json === "true") deps.print(JSON.stringify(collections, null, 2));
+		else printCollections(collections, deps.print);
+		return {
+			type: "list",
+			collections
+		};
+	}
+	if (subcommand === "items") {
+		const collectionId = parsed.positionals[1];
+		if (!collectionId) throw new Error("Collection ID is required: makefx collections items <collection-id>");
+		const items = await listCollectionItems(ctx, deps, collectionId);
+		if (parsed.options.json === "true") deps.print(JSON.stringify(items, null, 2));
+		else printCollectionItems(items, deps.print);
+		return {
+			type: "items",
+			items
+		};
+	}
+	if (subcommand === "create") {
+		const name = parsed.positionals.slice(1).join(" ").trim() || normalizeOption(parsed.options.name);
+		if (!name) throw new Error("Usage: makefx collections create \"<name>\"");
+		const collection = await withCollectionClient(ctx, deps, (client) => client.createCollection({
+			id: normalizeOption(parsed.options.id),
+			name,
+			kind: parseKind(normalizeOption(parsed.options.kind)),
+			color: parseNullableOption(parsed.options.color),
+			description: parseNullableOption(parsed.options.description),
+			sortIndex: parseOptionalInteger(parsed.options["sort-index"], "sort-index")
+		}));
+		printJsonOrLine(parsed, deps, collection, `Created collection ${collection.id} (${collection.name})`);
+		return {
+			type: "create",
+			collection
+		};
+	}
+	if (subcommand === "delete") {
+		const collectionId = parsed.positionals[1];
+		if (!collectionId) throw new Error("Collection ID is required: makefx collections delete <collection-id>");
+		await withCollectionClient(ctx, deps, (client) => client.deleteCollection(collectionId));
+		deps.print(`Deleted collection ${collectionId}`);
+		return {
+			type: "delete",
+			collectionId
+		};
+	}
+	if (subcommand === "add-asset") {
+		const collectionId = parsed.positionals[1];
+		const assetId = parsed.positionals[2] || normalizeOption(parsed.options.asset);
+		if (!collectionId || !assetId) throw new Error("Usage: makefx collections add-asset <collection-id> <asset-id>");
+		const item = await withCollectionClient(ctx, deps, (client) => client.createCollectionItem({
+			collectionId,
+			id: normalizeOption(parsed.options.id),
+			subjectType: "asset",
+			assetId,
+			role: normalizeOption(parsed.options.role),
+			pinnedVariantId: parseNullableOption(parsed.options.variant ?? parsed.options["pinned-variant"]),
+			sortIndex: parseOptionalInteger(parsed.options["sort-index"], "sort-index")
+		}));
+		printJsonOrLine(parsed, deps, item, `Added asset ${assetId} to collection ${collectionId} as item ${item.id}`);
+		return {
+			type: "add",
+			item
+		};
+	}
+	if (subcommand === "add-variant") {
+		const collectionId = parsed.positionals[1];
+		const variantId = parsed.positionals[2] || normalizeOption(parsed.options.variant);
+		if (!collectionId || !variantId) throw new Error("Usage: makefx collections add-variant <collection-id> <variant-id>");
+		const item = await withCollectionClient(ctx, deps, (client) => client.createCollectionItem({
+			collectionId,
+			id: normalizeOption(parsed.options.id),
+			subjectType: "variant",
+			variantId,
+			role: normalizeOption(parsed.options.role),
+			sortIndex: parseOptionalInteger(parsed.options["sort-index"], "sort-index")
+		}));
+		printJsonOrLine(parsed, deps, item, `Added variant ${variantId} to collection ${collectionId} as item ${item.id}`);
+		return {
+			type: "add",
+			item
+		};
+	}
+	if (subcommand === "remove") {
+		const collectionId = parsed.positionals[1];
+		const itemId = parsed.positionals[2] || normalizeOption(parsed.options.item);
+		if (!collectionId || !itemId) throw new Error("Usage: makefx collections remove <collection-id> <item-id>");
+		await withCollectionClient(ctx, deps, (client) => client.deleteCollectionItem(collectionId, itemId));
+		deps.print(`Removed item ${itemId} from collection ${collectionId}`);
+		return {
+			type: "remove",
+			collectionId,
+			itemId
+		};
+	}
+	if (subcommand === "reorder") {
+		const collectionId = parsed.positionals[1];
+		const itemIds = splitIds(parsed.positionals[2] || normalizeOption(parsed.options.items));
+		if (!collectionId || itemIds.length === 0) throw new Error("Usage: makefx collections reorder <collection-id> <item-id,item-id,...>");
+		const items = await withCollectionClient(ctx, deps, (client) => client.reorderCollectionItems(collectionId, itemIds));
+		if (parsed.options.json === "true") deps.print(JSON.stringify(items, null, 2));
+		else deps.print(`Reordered ${items.length} item(s) in collection ${collectionId}`);
+		return {
+			type: "reorder",
+			items
+		};
+	}
+	throw new Error(`Unknown collections command: ${subcommand}`);
+}
+async function buildContext$2(parsed, deps) {
+	const projectConfig = await deps.loadProjectConfig();
+	const env = resolveCommandEnvironment(parsed, projectConfig);
+	const spaceId = resolveCommandSpace(parsed, projectConfig);
+	if (!spaceId) throw new Error("--space is required, or run: makefx init --space <id>");
+	const config = await deps.loadConfig(env);
+	if (!config) throw new Error(`Not logged in to ${env} environment. Run: ${loginCommandForEnvironment(env)}`);
+	if (config.token.expiresAt < Date.now()) throw new Error(`Token expired for ${env} environment. Run: ${loginCommandForEnvironment(env)}`);
+	if (env === "local") process$1.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+	return {
+		env,
+		spaceId,
+		baseUrl: deps.resolveBaseUrl(env),
+		accessToken: config.token.accessToken
+	};
+}
+async function withCollectionClient(ctx, deps, run) {
+	const client = await deps.createMutationClient(ctx.env, ctx.spaceId);
+	await client.connect();
+	try {
+		return await run(client);
+	} finally {
+		client.disconnect();
+	}
+}
+async function listCollections(ctx, deps) {
+	return (await fetchJson(ctx, deps, `/api/spaces/${encodeURIComponent(ctx.spaceId)}/collections`)).collections || [];
+}
+async function listCollectionItems(ctx, deps, collectionId) {
+	return (await fetchJson(ctx, deps, `/api/spaces/${encodeURIComponent(ctx.spaceId)}/collections/${encodeURIComponent(collectionId)}/items`)).items || [];
+}
+async function fetchJson(ctx, deps, apiPath) {
+	const response = await deps.fetch(`${ctx.baseUrl}${apiPath}`, { headers: {
+		"Authorization": `Bearer ${ctx.accessToken}`,
+		"Accept": "application/json"
+	} });
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Request failed (${response.status}): ${errorText || response.statusText}`);
+	}
+	return response.json();
+}
+function normalizeOption(value) {
+	return !value || value === "true" ? void 0 : value;
+}
+function parseNullableOption(value) {
+	if (value === void 0) return void 0;
+	if (value === "true") return void 0;
+	if (value === "" || value === "null" || value === "none") return null;
+	return value;
+}
+function parseKind(value) {
+	if (!value) return void 0;
+	if (!COLLECTION_KINDS.has(value)) throw new Error(`Invalid collection kind "${value}". Expected one of: ${Array.from(COLLECTION_KINDS).join(", ")}`);
+	return value;
+}
+function parseOptionalInteger(value, name) {
+	const normalized = normalizeOption(value);
+	if (!normalized) return void 0;
+	const parsed = Number.parseInt(normalized, 10);
+	if (!Number.isInteger(parsed) || String(parsed) !== normalized) throw new Error(`--${name} must be an integer`);
+	return parsed;
+}
+function splitIds(value) {
+	return (value ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+}
+function printJsonOrLine(parsed, deps, value, line) {
+	if (parsed.options.json === "true") deps.print(JSON.stringify(value, null, 2));
+	else deps.print(line);
+}
+function printCollections(collections, print) {
+	if (collections.length === 0) {
+		print("No collections found.");
+		return;
+	}
+	print(`Found ${collections.length} collection(s):\n`);
+	print("Sort".padEnd(8) + "Kind".padEnd(15) + "Collection".padEnd(38) + "Name");
+	print("-".repeat(85));
+	for (const collection of collections) print(String(collection.sort_index).padEnd(8) + truncate(collection.kind, 13).padEnd(15) + truncate(collection.id, 36).padEnd(38) + truncate(collection.name, 40));
+}
+function printCollectionItems(items, print) {
+	if (items.length === 0) {
+		print("No collection items found.");
+		return;
+	}
+	print(`Found ${items.length} collection item(s):\n`);
+	print("Sort".padEnd(8) + "Subject".padEnd(10) + "Item".padEnd(34) + "Asset".padEnd(28) + "Variant".padEnd(28) + "Role");
+	print("-".repeat(128));
+	for (const item of items) print(String(item.sort_index).padEnd(8) + item.subject_type.padEnd(10) + truncate(item.id, 32).padEnd(34) + truncate(item.asset_id || "-", 26).padEnd(28) + truncate(item.variant_id || item.pinned_variant_id || "-", 26).padEnd(28) + truncate(item.role, 24));
+}
+function printUsage$1() {
+	console.log(`
+Usage:
+  makefx collections
+  makefx collections --json
+  makefx collections create "<name>" [--kind custom]
+  makefx collections delete <collection-id>
+  makefx collections items <collection-id>
+  makefx collections add-asset <collection-id> <asset-id> [--variant <variant-id>] [--role <role>]
+  makefx collections add-variant <collection-id> <variant-id> [--role <role>]
+  makefx collections remove <collection-id> <item-id>
+  makefx collections reorder <collection-id> <item-id,item-id,...>
+`);
+}
+//#endregion
 //#region src/cli/commands/usage.ts
 var defaultDeps$1 = {
 	loadConfig: loadStoredConfig,
@@ -9504,7 +9941,7 @@ Options:
 }
 //#endregion
 //#region src/cli/index.ts
-var CLI_VERSION = "1.0.5+22056848942e";
+var CLI_VERSION = "1.0.7+686298a71cee";
 async function main() {
 	const argv = process$1.argv.slice(2);
 	if (argv[0] === "--") argv.shift();
@@ -9555,7 +9992,8 @@ function imageCapabilityHelp() {
   --size <value>    Output size (${sizeLines})
   --aspect <ratio>  Aspect ratio: ${imageAspectValues()}
   --refs <refs>     Reference limit (${referenceLines})
-  --follow <id>     Resume/download a variant after a long generation or disconnect`;
+  --follow <id>     Resume/download a variant after a long generation or disconnect
+  --collection <id> Place the completed asset in a Space collection`;
 }
 function videoResolutionValues() {
 	return optionValues(uniqueValues(VIDEO_GENERATION_TIERS.flatMap((tier) => getVideoGenerationResolutionsForTier(tier))));
@@ -9583,6 +10021,7 @@ function videoCapabilityHelp() {
   --first-frame <ref>   Veo start frame image variant or local image path
   --last-frame <ref>    Veo final frame image variant or local image path
   --follow <id>         Resume/download a variant after a long generation or disconnect
+  --collection <id>     Place the completed asset in a Space collection
 
 Veo 3.1 frames:
   --first-frame resolves to the first referenceVariantId and becomes the Veo top-level image input.
@@ -9649,6 +10088,10 @@ function printCommandHelp(command, positionals) {
 		case "assets":
 			printAssetsHelp();
 			return;
+		case "collections":
+		case "collection":
+			printCollectionsHelp();
+			return;
 		case "usage":
 			printUsageHelp();
 			return;
@@ -9695,6 +10138,8 @@ Inspect:
   assets show <asset-id>                 Show variants and lineage
   assets download <variant-id> -o <file> Download variant media
   assets clone <variant-id> --from-space <id> --to-space <id>
+  collections add-asset <collection-id> <asset-id>
+  collections add-variant <collection-id> <variant-id>
   variants rate <variant-id> approved|rejected
   variants star <variant-id>
 
@@ -9703,6 +10148,7 @@ Details:
   help audio       Speech, dialogue, music, and SFX
   help video       Video generate/refine/derive and keyframes
   help assets      Asset inspection and downloads
+  help collections Space collection organization
   help spaces      Space setup and selection
   help upload      Upload local media into a Space
 
@@ -9740,7 +10186,8 @@ Examples:
   makefx derive --refs character.png,background.png --name "Hero Scene" --type scene "Place the character in the background" -o hero-scene.png
   makefx refine --variant variant_123 "Keep composition, make the lighting warmer" -o warm.png
 
-If the CLI stops waiting after a job has started, rerun the printed --follow command to download the variant.
+If the CLI stops waiting after a job has started, the job keeps running in Make Effects.
+Rerun the printed --follow command to resume the same variant instead of starting a duplicate.
 `);
 }
 function printInitHelp() {
@@ -9834,31 +10281,33 @@ function printForgeHelp(command) {
 	if (command === "generate") {
 		console.log(`
 Usage:
-  makefx generate "prompt" --name <name> --type <type> -o <file> [--model ${optionValues(IMAGE_MODEL_SELECTIONS)}] [--size ${imageSizeValues()}] [--aspect <ratio>] [--space <id>]
-  makefx generate --follow <variant_id> -o <file> [--space <id>]
+  makefx generate "prompt" --name <name> --type <type> -o <file> [--model ${optionValues(IMAGE_MODEL_SELECTIONS)}] [--size ${imageSizeValues()}] [--aspect <ratio>] [--collection <id>] [--space <id>]
+  makefx generate --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
 
 ${imageCapabilityHelp()}
 
-If the CLI stops waiting after a job has started, rerun the printed --follow command to download the variant.
+If the CLI stops waiting after a job has started, the job keeps running in Make Effects.
+Rerun the printed --follow command to resume the same variant instead of starting a duplicate.
 `);
 		return;
 	}
 	if (command === "refine") {
 		console.log(`
 Usage:
-  makefx refine --variant <variant_id> "prompt" -o <file> [--model ${optionValues(IMAGE_MODEL_SELECTIONS)}] [--size ${imageSizeValues()}] [--aspect <ratio>] [--space <id>]
-  makefx refine --follow <variant_id> -o <file> [--space <id>]
+  makefx refine --variant <variant_id> "prompt" -o <file> [--model ${optionValues(IMAGE_MODEL_SELECTIONS)}] [--size ${imageSizeValues()}] [--aspect <ratio>] [--collection <id>] [--space <id>]
+  makefx refine --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
 
 ${imageCapabilityHelp()}
 
-If the CLI stops waiting after a job has started, rerun the printed --follow command to download the variant.
+If the CLI stops waiting after a job has started, the job keeps running in Make Effects.
+Rerun the printed --follow command to resume the same variant instead of starting a duplicate.
 `);
 		return;
 	}
 	if (command === "batch") {
 		console.log(`
 Usage:
-  makefx batch "prompt" --name <name> --type <type> --count <2-8> --output-dir <dir> [--model ${optionValues(IMAGE_MODEL_SELECTIONS)}] [--size ${imageSizeValues()}] [--aspect <ratio>]
+  makefx batch "prompt" --name <name> --type <type> --count <2-8> --output-dir <dir> [--model ${optionValues(IMAGE_MODEL_SELECTIONS)}] [--size ${imageSizeValues()}] [--aspect <ratio>] [--collection <id>]
 
 ${imageCapabilityHelp()}
 
@@ -9869,12 +10318,13 @@ Batch creates several variants. If waiting stops, inspect the Space or download
 	}
 	console.log(`
 Usage:
-  makefx derive --refs <variant_or_file,variant_or_file> --name <name> --type <type> "prompt" -o <file> [--model ${optionValues(IMAGE_MODEL_SELECTIONS)}] [--size ${imageSizeValues()}] [--aspect <ratio>] [--space <id>]
-  makefx derive --follow <variant_id> -o <file> [--space <id>]
+  makefx derive --refs <variant_or_file,variant_or_file> --name <name> --type <type> "prompt" -o <file> [--model ${optionValues(IMAGE_MODEL_SELECTIONS)}] [--size ${imageSizeValues()}] [--aspect <ratio>] [--collection <id>] [--space <id>]
+  makefx derive --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
 
 ${imageCapabilityHelp()}
 
-If the CLI stops waiting after a job has started, rerun the printed --follow command to download the variant.
+If the CLI stops waiting after a job has started, the job keeps running in Make Effects.
+Rerun the printed --follow command to resume the same variant instead of starting a duplicate.
 `);
 }
 function printAudioHelp(positionals) {
@@ -9893,23 +10343,24 @@ Lists ElevenLabs voices available to the connected account when ElevenLabs is th
 		if (second === "generate") {
 			console.log(`
 Usage:
-  makefx audio ${first} generate "prompt" --name <name> -o <file> [--space <id>]
-  makefx audio ${first} generate --input <file> --name <name> -o <file> [--space <id>]
-  makefx audio ${first} generate --follow <variant_id> -o <file> [--space <id>]
-${first === "music" ? "  makefx audio music generate \"prompt\" --provider lyria --name <name> -o <file> [--space <id>]\n" : ""}
+  makefx audio ${first} generate "prompt" --name <name> -o <file> [--collection <id>] [--space <id>]
+  makefx audio ${first} generate --input <file> --name <name> -o <file> [--collection <id>] [--space <id>]
+  makefx audio ${first} generate --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
+${first === "music" ? "  makefx audio music generate \"prompt\" --provider lyria --name <name> -o <file> [--collection <id>] [--space <id>]\n" : ""}
 ${first === "music" ? "Provider selection:\n  --provider <elevenlabs|lyria>        Music provider (default: server default)\n" : ""}
 ${first === "speech" || first === "dialogue" ? "Model selection:\n  --model <model_id>                   ElevenLabs model (default: eleven_v3)\n" : ""}
 ${first === "speech" || first === "dialogue" ? "Voice selection:\n  --voice <voice_id>                    Speech voice, or dialogue fallback voice\n  --dialogue-voices <id,id,...>         Dialogue voices ordered by first speaker appearance\n" : ""}
 Long runs:
   --follow <variant_id>                 Resume/download a variant after a long generation or disconnect
+  --collection <id>                     Place the completed asset in a Space collection
 `);
 			return;
 		}
 		if (second === "batch") {
 			console.log(`
 Usage:
-  makefx audio ${first} batch "prompt" --name <name> --count <2-8> --output-dir <dir> [--space <id>]
-${first === "music" ? "  makefx audio music batch \"prompt\" --provider lyria --name <name> --count <2-8> --output-dir <dir> [--space <id>]\n" : ""}
+  makefx audio ${first} batch "prompt" --name <name> --count <2-8> --output-dir <dir> [--collection <id>] [--space <id>]
+${first === "music" ? "  makefx audio music batch \"prompt\" --provider lyria --name <name> --count <2-8> --output-dir <dir> [--collection <id>] [--space <id>]\n" : ""}
 ${first === "music" ? "Provider selection:\n  --provider <elevenlabs|lyria>        Music provider (default: server default)\n" : ""}
 ${first === "speech" || first === "dialogue" ? "Model selection:\n  --model <model_id>                   ElevenLabs model (default: eleven_v3)\n" : ""}
 ${first === "speech" || first === "dialogue" ? "Voice selection:\n  --voice <voice_id>                    Speech voice, or dialogue fallback voice\n  --dialogue-voices <id,id,...>         Dialogue voices ordered by first speaker appearance\n" : ""}
@@ -9918,8 +10369,8 @@ ${first === "speech" || first === "dialogue" ? "Voice selection:\n  --voice <voi
 		}
 		console.log(`
 Usage:
-  makefx audio ${first} generate "prompt" --name <name> -o <file> [--space <id>]
-  makefx audio ${first} batch "prompt" --name <name> --count <2-8> --output-dir <dir> [--space <id>]
+  makefx audio ${first} generate "prompt" --name <name> -o <file> [--collection <id>] [--space <id>]
+  makefx audio ${first} batch "prompt" --name <name> --count <2-8> --output-dir <dir> [--collection <id>] [--space <id>]
 ${first === "music" ? "\nProvider selection:\n  --provider <elevenlabs|lyria>        Music provider (default: server default)\n" : ""}
 ${first === "speech" || first === "dialogue" ? "\nModel selection:\n  --model <model_id>                   ElevenLabs model (default: eleven_v3)\n" : ""}
 ${first === "speech" || first === "dialogue" ? "\nVoice selection:\n  --voice <voice_id>                    Speech voice, or dialogue fallback voice\n  --dialogue-voices <id,id,...>         Dialogue voices ordered by first speaker appearance\n" : ""}
@@ -9929,31 +10380,31 @@ ${first === "speech" || first === "dialogue" ? "\nVoice selection:\n  --voice <v
 	if (first === "generate") {
 		console.log(`
 Usage:
-  makefx audio generate "prompt" --name <name> --type <type> -o <file> [--space <id>]
+  makefx audio generate "prompt" --name <name> --type <type> -o <file> [--collection <id>] [--space <id>]
 
 Preferred mode form:
-  makefx audio <${modes}> generate "prompt" --name <name> -o <file> [--space <id>]
+  makefx audio <${modes}> generate "prompt" --name <name> -o <file> [--collection <id>] [--space <id>]
 `);
 		return;
 	}
 	if (first === "batch") {
 		console.log(`
 Usage:
-  makefx audio batch "prompt" --name <name> --type <type> --count <2-8> --output-dir <dir> [--space <id>]
+  makefx audio batch "prompt" --name <name> --type <type> --count <2-8> --output-dir <dir> [--collection <id>] [--space <id>]
 
 Preferred mode form:
-  makefx audio <${modes}> batch "prompt" --name <name> --count <2-8> --output-dir <dir> [--space <id>]
+  makefx audio <${modes}> batch "prompt" --name <name> --count <2-8> --output-dir <dir> [--collection <id>] [--space <id>]
 `);
 		return;
 	}
 	console.log(`
 Usage:
-  makefx audio <${modes}> generate "prompt" --name <name> -o <file> [--space <id>]
-  makefx audio <${modes}> generate --input <file> --name <name> -o <file> [--space <id>]
-  makefx audio <${modes}> generate --follow <variant_id> -o <file> [--space <id>]
-  makefx audio <${modes}> batch "prompt" --name <name> --count <2-8> --output-dir <dir> [--space <id>]
+  makefx audio <${modes}> generate "prompt" --name <name> -o <file> [--collection <id>] [--space <id>]
+  makefx audio <${modes}> generate --input <file> --name <name> -o <file> [--collection <id>] [--space <id>]
+  makefx audio <${modes}> generate --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
+  makefx audio <${modes}> batch "prompt" --name <name> --count <2-8> --output-dir <dir> [--collection <id>] [--space <id>]
   makefx audio voices [--json]
-  makefx audio music generate "prompt" --provider <elevenlabs|lyria> --name <name> -o <file> [--space <id>]
+  makefx audio music generate "prompt" --provider <elevenlabs|lyria> --name <name> -o <file> [--collection <id>] [--space <id>]
 
 Modes:
   speech      Spoken narration or voiceover
@@ -9969,11 +10420,12 @@ Model selection:
   --model <model_id>                   ElevenLabs speech/dialogue model (default: eleven_v3)
 
 Low-level compatibility:
-  makefx audio generate "prompt" --name <name> --type <type> -o <file> [--space <id>]
-  makefx audio batch "prompt" --name <name> --type <type> --count <2-8> --output-dir <dir> [--space <id>]
+  makefx audio generate "prompt" --name <name> --type <type> -o <file> [--collection <id>] [--space <id>]
+  makefx audio batch "prompt" --name <name> --type <type> --count <2-8> --output-dir <dir> [--collection <id>] [--space <id>]
 
 Long runs:
-  If the CLI stops waiting after a job has started, rerun the printed --follow command to download the variant.
+  If the CLI stops waiting after a job has started, the job keeps running in Make Effects.
+  Rerun the printed --follow command to resume the same variant instead of starting a duplicate.
 `);
 }
 function printVideoHelp(positionals) {
@@ -9981,8 +10433,8 @@ function printVideoHelp(positionals) {
 	if (subcommand === "generate") {
 		console.log(`
 Usage:
-  makefx video generate "prompt" --name <name> --type <type> -o <file> [--model ${videoModelValues()}] [--first-frame <variant_or_file>] [--last-frame <variant_or_file>] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--space <id>]
-  makefx video generate --follow <variant_id> -o <file> [--space <id>]
+  makefx video generate "prompt" --name <name> --type <type> -o <file> [--model ${videoModelValues()}] [--first-frame <variant_or_file>] [--last-frame <variant_or_file>] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--collection <id>] [--space <id>]
+  makefx video generate --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
 
 ${videoCapabilityHelp()}
 
@@ -9990,15 +10442,16 @@ Audio:
   Video defaults to generated audio. Current Veo models do not support --no-audio; the CLI rejects it before creating a job.
 
 Long runs:
-  If the CLI stops waiting after a job has started, rerun the printed --follow command to download the variant.
+  If the CLI stops waiting after a job has started, the job keeps running in Make Effects.
+  Rerun the printed --follow command to resume the same variant instead of starting a duplicate.
 `);
 		return;
 	}
 	if (subcommand === "refine") {
 		console.log(`
 Usage:
-  makefx video refine --variant <variant_id> "prompt" -o <file> [--model ${videoModelValues()}] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--space <id>]
-  makefx video refine --follow <variant_id> -o <file> [--space <id>]
+  makefx video refine --variant <variant_id> "prompt" -o <file> [--model ${videoModelValues()}] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--collection <id>] [--space <id>]
+  makefx video refine --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
 
 ${videoCapabilityHelp()}
 
@@ -10006,16 +10459,17 @@ Audio:
   Video defaults to generated audio. Current Veo models do not support --no-audio; the CLI rejects it before creating a job.
 
 Long runs:
-  If the CLI stops waiting after a job has started, rerun the printed --follow command to download the variant.
+  If the CLI stops waiting after a job has started, the job keeps running in Make Effects.
+  Rerun the printed --follow command to resume the same variant instead of starting a duplicate.
 `);
 		return;
 	}
 	if (subcommand === "derive") {
 		console.log(`
 Usage:
-  makefx video derive --refs <variant_or_file,variant_or_file> --name <name> --type <type> "prompt" -o <file> [--model ${videoModelValues()}] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--space <id>]
-  makefx video derive --first-frame <variant_or_file> [--last-frame <variant_or_file>] --name <name> --type <type> "prompt" -o <file> [--model veo-3.1] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--space <id>]
-  makefx video derive --follow <variant_id> -o <file> [--space <id>]
+  makefx video derive --refs <variant_or_file,variant_or_file> --name <name> --type <type> "prompt" -o <file> [--model ${videoModelValues()}] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--collection <id>] [--space <id>]
+  makefx video derive --first-frame <variant_or_file> [--last-frame <variant_or_file>] --name <name> --type <type> "prompt" -o <file> [--model veo-3.1] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--collection <id>] [--space <id>]
+  makefx video derive --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
 
 ${videoCapabilityHelp()}
 
@@ -10023,17 +10477,18 @@ Audio:
   Video defaults to generated audio. Current Veo models do not support --no-audio; the CLI rejects it before creating a job.
 
 Long runs:
-  If the CLI stops waiting after a job has started, rerun the printed --follow command to download the variant.
+  If the CLI stops waiting after a job has started, the job keeps running in Make Effects.
+  Rerun the printed --follow command to resume the same variant instead of starting a duplicate.
 `);
 		return;
 	}
 	console.log(`
 Usage:
-  makefx video generate "prompt" --name <name> --type <type> -o <file> [--model ${videoModelValues()}] [--first-frame <variant_or_file>] [--last-frame <variant_or_file>] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--space <id>]
-  makefx video generate --follow <variant_id> -o <file> [--space <id>]
-  makefx video refine --variant <variant_id> "prompt" -o <file> [--model ${videoModelValues()}] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--space <id>]
-  makefx video derive --refs <variant_or_file,variant_or_file> --name <name> --type <type> "prompt" -o <file> [--model ${videoModelValues()}] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--space <id>]
-  makefx video derive --first-frame <variant_or_file> [--last-frame <variant_or_file>] --name <name> --type <type> "prompt" -o <file> [--model veo-3.1] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--space <id>]
+  makefx video generate "prompt" --name <name> --type <type> -o <file> [--model ${videoModelValues()}] [--first-frame <variant_or_file>] [--last-frame <variant_or_file>] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--collection <id>] [--space <id>]
+  makefx video generate --follow <variant_id> -o <file> [--collection <id>] [--space <id>]
+  makefx video refine --variant <variant_id> "prompt" -o <file> [--model ${videoModelValues()}] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--collection <id>] [--space <id>]
+  makefx video derive --refs <variant_or_file,variant_or_file> --name <name> --type <type> "prompt" -o <file> [--model ${videoModelValues()}] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--collection <id>] [--space <id>]
+  makefx video derive --first-frame <variant_or_file> [--last-frame <variant_or_file>] --name <name> --type <type> "prompt" -o <file> [--model veo-3.1] [--aspect ${videoAspectValues()}] [--resolution ${videoResolutionValues()}] [--duration ${videoDurationValues()}] [--tier ${videoTierValues()}] [--audio] [--collection <id>] [--space <id>]
 
 ${videoCapabilityHelp()}
 
@@ -10041,7 +10496,8 @@ Audio:
   Video defaults to generated audio. Current Veo models do not support --no-audio; the CLI rejects it before creating a job.
 
 Long runs:
-  If the CLI stops waiting after a job has started, rerun the printed --follow command to download the variant.
+  If the CLI stops waiting after a job has started, the job keeps running in Make Effects.
+  Rerun the printed --follow command to resume the same variant instead of starting a duplicate.
 `);
 }
 function printRunsHelp() {
@@ -10091,6 +10547,26 @@ Usage:
   makefx assets set-active <asset-id> <variant-id>
 `);
 }
+function printCollectionsHelp() {
+	console.log(`
+Usage:
+  makefx collections
+  makefx collections --json
+  makefx collections create "<name>" [--kind cast|backgrounds|scenes|thumbnails|maps|deliverables|custom]
+  makefx collections delete <collection-id>
+  makefx collections items <collection-id>
+  makefx collections add-asset <collection-id> <asset-id> [--variant <variant-id>] [--role <role>]
+  makefx collections add-variant <collection-id> <variant-id> [--role <role>]
+  makefx collections remove <collection-id> <item-id>
+  makefx collections reorder <collection-id> <item-id,item-id,...>
+
+Options:
+  --space <id>      Target space ID; defaults from the initialized project
+  --env <env>       Environment (production|stage|local)
+  --local           Shortcut for --env local
+  --json            Print machine-readable output where supported
+`);
+}
 function printUsageHelp() {
 	console.log(`
 Usage:
@@ -10173,6 +10649,10 @@ async function dispatchCommand(command, parsed) {
 		case "assets":
 			await handleAssets(parsed);
 			break;
+		case "collections":
+		case "collection":
+			await handleCollections(parsed);
+			break;
 		case "usage":
 			await handleUsage(parsed);
 			break;