makefx 1.2.0 → 1.3.0

package/makefx.mjs

@@ -8,9 +8,9 @@ import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/p
 import os from "node:os";
 import path from "node:path";
 import { createReadStream, createWriteStream } from "node:fs";
+import https from "node:https";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import https from "node:https";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -831,6 +831,78 @@ function validateProjectConfig(config, configPath) {
 	if (!config.spaceId || typeof config.spaceId !== "string") throw new Error(`Make Effects project config is missing spaceId: ${configPath}`);
 }
 //#endregion
+//#region src/shared/compact-references.ts
+var COMPACT_ID_LENGTH = 8;
+var CompactReferenceError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "CompactReferenceError";
+	}
+};
+function normalizeId(value) {
+	return value.toLowerCase().replaceAll(/[^a-z0-9]/gu, "");
+}
+function slugify$1(value) {
+	return value.normalize("NFKD").replaceAll(/\p{Mark}/gu, "").toLowerCase().replaceAll(/[^\p{Letter}\p{Number}]+/gu, "-").replaceAll(/^-+|-+$/gu, "").slice(0, 32).replaceAll(/-+$/gu, "") || "asset";
+}
+function compactIdPrefix(id) {
+	return normalizeId(id).slice(0, COMPACT_ID_LENGTH);
+}
+function createAssetRef(name, assetId) {
+	return `asset:${slugify$1(name)}~${compactIdPrefix(assetId)}`;
+}
+function createVariantRef(name, assetId, variantId) {
+	return `${createAssetRef(name, assetId)}@${compactIdPrefix(variantId)}`;
+}
+function parseAssetRef(value) {
+	const match = /^asset:[^~]+~([a-z0-9]{4,8})$/u.exec(value);
+	return match ? { idPrefix: match[1] } : null;
+}
+function parseVariantRef(value) {
+	const separator = value.lastIndexOf("@");
+	if (separator < 0) return null;
+	const assetRef = value.slice(0, separator);
+	const variant = value.slice(separator + 1);
+	if (!parseAssetRef(assetRef) || variant !== "active" && !/^[a-z0-9]{4,8}$/u.test(variant)) return null;
+	return {
+		assetRef,
+		variant
+	};
+}
+function idMatchesPrefix(id, prefix) {
+	return normalizeId(id).startsWith(prefix.toLowerCase());
+}
+function resolveAssetRef(identifier, assets) {
+	const parsed = parseAssetRef(identifier);
+	if (!parsed) {
+		if (identifier.startsWith("asset:")) throw new CompactReferenceError("MALFORMED_REFERENCE", `Asset reference ${identifier} is malformed`);
+		return identifier;
+	}
+	const matches = assets.filter((asset) => idMatchesPrefix(asset.id, parsed.idPrefix));
+	if (matches.length === 0) throw new CompactReferenceError("NOT_FOUND", `Asset reference ${identifier} was not found`);
+	if (matches.length > 1) throw new CompactReferenceError("AMBIGUOUS_REFERENCE", `Asset reference ${identifier} is ambiguous`);
+	return matches[0].id;
+}
+function resolveVariantRef(identifier, assets, variants) {
+	const parsed = parseVariantRef(identifier);
+	if (!parsed) {
+		if (identifier.startsWith("asset:")) throw new CompactReferenceError("MALFORMED_REFERENCE", `Variant reference ${identifier} is malformed`);
+		return identifier;
+	}
+	const assetId = resolveAssetRef(parsed.assetRef, assets);
+	const asset = assets.find((candidate) => candidate.id === assetId);
+	if (parsed.variant === "active") {
+		if (!asset?.active_variant_id) throw new CompactReferenceError("NOT_FOUND", `Asset reference ${parsed.assetRef} has no active variant`);
+		return asset.active_variant_id;
+	}
+	const matches = variants.filter((variant) => variant.asset_id === assetId && idMatchesPrefix(variant.id, parsed.variant));
+	if (matches.length === 0) throw new CompactReferenceError("NOT_FOUND", `Variant reference ${identifier} was not found`);
+	if (matches.length > 1) throw new CompactReferenceError("AMBIGUOUS_REFERENCE", `Variant reference ${identifier} is ambiguous`);
+	return matches[0].id;
+}
+//#endregion
 //#region src/cli/commands/spaces.ts
 /**
 * Spaces Command - List and manage user's spaces
@@ -933,7 +1005,14 @@ async function executeSpaces(parsed, deps = defaultDeps$11) {
 	}
 	if (spaceId) {
 		const details = await getSpaceDetails(ctx, deps, spaceId);
-		if (jsonOutput) deps.print(JSON.stringify(details, null, 2));
+		if (jsonOutput) deps.print(JSON.stringify({
+			...details,
+			assets: details.assets.map((asset) => ({
+				...asset,
+				assetRef: createAssetRef(asset.name, asset.id),
+				variantRef: asset.active_variant_id ? createVariantRef(asset.name, asset.id, asset.active_variant_id) : null
+			}))
+		}, null, 2));
 		else printSpaceDetails(details, deps.print);
 		return {
 			type: "show",
@@ -1144,8 +1223,8 @@ function printSpaceDetails(details, print) {
 	for (const [type, typeAssets] of byType) {
 		print(`${type.charAt(0).toUpperCase() + type.slice(1)}s (${typeAssets.length}):`);
 		for (const asset of typeAssets) {
-			print(`  ${asset.active_variant_id ? "✓" : "○"} ${asset.name}`);
-			print(`    ID: ${asset.id}`);
+			print(`  ${asset.active_variant_id ? "✓" : "○"} ${createAssetRef(asset.name, asset.id)} — ${asset.name}`);
+			if (asset.active_variant_id) print(`    Active: ${createVariantRef(asset.name, asset.id, asset.active_variant_id)}`);
 		}
 		print("");
 	}
@@ -5377,556 +5456,42 @@ function isMirrorEntry(value) {
 	return entry.version === MIRROR_REGISTRY_VERSION && typeof entry.baseUrl === "string" && (entry.environment === void 0 || typeof entry.environment === "string") && typeof entry.spaceId === "string" && typeof entry.sha256 === "string" && typeof entry.sizeBytes === "number" && Array.isArray(entry.paths) && entry.paths.every((item) => typeof item === "string") && typeof entry.assetId === "string" && typeof entry.variantId === "string" && typeof entry.mediaKind === "string" && (entry.mediaKey === void 0 || entry.mediaKey === null || typeof entry.mediaKey === "string") && typeof entry.updatedAt === "string";
 }
 //#endregion
-//#region src/cli/commands/upload.ts
+//#region src/cli/lib/websocket-client.ts
 /**
-* Upload Command - Upload one media file to create variants
+* WebSocket Client for CLI
 *
-* Usage:
-*   makefx upload <file> --space <id> --asset <id>     Upload to existing asset
-*   makefx upload <file> --space <id> --name <name>    Upload as new asset
-*   makefx upload <file> --space <id> --name <name> --type <type>
+* Provides WebSocket-based communication with the Space Durable Object.
+* Replaces HTTP API calls with WebSocket messages for chat and generation.
 */
-var defaultDeps$10 = {
-	loadConfig: loadStoredConfig,
-	loadProjectConfig,
-	resolveBaseUrl,
-	fetch,
-	readFile,
-	stat,
-	recordMirrorForFile,
-	print: console.log
-};
-var UploadUsageError = class extends Error {};
-var RETIRED_UPLOAD_ORGANIZATION_OPTIONS = [
-	["collection", "--collection"],
-	["collection-name", "--collection-name"],
-	["collectionName", "--collection-name"],
-	["collection-role", "--collection-role"],
-	["collectionRole", "--collection-role"],
-	["collection-subject", "--collection-subject"],
-	["collectionSubject", "--collection-subject"],
-	["manual-relation", "--manual-relation"],
-	["manualRelation", "--manual-relation"],
-	["manual-relation-context", "--manual-relation-context"],
-	["manualRelationContext", "--manual-relation-context"]
-];
-async function handleUpload(parsed) {
-	try {
-		await executeUpload(parsed);
-	} catch (error) {
-		console.error(error instanceof Error ? `Error: ${error.message}` : "Error: Upload failed");
-		if (error instanceof UploadUsageError) printUsage$10();
-		process$1.exitCode = 1;
-	}
-}
-async function executeUpload(parsed, deps = defaultDeps$10) {
-	const filePath = parsed.positionals[0];
-	if (!filePath) throw new UploadUsageError("File path is required");
-	rejectRetiredUploadOrganizationOptions(parsed);
-	const projectConfig = await deps.loadProjectConfig();
-	const env = resolveCommandEnvironment(parsed, projectConfig);
-	const spaceId = resolveCommandSpace(parsed, projectConfig);
-	const assetId = parsed.options.asset;
-	const assetName = parsed.options.name;
-	const assetType = parsed.options.type || "character";
-	const requestedMediaKind = parsed.options["media-kind"] || parsed.options.mediaKind;
-	const prompt = parsed.options.prompt;
-	const model = parsed.options.model;
-	const provider = parsed.options.provider;
-	const rawProviderMetadata = parsed.options["provider-metadata"] ?? parsed.options.providerMetadata ?? parsed.options.provider_metadata;
-	const rawGenerationProvenance = parsed.options["generation-provenance"] ?? parsed.options.generationProvenance ?? parsed.options.generation_provenance;
-	const rawSourceVariantIds = parsed.options["source-variants"] ?? parsed.options.sourceVariants ?? parsed.options.sourceVariantIds ?? parsed.options["source-variant"] ?? parsed.options.sourceVariantId ?? parsed.options.parentVariantId;
-	const rawRelationType = parsed.options["relation-type"] ?? parsed.options.relationType;
-	const rawActiveVariantBehavior = parsed.options["active-variant-behavior"] ?? parsed.options.activeVariantBehavior;
-	const jsonOutput = parsed.options.json === "true";
-	if (parsed.options["dry-run"] === "true" || parsed.options.dryRun === "true") throw new UploadUsageError("--dry-run is not supported for direct file upload");
-	if (!spaceId) throw new UploadUsageError("--space is required, or run: makefx init --space <id>");
-	if (!assetId && !assetName) throw new UploadUsageError("Either --asset or --name is required");
-	const providerMetadata = parseJsonObjectOption(rawProviderMetadata, "--provider-metadata");
-	const generationProvenance = parseJsonObjectOption(rawGenerationProvenance, "--generation-provenance");
-	const sourceVariantIds = parseCsvOption(rawSourceVariantIds, "--source-variant");
-	const relationType = normalizeRelationType(rawRelationType);
-	const activeVariantBehavior = normalizeActiveVariantBehavior(rawActiveVariantBehavior);
-	if (sourceVariantIds.length === 0 && (parsed.options["relation-type"] || parsed.options.relationType)) throw new UploadUsageError("--relation-type requires --source-variant or --source-variants");
-	const mediaType = resolveMediaType(path.extname(filePath).toLowerCase(), requestedMediaKind);
-	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)}`);
-	const baseUrl = deps.resolveBaseUrl(env);
-	const accessToken = config.token.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`);
-		const fileBuffer = await deps.readFile(filePath);
-		const fileName = path.basename(filePath);
-		const formData = new FormData();
-		const blob = new Blob([fileBuffer], { type: mediaType.mimeType });
-		formData.append("file", blob, fileName);
-		formData.append("mediaKind", mediaType.mediaKind);
-		formData.append("activeVariantBehavior", activeVariantBehavior);
-		if (assetId) formData.append("assetId", assetId);
-		else {
-			formData.append("assetName", assetName);
-			formData.append("assetType", assetType);
-		}
-		if (prompt) formData.append("prompt", prompt);
-		if (model) formData.append("model", model);
-		if (provider) formData.append("provider", provider);
-		if (providerMetadata) formData.append("providerMetadata", JSON.stringify(providerMetadata));
-		if (generationProvenance) formData.append("generationProvenance", JSON.stringify(generationProvenance));
-		if (sourceVariantIds.length > 0) formData.append("lineage", JSON.stringify(sourceVariantIds.map((parentVariantId) => ({
-			parentVariantId,
-			relationType
-		}))));
-		if (!jsonOutput) {
-			deps.print(`\nUploading "${fileName}" to space ${spaceId}...`);
-			deps.print(`  Media kind: ${mediaType.mediaKind}`);
-			if (assetId) deps.print(`  Target asset: ${assetId}`);
-			else deps.print(`  Creating asset: "${assetName}" (${assetType})`);
-			if (sourceVariantIds.length === 1) deps.print(`  Source variant: ${sourceVariantIds[0]} (${relationType})`);
-			else if (sourceVariantIds.length > 1) deps.print(`  Source variants: ${sourceVariantIds.join(", ")} (${relationType})`);
-		}
-		const response = await deps.fetch(`${baseUrl}/api/spaces/${spaceId}/upload`, {
-			method: "POST",
-			headers: { "Authorization": `Bearer ${accessToken}` },
-			body: formData
-		});
-		const data = await response.json();
-		if (!response.ok) throw new Error(`Upload failed: ${"error" in data ? data.error : response.statusText}`);
-		const upload = data;
-		const result = {
-			asset: upload.asset,
-			variant: upload.variant,
-			lineage: upload.lineage
-		};
-		await recordUploadMirror({
-			deps,
-			projectRoot: projectConfig?.projectRoot,
-			env,
-			baseUrl,
-			spaceId,
-			filePath,
-			assetId: upload.asset?.id ?? upload.variant.asset_id,
-			variantId: upload.variant.id,
-			mediaKind: upload.variant.media_kind || mediaType.mediaKind,
-			mediaKey: upload.variant.media_key || upload.variant.image_key
-		});
-		if (jsonOutput) {
-			deps.print(JSON.stringify(result, null, 2));
-			return result;
-		}
-		deps.print("\nUpload successful!\n");
-		if (upload.asset) {
-			deps.print("New Asset:");
-			deps.print(`  ID:   ${upload.asset.id}`);
-			deps.print(`  Name: ${upload.asset.name}`);
-			deps.print(`  Type: ${upload.asset.type}`);
-			deps.print("");
-		}
-		deps.print("Variant:");
-		deps.print(`  ID:       ${upload.variant.id}`);
-		deps.print(`  Asset:    ${upload.variant.asset_id}`);
-		deps.print(`  Status:   ${upload.variant.status}`);
-		deps.print(`  Media:    ${upload.variant.media_kind || mediaType.mediaKind}`);
-		deps.print(`  File:     ${upload.variant.media_key || upload.variant.image_key || "-"}`);
-		if (upload.variant.image_key) deps.print(`  Image:    ${upload.variant.image_key}`);
-		if (upload.variant.thumb_key) deps.print(`  Thumb:    ${upload.variant.thumb_key}`);
-		if (upload.variant.media_mime_type) deps.print(`  MIME:     ${upload.variant.media_mime_type}`);
-		if (upload.variant.recipe) try {
-			const recipe = JSON.parse(upload.variant.recipe);
-			deps.print("\nRecipe:");
-			deps.print(`  Operation: ${recipe.operation}`);
-			deps.print(`  Original:  ${recipe.originalFilename}`);
-			deps.print(`  Uploaded:  ${recipe.uploadedAt}`);
-		} catch {}
-		deps.print("\nTo inspect:");
-		deps.print(`  makefx assets show ${upload.variant.asset_id} --space ${spaceId}`);
-		return result;
-	} catch (error) {
-		if (error.code === "ENOENT") throw new Error(`File not found: ${filePath}`);
-		throw error;
-	}
-}
-async function recordUploadMirror(input) {
-	if (!input.deps.recordMirrorForFile) return;
-	try {
-		await input.deps.recordMirrorForFile({
-			projectRoot: input.projectRoot,
-			baseUrl: input.baseUrl,
-			environment: input.env,
-			spaceId: input.spaceId,
-			filePath: input.filePath,
-			assetId: input.assetId,
-			variantId: input.variantId,
-			mediaKind: input.mediaKind,
-			mediaKey: input.mediaKey
-		});
-	} catch (error) {
-		console.warn(`Warning: upload succeeded but mirror registry was not updated: ${error instanceof Error ? error.message : String(error)}`);
-	}
+var GENERATION_REQUEST_TIMEOUT_MS = 3e5;
+var VIDEO_GENERATION_REQUEST_TIMEOUT_MS = 72e4;
+function getGenerationRequestTimeoutMs(mediaKind) {
+	return mediaKind === "video" ? VIDEO_GENERATION_REQUEST_TIMEOUT_MS : GENERATION_REQUEST_TIMEOUT_MS;
 }
-function parseJsonObjectOption(value, optionName) {
-	if (value === void 0) return void 0;
-	let parsed;
-	try {
-		parsed = JSON.parse(value);
-	} catch {
-		throw new UploadUsageError(`${optionName} must be valid JSON`);
+/**
+* Thrown when a mutation's confirmation broadcast does not arrive within the
+* timeout. The server write may still have landed — callers can re-read state
+* to confirm. Distinct from server-rejection errors (PERMISSION_DENIED,
+* VALIDATION_ERROR, …), which reject with their own message and must not be
+* treated as a missing confirmation.
+*/
+var ServerConfirmationTimeoutError = class extends Error {
+	constructor(message = "Timed out waiting for server confirmation") {
+		super(message);
+		this.name = "ServerConfirmationTimeoutError";
 	}
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new UploadUsageError(`${optionName} must be a JSON object`);
-	return parsed;
-}
-function normalizeRelationType(value) {
-	if (!value) return "derived";
-	if (value === "derived" || value === "refined" || value === "forked") return value;
-	throw new UploadUsageError("--relation-type must be derived, refined, or forked");
+};
+function booleanFromSqlite(value) {
+	return value === true || value === 1;
 }
-function normalizeActiveVariantBehavior(value) {
-	if (!value || value === "if-missing" || value === "if_missing") return "if-missing";
-	if (value === "set-active" || value === "set_active") return "set-active";
-	if (value === "keep") return "keep";
-	throw new UploadUsageError("--active-variant-behavior must be if-missing, set-active, or keep");
-}
-function rejectRetiredUploadOrganizationOptions(parsed) {
-	const usedOptions = RETIRED_UPLOAD_ORGANIZATION_OPTIONS.filter(([key]) => parsed.options[key] !== void 0).map(([, flag]) => flag);
-	if (usedOptions.length === 0) return;
-	throw new UploadUsageError(`${Array.from(new Set(usedOptions)).join(", ")} ${usedOptions.length === 1 ? "was" : "were"} removed. Upload creates assets or variants only; organize the result visually on the Space canvas. Use --source-variant for immutable lineage provenance.`);
-}
-function parseCsvOption(value, optionName) {
-	if (!value) return [];
-	if (value === "true") throw new UploadUsageError(`${optionName} requires a value`);
-	return value.split(",").map((entry) => entry.trim()).filter(Boolean);
-}
-function printUsage$10() {
-	console.log(`
-Usage:
-  makefx upload <file> --asset <id> [--space <id>]     Upload media to existing asset
-  makefx upload <file> --name <name> [--space <id>]    Upload media as a new asset
-
-Options:
-  --space <id>      Target space ID; defaults from initialized project
-  --asset <id>      Target asset ID (upload as new variant)
-  --name <name>     New asset name (creates asset + variant)
-  --type <type>     Asset type for new assets (default: character)
-  --media-kind <k>  Optional explicit kind: image, audio, or video
-  --prompt <text>   Prompt provenance for uploaded media
-  --model <model>   Model provenance for uploaded media
-  --provider <name> Provider provenance for uploaded media
-  --provider-metadata <json>     Provider metadata JSON object
-  --generation-provenance <json> Extra provenance JSON object
-  --source-variant <ids>         Comma-separated source variants for upload lineage
-  --source-variants <ids>        Alias for --source-variant
-  --relation-type <type>         Lineage type: derived, refined, or forked (default: derived)
-  --active-variant-behavior <b>  if-missing, set-active, or keep
-  --json            Print machine-readable upload output with Space IDs
-  --env <env>       Environment (production|stage|local)
-  --local           Shortcut for --env local
-
-Examples:
-  makefx upload hero.png --space abc123 --name "Hero Character"
-  makefx upload hero.png --space abc123 --name "Hero" --prompt "external render" --provider blender
-  makefx upload paintover.png --space abc123 --asset def456 --source-variant var123 --relation-type refined
-  makefx upload scene.png --space abc123 --name "Cocina" --type scene --source-variants anna,roman,bg
-  makefx upload theme.mp3 --space abc123 --name "Theme Music" --type audio
-  makefx upload cutscene.mp4 --space abc123 --name "Opening Cutscene" --type video
-  makefx upload variant.jpg --space abc123 --asset def456
-  makefx upload hero.png --space abc123 --name "Hero" --json
-`);
-}
-//#endregion
-//#region src/cli/lib/run-manifest.ts
-function createRunId(date = /* @__PURE__ */ new Date()) {
-	return `${date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z")}-${crypto.randomUUID().slice(0, 8)}`;
-}
-async function saveRunManifest(manifest, cwd = process.cwd()) {
-	const manifestPath = path.join(cwd, ".inventory", "runs", `${manifest.runId}.json`);
-	await mkdir(path.dirname(manifestPath), { recursive: true });
-	await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
-	return manifestPath;
-}
-function getRunManifestDir(projectRoot = process.cwd()) {
-	return path.join(projectRoot, ".inventory", "runs");
-}
-async function listRunManifests(projectRoot = process.cwd()) {
-	const runsDir = getRunManifestDir(projectRoot);
-	let entries;
-	try {
-		entries = await readdir(runsDir);
-	} catch (error) {
-		if (error.code === "ENOENT") return [];
-		throw error;
-	}
-	return (await Promise.all(entries.filter((entry) => entry.endsWith(".json")).map((entry) => readRunManifest(path.join(runsDir, entry))))).sort((a, b) => {
-		const byCreatedAt = Date.parse(b.manifest.createdAt) - Date.parse(a.manifest.createdAt);
-		if (Number.isFinite(byCreatedAt) && byCreatedAt !== 0) return byCreatedAt;
-		return b.manifestPath.localeCompare(a.manifestPath);
-	});
-}
-async function readRunManifest(manifestPath) {
-	const raw = await readFile(manifestPath, "utf8");
-	return {
-		manifest: normalizeRunManifest(JSON.parse(raw), manifestPath),
-		manifestPath
-	};
-}
-async function resolveRunManifest(input) {
-	if (input.latest) {
-		const manifests = await listRunManifests(input.projectRoot);
-		if (manifests.length === 0) throw new Error(`No run manifests found in ${getRunManifestDir(input.projectRoot)}`);
-		return manifests[0];
-	}
-	const selector = input.runIdOrPath;
-	if (!selector) throw new Error("Run ID, manifest path, or --latest is required");
-	return readRunManifest(looksLikeManifestPath(selector) ? path.resolve(selector) : path.join(getRunManifestDir(input.projectRoot), `${selector}.json`));
-}
-function createMediaRunExport(record, projectRoot) {
-	const pathBase = record.manifest.workingDir || projectRoot;
-	return {
-		version: 1,
-		format: "media-handoff",
-		runId: record.manifest.runId,
-		manifestPath: record.manifestPath,
-		projectRoot,
-		success: record.manifest.success,
-		prompt: record.manifest.prompt,
-		name: record.manifest.name,
-		assetType: record.manifest.assetType,
-		spaceId: record.manifest.spaceId,
-		baseUrl: record.manifest.baseUrl,
-		refs: record.manifest.refs,
-		referenceVariantIds: record.manifest.referenceVariantIds,
-		createdAt: record.manifest.createdAt,
-		completedAt: record.manifest.completedAt,
-		media: sortedMedia(record.manifest).map((media) => ({
-			...media,
-			absolutePath: path.resolve(pathBase, media.localPath)
-		})),
-		images: [...record.manifest.images].sort((a, b) => a.index - b.index).map((image) => ({
-			...image,
-			absolutePath: path.resolve(pathBase, image.localPath)
-		})),
-		failed: record.manifest.failed
-	};
-}
-function createRemotionRunExport(record, projectRoot) {
-	return {
-		...createMediaRunExport(record, projectRoot),
-		format: "remotion-keyframes"
-	};
-}
-function manifestMediaFromVariant(input) {
-	const mediaKind = input.variant.media_kind || "image";
-	const mediaKey = input.variant.media_key || input.variant.image_key;
-	if (!mediaKey) throw new Error(`Variant has no media key: ${input.variant.id}`);
-	return {
-		index: input.index,
-		mediaKind,
-		assetId: input.variant.asset_id,
-		variantId: input.variant.id,
-		mediaKey,
-		imageKey: input.variant.image_key,
-		thumbKey: input.variant.thumb_key,
-		mimeType: input.variant.media_mime_type || null,
-		sizeBytes: input.variant.media_size_bytes ?? null,
-		width: input.variant.media_width ?? null,
-		height: input.variant.media_height ?? null,
-		durationMs: input.variant.media_duration_ms ?? null,
-		localPath: input.localPath,
-		webUrl: `${input.baseUrl}/spaces/${input.spaceId}/assets/${input.variant.asset_id}`
-	};
-}
-function looksLikeManifestPath(value) {
-	return path.isAbsolute(value) || value.endsWith(".json") || value.includes("/") || value.includes("\\");
-}
-function normalizeRunManifest(manifest, manifestPath) {
-	if (manifest.version !== 1) throw new Error(`Unsupported run manifest version in ${manifestPath}`);
-	if (!isSupportedCommand(manifest.command)) throw new Error(`Unsupported run manifest command in ${manifestPath}`);
-	if (!manifest.runId || typeof manifest.runId !== "string") throw new Error(`Run manifest is missing runId: ${manifestPath}`);
-	const media = Array.isArray(manifest.media) ? manifest.media : manifest.images;
-	if (!Array.isArray(media)) throw new Error(`Run manifest is missing media: ${manifestPath}`);
-	if (!Array.isArray(manifest.failed)) throw new Error(`Run manifest is missing failed entries: ${manifestPath}`);
-	const normalizedMedia = media.map((entry) => normalizeManifestMedia(entry));
-	return {
-		...manifest,
-		mediaKind: manifest.mediaKind || inferManifestMediaKind(normalizedMedia),
-		media: normalizedMedia,
-		images: normalizedMedia.filter(isRunManifestImage)
-	};
-}
-function sortedMedia(manifest) {
-	return [...manifest.media].sort((a, b) => a.index - b.index);
-}
-function isSupportedCommand(command) {
-	return command === "generate" || command === "refine" || command === "derive" || command === "batch";
-}
-function normalizeManifestMedia(entry) {
-	const legacyImageKey = "imageKey" in entry ? entry.imageKey : null;
-	const mediaKey = "mediaKey" in entry ? entry.mediaKey : legacyImageKey;
-	return {
-		index: entry.index,
-		mediaKind: entry.mediaKind || "image",
-		assetId: entry.assetId,
-		variantId: entry.variantId,
-		mediaKey: mediaKey || "",
-		imageKey: legacyImageKey,
-		thumbKey: entry.thumbKey,
-		mimeType: "mimeType" in entry ? entry.mimeType : null,
-		sizeBytes: "sizeBytes" in entry ? entry.sizeBytes : null,
-		width: "width" in entry ? entry.width : null,
-		height: "height" in entry ? entry.height : null,
-		durationMs: "durationMs" in entry ? entry.durationMs : null,
-		localPath: entry.localPath,
-		webUrl: entry.webUrl
-	};
-}
-function isRunManifestImage(entry) {
-	return entry.mediaKind === "image" && Boolean(entry.imageKey);
-}
-function inferManifestMediaKind(media) {
-	return media[0]?.mediaKind || "image";
-}
-//#endregion
-//#region src/cli/lib/image-transfer.ts
-var MAX_FILE_SIZE_MB = 10;
-var MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024;
-var ALLOWED_EXTENSIONS = [
-	".jpg",
-	".jpeg",
-	".png",
-	".gif",
-	".webp"
-];
-var EXT_TO_MIME = {
-	".jpg": "image/jpeg",
-	".jpeg": "image/jpeg",
-	".png": "image/png",
-	".gif": "image/gif",
-	".webp": "image/webp"
-};
-function isSupportedImagePath(filePath) {
-	return ALLOWED_EXTENSIONS.includes(path.extname(filePath).toLowerCase());
-}
-function looksLikeFilePath(value) {
-	return value.startsWith(".") || value.includes("/") || value.includes("\\") || isSupportedImagePath(value);
-}
-async function uploadLocalImageAsReference(input) {
-	const ext = path.extname(input.filePath).toLowerCase();
-	if (!ALLOWED_EXTENSIONS.includes(ext)) throw new Error(`Invalid reference file type "${ext}". Allowed: ${ALLOWED_EXTENSIONS.join(", ")}`);
-	const fileStat = await stat(input.filePath);
-	if (!fileStat.isFile()) throw new Error(`Reference is not a file: ${input.filePath}`);
-	if (fileStat.size > MAX_FILE_SIZE_BYTES) throw new Error(`Reference file too large (${(fileStat.size / 1024 / 1024).toFixed(2)}MB). Maximum size: ${MAX_FILE_SIZE_MB}MB`);
-	const fileBuffer = await readFile(input.filePath);
-	const filename = path.basename(input.filePath);
-	const mimeType = EXT_TO_MIME[ext] || "image/png";
-	const assetName = input.assetName || `Reference: ${filename.replace(/\.[^/.]+$/, "")}`;
-	const formData = new FormData();
-	formData.append("file", new Blob([fileBuffer], { type: mimeType }), filename);
-	formData.append("assetName", assetName);
-	formData.append("assetType", "reference");
-	formData.append("mediaKind", DEFAULT_MEDIA_KIND);
-	const response = await fetch(`${input.baseUrl}/api/spaces/${input.spaceId}/upload`, {
-		method: "POST",
-		headers: { "Authorization": `Bearer ${input.accessToken}` },
-		body: formData
-	});
-	const data = await response.json();
-	if (!response.ok || !data.success || !data.variant) throw new Error(`Failed to upload reference "${input.filePath}": ${data.error || response.statusText}`);
-	return {
-		asset: data.asset,
-		variant: data.variant
-	};
-}
-async function downloadFile(input) {
-	if (!input.force) try {
-		if ((await stat(input.outputPath)).isFile()) throw new Error(`Output file already exists: ${input.outputPath}. Pass --force to overwrite.`);
-	} catch (error) {
-		if (error.code !== "ENOENT") throw error;
-	}
-	const headers = {};
-	if (input.accessToken) headers.Authorization = `Bearer ${input.accessToken}`;
-	const requestUrl = `${input.baseUrl}${input.requestPath}`;
-	let response;
-	try {
-		response = await fetch(requestUrl, { headers });
-	} catch (error) {
-		throw new Error(`Failed to download ${input.requestPath}: ${formatFetchError(error)}`);
-	}
-	if (!response.ok) {
-		const errorText = await readErrorText(response);
-		throw new Error(`Failed to download ${input.requestPath}: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`);
-	}
-	await mkdir(path.dirname(input.outputPath), { recursive: true });
-	if (!response.body) throw new Error(`Failed to download ${input.requestPath}: response body was empty`);
-	try {
-		await pipeline(Readable.fromWeb(response.body), createWriteStream(input.outputPath));
-	} catch (error) {
-		throw new Error(`Failed to write download ${input.requestPath} to ${input.outputPath}: ${formatFetchError(error)}`);
-	}
-	return {
-		headers: response.headers,
-		requestUrl
-	};
-}
-async function readErrorText(response) {
-	try {
-		return (await response.text()).slice(0, 500).trim();
-	} catch {
-		return "";
-	}
-}
-function formatFetchError(error) {
-	if (!(error instanceof Error)) return String(error);
-	const cause = error.cause instanceof Error ? ` (${error.cause.message})` : "";
-	return `${error.message}${cause}`;
-}
-async function downloadImage(input) {
-	await downloadFile({
-		baseUrl: input.baseUrl,
-		accessToken: input.accessToken,
-		requestPath: `/api/images/${input.imageKey}`,
-		outputPath: input.outputPath,
-		force: input.force
-	});
-}
-//#endregion
-//#region src/cli/lib/websocket-client.ts
-/**
-* WebSocket Client for CLI
-*
-* Provides WebSocket-based communication with the Space Durable Object.
-* Replaces HTTP API calls with WebSocket messages for chat and generation.
-*/
-var GENERATION_REQUEST_TIMEOUT_MS = 3e5;
-var VIDEO_GENERATION_REQUEST_TIMEOUT_MS = 72e4;
-function getGenerationRequestTimeoutMs(mediaKind) {
-	return mediaKind === "video" ? VIDEO_GENERATION_REQUEST_TIMEOUT_MS : GENERATION_REQUEST_TIMEOUT_MS;
-}
-/**
-* Thrown when a mutation's confirmation broadcast does not arrive within the
-* timeout. The server write may still have landed — callers can re-read state
-* to confirm. Distinct from server-rejection errors (PERMISSION_DENIED,
-* VALIDATION_ERROR, …), which reject with their own message and must not be
-* treated as a missing confirmation.
-*/
-var ServerConfirmationTimeoutError = class extends Error {
-	constructor(message = "Timed out waiting for server confirmation") {
-		super(message);
-		this.name = "ServerConfirmationTimeoutError";
-	}
-};
-function booleanFromSqlite(value) {
-	return value === true || value === 1;
-}
-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;
+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;
@@ -6602,176 +6167,741 @@ var WebSocketClient = class WebSocketClient {
 			try {
 				this.send(message);
 			} catch (err) {
-				this.generateHandlers.delete(requestId);
-				clearTimeout(timeout);
+				this.generateHandlers.delete(requestId);
+				clearTimeout(timeout);
+				reject(err);
+			}
+		});
+	}
+	/**
+	* Send a batch generation request and wait for all variants to finish.
+	*/
+	async sendBatchRequest(params) {
+		const requestId = crypto.randomUUID();
+		return new Promise((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				const handler = this.batchHandlers.get(requestId);
+				if (handler) {
+					this.batchHandlers.delete(requestId);
+					for (const variantId of handler.pending) this.batchVariantToRequestId.delete(variantId);
+					reject(/* @__PURE__ */ new Error("Batch request timed out"));
+				}
+			}, 3e5);
+			this.batchHandlers.set(requestId, {
+				onStarted: params.onStarted,
+				onResult: resolve,
+				reject,
+				timeout,
+				pending: /* @__PURE__ */ new Set(),
+				completed: [],
+				failed: []
+			});
+			const message = {
+				type: "batch:request",
+				requestId,
+				name: params.name,
+				assetType: params.assetType,
+				prompt: params.prompt,
+				count: params.count,
+				mode: params.mode,
+				referenceVariantIds: params.referenceVariantIds,
+				model: params.model,
+				aspectRatio: params.aspectRatio,
+				imageSize: params.imageSize,
+				mediaKind: params.mediaKind,
+				voiceId: params.voiceId,
+				dialogueVoiceIds: params.dialogueVoiceIds,
+				musicProvider: params.musicProvider
+			};
+			try {
+				this.send(message);
+			} catch (err) {
+				this.batchHandlers.delete(requestId);
+				clearTimeout(timeout);
+				reject(err);
+			}
+		});
+	}
+	/**
+	* Send a describe image request and wait for response
+	*/
+	async sendDescribeRequest(params) {
+		const requestId = crypto.randomUUID();
+		return new Promise((resolve, reject) => {
+			this.describeHandlers.set(requestId, {
+				resolve,
+				reject
+			});
+			const message = {
+				type: "describe:request",
+				requestId,
+				assetId: params.assetId,
+				variantId: params.variantId,
+				assetName: params.assetName,
+				focus: params.focus,
+				question: params.question
+			};
+			try {
+				this.send(message);
+			} catch (err) {
+				this.describeHandlers.delete(requestId);
 				reject(err);
 			}
+			setTimeout(() => {
+				if (this.describeHandlers.has(requestId)) {
+					this.describeHandlers.delete(requestId);
+					reject(/* @__PURE__ */ new Error("Describe request timed out"));
+				}
+			}, 6e4);
 		});
 	}
 	/**
-	* Send a batch generation request and wait for all variants to finish.
+	* Send a compare images request and wait for response
 	*/
-	async sendBatchRequest(params) {
+	async sendCompareRequest(params) {
 		const requestId = crypto.randomUUID();
 		return new Promise((resolve, reject) => {
-			const timeout = setTimeout(() => {
-				const handler = this.batchHandlers.get(requestId);
-				if (handler) {
-					this.batchHandlers.delete(requestId);
-					for (const variantId of handler.pending) this.batchVariantToRequestId.delete(variantId);
-					reject(/* @__PURE__ */ new Error("Batch request timed out"));
-				}
-			}, 3e5);
-			this.batchHandlers.set(requestId, {
-				onStarted: params.onStarted,
-				onResult: resolve,
-				reject,
-				timeout,
-				pending: /* @__PURE__ */ new Set(),
-				completed: [],
-				failed: []
+			this.compareHandlers.set(requestId, {
+				resolve,
+				reject
 			});
 			const message = {
-				type: "batch:request",
+				type: "compare:request",
 				requestId,
-				name: params.name,
-				assetType: params.assetType,
-				prompt: params.prompt,
-				count: params.count,
-				mode: params.mode,
-				referenceVariantIds: params.referenceVariantIds,
-				model: params.model,
-				aspectRatio: params.aspectRatio,
-				imageSize: params.imageSize,
-				mediaKind: params.mediaKind,
-				voiceId: params.voiceId,
-				dialogueVoiceIds: params.dialogueVoiceIds,
-				musicProvider: params.musicProvider
+				variantIds: params.variantIds,
+				aspects: params.aspects
 			};
 			try {
 				this.send(message);
 			} catch (err) {
-				this.batchHandlers.delete(requestId);
-				clearTimeout(timeout);
+				this.compareHandlers.delete(requestId);
 				reject(err);
 			}
+			setTimeout(() => {
+				if (this.compareHandlers.has(requestId)) {
+					this.compareHandlers.delete(requestId);
+					reject(/* @__PURE__ */ new Error("Compare request timed out"));
+				}
+			}, 6e4);
+		});
+	}
+	/**
+	* Request sync state (initial state load)
+	*/
+	requestSync() {
+		this.send({ type: "sync:request" });
+	}
+	/**
+	* Approve a pending approval
+	*/
+	approveApproval(approvalId) {
+		this.send({
+			type: "approval:approve",
+			approvalId
+		});
+	}
+	/**
+	* Reject a pending approval
+	*/
+	rejectApproval(approvalId) {
+		this.send({
+			type: "approval:reject",
+			approvalId
+		});
+	}
+	/**
+	* Request list of pending approvals
+	*/
+	listApprovals() {
+		this.send({ type: "approval:list" });
+	}
+	/**
+	* Get current session state
+	*/
+	getSession() {
+		this.send({ type: "session:get" });
+	}
+	/**
+	* Update session context (viewing, forge tray)
+	*/
+	updateSession(data) {
+		this.send({
+			type: "session:update",
+			...data
+		});
+	}
+	/**
+	* Check if connected
+	*/
+	isConnected() {
+		return this.ws !== null && this.ws.readyState === wrapper_default.OPEN;
+	}
+};
+//#endregion
+//#region src/cli/lib/reference-resolver.ts
+async function resolveCliAssetIdentifier(identifier, createClient) {
+	if (!identifier.startsWith("asset:")) return identifier;
+	return resolveAssetRef(identifier, (await readReferenceSpaceState(createClient)).assets);
+}
+async function resolveCliVariantIdentifier(identifier, createClient) {
+	if (!identifier.startsWith("asset:")) return identifier;
+	const state = await readReferenceSpaceState(createClient);
+	return resolveVariantRef(identifier, state.assets, state.variants);
+}
+async function resolveCliVariantIdentifiers(identifiers, createClient) {
+	if (!identifiers.some((identifier) => identifier.startsWith("asset:"))) return [...identifiers];
+	const state = await readReferenceSpaceState(createClient);
+	return identifiers.map((identifier) => resolveVariantRef(identifier, state.assets, state.variants));
+}
+async function readReferenceSpaceState(createClient) {
+	const client = await createClient();
+	await client.connect();
+	try {
+		const syncClient = client;
+		if (typeof syncClient.setOnSyncState !== "function" || typeof syncClient.requestSync !== "function") throw new Error("Space sync is not available");
+		return await new Promise((resolve, reject) => {
+			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();
+	}
+}
+//#endregion
+//#region src/cli/commands/upload.ts
+/**
+* Upload Command - Upload one media file to create variants
+*
+* Usage:
+*   makefx upload <file> --space <id> --asset <id>     Upload to existing asset
+*   makefx upload <file> --space <id> --name <name>    Upload as new asset
+*   makefx upload <file> --space <id> --name <name> --type <type>
+*/
+var defaultDeps$10 = {
+	loadConfig: loadStoredConfig,
+	loadProjectConfig,
+	resolveBaseUrl,
+	fetch,
+	readFile,
+	stat,
+	recordMirrorForFile,
+	createStateClient: (env, spaceId) => WebSocketClient.create(env, spaceId),
+	print: console.log
+};
+var UploadUsageError = class extends Error {};
+var RETIRED_UPLOAD_ORGANIZATION_OPTIONS = [
+	["collection", "--collection"],
+	["collection-name", "--collection-name"],
+	["collectionName", "--collection-name"],
+	["collection-role", "--collection-role"],
+	["collectionRole", "--collection-role"],
+	["collection-subject", "--collection-subject"],
+	["collectionSubject", "--collection-subject"],
+	["manual-relation", "--manual-relation"],
+	["manualRelation", "--manual-relation"],
+	["manual-relation-context", "--manual-relation-context"],
+	["manualRelationContext", "--manual-relation-context"]
+];
+async function handleUpload(parsed) {
+	try {
+		await executeUpload(parsed);
+	} catch (error) {
+		console.error(error instanceof Error ? `Error: ${error.message}` : "Error: Upload failed");
+		if (error instanceof UploadUsageError) printUsage$10();
+		process$1.exitCode = 1;
+	}
+}
+async function executeUpload(parsed, deps = defaultDeps$10) {
+	const filePath = parsed.positionals[0];
+	if (!filePath) throw new UploadUsageError("File path is required");
+	rejectRetiredUploadOrganizationOptions(parsed);
+	const projectConfig = await deps.loadProjectConfig();
+	const env = resolveCommandEnvironment(parsed, projectConfig);
+	const spaceId = resolveCommandSpace(parsed, projectConfig);
+	let assetId = parsed.options.asset;
+	const assetName = parsed.options.name;
+	const assetType = parsed.options.type || "character";
+	const requestedMediaKind = parsed.options["media-kind"] || parsed.options.mediaKind;
+	const prompt = parsed.options.prompt;
+	const model = parsed.options.model;
+	const provider = parsed.options.provider;
+	const rawProviderMetadata = parsed.options["provider-metadata"] ?? parsed.options.providerMetadata ?? parsed.options.provider_metadata;
+	const rawGenerationProvenance = parsed.options["generation-provenance"] ?? parsed.options.generationProvenance ?? parsed.options.generation_provenance;
+	const rawSourceVariantIds = parsed.options["source-variants"] ?? parsed.options.sourceVariants ?? parsed.options.sourceVariantIds ?? parsed.options["source-variant"] ?? parsed.options.sourceVariantId ?? parsed.options.parentVariantId;
+	const rawRelationType = parsed.options["relation-type"] ?? parsed.options.relationType;
+	const rawActiveVariantBehavior = parsed.options["active-variant-behavior"] ?? parsed.options.activeVariantBehavior;
+	const jsonOutput = parsed.options.json === "true";
+	if (parsed.options["dry-run"] === "true" || parsed.options.dryRun === "true") throw new UploadUsageError("--dry-run is not supported for direct file upload");
+	if (!spaceId) throw new UploadUsageError("--space is required, or run: makefx init --space <id>");
+	if (!assetId && !assetName) throw new UploadUsageError("Either --asset or --name is required");
+	const providerMetadata = parseJsonObjectOption(rawProviderMetadata, "--provider-metadata");
+	const generationProvenance = parseJsonObjectOption(rawGenerationProvenance, "--generation-provenance");
+	let sourceVariantIds = parseCsvOption(rawSourceVariantIds, "--source-variant");
+	const relationType = normalizeRelationType(rawRelationType);
+	const activeVariantBehavior = normalizeActiveVariantBehavior(rawActiveVariantBehavior);
+	if (sourceVariantIds.length === 0 && (parsed.options["relation-type"] || parsed.options.relationType)) throw new UploadUsageError("--relation-type requires --source-variant or --source-variants");
+	const mediaType = resolveMediaType(path.extname(filePath).toLowerCase(), requestedMediaKind);
+	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)}`);
+	const baseUrl = deps.resolveBaseUrl(env);
+	const accessToken = config.token.accessToken;
+	const createStateClient = () => (deps.createStateClient ?? defaultDeps$10.createStateClient)(env, spaceId);
+	if (assetId) assetId = await resolveCliAssetIdentifier(assetId, createStateClient);
+	sourceVariantIds = await resolveCliVariantIdentifiers(sourceVariantIds, createStateClient);
+	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`);
+		const fileBuffer = await deps.readFile(filePath);
+		const fileName = path.basename(filePath);
+		const formData = new FormData();
+		const blob = new Blob([fileBuffer], { type: mediaType.mimeType });
+		formData.append("file", blob, fileName);
+		formData.append("mediaKind", mediaType.mediaKind);
+		formData.append("activeVariantBehavior", activeVariantBehavior);
+		if (assetId) formData.append("assetId", assetId);
+		else {
+			formData.append("assetName", assetName);
+			formData.append("assetType", assetType);
+		}
+		if (prompt) formData.append("prompt", prompt);
+		if (model) formData.append("model", model);
+		if (provider) formData.append("provider", provider);
+		if (providerMetadata) formData.append("providerMetadata", JSON.stringify(providerMetadata));
+		if (generationProvenance) formData.append("generationProvenance", JSON.stringify(generationProvenance));
+		if (sourceVariantIds.length > 0) formData.append("lineage", JSON.stringify(sourceVariantIds.map((parentVariantId) => ({
+			parentVariantId,
+			relationType
+		}))));
+		if (!jsonOutput) {
+			deps.print(`\nUploading "${fileName}" to space ${spaceId}...`);
+			deps.print(`  Media kind: ${mediaType.mediaKind}`);
+			if (assetId) deps.print(`  Target asset: ${assetId}`);
+			else deps.print(`  Creating asset: "${assetName}" (${assetType})`);
+			if (sourceVariantIds.length === 1) deps.print(`  Source variant: ${sourceVariantIds[0]} (${relationType})`);
+			else if (sourceVariantIds.length > 1) deps.print(`  Source variants: ${sourceVariantIds.join(", ")} (${relationType})`);
+		}
+		const response = await deps.fetch(`${baseUrl}/api/spaces/${spaceId}/upload`, {
+			method: "POST",
+			headers: { "Authorization": `Bearer ${accessToken}` },
+			body: formData
+		});
+		const data = await response.json();
+		if (!response.ok) throw new Error(`Upload failed: ${"error" in data ? data.error : response.statusText}`);
+		const upload = data;
+		const result = {
+			asset: upload.asset,
+			variant: upload.variant,
+			lineage: upload.lineage
+		};
+		const resultAssetName = upload.asset?.name ?? assetName ?? "asset";
+		result.assetRef = createAssetRef(resultAssetName, upload.asset?.id ?? upload.variant.asset_id);
+		result.variantRef = createVariantRef(resultAssetName, upload.variant.asset_id, upload.variant.id);
+		await recordUploadMirror({
+			deps,
+			projectRoot: projectConfig?.projectRoot,
+			env,
+			baseUrl,
+			spaceId,
+			filePath,
+			assetId: upload.asset?.id ?? upload.variant.asset_id,
+			variantId: upload.variant.id,
+			mediaKind: upload.variant.media_kind || mediaType.mediaKind,
+			mediaKey: upload.variant.media_key || upload.variant.image_key
 		});
+		if (jsonOutput) {
+			deps.print(JSON.stringify(result, null, 2));
+			return result;
+		}
+		deps.print("\nUpload successful!\n");
+		if (upload.asset) {
+			deps.print("New Asset:");
+			deps.print(`  Ref:  ${result.assetRef}`);
+			deps.print(`  ID:   ${upload.asset.id}`);
+			deps.print(`  Name: ${upload.asset.name}`);
+			deps.print(`  Type: ${upload.asset.type}`);
+			deps.print("");
+		}
+		deps.print("Variant:");
+		deps.print(`  Ref:      ${result.variantRef}`);
+		deps.print(`  ID:       ${upload.variant.id}`);
+		deps.print(`  Asset:    ${upload.variant.asset_id}`);
+		deps.print(`  Status:   ${upload.variant.status}`);
+		deps.print(`  Media:    ${upload.variant.media_kind || mediaType.mediaKind}`);
+		deps.print(`  File:     ${upload.variant.media_key || upload.variant.image_key || "-"}`);
+		if (upload.variant.image_key) deps.print(`  Image:    ${upload.variant.image_key}`);
+		if (upload.variant.thumb_key) deps.print(`  Thumb:    ${upload.variant.thumb_key}`);
+		if (upload.variant.media_mime_type) deps.print(`  MIME:     ${upload.variant.media_mime_type}`);
+		if (upload.variant.recipe) try {
+			const recipe = JSON.parse(upload.variant.recipe);
+			deps.print("\nRecipe:");
+			deps.print(`  Operation: ${recipe.operation}`);
+			deps.print(`  Original:  ${recipe.originalFilename}`);
+			deps.print(`  Uploaded:  ${recipe.uploadedAt}`);
+		} catch {}
+		deps.print("\nTo inspect:");
+		deps.print(`  makefx assets show ${result.assetRef} --space ${spaceId}`);
+		return result;
+	} catch (error) {
+		if (error.code === "ENOENT") throw new Error(`File not found: ${filePath}`);
+		throw error;
 	}
-	/**
-	* Send a describe image request and wait for response
-	*/
-	async sendDescribeRequest(params) {
-		const requestId = crypto.randomUUID();
-		return new Promise((resolve, reject) => {
-			this.describeHandlers.set(requestId, {
-				resolve,
-				reject
-			});
-			const message = {
-				type: "describe:request",
-				requestId,
-				assetId: params.assetId,
-				variantId: params.variantId,
-				assetName: params.assetName,
-				focus: params.focus,
-				question: params.question
-			};
-			try {
-				this.send(message);
-			} catch (err) {
-				this.describeHandlers.delete(requestId);
-				reject(err);
-			}
-			setTimeout(() => {
-				if (this.describeHandlers.has(requestId)) {
-					this.describeHandlers.delete(requestId);
-					reject(/* @__PURE__ */ new Error("Describe request timed out"));
-				}
-			}, 6e4);
+}
+async function recordUploadMirror(input) {
+	if (!input.deps.recordMirrorForFile) return;
+	try {
+		await input.deps.recordMirrorForFile({
+			projectRoot: input.projectRoot,
+			baseUrl: input.baseUrl,
+			environment: input.env,
+			spaceId: input.spaceId,
+			filePath: input.filePath,
+			assetId: input.assetId,
+			variantId: input.variantId,
+			mediaKind: input.mediaKind,
+			mediaKey: input.mediaKey
 		});
+	} catch (error) {
+		console.warn(`Warning: upload succeeded but mirror registry was not updated: ${error instanceof Error ? error.message : String(error)}`);
 	}
-	/**
-	* Send a compare images request and wait for response
-	*/
-	async sendCompareRequest(params) {
-		const requestId = crypto.randomUUID();
-		return new Promise((resolve, reject) => {
-			this.compareHandlers.set(requestId, {
-				resolve,
-				reject
-			});
-			const message = {
-				type: "compare:request",
-				requestId,
-				variantIds: params.variantIds,
-				aspects: params.aspects
-			};
-			try {
-				this.send(message);
-			} catch (err) {
-				this.compareHandlers.delete(requestId);
-				reject(err);
-			}
-			setTimeout(() => {
-				if (this.compareHandlers.has(requestId)) {
-					this.compareHandlers.delete(requestId);
-					reject(/* @__PURE__ */ new Error("Compare request timed out"));
-				}
-			}, 6e4);
-		});
+}
+function parseJsonObjectOption(value, optionName) {
+	if (value === void 0) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		throw new UploadUsageError(`${optionName} must be valid JSON`);
 	}
-	/**
-	* Request sync state (initial state load)
-	*/
-	requestSync() {
-		this.send({ type: "sync:request" });
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new UploadUsageError(`${optionName} must be a JSON object`);
+	return parsed;
+}
+function normalizeRelationType(value) {
+	if (!value) return "derived";
+	if (value === "derived" || value === "refined" || value === "forked") return value;
+	throw new UploadUsageError("--relation-type must be derived, refined, or forked");
+}
+function normalizeActiveVariantBehavior(value) {
+	if (!value || value === "if-missing" || value === "if_missing") return "if-missing";
+	if (value === "set-active" || value === "set_active") return "set-active";
+	if (value === "keep") return "keep";
+	throw new UploadUsageError("--active-variant-behavior must be if-missing, set-active, or keep");
+}
+function rejectRetiredUploadOrganizationOptions(parsed) {
+	const usedOptions = RETIRED_UPLOAD_ORGANIZATION_OPTIONS.filter(([key]) => parsed.options[key] !== void 0).map(([, flag]) => flag);
+	if (usedOptions.length === 0) return;
+	throw new UploadUsageError(`${Array.from(new Set(usedOptions)).join(", ")} ${usedOptions.length === 1 ? "was" : "were"} removed. Upload creates assets or variants only; organize the result visually on the Space canvas. Use --source-variant for immutable lineage provenance.`);
+}
+function parseCsvOption(value, optionName) {
+	if (!value) return [];
+	if (value === "true") throw new UploadUsageError(`${optionName} requires a value`);
+	return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+}
+function printUsage$10() {
+	console.log(`
+Usage:
+  makefx upload <file> --asset <id> [--space <id>]     Upload media to existing asset
+  makefx upload <file> --name <name> [--space <id>]    Upload media as a new asset
+
+Options:
+  --space <id>      Target space ID; defaults from initialized project
+  --asset <id>      Target asset ID (upload as new variant)
+  --name <name>     New asset name (creates asset + variant)
+  --type <type>     Asset type for new assets (default: character)
+  --media-kind <k>  Optional explicit kind: image, audio, or video
+  --prompt <text>   Prompt provenance for uploaded media
+  --model <model>   Model provenance for uploaded media
+  --provider <name> Provider provenance for uploaded media
+  --provider-metadata <json>     Provider metadata JSON object
+  --generation-provenance <json> Extra provenance JSON object
+  --source-variant <ids>         Comma-separated source variants for upload lineage
+  --source-variants <ids>        Alias for --source-variant
+  --relation-type <type>         Lineage type: derived, refined, or forked (default: derived)
+  --active-variant-behavior <b>  if-missing, set-active, or keep
+  --json            Print machine-readable upload output with Space IDs
+  --env <env>       Environment (production|stage|local)
+  --local           Shortcut for --env local
+
+Examples:
+  makefx upload hero.png --space abc123 --name "Hero Character"
+  makefx upload hero.png --space abc123 --name "Hero" --prompt "external render" --provider blender
+  makefx upload paintover.png --space abc123 --asset def456 --source-variant var123 --relation-type refined
+  makefx upload scene.png --space abc123 --name "Cocina" --type scene --source-variants anna,roman,bg
+  makefx upload theme.mp3 --space abc123 --name "Theme Music" --type audio
+  makefx upload cutscene.mp4 --space abc123 --name "Opening Cutscene" --type video
+  makefx upload variant.jpg --space abc123 --asset def456
+  makefx upload hero.png --space abc123 --name "Hero" --json
+`);
+}
+//#endregion
+//#region src/cli/lib/run-manifest.ts
+function createRunId(date = /* @__PURE__ */ new Date()) {
+	return `${date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z")}-${crypto.randomUUID().slice(0, 8)}`;
+}
+async function saveRunManifest(manifest, cwd = process.cwd()) {
+	const manifestPath = path.join(cwd, ".inventory", "runs", `${manifest.runId}.json`);
+	await mkdir(path.dirname(manifestPath), { recursive: true });
+	await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+	return manifestPath;
+}
+function getRunManifestDir(projectRoot = process.cwd()) {
+	return path.join(projectRoot, ".inventory", "runs");
+}
+async function listRunManifests(projectRoot = process.cwd()) {
+	const runsDir = getRunManifestDir(projectRoot);
+	let entries;
+	try {
+		entries = await readdir(runsDir);
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
 	}
-	/**
-	* Approve a pending approval
-	*/
-	approveApproval(approvalId) {
-		this.send({
-			type: "approval:approve",
-			approvalId
-		});
+	return (await Promise.all(entries.filter((entry) => entry.endsWith(".json")).map((entry) => readRunManifest(path.join(runsDir, entry))))).sort((a, b) => {
+		const byCreatedAt = Date.parse(b.manifest.createdAt) - Date.parse(a.manifest.createdAt);
+		if (Number.isFinite(byCreatedAt) && byCreatedAt !== 0) return byCreatedAt;
+		return b.manifestPath.localeCompare(a.manifestPath);
+	});
+}
+async function readRunManifest(manifestPath) {
+	const raw = await readFile(manifestPath, "utf8");
+	return {
+		manifest: normalizeRunManifest(JSON.parse(raw), manifestPath),
+		manifestPath
+	};
+}
+async function resolveRunManifest(input) {
+	if (input.latest) {
+		const manifests = await listRunManifests(input.projectRoot);
+		if (manifests.length === 0) throw new Error(`No run manifests found in ${getRunManifestDir(input.projectRoot)}`);
+		return manifests[0];
 	}
-	/**
-	* Reject a pending approval
-	*/
-	rejectApproval(approvalId) {
-		this.send({
-			type: "approval:reject",
-			approvalId
-		});
+	const selector = input.runIdOrPath;
+	if (!selector) throw new Error("Run ID, manifest path, or --latest is required");
+	return readRunManifest(looksLikeManifestPath(selector) ? path.resolve(selector) : path.join(getRunManifestDir(input.projectRoot), `${selector}.json`));
+}
+function createMediaRunExport(record, projectRoot) {
+	const pathBase = record.manifest.workingDir || projectRoot;
+	return {
+		version: 1,
+		format: "media-handoff",
+		runId: record.manifest.runId,
+		manifestPath: record.manifestPath,
+		projectRoot,
+		success: record.manifest.success,
+		prompt: record.manifest.prompt,
+		name: record.manifest.name,
+		assetType: record.manifest.assetType,
+		spaceId: record.manifest.spaceId,
+		baseUrl: record.manifest.baseUrl,
+		refs: record.manifest.refs,
+		referenceVariantIds: record.manifest.referenceVariantIds,
+		createdAt: record.manifest.createdAt,
+		completedAt: record.manifest.completedAt,
+		media: sortedMedia(record.manifest).map((media) => ({
+			...media,
+			absolutePath: path.resolve(pathBase, media.localPath)
+		})),
+		images: [...record.manifest.images].sort((a, b) => a.index - b.index).map((image) => ({
+			...image,
+			absolutePath: path.resolve(pathBase, image.localPath)
+		})),
+		failed: record.manifest.failed
+	};
+}
+function createRemotionRunExport(record, projectRoot) {
+	return {
+		...createMediaRunExport(record, projectRoot),
+		format: "remotion-keyframes"
+	};
+}
+function manifestMediaFromVariant(input) {
+	const mediaKind = input.variant.media_kind || "image";
+	const mediaKey = input.variant.media_key || input.variant.image_key;
+	if (!mediaKey) throw new Error(`Variant has no media key: ${input.variant.id}`);
+	return {
+		index: input.index,
+		mediaKind,
+		assetId: input.variant.asset_id,
+		variantId: input.variant.id,
+		mediaKey,
+		imageKey: input.variant.image_key,
+		thumbKey: input.variant.thumb_key,
+		mimeType: input.variant.media_mime_type || null,
+		sizeBytes: input.variant.media_size_bytes ?? null,
+		width: input.variant.media_width ?? null,
+		height: input.variant.media_height ?? null,
+		durationMs: input.variant.media_duration_ms ?? null,
+		localPath: input.localPath,
+		webUrl: `${input.baseUrl}/spaces/${input.spaceId}/assets/${input.variant.asset_id}`
+	};
+}
+function looksLikeManifestPath(value) {
+	return path.isAbsolute(value) || value.endsWith(".json") || value.includes("/") || value.includes("\\");
+}
+function normalizeRunManifest(manifest, manifestPath) {
+	if (manifest.version !== 1) throw new Error(`Unsupported run manifest version in ${manifestPath}`);
+	if (!isSupportedCommand(manifest.command)) throw new Error(`Unsupported run manifest command in ${manifestPath}`);
+	if (!manifest.runId || typeof manifest.runId !== "string") throw new Error(`Run manifest is missing runId: ${manifestPath}`);
+	const media = Array.isArray(manifest.media) ? manifest.media : manifest.images;
+	if (!Array.isArray(media)) throw new Error(`Run manifest is missing media: ${manifestPath}`);
+	if (!Array.isArray(manifest.failed)) throw new Error(`Run manifest is missing failed entries: ${manifestPath}`);
+	const normalizedMedia = media.map((entry) => normalizeManifestMedia(entry));
+	return {
+		...manifest,
+		mediaKind: manifest.mediaKind || inferManifestMediaKind(normalizedMedia),
+		media: normalizedMedia,
+		images: normalizedMedia.filter(isRunManifestImage)
+	};
+}
+function sortedMedia(manifest) {
+	return [...manifest.media].sort((a, b) => a.index - b.index);
+}
+function isSupportedCommand(command) {
+	return command === "generate" || command === "refine" || command === "derive" || command === "batch";
+}
+function normalizeManifestMedia(entry) {
+	const legacyImageKey = "imageKey" in entry ? entry.imageKey : null;
+	const mediaKey = "mediaKey" in entry ? entry.mediaKey : legacyImageKey;
+	return {
+		index: entry.index,
+		mediaKind: entry.mediaKind || "image",
+		assetId: entry.assetId,
+		variantId: entry.variantId,
+		mediaKey: mediaKey || "",
+		imageKey: legacyImageKey,
+		thumbKey: entry.thumbKey,
+		mimeType: "mimeType" in entry ? entry.mimeType : null,
+		sizeBytes: "sizeBytes" in entry ? entry.sizeBytes : null,
+		width: "width" in entry ? entry.width : null,
+		height: "height" in entry ? entry.height : null,
+		durationMs: "durationMs" in entry ? entry.durationMs : null,
+		localPath: entry.localPath,
+		webUrl: entry.webUrl
+	};
+}
+function isRunManifestImage(entry) {
+	return entry.mediaKind === "image" && Boolean(entry.imageKey);
+}
+function inferManifestMediaKind(media) {
+	return media[0]?.mediaKind || "image";
+}
+//#endregion
+//#region src/cli/lib/image-transfer.ts
+var MAX_FILE_SIZE_MB = 10;
+var MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024;
+var ALLOWED_EXTENSIONS = [
+	".jpg",
+	".jpeg",
+	".png",
+	".gif",
+	".webp"
+];
+var EXT_TO_MIME = {
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".png": "image/png",
+	".gif": "image/gif",
+	".webp": "image/webp"
+};
+function isSupportedImagePath(filePath) {
+	return ALLOWED_EXTENSIONS.includes(path.extname(filePath).toLowerCase());
+}
+function looksLikeFilePath(value) {
+	return value.startsWith(".") || value.includes("/") || value.includes("\\") || isSupportedImagePath(value);
+}
+async function uploadLocalImageAsReference(input) {
+	const ext = path.extname(input.filePath).toLowerCase();
+	if (!ALLOWED_EXTENSIONS.includes(ext)) throw new Error(`Invalid reference file type "${ext}". Allowed: ${ALLOWED_EXTENSIONS.join(", ")}`);
+	const fileStat = await stat(input.filePath);
+	if (!fileStat.isFile()) throw new Error(`Reference is not a file: ${input.filePath}`);
+	if (fileStat.size > MAX_FILE_SIZE_BYTES) throw new Error(`Reference file too large (${(fileStat.size / 1024 / 1024).toFixed(2)}MB). Maximum size: ${MAX_FILE_SIZE_MB}MB`);
+	const fileBuffer = await readFile(input.filePath);
+	const filename = path.basename(input.filePath);
+	const mimeType = EXT_TO_MIME[ext] || "image/png";
+	const assetName = input.assetName || `Reference: ${filename.replace(/\.[^/.]+$/, "")}`;
+	const formData = new FormData();
+	formData.append("file", new Blob([fileBuffer], { type: mimeType }), filename);
+	formData.append("assetName", assetName);
+	formData.append("assetType", "reference");
+	formData.append("mediaKind", DEFAULT_MEDIA_KIND);
+	const response = await fetch(`${input.baseUrl}/api/spaces/${input.spaceId}/upload`, {
+		method: "POST",
+		headers: { "Authorization": `Bearer ${input.accessToken}` },
+		body: formData
+	});
+	const data = await response.json();
+	if (!response.ok || !data.success || !data.variant) throw new Error(`Failed to upload reference "${input.filePath}": ${data.error || response.statusText}`);
+	return {
+		asset: data.asset,
+		variant: data.variant
+	};
+}
+async function downloadFile(input) {
+	if (!input.force) try {
+		if ((await stat(input.outputPath)).isFile()) throw new Error(`Output file already exists: ${input.outputPath}. Pass --force to overwrite.`);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
 	}
-	/**
-	* Request list of pending approvals
-	*/
-	listApprovals() {
-		this.send({ type: "approval:list" });
+	const headers = {};
+	if (input.accessToken) headers.Authorization = `Bearer ${input.accessToken}`;
+	const requestUrl = `${input.baseUrl}${input.requestPath}`;
+	let response;
+	try {
+		response = await fetch(requestUrl, { headers });
+	} catch (error) {
+		throw new Error(`Failed to download ${input.requestPath}: ${formatFetchError(error)}`);
 	}
-	/**
-	* Get current session state
-	*/
-	getSession() {
-		this.send({ type: "session:get" });
+	if (!response.ok) {
+		const errorText = await readErrorText(response);
+		throw new Error(`Failed to download ${input.requestPath}: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}`);
 	}
-	/**
-	* Update session context (viewing, forge tray)
-	*/
-	updateSession(data) {
-		this.send({
-			type: "session:update",
-			...data
-		});
+	await mkdir(path.dirname(input.outputPath), { recursive: true });
+	if (!response.body) throw new Error(`Failed to download ${input.requestPath}: response body was empty`);
+	try {
+		await pipeline(Readable.fromWeb(response.body), createWriteStream(input.outputPath));
+	} catch (error) {
+		throw new Error(`Failed to write download ${input.requestPath} to ${input.outputPath}: ${formatFetchError(error)}`);
 	}
-	/**
-	* Check if connected
-	*/
-	isConnected() {
-		return this.ws !== null && this.ws.readyState === wrapper_default.OPEN;
+	return {
+		headers: response.headers,
+		requestUrl
+	};
+}
+async function readErrorText(response) {
+	try {
+		return (await response.text()).slice(0, 500).trim();
+	} catch {
+		return "";
 	}
-};
+}
+function formatFetchError(error) {
+	if (!(error instanceof Error)) return String(error);
+	const cause = error.cause instanceof Error ? ` (${error.cause.message})` : "";
+	return `${error.message}${cause}`;
+}
+async function downloadImage(input) {
+	await downloadFile({
+		baseUrl: input.baseUrl,
+		accessToken: input.accessToken,
+		requestPath: `/api/images/${input.imageKey}`,
+		outputPath: input.outputPath,
+		force: input.force
+	});
+}
 //#endregion
 //#region src/shared/videoGenerationOptions.ts
 var VIDEO_GENERATION_ASPECT_RATIOS = ["16:9", "9:16"];
@@ -7347,7 +7477,7 @@ async function executeGenerate(parsed, ctx, client, deps, mediaKind, followOptio
 	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 	const videoFrameRefs = parseVideoFrameReferenceOptions(parsed, "generate", mediaKind).refs;
 	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 referenceVariantIds = videoFrameRefs.length > 0 ? await resolveReferenceVariantIds(videoFrameRefs, ctx, deps, state?.variants, CLI_GENERATION_MEDIA_KIND, state?.assets) : [];
 	const imageOptions = parseImageGenerationOptions(parsed, mediaKind);
 	const audioModelOptions = parseAudioGenerationOptions(parsed, mediaKind);
 	const videoAudioOptions = parseVideoAudioOptions(parsed, mediaKind);
@@ -7379,7 +7509,7 @@ async function executeGenerate(parsed, ctx, client, deps, mediaKind, followOptio
 			...videoAudioOptions,
 			...videoOptions,
 			onStarted: (started) => {
-				startedVariantId = started.jobId;
+				startedVariantId = compactStartedVariantRef(started);
 				printFollowHint(started, ctx, outputPath, "generate", mediaKind, followCommandOptions);
 			}
 		});
@@ -7434,9 +7564,11 @@ function parseMusicProviderOption(parsed, mediaKind, assetType) {
 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 sourceVariantIdentifier = requireOption$1(parsed, "variant");
 	const state = await requestSpaceState$1(client);
-	const sourceVariant = state.variants.find((variant) => variant.id === sourceVariantId);
+	const variants = state.variants;
+	const sourceVariantId = resolveVariantRef(sourceVariantIdentifier, state.assets, variants);
+	const sourceVariant = 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);
 	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -7459,7 +7591,7 @@ async function executeRefine(parsed, ctx, client, deps, mediaKind) {
 			...videoAudioOptions,
 			...videoOptions,
 			onStarted: (started) => {
-				startedVariantId = started.jobId;
+				startedVariantId = compactStartedVariantRef(started);
 				printFollowHint(started, ctx, outputPath, "refine", mediaKind, followCommandOptions);
 			}
 		});
@@ -7503,7 +7635,8 @@ 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$1(client)).variants, videoFrameRefs.length > 0 ? CLI_GENERATION_MEDIA_KIND : mediaKind);
+	const state = await requestSpaceState$1(client);
+	const referenceVariantIds = await resolveReferenceVariantIds(referenceRefs, ctx, deps, state.variants, videoFrameRefs.length > 0 ? CLI_GENERATION_MEDIA_KIND : mediaKind, state.assets);
 	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 	const videoAudioOptions = parseVideoAudioOptions(parsed, mediaKind);
 	const videoOptions = parseVideoGenerationOptions(parsed, mediaKind);
@@ -7530,7 +7663,7 @@ async function executeDerive(parsed, ctx, client, deps, mediaKind, followOptions
 			...videoAudioOptions,
 			...videoOptions,
 			onStarted: (started) => {
-				startedVariantId = started.jobId;
+				startedVariantId = compactStartedVariantRef(started);
 				printFollowHint(started, ctx, outputPath, "derive", mediaKind, followCommandOptions);
 			}
 		});
@@ -7564,8 +7697,8 @@ async function executeDerive(parsed, ctx, client, deps, mediaKind, followOptions
 	return result;
 }
 async function executeFollow(parsed, ctx, client, deps, command, mediaKind, followOptions = {}) {
-	const variantId = normalizeCliOption(parsed.options.follow);
-	if (!variantId) throw new Error("--follow requires a variant ID");
+	const variantIdentifier = normalizeCliOption(parsed.options.follow);
+	if (!variantIdentifier) throw new Error("--follow requires a variant ID");
 	const outputPath = getOutputPath$1(parsed);
 	const timeoutMs = parseFollowTimeoutMs(parsed, mediaKind);
 	const collectionPlacement = parseCollectionPlacementOptions(parsed);
@@ -7573,9 +7706,11 @@ async function executeFollow(parsed, ctx, client, deps, command, mediaKind, foll
 		...followOptions,
 		...collectionPlacement
 	};
-	console.log(`Following variant ${variantId} in space ${ctx.spaceId}...`);
 	const state = await requestSpaceState$1(client);
-	const initialVariant = state.variants.find((variant) => variant.id === variantId);
+	const variants = state.variants;
+	const variantId = resolveVariantRef(variantIdentifier, state.assets, variants);
+	console.log(`Following variant ${variantId} in space ${ctx.spaceId}...`);
+	const initialVariant = variants.find((variant) => variant.id === variantId);
 	if (!initialVariant) throw new Error(`Variant not found in space sync state: ${variantId}`);
 	const initialStatus = initialVariant.status;
 	const requestId = `follow:${variantId}`;
@@ -7723,7 +7858,7 @@ async function executeBatch(parsed, ctx, client, deps, mediaKind, saveBatchManif
 	const audioModelOptions = parseAudioGenerationOptions(parsed, mediaKind);
 	if (mediaKind === "image") validateImageReferenceCount(imageOptions.model, refs.length);
 	const state = await requestSpaceState$1(client);
-	const referenceVariantIds = refs.length > 0 ? await resolveReferenceVariantIds(refs, ctx, deps, state.variants, mediaKind) : void 0;
+	const referenceVariantIds = refs.length > 0 ? await resolveReferenceVariantIds(refs, ctx, deps, state.variants, mediaKind, state.assets) : void 0;
 	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 	const runId = deps.createRunId();
 	const collectionPlacement = parseCollectionPlacementOptions(parsed);
@@ -7927,7 +8062,7 @@ function parseRefs(value) {
 	if (refs.length === 0) throw new Error("--refs must include at least one reference");
 	return refs;
 }
-async function resolveReferenceVariantIds(refs, ctx, deps, variants = [], mediaKind = CLI_GENERATION_MEDIA_KIND) {
+async function resolveReferenceVariantIds(refs, ctx, deps, variants = [], mediaKind = CLI_GENERATION_MEDIA_KIND, assets = []) {
 	const variantIds = [];
 	for (const ref of refs) {
 		if (await deps.fileExists(ref)) {
@@ -7970,8 +8105,9 @@ async function resolveReferenceVariantIds(refs, ctx, deps, variants = [], mediaK
 			continue;
 		}
 		if (looksLikeFilePath(ref)) throw new Error(`Reference file not found: ${ref}`);
-		validateReferenceVariant(ref, variants, mediaKind);
-		variantIds.push(ref);
+		const variantId = resolveVariantRef(ref, assets, variants);
+		validateReferenceVariant(variantId, variants, mediaKind);
+		variantIds.push(variantId);
 	}
 	return variantIds;
 }
@@ -8059,8 +8195,8 @@ function printResult(result, outputPath, ctx, manifestPath) {
 	const variant = result.variant;
 	if (!variant) return;
 	console.log("\nDone.\n");
-	console.log(`  Asset:   ${variant.asset_id}`);
-	console.log(`  Variant: ${variant.id}`);
+	console.log(`  Asset:   ${createAssetRef("asset", variant.asset_id)}`);
+	console.log(`  Variant: ${createVariantRef("asset", variant.asset_id, variant.id)}`);
 	console.log(`  Media:   ${variant.media_key || variant.image_key || "-"}`);
 	if (variant.image_key && variant.media_key !== variant.image_key) console.log(`  Image:   ${variant.image_key}`);
 	console.log(`  Local:   ${outputPath}`);
@@ -8068,8 +8204,12 @@ function printResult(result, outputPath, ctx, manifestPath) {
 	console.log(`  Web:     ${ctx.baseUrl}/spaces/${ctx.spaceId}/assets/${variant.asset_id}`);
 }
 function printFollowHint(started, ctx, outputPath, command, mediaKind, options = {}) {
-	console.log(`  Started variant: ${started.jobId}`);
-	console.log(`  Follow: ${formatFollowCommand(started.jobId, outputPath, ctx, command, mediaKind, options)}`);
+	const variantRef = compactStartedVariantRef(started);
+	console.log(`  Started variant: ${variantRef}`);
+	console.log(`  Follow: ${formatFollowCommand(variantRef, outputPath, ctx, command, mediaKind, options)}`);
+}
+function compactStartedVariantRef(started) {
+	return createVariantRef(started.assetName || "asset", started.assetId || "asset", started.jobId);
 }
 function throwGenerationWaitErrorIfNeeded(input, params) {
 	if (!isGenerationWaitTimeout(input)) throw input;
@@ -8137,7 +8277,7 @@ function formatFollowCommand(variantId, outputPath, ctx, command, mediaKind, opt
 	].map(shellQuote).join(" ");
 }
 function shellQuote(value) {
-	if (/^[A-Za-z0-9_./:=@-]+$/.test(value)) return value;
+	if (/^[A-Za-z0-9_./:=@~-]+$/.test(value)) return value;
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function getPrompt(parsed, command) {
@@ -8851,10 +8991,10 @@ async function executeAssets(parsed, deps = defaultDeps$5) {
 		};
 	}
 	if (subcommand === "show") {
-		const assetId = parsed.positionals[1];
-		if (!assetId) throw new Error("Asset ID is required: makefx assets show <asset-id>");
-		const details = await getAssetDetails(ctx, deps, assetId);
-		if (parsed.options.json === "true") deps.print(JSON.stringify(details, null, 2));
+		const identifier = parsed.positionals[1];
+		if (!identifier) throw new Error("Asset ID is required: makefx assets show <asset-id>");
+		const details = await getAssetDetails(ctx, deps, await resolveAssetAtBoundary(ctx, deps, identifier));
+		if (parsed.options.json === "true") deps.print(JSON.stringify(toAssetDetailsJson(details), null, 2));
 		else printAssetDetails(details, ctx, deps.print);
 		return {
 			type: "show",
@@ -8862,10 +9002,10 @@ async function executeAssets(parsed, deps = defaultDeps$5) {
 		};
 	}
 	if (subcommand === "download") {
-		const ref = parsed.positionals[1];
-		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 identifier = parsed.positionals[1];
+		if (!identifier) 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 resolved = resolveDownloadRef(await resolveVariantAtBoundary$1(ctx, deps, identifier), ctx);
 		let download;
 		try {
 			download = await deps.downloadFile({
@@ -8896,8 +9036,9 @@ async function executeAssets(parsed, deps = defaultDeps$5) {
 		};
 	}
 	if (subcommand === "delete") {
-		const assetId = parsed.positionals[1];
-		if (!assetId) throw new Error("Asset ID is required: makefx assets delete <asset-id>");
+		const identifier = parsed.positionals[1];
+		if (!identifier) throw new Error("Asset ID is required: makefx assets delete <asset-id>");
+		const assetId = await resolveAssetAtBoundary(ctx, deps, identifier);
 		await withAssetClient(ctx, deps, (client) => client.deleteAsset(assetId));
 		deps.print(`Deleted asset ${assetId}`);
 		return {
@@ -8906,9 +9047,10 @@ async function executeAssets(parsed, deps = defaultDeps$5) {
 		};
 	}
 	if (subcommand === "rename") {
-		const assetId = parsed.positionals[1];
+		const identifier = parsed.positionals[1];
 		const name = parsed.positionals[2];
-		if (!assetId || !name) throw new Error("Usage: makefx assets rename <asset-id> \"<new-name>\"");
+		if (!identifier || !name) throw new Error("Usage: makefx assets rename <asset-id> \"<new-name>\"");
+		const assetId = await resolveAssetAtBoundary(ctx, deps, identifier);
 		const asset = await withAssetClient(ctx, deps, (client) => client.renameAsset(assetId, name));
 		deps.print(`Renamed asset ${assetId} -> "${asset.name}"`);
 		return {
@@ -8917,10 +9059,11 @@ async function executeAssets(parsed, deps = defaultDeps$5) {
 		};
 	}
 	if (subcommand === "set-active") {
-		const assetId = parsed.positionals[1];
-		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);
+		const assetIdentifier = parsed.positionals[1];
+		const variantIdentifier = parsed.positionals[2] || normalizeOption$1(parsed.options.variant);
+		if (!assetIdentifier || !variantIdentifier) throw new Error("Usage: makefx assets set-active <asset-id> <variant-id>");
+		const assetId = await resolveAssetAtBoundary(ctx, deps, assetIdentifier);
+		const asset = await setActiveVariant(ctx, deps, assetId, await resolveVariantAtBoundary$1(ctx, deps, variantIdentifier));
 		deps.print(`Set active variant of asset ${assetId} to ${asset.active_variant_id}`);
 		return {
 			type: "set-active",
@@ -8950,6 +9093,15 @@ async function buildContext$5(parsed, deps) {
 		projectRoot: projectConfig?.projectRoot
 	};
 }
+function createReferenceClient(ctx, deps) {
+	return () => deps.createMutationClient(ctx.env, ctx.spaceId);
+}
+function resolveAssetAtBoundary(ctx, deps, identifier) {
+	return resolveCliAssetIdentifier(identifier, createReferenceClient(ctx, deps));
+}
+function resolveVariantAtBoundary$1(ctx, deps, identifier) {
+	return resolveCliVariantIdentifier(identifier, createReferenceClient(ctx, deps));
+}
 async function buildAuthContext(parsed, deps) {
 	const env = resolveCommandEnvironment(parsed, await deps.loadProjectConfig());
 	const config = await deps.loadConfig(env);
@@ -8983,7 +9135,11 @@ async function searchAssets(parsed, deps) {
 	const response = await deps.fetch(`${ctx.baseUrl}/api/assets/search?${params.toString()}`, { headers: { Authorization: `Bearer ${ctx.accessToken}` } });
 	if (!response.ok) throw new Error(`Search failed: ${response.status} - ${await response.text()}`);
 	const results = (await response.json()).results ?? [];
-	if (parsed.options.json === "true") deps.print(JSON.stringify(results, null, 2));
+	if (parsed.options.json === "true") deps.print(JSON.stringify(results.map((result) => ({
+		...result,
+		assetRef: createAssetRef(result.assetName, result.assetId),
+		variantRef: result.activeVariantId ? createVariantRef(result.assetName, result.assetId, result.activeVariantId) : null
+	})), null, 2));
 	else printAssetSearchResults(results, deps.print);
 	return {
 		type: "search",
@@ -8992,10 +9148,11 @@ async function searchAssets(parsed, deps) {
 }
 async function cloneAsset(parsed, deps) {
 	const ctx = await buildAuthContext(parsed, deps);
-	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 sourceVariantIdentifier = parsed.positionals[1] ?? normalizeOption$1(parsed.options.variant);
+	if (!sourceVariantIdentifier) 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>");
+	const sourceVariantId = await resolveCliVariantIdentifier(sourceVariantIdentifier, () => deps.createMutationClient(ctx.env, sourceSpaceId));
 	const body = {
 		sourceSpaceId,
 		sourceVariantId
@@ -9014,14 +9171,20 @@ async function cloneAsset(parsed, deps) {
 	});
 	if (!response.ok) throw new Error(`Clone failed: ${response.status} - ${await response.text()}`);
 	const payload = await response.json();
-	if (parsed.options.json === "true") deps.print(JSON.stringify(payload, null, 2));
+	const clonedAsset = payload.asset;
+	const clonedVariantPayload = payload.variant;
+	const clonedVariant = clonedVariantPayload?.variant ?? clonedVariantPayload;
+	const clonedAssetRef = clonedAsset?.id ? createAssetRef(clonedAsset.name ?? "asset", clonedAsset.id) : void 0;
+	const clonedVariantRef = clonedAsset?.id && clonedVariant?.id ? createVariantRef(clonedAsset.name ?? "asset", clonedAsset.id, clonedVariant.id) : void 0;
+	if (parsed.options.json === "true") deps.print(JSON.stringify({
+		...payload,
+		assetRef: clonedAssetRef,
+		variantRef: clonedVariantRef
+	}, null, 2));
 	else {
-		const asset = payload.asset;
-		const variantPayload = payload.variant;
-		const variant = variantPayload?.variant ?? variantPayload;
 		deps.print(`Cloned variant ${sourceVariantId} into space ${targetSpaceId}`);
-		if (asset?.id) deps.print(`  Asset:   ${asset.id}${asset.name ? ` (${asset.name})` : ""}`);
-		if (variant?.id) deps.print(`  Variant: ${variant.id}`);
+		if (clonedAssetRef) deps.print(`  Asset:   ${clonedAssetRef}`);
+		if (clonedVariantRef) deps.print(`  Variant: ${clonedVariantRef}`);
 	}
 	return {
 		type: "clone",
@@ -9199,9 +9362,13 @@ function printAssetList(assets, print) {
 		return;
 	}
 	print(`Found ${assets.length} asset(s):\n`);
-	print("Updated".padEnd(21) + "Type".padEnd(14) + "Media".padEnd(9) + "Active Variant".padEnd(26) + "Asset".padEnd(28) + "Name");
-	print("-".repeat(113));
-	for (const asset of assets) print(formatTimestamp(asset.updated_at).padEnd(21) + truncate(asset.type || "unknown", 12).padEnd(14) + truncate(asset.media_kind || "-", 7).padEnd(9) + truncate(asset.active_variant_id || "-", 24).padEnd(26) + truncate(asset.id, 26).padEnd(28) + truncate(asset.name, 32));
+	print("Updated".padEnd(21) + "Type".padEnd(14) + "Media".padEnd(9) + "Active Variant Reference".padEnd(54) + "Asset Reference".padEnd(54) + "Name");
+	print("-".repeat(167));
+	for (const asset of assets) {
+		const assetRef = createAssetRef(asset.name, asset.id);
+		const activeVariantRef = asset.active_variant_id ? createVariantRef(asset.name, asset.id, asset.active_variant_id) : "-";
+		print(formatTimestamp(asset.updated_at).padEnd(21) + truncate(asset.type || "unknown", 12).padEnd(14) + truncate(asset.media_kind || "-", 7).padEnd(9) + activeVariantRef.padEnd(54) + assetRef.padEnd(54) + truncate(asset.name, 32));
+	}
 }
 function printAssetSearchResults(results, print) {
 	if (results.length === 0) {
@@ -9209,16 +9376,17 @@ function printAssetSearchResults(results, print) {
 		return;
 	}
 	for (const result of results) {
-		print(`${result.assetName} (${result.assetId})`);
+		print(`${createAssetRef(result.assetName, result.assetId)} — ${result.assetName}`);
 		print(`  Space:   ${result.spaceName} (${result.spaceId})`);
 		print(`  Type:    ${result.assetType ?? "-"}  Media: ${result.mediaKind}`);
-		print(`  Active:  ${result.activeVariantId ?? "-"}${result.activeVariantStatus ? ` (${result.activeVariantStatus})` : ""}`);
+		print(`  Active:  ${result.activeVariantId ? createVariantRef(result.assetName, result.assetId, result.activeVariantId) : "-"}${result.activeVariantStatus ? ` (${result.activeVariantStatus})` : ""}`);
 		print(`  Counts:  variants=${result.variantCount} completed=${result.completedVariantCount} starred=${result.starredVariantCount}`);
 	}
 }
 function printAssetDetails(details, ctx, print) {
 	const { asset, variants, lineage } = details;
-	print(`\nAsset ${asset.id}\n`);
+	print(`\nAsset ${createAssetRef(asset.name, asset.id)}\n`);
+	print(`  ID:       ${asset.id}`);
 	print(`  Name:     ${asset.name}`);
 	print(`  Type:     ${asset.type || "unknown"}`);
 	print(`  Media:    ${asset.media_kind || "-"}`);
@@ -9229,7 +9397,8 @@ function printAssetDetails(details, ctx, print) {
 	if (variants.length > 0) {
 		print("\nVariants:");
 		for (const variant of [...variants].sort((a, b) => (b.updated_at || 0) - (a.updated_at || 0))) {
-			print(` ${variant.id === asset.active_variant_id ? "*" : " "} ${variant.id}`);
+			print(` ${variant.id === asset.active_variant_id ? "*" : " "} ${createVariantRef(asset.name, asset.id, variant.id)}`);
+			print(`     ID:     ${variant.id}`);
 			print(`     Status: ${variant.status}`);
 			print(`     Media:  ${variant.media_kind || "-"}`);
 			print(`     File:   ${variant.media_key || variant.image_key || "-"}`);
@@ -9272,7 +9441,21 @@ function toAssetJson(asset) {
 		media_kind: asset.media_kind || null,
 		activeVariantId: asset.active_variant_id,
 		createdAt: asset.created_at || null,
-		updatedAt: asset.updated_at || null
+		updatedAt: asset.updated_at || null,
+		assetRef: createAssetRef(asset.name, asset.id)
+	};
+}
+function toAssetDetailsJson(details) {
+	return {
+		...details,
+		asset: {
+			...details.asset,
+			assetRef: createAssetRef(details.asset.name, details.asset.id)
+		},
+		variants: details.variants.map((variant) => ({
+			...variant,
+			variantRef: createVariantRef(details.asset.name, details.asset.id, variant.id)
+		}))
 	};
 }
 function formatMetadataSummary(value, preferredKeys) {
@@ -9339,7 +9522,7 @@ async function executeVariants(parsed, deps = defaultDeps$4) {
 	const ctx = await buildContext$4(parsed, deps);
 	const subcommand = parsed.positionals[0];
 	if (subcommand === "delete") {
-		const variantId = requireVariantId(parsed, "delete");
+		const variantId = await resolveVariantAtBoundary(ctx, deps, requireVariantId(parsed, "delete"));
 		await withVariantClient(ctx, deps, (client) => client.deleteVariant(variantId));
 		deps.print(`Deleted variant ${variantId}`);
 		return {
@@ -9348,9 +9531,11 @@ async function executeVariants(parsed, deps = defaultDeps$4) {
 		};
 	}
 	if (subcommand === "retry") {
-		const variantId = requireVariantId(parsed, "retry");
+		const variantId = await resolveVariantAtBoundary(ctx, deps, requireVariantId(parsed, "retry"));
 		const variant = await withVariantClient(ctx, deps, (client) => client.retryVariant(variantId));
-		deps.print(`Re-queued variant ${variantId} (status: ${variant.status}). Watch progress with: assets show ${variant.asset_id}`);
+		const variantRef = createVariantRef("asset", variant.asset_id, variant.id);
+		const assetRef = createAssetRef("asset", variant.asset_id);
+		deps.print(`Re-queued variant ${variantRef} (status: ${variant.status}). Watch progress with: assets show ${assetRef}`);
 		return {
 			type: "retry",
 			variant
@@ -9358,7 +9543,7 @@ async function executeVariants(parsed, deps = defaultDeps$4) {
 	}
 	if (subcommand === "star" || subcommand === "unstar") {
 		const starred = subcommand === "star";
-		const variantId = requireVariantId(parsed, subcommand);
+		const variantId = await resolveVariantAtBoundary(ctx, deps, requireVariantId(parsed, subcommand));
 		const variant = await withVariantClient(ctx, deps, (client) => client.starVariant(variantId, starred));
 		deps.print(`${starred ? "Starred" : "Unstarred"} variant ${variantId}`);
 		return {
@@ -9367,9 +9552,10 @@ async function executeVariants(parsed, deps = defaultDeps$4) {
 		};
 	}
 	if (subcommand === "rate") {
-		const variantId = parsed.positionals[1];
+		const variantIdentifier = parsed.positionals[1];
 		const rating = parsed.positionals[2];
-		if (!variantId || rating !== "approved" && rating !== "rejected") throw new Error("Usage: makefx variants rate <variant-id> <approved|rejected>");
+		if (!variantIdentifier || rating !== "approved" && rating !== "rejected") throw new Error("Usage: makefx variants rate <variant-id> <approved|rejected>");
+		const variantId = await resolveVariantAtBoundary(ctx, deps, variantIdentifier);
 		const variant = await withVariantClient(ctx, deps, (client) => client.rateVariant(variantId, rating));
 		deps.print(`Rated variant ${variantId} as ${rating}`);
 		return {
@@ -9398,6 +9584,9 @@ async function buildContext$4(parsed, deps) {
 		spaceId
 	};
 }
+function resolveVariantAtBoundary(ctx, deps, identifier) {
+	return resolveCliVariantIdentifier(identifier, () => deps.createMutationClient(ctx.env, ctx.spaceId));
+}
 async function withVariantClient(ctx, deps, run) {
 	const client = await deps.createMutationClient(ctx.env, ctx.spaceId);
 	await client.connect();
@@ -9429,6 +9618,7 @@ var defaultDeps$3 = {
 	loadProjectConfig,
 	resolveBaseUrl,
 	fetch,
+	createStateClient: (env, spaceId) => WebSocketClient.create(env, spaceId),
 	print: console.log
 };
 async function handleRecipes(parsed) {
@@ -9443,15 +9633,22 @@ async function handleRecipes(parsed) {
 async function executeRecipes(parsed, deps = defaultDeps$3) {
 	const subcommand = parsed.positionals[0];
 	if (subcommand !== "run") throw new Error(`Unknown recipes command: ${subcommand ?? "(none)"}`);
-	const sourceVariantId = parsed.positionals[1];
-	if (!sourceVariantId) throw new Error("Variant ID is required: makefx recipes run <variant-id>");
-	const rerun = await runRecipe(await buildContext$3(parsed, deps), deps, sourceVariantId);
-	if (parsed.options.json === "true") deps.print(JSON.stringify(rerun, null, 2));
+	const sourceVariantIdentifier = parsed.positionals[1];
+	if (!sourceVariantIdentifier) throw new Error("Variant ID is required: makefx recipes run <variant-id>");
+	const ctx = await buildContext$3(parsed, deps);
+	const rerun = await runRecipe(ctx, deps, await resolveCliVariantIdentifier(sourceVariantIdentifier, () => (deps.createStateClient ?? defaultDeps$3.createStateClient)(ctx.env, ctx.spaceId)));
+	const assetRef = createAssetRef("asset", rerun.variant.asset_id);
+	const variantRef = createVariantRef("asset", rerun.variant.asset_id, rerun.variant.id);
+	if (parsed.options.json === "true") deps.print(JSON.stringify({
+		...rerun,
+		assetRef,
+		variantRef
+	}, null, 2));
 	else {
 		deps.print(`Re-ran recipe from variant ${rerun.sourceVariantId}`);
-		deps.print(`  Variant: ${rerun.variant.id} (status: ${rerun.variant.status})`);
+		deps.print(`  Variant: ${variantRef} (status: ${rerun.variant.status})`);
 		deps.print(`  Request: ${rerun.requestId}`);
-		deps.print(`Watch progress with: makefx assets show ${rerun.variant.asset_id}`);
+		deps.print(`Watch progress with: makefx assets show ${assetRef}`);
 	}
 	return {
 		type: "run",
@@ -9468,6 +9665,7 @@ async function buildContext$3(parsed, deps) {
 	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
@@ -9582,13 +9780,16 @@ async function executeCollections(parsed, deps = defaultDeps$2) {
 		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 resolvedAssetId = await resolveCliAssetIdentifier(assetId, () => deps.createMutationClient(ctx.env, ctx.spaceId));
+		const pinnedIdentifier = parseNullableOption(parsed.options.variant ?? parsed.options["pinned-variant"]);
+		const pinnedVariantId = pinnedIdentifier ? await resolveCliVariantIdentifier(pinnedIdentifier, () => deps.createMutationClient(ctx.env, ctx.spaceId)) : null;
 		const item = await withCollectionClient(ctx, deps, (client) => client.createCollectionItem({
 			collectionId,
 			id: normalizeOption(parsed.options.id),
 			subjectType: "asset",
-			assetId,
+			assetId: resolvedAssetId,
 			role: normalizeOption(parsed.options.role),
-			pinnedVariantId: parseNullableOption(parsed.options.variant ?? parsed.options["pinned-variant"]),
+			pinnedVariantId,
 			sortIndex: parseOptionalInteger(parsed.options["sort-index"], "sort-index")
 		}));
 		printJsonOrLine(parsed, deps, item, `Added asset ${assetId} to collection ${collectionId} as item ${item.id}`);
@@ -9601,11 +9802,12 @@ async function executeCollections(parsed, deps = defaultDeps$2) {
 		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 resolvedVariantId = await resolveCliVariantIdentifier(variantId, () => deps.createMutationClient(ctx.env, ctx.spaceId));
 		const item = await withCollectionClient(ctx, deps, (client) => client.createCollectionItem({
 			collectionId,
 			id: normalizeOption(parsed.options.id),
 			subjectType: "variant",
-			variantId,
+			variantId: resolvedVariantId,
 			role: normalizeOption(parsed.options.role),
 			sortIndex: parseOptionalInteger(parsed.options["sort-index"], "sort-index")
 		}));
@@ -10047,7 +10249,7 @@ Options:
 }
 //#endregion
 //#region src/cli/index.ts
-var CLI_VERSION = "1.2.0+10cb109b7379";
+var CLI_VERSION = "1.3.0+89c141a8883e";
 async function main() {
 	const argv = process$1.argv.slice(2);
 	if (argv[0] === "--") argv.shift();
@@ -10101,9 +10303,9 @@ function imageCapabilityHelp(operation) {
   --model <value>   Image model: ${imageModelValues(operation)}
   --size <value>    Output size (${sizeLines})
   --aspect <ratio>  Aspect ratio: ${imageAspectValues()}
-  --refs <refs>     Reference limit (${referenceLines})
+  --refs <refs>     Compact variant refs, raw IDs, or local image paths; limit (${referenceLines})
   Model operations: ${operationLines}
-  --follow <id>     Resume/download a variant after a long generation or disconnect
+  --follow <ref-or-id> Resume/download a variant after a long generation or disconnect
   --collection <id> Place the completed asset in a Space collection`;
 }
 function videoResolutionValues() {
@@ -10130,10 +10332,10 @@ function videoCapabilityHelp(operation) {
   --resolution <value>  Supported: ${videoResolutionValues()}; Veo: 720p|1080p|4k; Kling: 720p|1080p; Seedance 2: standard 480p|720p|1080p, fast 480p|720p (${resolutionLines})
   --duration <seconds>  Veo/Kling: ${optionValues(VIDEO_GENERATION_DURATION_SECONDS)}; Seedance 2: ${optionValues(SEEDANCE_2_DURATION_SECONDS)}
   --tier <tier>         Veo-only model tier: ${videoTierValues()}
-  --first-frame <ref>   Veo or Seedance 2 start frame image variant or local image path
-  --last-frame <ref>    Veo or Seedance 2 final frame image variant or local image path
+  --first-frame <ref>   Veo or Seedance 2 start frame compact ref, raw ID, or local image path
+  --last-frame <ref>    Veo or Seedance 2 final frame compact ref, raw ID, or local image path
   Model operations: ${operationLines}
-  --follow <id>         Resume/download a variant after a long generation or disconnect
+  --follow <ref-or-id>  Resume/download a variant after a long generation or disconnect
   --collection <id>     Place the completed asset in a Space collection
 
 Frame inputs:
@@ -10233,6 +10435,7 @@ Make Effects CLI
 Generation model:
   Assets are named things in a Space. Variants are generated or uploaded versions of one asset.
   References are ordinary completed variants or local files. Lineage records how a variant was made.
+  Asset and variant arguments accept compact refs (asset:name~prefix[@variant|@active]) or raw IDs.
 
 Start:
   login                                  Authenticate
@@ -10378,7 +10581,7 @@ Usage:
 
 Options:
   --space <id>      Target space ID; defaults from initialized project
-  --asset <id>      Target asset ID (upload as new variant)
+  --asset <ref|id>  Target asset compact ref or raw ID (upload as new variant)
   --name <name>     New asset name (creates asset + variant)
   --type <type>     Asset type for new assets (default: character)
   --media-kind <k>  Optional explicit kind: image, audio, or video
@@ -10387,8 +10590,8 @@ Options:
   --provider <name> Provider provenance for uploaded media
   --provider-metadata <json>     Provider metadata JSON object
   --generation-provenance <json> Extra provenance JSON object
-  --source-variant <ids>         Comma-separated source variants for upload lineage
-  --source-variants <ids>        Alias for --source-variant
+  --source-variant <refs>        Comma-separated compact refs or raw IDs for upload lineage
+  --source-variants <refs>       Alias for --source-variant
   --relation-type <type>         Lineage type: derived, refined, or forked (default: derived)
   --active-variant-behavior <b>  if-missing, set-active, or keep
   --json            Print machine-readable upload output with Space IDs
@@ -10647,6 +10850,8 @@ Usage:
   makefx variants unstar <variant-id>
   makefx variants rate <variant-id> <approved|rejected>
 
+Variant arguments accept compact refs (asset:name~prefix@variant) or raw IDs.
+
 Options:
   --space <id>      Target space ID; defaults from the initialized project
   --env <env>       Environment (production|stage|local)
@@ -10661,6 +10866,8 @@ Usage:
 
 Re-runs the stored generation recipe as a new sibling variant of the same asset.
 
+The variant argument accepts a compact ref (asset:name~prefix@variant) or raw ID.
+
 Options:
   --space <id>      Target space ID; defaults from the initialized project
   --json            Print machine-readable output
@@ -10681,6 +10888,8 @@ Usage:
   makefx assets delete <asset-id>
   makefx assets rename <asset-id> "<new-name>"
   makefx assets set-active <asset-id> <variant-id>
+
+Asset and variant arguments accept compact refs (asset:name~prefix[@variant|@active]) or raw IDs.
 `);
 }
 function printCollectionsHelp() {
@@ -10696,6 +10905,8 @@ Usage:
   makefx collections remove <collection-id> <item-id>
   makefx collections reorder <collection-id> <item-id,item-id,...>
 
+Asset and variant arguments accept compact refs (asset:name~prefix[@variant|@active]) or raw IDs.
+
 Options:
   --space <id>      Target space ID; defaults from the initialized project
   --env <env>       Environment (production|stage|local)