@ycs77/devbox 0.6.0 → 0.7.1

package/dist/cli.mjs

@@ -2,16 +2,120 @@ import * as p from "@clack/prompts";
 import { intro, outro } from "@clack/prompts";
 import { cac } from "cac";
 import c from "picocolors";
-import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, readFile, rename, rm, rmdir, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, parse, relative, sep } from "node:path";
+import { parse as parse$1, parseDocument, stringify } from "yaml";
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
-import { parse as parse$1, parseDocument, stringify } from "yaml";
+import { createHash, randomUUID } from "node:crypto";
 import { once } from "node:events";
 //#region package.json
-var version = "0.6.0";
+var version = "0.7.1";
+//#endregion
+//#region src/result.ts
+function success(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function failure(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+//#endregion
+//#region src/host.ts
+const execFile$1 = promisify(execFile);
+var HostCommandError = class extends Error {
+	exitCode;
+	constructor(file, args, exitCode) {
+		super(`${file} ${args.join(" ")} exited with status ${exitCode}.`);
+		this.exitCode = exitCode;
+		this.name = "HostCommandError";
+	}
+};
+const supportedHostAction = "Start Docker Desktop and ensure Docker Compose is available.";
+function currentHostEnvironment() {
+	return {
+		run: async (file, args) => {
+			await execFile$1(file, args);
+		},
+		runDirect: async (file, args) => new Promise((resolve, reject) => {
+			const command = spawn(file, args, { stdio: "inherit" });
+			command.once("error", reject);
+			command.once("close", (code) => {
+				if (code === 0) {
+					resolve();
+					return;
+				}
+				reject(new HostCommandError(file, args, code ?? 1));
+			});
+		})
+	};
+}
+async function validateSupportedHost(environment = currentHostEnvironment()) {
+	for (const [file, args, description] of [[
+		"docker",
+		["--version"],
+		"Docker"
+	], [
+		"docker",
+		["compose", "version"],
+		"Docker Compose"
+	]]) try {
+		await environment.run(file, args);
+	} catch {
+		return failure({
+			kind: "validation",
+			code: "missing-host-prerequisite",
+			observed: `${description} is unavailable.`,
+			nextAction: supportedHostAction
+		});
+	}
+	return success(void 0);
+}
+//#endregion
+//#region src/agent/volumes.ts
+async function ensureSharedAgentVolumes(composeSource, environment = currentHostEnvironment()) {
+	const volumeNames = /* @__PURE__ */ new Set();
+	try {
+		const definition = parse$1(composeSource);
+		if (!isMapping(definition)) throw new Error("Expected a Compose mapping.");
+		const volumes = definition.volumes;
+		if (volumes !== void 0) {
+			if (!isMapping(volumes)) throw new Error("Expected a volume mapping.");
+			for (const [key, volume] of Object.entries(volumes)) {
+				if (volume === null) continue;
+				if (!isMapping(volume)) throw new Error("Expected a volume definition.");
+				if (volume.external !== true) continue;
+				const name = volume.name ?? key;
+				if (typeof name !== "string" || name.length === 0) throw new Error("Expected an external volume name.");
+				volumeNames.add(name);
+			}
+		}
+	} catch {
+		return failure({
+			kind: "operational",
+			code: "invalid-project-compose",
+			observed: "Devbox could not read external volumes from the retained Sandbox definition.",
+			nextAction: "Run devbox config to publish the Sandbox definition, then retry devbox up."
+		});
+	}
+	for (const volumeName of volumeNames) await environment.run("docker", [
+		"volume",
+		"create",
+		"--driver",
+		"local",
+		volumeName
+	]);
+	return success(void 0);
+}
+function isMapping(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 //#endregion
 //#region src/catalog/index.ts
 const NODE_RELEASE_KEYS = [
@@ -55,7 +159,7 @@ const PACKAGED_AGENTS = {
 		},
 		supportsNotifications: true,
 		notificationInstallationCommands: ["claude plugin marketplace add ycs77/claude-code-notifications", "claude plugin install notification-basic-wsl@ycs77-notifications"],
-		supportsSkillInstallation: true
+		skillInstallationTarget: "claude-code"
 	},
 	codex: {
 		home: {
@@ -67,7 +171,7 @@ const PACKAGED_AGENTS = {
 			shell: "sh"
 		},
 		supportsNotifications: true,
-		supportsSkillInstallation: true,
+		skillInstallationTarget: "codex",
 		notificationInstallationCommands: ["codex plugin marketplace add ycs77/codex-notifications", "codex plugin add notification-basic-wsl@ycs77-notifications"]
 	},
 	agy: {
@@ -79,8 +183,7 @@ const PACKAGED_AGENTS = {
 			url: "https://antigravity.google/cli/install.sh",
 			shell: "bash"
 		},
-		supportsNotifications: false,
-		supportsSkillInstallation: false
+		supportsNotifications: false
 	},
 	omp: {
 		home: {
@@ -92,7 +195,7 @@ const PACKAGED_AGENTS = {
 			shell: "sh"
 		},
 		supportsNotifications: true,
-		supportsSkillInstallation: false,
+		skillInstallationTarget: "codex",
 		notificationInstallationCommands: ["omp plugin marketplace add ycs77/omp-notifications", "omp plugin install notification-basic@ycs77-notifications"]
 	}
 };
@@ -101,85 +204,6 @@ const PACKAGED_RUNTIME_CATALOG = {
 	agents: Object.keys(PACKAGED_AGENTS)
 };
 //#endregion
-//#region src/result.ts
-function success(value) {
-	return {
-		ok: true,
-		value
-	};
-}
-function failure(error) {
-	return {
-		ok: false,
-		error
-	};
-}
-//#endregion
-//#region src/host.ts
-const execFile$1 = promisify(execFile);
-var HostCommandError = class extends Error {
-	exitCode;
-	constructor(file, args, exitCode) {
-		super(`${file} ${args.join(" ")} exited with status ${exitCode}.`);
-		this.exitCode = exitCode;
-		this.name = "HostCommandError";
-	}
-};
-const supportedHostAction = "Start Docker Desktop and ensure Docker Compose is available.";
-function currentHostEnvironment() {
-	return {
-		run: async (file, args) => {
-			await execFile$1(file, args);
-		},
-		runDirect: async (file, args) => new Promise((resolve, reject) => {
-			const command = spawn(file, args, { stdio: "inherit" });
-			command.once("error", reject);
-			command.once("close", (code) => {
-				if (code === 0) {
-					resolve();
-					return;
-				}
-				reject(new HostCommandError(file, args, code ?? 1));
-			});
-		})
-	};
-}
-async function validateSupportedHost(environment = currentHostEnvironment()) {
-	for (const [file, args, description] of [[
-		"docker",
-		["--version"],
-		"Docker"
-	], [
-		"docker",
-		["compose", "version"],
-		"Docker Compose"
-	]]) try {
-		await environment.run(file, args);
-	} catch {
-		return failure({
-			kind: "validation",
-			code: "missing-host-prerequisite",
-			observed: `${description} is unavailable.`,
-			nextAction: supportedHostAction
-		});
-	}
-	return success(void 0);
-}
-//#endregion
-//#region src/agent/volumes.ts
-async function ensureSharedAgentVolumes(configuredAgents, environment = currentHostEnvironment()) {
-	for (const configuredAgent of configuredAgents) {
-		const volumeName = PACKAGED_AGENTS[configuredAgent]?.home.volumeName;
-		if (volumeName !== void 0) await environment.run("docker", [
-			"volume",
-			"create",
-			"--driver",
-			"local",
-			volumeName
-		]);
-	}
-}
-//#endregion
 //#region src/configuration/index.ts
 function normalizeCatalog(catalog = PACKAGED_RUNTIME_CATALOG) {
 	if (!isRecord(catalog.runtimes) || !Array.isArray(catalog.agents)) return invalid$1("invalid-runtime-catalog", "The packaged Runtime catalog is invalid.");
@@ -405,7 +429,7 @@ async function withStateLocks(input, operation) {
 	try {
 		await lstat(input.devboxHome);
 	} catch (error) {
-		if (isMissingFileError$1(error)) devboxHomeExisted = false;
+		if (isMissingFileError$2(error)) devboxHomeExisted = false;
 		else throw error;
 	}
 	const acquired = [];
@@ -468,7 +492,7 @@ async function acquireLock(target) {
 function isFileExistsError(error) {
 	return typeof error === "object" && error !== null && error.code === "EEXIST";
 }
-function isMissingFileError$1(error) {
+function isMissingFileError$2(error) {
 	return typeof error === "object" && error !== null && error.code === "ENOENT";
 }
 //#endregion
@@ -514,6 +538,7 @@ const WORKSPACE_IMAGE = "devbox-workspace:latest";
 //#endregion
 //#region src/project/compose.ts
 function renderProjectCompose(input) {
+	const containerName = `devbox-${input.sandboxName}`;
 	const node = selectNodeComposeFragment(input.selectedNode);
 	const agent = selectAgentComposeFragments(input.configuredAgents, input.agentNotifications);
 	const environment = {
@@ -544,17 +569,17 @@ function renderProjectCompose(input) {
 		}]
 	];
 	const definition = {
-		name: input.sandboxName,
+		name: containerName,
 		"x-devbox": {
 			version: 1,
 			project_root: input.projectRoot,
-			compose_name: input.sandboxName,
+			container_name: containerName,
 			sandbox_service: "devbox"
 		},
 		services: { devbox: {
 			image: WORKSPACE_IMAGE,
 			hostname: "devbox",
-			container_name: `devbox-${input.sandboxName}`,
+			container_name: containerName,
 			working_dir: `/workspace/${input.sandboxName}`,
 			...input.ports.length === 0 ? {} : { ports: input.ports.map((port) => renderComposePortMapping(port)) },
 			...Object.keys(environment).length === 0 ? {} : { environment },
@@ -566,21 +591,21 @@ function renderProjectCompose(input) {
 		}])) }
 	};
 	const source = stringify(definition);
-	return validatesProjectCompose(source, input) ? success(source) : failure({
+	return validatesProjectCompose(source, input, containerName) ? success(source) : failure({
 		kind: "operational",
 		code: "invalid-project-compose",
 		observed: `Devbox generated an invalid Compose definition for Project ${input.projectRoot}.`,
 		nextAction: "Run the command again. If the problem continues, report it as a Devbox bug."
 	});
 }
-function validatesProjectCompose(source, input) {
+function validatesProjectCompose(source, input, containerName) {
 	try {
 		const definition = parse$1(source);
-		if (definition.name !== input.sandboxName) return false;
+		if (definition.name !== containerName) return false;
 		const metadata = definition["x-devbox"];
-		if (metadata.version !== 1 || metadata.project_root !== input.projectRoot || metadata.compose_name !== input.sandboxName || metadata.sandbox_service !== "devbox") return false;
+		if (metadata.version !== 1 || metadata.project_root !== input.projectRoot || metadata.container_name !== containerName || metadata.sandbox_service !== "devbox") return false;
 		const service = definition.services.devbox;
-		if (service.image !== "devbox-workspace:latest" || service.container_name !== `devbox-${input.sandboxName}` || service.working_dir !== `/workspace/${input.sandboxName}` || "build" in service) return false;
+		if (service.image !== "devbox-workspace:latest" || service.container_name !== containerName || service.working_dir !== `/workspace/${input.sandboxName}` || "build" in service) return false;
 		const ports = input.ports.map((port) => renderComposePortMapping(port));
 		return JSON.stringify(service.ports ?? []) === JSON.stringify(ports) && (input.selectedNode === null && service.environment?.NODE_VERSION === void 0 || input.selectedNode !== null && service.environment?.NODE_VERSION === input.selectedNode);
 	} catch {
@@ -658,6 +683,200 @@ function invalid(observed) {
 	});
 }
 //#endregion
+//#region src/project/publication.ts
+async function publishProjectState(input) {
+	const definitions = [];
+	for (const project of input.projects) {
+		const prepared = project.preparedDefinition === void 0 ? await prepareSandboxDefinition(input.devboxHome, input.globalConfiguration, project) : success(project.preparedDefinition);
+		if (!prepared.ok) return prepared;
+		definitions.push(prepared.value);
+	}
+	const claudeHostConfiguration = await ensureClaudeHostConfiguration(input.devboxHome, input.globalConfiguration);
+	if (!claudeHostConfiguration.ok) return claudeHostConfiguration;
+	const writes = [
+		...input.globalPrevious === void 0 ? [] : [{
+			path: join(input.devboxHome, "config.yaml"),
+			content: serializeGlobalConfiguration(input.globalConfiguration),
+			previous: input.globalPrevious
+		}],
+		...input.projects.flatMap((project) => project.localPrevious === void 0 ? [] : [{
+			path: join(project.stateDirectory, "config.yaml"),
+			content: serializeLocalConfiguration(project.localConfiguration),
+			previous: project.localPrevious
+		}]),
+		...input.registry === void 0 ? [] : [{
+			path: join(input.devboxHome, "projects.yaml"),
+			content: serializeProjectRegistry(input.registry.value),
+			previous: input.registry.previous
+		}],
+		...definitions
+	].filter((write) => !write.previous.exists || write.content !== write.previous.content);
+	const written = await writeStateTransaction(writes);
+	return written.ok ? success(writes.length > 0) : written;
+}
+async function prepareSandboxDefinition(devboxHome, globalConfiguration, project) {
+	const claudeHostConfiguration = globalConfiguration.agent.includes("claude-code") ? join(devboxHome, "agents", "claude", ".claude.json") : void 0;
+	const rendered = renderProjectCompose({
+		projectRoot: project.root,
+		sandboxName: project.name,
+		selectedNode: project.localConfiguration.node,
+		configuredAgents: globalConfiguration.agent,
+		agentNotifications: globalConfiguration.agent_notifications,
+		claudeHostConfiguration,
+		ports: project.localConfiguration.ports
+	});
+	if (!rendered.ok) return rendered;
+	const path = join(project.stateDirectory, "compose.yaml");
+	const previous = await readOptionalFile(path);
+	if (!previous.ok) return previous;
+	return success({
+		path,
+		content: rendered.value,
+		previous: previous.value
+	});
+}
+async function ensureClaudeHostConfiguration(devboxHome, globalConfiguration) {
+	if (!globalConfiguration.agent.includes("claude-code")) return success(void 0);
+	const path = join(devboxHome, "agents", "claude", ".claude.json");
+	try {
+		if ((await lstat(path)).isFile()) return success(path);
+		return failure({
+			kind: "operational",
+			code: "claude-host-configuration-invalid",
+			observed: `Claude host configuration is not a regular file: ${path}.`,
+			nextAction: "Replace it with a regular file, then run the command again."
+		});
+	} catch (error) {
+		if (!isMissingFileError$1(error)) return failure({
+			kind: "operational",
+			code: "claude-host-configuration-unreadable",
+			observed: `Devbox could not inspect Claude host configuration: ${path}.`,
+			nextAction: "Check access to ~/.devbox and run the command again."
+		});
+	}
+	try {
+		await mkdir(dirname(path), {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(path, "{}\n", {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 384
+		});
+		return success(path);
+	} catch (error) {
+		if (error.code === "EEXIST") return ensureClaudeHostConfiguration(devboxHome, globalConfiguration);
+		return failure({
+			kind: "operational",
+			code: "claude-host-configuration-write-failed",
+			observed: `Devbox could not create Claude host configuration: ${path}.`,
+			nextAction: "Check write access to ~/.devbox and run the command again."
+		});
+	}
+}
+async function readOptionalFile(path) {
+	try {
+		return success({
+			exists: true,
+			content: await readFile(path, "utf8")
+		});
+	} catch (error) {
+		if (isMissingFileError$1(error)) return success({
+			exists: false,
+			content: ""
+		});
+		return failure({
+			kind: "operational",
+			code: "state-read-failed",
+			observed: `Devbox could not read state file: ${path}.`,
+			nextAction: "Check write access to ~/.devbox and try again."
+		});
+	}
+}
+async function writeAtomically(path, content) {
+	const staged = await stageStateWrite(path, content, "tmp");
+	if (!staged.ok) return staged;
+	try {
+		await rename(staged.value, path);
+		return success(void 0);
+	} catch {
+		await rm(staged.value, { force: true }).catch(() => void 0);
+		return failure({
+			kind: "operational",
+			code: "state-write-failed",
+			observed: `Devbox could not atomically write state file: ${path}.`,
+			nextAction: "Check write access to ~/.devbox and run the command again."
+		});
+	}
+}
+async function stageStateWrite(path, content, suffix) {
+	const directory = dirname(path);
+	const temporaryPath = join(directory, `.${basename(path)}-${process.pid}-${randomUUID()}.${suffix}`);
+	try {
+		await mkdir(directory, {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(temporaryPath, content, {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 384
+		});
+		return success(temporaryPath);
+	} catch {
+		await rm(temporaryPath, { force: true }).catch(() => void 0);
+		return failure({
+			kind: "operational",
+			code: "state-write-failed",
+			observed: `Devbox could not atomically write state file: ${path}.`,
+			nextAction: "Check write access to ~/.devbox and run the command again."
+		});
+	}
+}
+async function writeStateTransaction(writes) {
+	const staged = [];
+	for (const write of writes) {
+		const stagedWrite = await stageStateWrite(write.path, write.content, "transaction.tmp");
+		if (!stagedWrite.ok) {
+			await Promise.all(staged.map((stage) => rm(stage.path, { force: true }).catch(() => void 0)));
+			return stagedWrite;
+		}
+		staged.push({
+			write,
+			path: stagedWrite.value
+		});
+	}
+	const published = [];
+	try {
+		for (const stage of staged) {
+			await rename(stage.path, stage.write.path);
+			published.push(stage.write);
+		}
+		return success(void 0);
+	} catch {
+		let restored = true;
+		for (const write of published.reverse()) if (write.previous.exists) {
+			const restoredWrite = await writeAtomically(write.path, write.previous.content);
+			restored &&= restoredWrite.ok;
+		} else try {
+			await rm(write.path, { force: true });
+		} catch {
+			restored = false;
+		}
+		await Promise.all(staged.map((stage) => rm(stage.path, { force: true }).catch(() => void 0)));
+		return failure({
+			kind: "operational",
+			code: "state-write-failed",
+			observed: restored ? "Devbox could not publish Project state; the previous state was restored." : "Devbox could not publish Project state or restore the previous state.",
+			nextAction: "Check write access to ~/.devbox and run the command again."
+		});
+	}
+}
+function isMissingFileError$1(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//#endregion
 //#region src/project/index.ts
 function devboxPaths(devboxHome = join(homedir(), ".devbox")) {
 	return {
@@ -719,24 +938,22 @@ async function initializeProjectUnlocked(input = {}) {
 	if (!registryCheck.ok) return registryCheck;
 	const registry = registryCheck.value;
 	const registration = registry.projects[projectRoot];
-	let identity;
-	let name;
-	if (registration !== void 0) {
-		identity = registration.identity;
-		name = registration.name;
-	} else {
-		const allocatedIdentity = await allocateSandboxIdentity(projectRoot, paths, registry);
-		if (!allocatedIdentity.ok) return allocatedIdentity;
-		const allocatedName = allocateSandboxName(projectRoot, registry);
-		if (!allocatedName.ok) return allocatedName;
-		identity = allocatedIdentity.value;
-		name = allocatedName.value;
-	}
+	if (registration !== void 0) return success({
+		root: projectRoot,
+		stateDirectory: projectStateDirectory(registration.identity, paths.home),
+		sandboxName: registration.name,
+		created: false,
+		globalConfigurationCreated: false
+	});
+	const allocatedIdentity = await allocateSandboxIdentity(projectRoot, paths, registry);
+	if (!allocatedIdentity.ok) return allocatedIdentity;
+	const allocatedName = allocateSandboxName(projectRoot, registry);
+	if (!allocatedName.ok) return allocatedName;
+	const identity = allocatedIdentity.value;
+	const name = allocatedName.value;
 	const stateDirectory = projectStateDirectory(identity, paths.home);
-	const registered = registration !== void 0;
 	const globalState = await readOptionalFile(paths.globalConfiguration);
 	if (!globalState.ok) return globalState;
-	if (registered && !globalState.value.exists) return missingConfiguration("global", paths.globalConfiguration);
 	let globalConfiguration;
 	let globalChanged = false;
 	if (globalState.value.exists) {
@@ -757,24 +974,11 @@ async function initializeProjectUnlocked(input = {}) {
 		}
 		globalChanged = true;
 	}
-	const localPath = join(stateDirectory, "config.yaml");
-	const localState = registered ? await readOptionalFile(localPath) : success({
-		exists: false,
-		content: ""
-	});
-	if (!localState.ok) return localState;
-	if (registered && !localState.value.exists) return missingConfiguration("local", localPath);
 	let localConfiguration;
-	let localChanged = false;
-	if (localState.value.exists) {
-		const parsedLocal = parseLocalConfiguration(localState.value.content, globalConfiguration, catalog);
-		if (!parsedLocal.ok) return parsedLocal;
-		localConfiguration = parsedLocal.value;
-	} else if (input.initialLocalConfiguration !== void 0) {
+	if (input.initialLocalConfiguration !== void 0) {
 		const initialLocal = validateLocalObject(input.initialLocalConfiguration, globalConfiguration, catalog);
 		if (!initialLocal.ok) return initialLocal;
 		localConfiguration = initialLocal.value;
-		localChanged = true;
 	} else {
 		localConfiguration = defaultLocalConfiguration(globalConfiguration);
 		if (input.prompt?.editLocal) {
@@ -782,35 +986,20 @@ async function initializeProjectUnlocked(input = {}) {
 			if (!checkedLocal.ok) return checkedLocal;
 			localConfiguration = checkedLocal.value;
 		}
-		localChanged = true;
 	}
-	const composeWrite = await composeStateWrite({
-		projectRoot,
-		sandboxName: name,
+	const definition = await prepareSandboxDefinition(paths.home, globalConfiguration, {
+		root: projectRoot,
+		name,
 		stateDirectory,
-		devboxHome: paths.home,
-		globalConfiguration,
 		localConfiguration
 	});
-	if (!composeWrite.ok) return composeWrite;
-	if (registered) {
-		if (!composeWrite.value.previous.exists || composeWrite.value.content !== composeWrite.value.previous.content) {
-			const written = await writeStateTransaction([composeWrite.value]);
-			if (!written.ok) return written;
-		}
-		return success({
-			root: projectRoot,
-			stateDirectory,
-			sandboxName: name,
-			created: false,
-			confirmed: true
-		});
-	}
+	if (!definition.ok) return definition;
 	if (!await (input.confirm ?? input.prompt?.confirm ?? (async () => true))("Save configuration?")) return success({
 		root: projectRoot,
 		stateDirectory,
 		sandboxName: name,
 		created: false,
+		globalConfigurationCreated: false,
 		confirmed: false
 	});
 	const nextRegistry = {
@@ -823,30 +1012,33 @@ async function initializeProjectUnlocked(input = {}) {
 			}
 		}
 	};
-	const written = await writeStateTransaction([
-		...globalChanged ? [{
-			path: paths.globalConfiguration,
-			content: serializeGlobalConfiguration(globalConfiguration),
-			previous: globalState.value
-		}] : [],
-		...localChanged ? [{
-			path: localPath,
-			content: serializeLocalConfiguration(localConfiguration),
-			previous: localState.value
-		}] : [],
-		{
-			path: paths.projectRegistry,
-			content: serializeProjectRegistry(nextRegistry),
+	const written = await publishProjectState({
+		devboxHome: paths.home,
+		globalConfiguration,
+		globalPrevious: globalChanged ? globalState.value : void 0,
+		registry: {
+			value: nextRegistry,
 			previous: registryState.value
 		},
-		composeWrite.value
-	]);
+		projects: [{
+			root: projectRoot,
+			name,
+			stateDirectory,
+			localConfiguration,
+			localPrevious: {
+				exists: false,
+				content: ""
+			},
+			preparedDefinition: definition.value
+		}]
+	});
 	if (!written.ok) return written;
 	return success({
 		root: projectRoot,
 		stateDirectory,
 		sandboxName: name,
 		created: true,
+		globalConfigurationCreated: globalChanged,
 		confirmed: true
 	});
 }
@@ -882,14 +1074,10 @@ async function configureLocalProjectUnlocked(input = {}) {
 	const localCheck = parseLocalConfiguration(localState.value.content, globalCheck.value, catalog);
 	if (!localCheck.ok) return localCheck;
 	let nextConfiguration = input.nextConfiguration ?? localCheck.value;
-	if (input.nextConfiguration === void 0 && input.prompt?.editLocal) nextConfiguration = await input.prompt.editLocal(localCheck.value, catalog, globalCheck.value);
-	const nextCheck = validateLocalObject(nextConfiguration, globalCheck.value, catalog);
-	if (!nextCheck.ok) return nextCheck;
-	if (configurationsEqual(localCheck.value, nextCheck.value)) return success({
-		scope: "local",
-		root: projectRoot,
-		changed: false
-	});
+	if (input.nextConfiguration === void 0 && input.prompt?.editLocal) nextConfiguration = await input.prompt.editLocal(localCheck.value, catalog, globalCheck.value);
+	const nextCheck = validateLocalObject(nextConfiguration, globalCheck.value, catalog);
+	if (!nextCheck.ok) return nextCheck;
+	const localChanged = !configurationsEqual(localCheck.value, nextCheck.value);
 	if (!await (input.confirm ?? input.prompt?.confirm ?? (async () => true))("Save Project configuration?", {
 		title: "Review configuration",
 		sections: [{
@@ -903,25 +1091,22 @@ async function configureLocalProjectUnlocked(input = {}) {
 		changed: false
 	});
 	if (input.signal?.aborted) throw new InterruptedError();
-	const composeWrite = await composeStateWrite({
-		projectRoot,
-		sandboxName: registration.name,
-		stateDirectory,
+	const written = await publishProjectState({
 		devboxHome: paths.home,
 		globalConfiguration: globalCheck.value,
-		localConfiguration: nextCheck.value
+		projects: [{
+			root: projectRoot,
+			name: registration.name,
+			stateDirectory,
+			localConfiguration: nextCheck.value,
+			localPrevious: localChanged ? localState.value : void 0
+		}]
 	});
-	if (!composeWrite.ok) return composeWrite;
-	const written = await writeStateTransaction([{
-		path: localPath,
-		content: serializeLocalConfiguration(nextCheck.value),
-		previous: localState.value
-	}, composeWrite.value]);
 	if (!written.ok) return written;
 	return success({
 		scope: "local",
 		root: projectRoot,
-		changed: true
+		changed: written.value
 	});
 }
 async function configureGlobal(input = {}) {
@@ -986,10 +1171,7 @@ async function configureGlobalUnlocked(input = {}, locks) {
 		if (!replacementCheck.ok) return replacementCheck;
 		replacementConfigurations.set(root, replacementCheck.value);
 	}
-	if (!(!globalState.value.exists || !configurationsEqual(currentConfiguration, nextCheck.value)) && replacementConfigurations.size === 0) return success({
-		scope: "global",
-		changed: false
-	});
+	const globalChanged = !globalState.value.exists || !configurationsEqual(currentConfiguration, nextCheck.value);
 	if (!await (input.confirm ?? input.prompt?.confirm ?? (async () => true))("Save Global configuration?", {
 		title: "Review configuration",
 		sections: [{
@@ -1006,39 +1188,25 @@ async function configureGlobalUnlocked(input = {}, locks) {
 		changed: false
 	});
 	if (input.signal?.aborted) throw new InterruptedError();
-	const composeWrites = [];
-	for (const [root, registration] of Object.entries(registryCheck.value.projects)) {
-		const composeWrite = await composeStateWrite({
-			projectRoot: root,
-			sandboxName: registration.name,
+	const written = await publishProjectState({
+		devboxHome: paths.home,
+		globalConfiguration: nextCheck.value,
+		globalPrevious: globalChanged ? globalState.value : void 0,
+		projects: Object.entries(registryCheck.value.projects).map(([root, registration]) => ({
+			root,
+			name: registration.name,
 			stateDirectory: projectStateDirectory(registration.identity, paths.home),
-			devboxHome: paths.home,
-			globalConfiguration: nextCheck.value,
-			localConfiguration: replacementConfigurations.get(root) ?? localConfigurations.get(root)
-		});
-		if (!composeWrite.ok) return composeWrite;
-		if (!composeWrite.value.previous.exists || composeWrite.value.content !== composeWrite.value.previous.content) composeWrites.push(composeWrite.value);
-	}
-	const written = await writeStateTransaction([
-		{
-			path: paths.globalConfiguration,
-			content: serializeGlobalConfiguration(nextCheck.value),
-			previous: globalState.value
-		},
-		...[...replacementConfigurations].map(([root, configuration]) => ({
-			path: join(paths.projects, registryCheck.value.projects[root].identity, "config.yaml"),
-			content: serializeLocalConfiguration(configuration),
-			previous: {
+			localConfiguration: replacementConfigurations.get(root) ?? localConfigurations.get(root),
+			localPrevious: replacementConfigurations.has(root) ? {
 				exists: true,
 				content: localConfigurationSources.get(root)
-			}
-		})),
-		...composeWrites
-	]);
+			} : void 0
+		}))
+	});
 	if (!written.ok) return written;
 	return success({
 		scope: "global",
-		changed: true
+		changed: written.value
 	});
 }
 async function removeProject(input = {}) {
@@ -1060,13 +1228,20 @@ async function removeProjectUnlocked(input = {}) {
 	const registration = registryCheck.value.projects[projectRoot];
 	if (registration === void 0) return notRegistered(projectRoot);
 	if (!input.yes) {
-		if (!await (input.confirm ?? (async () => false))(`Remove Project ${projectRoot} and its Devbox state?`)) return success({
+		if (!await (input.confirm ?? (async () => false))(`Remove Project ${projectRoot}, its Sandbox, and Devbox state?`)) return success({
 			root: projectRoot,
 			removed: false
 		});
 	}
 	if (input.signal?.aborted) throw new InterruptedError();
 	const stateDirectory = projectStateDirectory(registration.identity, paths.home);
+	const environment = input.environment ?? currentHostEnvironment();
+	await (environment.runDirect ?? environment.run)("docker", [
+		"compose",
+		"--file",
+		join(stateDirectory, "compose.yaml"),
+		"down"
+	]);
 	try {
 		await rm(stateDirectory, {
 			recursive: true,
@@ -1092,107 +1267,6 @@ async function removeProjectUnlocked(input = {}) {
 		removed: true
 	});
 }
-async function cleanupMissingProjects(input = {}) {
-	return withStateLocks({
-		devboxHome: input.devboxHome ?? join(homedir(), ".devbox"),
-		global: true,
-		projectRoots: [],
-		signal: input.signal
-	}, async (locks) => {
-		const discovery = await discoverMissingProjects(input);
-		if (!discovery.ok) return discovery;
-		await locks.acquireProjectScopes(discovery.value.missingRoots);
-		return cleanupMissingProjectsUnlocked(input, discovery.value);
-	});
-}
-async function discoverMissingProjects(input) {
-	if (input.signal?.aborted) throw new InterruptedError();
-	const paths = devboxPaths(input.devboxHome);
-	const registryState = await readOptionalFile(paths.projectRegistry);
-	if (!registryState.ok) return registryState;
-	if (!registryState.value.exists) return success({
-		paths,
-		registry: {
-			version: 1,
-			projects: {}
-		},
-		missingRoots: []
-	});
-	const registryCheck = parseProjectRegistry(registryState.value.content);
-	if (!registryCheck.ok) return registryCheck;
-	const missingRoots = [];
-	for (const root of Object.keys(registryCheck.value.projects)) {
-		if (input.signal?.aborted) throw new InterruptedError();
-		const exists = await projectRootExists(root);
-		if (exists === void 0) return failure({
-			kind: "operational",
-			code: "project-root-observation-failed",
-			observed: `Devbox could not inspect Project root: ${root}.`,
-			nextAction: "Check access to the registered Project root and try cleanup again."
-		});
-		if (!exists) missingRoots.push(root);
-	}
-	return success({
-		paths,
-		registry: registryCheck.value,
-		missingRoots
-	});
-}
-async function cleanupMissingProjectsUnlocked(input, discovery) {
-	if (input.signal?.aborted) throw new InterruptedError();
-	if (discovery.missingRoots.length === 0) return success({
-		roots: [],
-		removed: false
-	});
-	if (!input.yes) {
-		if (!await (input.confirm ?? (async () => false))(`Remove Missing-root Project registrations?\n${discovery.missingRoots.map((root) => `- ${root}`).join("\n")}`)) return success({
-			roots: [],
-			removed: false
-		});
-	}
-	const removedRoots = [];
-	const projects = { ...discovery.registry.projects };
-	for (const root of discovery.missingRoots) {
-		const rootExists = await projectRootExists(root);
-		if (rootExists === void 0) return failure({
-			kind: "operational",
-			code: "project-root-observation-failed",
-			observed: `Devbox could not recheck Project root: ${root}.`,
-			nextAction: "Check access to the registered Project root and try cleanup again."
-		});
-		if (rootExists) continue;
-		const registration = projects[root];
-		if (registration === void 0) continue;
-		try {
-			await rm(projectStateDirectory(registration.identity, discovery.paths.home), {
-				recursive: true,
-				force: true
-			});
-		} catch {
-			return failure({
-				kind: "operational",
-				code: "missing-project-state-removal-failed",
-				observed: `Devbox could not remove Missing-root Project state for ${root}.`,
-				nextAction: "Check write access to ~/.devbox and try cleanup again."
-			});
-		}
-		delete projects[root];
-		removedRoots.push(root);
-	}
-	if (removedRoots.length === 0) return success({
-		roots: [],
-		removed: false
-	});
-	const written = await writeAtomically(discovery.paths.projectRegistry, serializeProjectRegistry({
-		version: 1,
-		projects
-	}));
-	if (!written.ok) return written;
-	return success({
-		roots: removedRoots,
-		removed: true
-	});
-}
 async function runSandboxLifecycle(command, input = {}) {
 	const projectRoot = input.root ?? process.cwd();
 	return withStateLocks({
@@ -1215,15 +1289,19 @@ async function runSandboxCommandUnlocked(command, input, projectRoot) {
 	const registration = registryCheck.value.projects[projectRoot];
 	if (registration === void 0) return notRegistered(projectRoot);
 	const environment = input.environment ?? currentHostEnvironment();
+	const composePath = join(projectStateDirectory(registration.identity, paths.home), "compose.yaml");
 	if (command === "up") {
-		const globalState = await readOptionalFile(paths.globalConfiguration);
-		if (!globalState.ok) return globalState;
-		if (!globalState.value.exists) return missingConfiguration("global", paths.globalConfiguration);
-		const globalCheck = parseGlobalConfiguration(globalState.value.content);
-		if (!globalCheck.ok) return globalCheck;
-		await ensureSharedAgentVolumes(globalCheck.value.agent, environment);
+		const composeState = await readOptionalFile(composePath);
+		if (!composeState.ok) return composeState;
+		if (!composeState.value.exists) return failure({
+			kind: "operational",
+			code: "missing-project-compose",
+			observed: `Sandbox definition is missing: ${composePath}.`,
+			nextAction: "Run devbox config to publish the Sandbox definition, then retry devbox up."
+		});
+		const volumes = await ensureSharedAgentVolumes(composeState.value.content, environment);
+		if (!volumes.ok) return volumes;
 	}
-	const composePath = join(projectStateDirectory(registration.identity, paths.home), "compose.yaml");
 	const operation = command === "up" ? ["up", "-d"] : command === "sh" ? [
 		"exec",
 		"--user",
@@ -1311,174 +1389,6 @@ function allocateSandboxName(projectRoot, registry) {
 		nextAction: "Remove stale Devbox state only through its supported command and try again."
 	});
 }
-async function projectRootExists(projectRoot) {
-	try {
-		return (await lstat(projectRoot)).isDirectory();
-	} catch (error) {
-		if (isMissingFileError(error)) return false;
-		return;
-	}
-}
-async function readOptionalFile(path) {
-	try {
-		return success({
-			exists: true,
-			content: await readFile(path, "utf8")
-		});
-	} catch (error) {
-		if (isMissingFileError(error)) return success({
-			exists: false,
-			content: ""
-		});
-		return failure({
-			kind: "operational",
-			code: "state-read-failed",
-			observed: `Devbox could not read state file: ${path}.`,
-			nextAction: "Check write access to ~/.devbox and try again."
-		});
-	}
-}
-async function writeAtomically(path, content) {
-	const staged = await stageStateWrite(path, content, "tmp");
-	if (!staged.ok) return staged;
-	try {
-		await rename(staged.value, path);
-		return success(void 0);
-	} catch {
-		await rm(staged.value, { force: true }).catch(() => void 0);
-		return failure({
-			kind: "operational",
-			code: "state-write-failed",
-			observed: `Devbox could not atomically write state file: ${path}.`,
-			nextAction: "Check write access to ~/.devbox and run the command again."
-		});
-	}
-}
-async function stageStateWrite(path, content, suffix) {
-	const directory = dirname(path);
-	const temporaryPath = join(directory, `.${basename(path)}-${process.pid}-${randomUUID()}.${suffix}`);
-	try {
-		await mkdir(directory, {
-			recursive: true,
-			mode: 448
-		});
-		await writeFile(temporaryPath, content, {
-			encoding: "utf8",
-			flag: "wx",
-			mode: 384
-		});
-		return success(temporaryPath);
-	} catch {
-		await rm(temporaryPath, { force: true }).catch(() => void 0);
-		return failure({
-			kind: "operational",
-			code: "state-write-failed",
-			observed: `Devbox could not atomically write state file: ${path}.`,
-			nextAction: "Check write access to ~/.devbox and run the command again."
-		});
-	}
-}
-async function composeStateWrite(input) {
-	const claudeHostConfiguration = await ensureClaudeHostConfiguration(input.devboxHome, input.globalConfiguration);
-	if (!claudeHostConfiguration.ok) return claudeHostConfiguration;
-	const rendered = renderProjectCompose({
-		projectRoot: input.projectRoot,
-		sandboxName: input.sandboxName,
-		selectedNode: input.localConfiguration.node,
-		configuredAgents: input.globalConfiguration.agent,
-		agentNotifications: input.globalConfiguration.agent_notifications,
-		claudeHostConfiguration: claudeHostConfiguration.value,
-		ports: input.localConfiguration.ports
-	});
-	if (!rendered.ok) return rendered;
-	const path = join(input.stateDirectory, "compose.yaml");
-	const previous = await readOptionalFile(path);
-	if (!previous.ok) return previous;
-	return success({
-		path,
-		content: rendered.value,
-		previous: previous.value
-	});
-}
-async function ensureClaudeHostConfiguration(devboxHome, globalConfiguration) {
-	if (!globalConfiguration.agent.includes("claude-code")) return success(void 0);
-	const path = devboxPaths(devboxHome).claudeHostConfiguration;
-	try {
-		if ((await lstat(path)).isFile()) return success(path);
-		return failure({
-			kind: "operational",
-			code: "claude-host-configuration-invalid",
-			observed: `Claude host configuration is not a regular file: ${path}.`,
-			nextAction: "Replace it with a regular file, then run the command again."
-		});
-	} catch (error) {
-		if (!isMissingFileError(error)) return failure({
-			kind: "operational",
-			code: "claude-host-configuration-unreadable",
-			observed: `Devbox could not inspect Claude host configuration: ${path}.`,
-			nextAction: "Check access to ~/.devbox and run the command again."
-		});
-	}
-	try {
-		await mkdir(dirname(path), {
-			recursive: true,
-			mode: 448
-		});
-		await writeFile(path, "{}\n", {
-			encoding: "utf8",
-			flag: "wx",
-			mode: 384
-		});
-		return success(path);
-	} catch (error) {
-		if (error.code === "EEXIST") return ensureClaudeHostConfiguration(devboxHome, globalConfiguration);
-		return failure({
-			kind: "operational",
-			code: "claude-host-configuration-write-failed",
-			observed: `Devbox could not create Claude host configuration: ${path}.`,
-			nextAction: "Check write access to ~/.devbox and run the command again."
-		});
-	}
-}
-async function writeStateTransaction(writes) {
-	const staged = [];
-	for (const write of writes) {
-		const stagedWrite = await stageStateWrite(write.path, write.content, "transaction.tmp");
-		if (!stagedWrite.ok) {
-			await Promise.all(staged.map((stage) => rm(stage.path, { force: true }).catch(() => void 0)));
-			return stagedWrite;
-		}
-		staged.push({
-			write,
-			path: stagedWrite.value
-		});
-	}
-	const published = [];
-	try {
-		for (const stage of staged) {
-			await rename(stage.path, stage.write.path);
-			published.push(stage.write);
-		}
-		return success(void 0);
-	} catch {
-		let restored = true;
-		for (const write of published.reverse()) if (write.previous.exists) {
-			const restoredWrite = await writeAtomically(write.path, write.previous.content);
-			restored &&= restoredWrite.ok;
-		} else try {
-			await rm(write.path, { force: true });
-		} catch {
-			restored = false;
-		}
-		await Promise.all(staged.map((stage) => rm(stage.path, { force: true }).catch(() => void 0)));
-		return failure({
-			kind: "operational",
-			code: "state-write-failed",
-			observed: restored ? "Devbox could not publish Project state; the previous state was restored." : "Devbox could not publish Project state or restore the previous state.",
-			nextAction: "Check write access to ~/.devbox and run the command again."
-		});
-	}
-}
 function validateGlobalObject(configuration, catalog) {
 	try {
 		return parseGlobalConfiguration(serializeGlobalConfiguration(configuration), catalog);
@@ -1547,17 +1457,15 @@ function createConfigurationPrompter({ signal, input, output }) {
 			message: "Where should this configuration apply?",
 			options: [{
 				value: "local",
-				label: "Current project",
-				hint: "Enabled when this project’s container starts."
+				label: "Current project"
 			}, {
 				value: "global",
-				label: "Workspace Docker image",
-				hint: "Built into the shared image. It affects image size and disk usage."
+				label: "Workspace Docker image"
 			}],
 			...common
 		})),
 		editGlobal: async (configuration, catalog) => {
-			p.log.step(`${c.bold(c.cyan("Workspace Docker image"))}\n${c.dim("Add runtimes and agents to the shared image. They are available to every project and increase the image size.")}`, common);
+			p.log.step(c.bold(c.cyan("Workspace Docker image")), common);
 			return {
 				version: 1,
 				node: await promptValue(p.multiselect({
@@ -1582,7 +1490,7 @@ function createConfigurationPrompter({ signal, input, output }) {
 			};
 		},
 		editLocal: async (configuration, catalog, globalConfiguration, editPorts = true) => {
-			p.log.step(`${c.bold(c.cyan("Project configuration"))}\n${c.dim(editPorts ? "Choose the Node version and ports to use when this project’s container starts." : "Choose the Node version to use when this project’s container starts.")}`, common);
+			p.log.step(c.bold(c.cyan("Project configuration")), common);
 			const node = await promptValue(p.select({
 				message: "Selected Node release line",
 				options: [{
@@ -1600,7 +1508,7 @@ function createConfigurationPrompter({ signal, input, output }) {
 				node
 			};
 			const ports = normalizePortMappings((await promptValue(p.multiline({
-				message: "Published ports",
+				message: "Published ports" + c.dim(" (multiline; one mapping per line; press Enter twice to submit)"),
 				initialValue: configuration.ports.join("\n"),
 				validate: (value) => {
 					const ports = normalizePortMappings((value ?? "").split("\n"));
@@ -1652,20 +1560,28 @@ function showLogo() {
 	for (let i = 0; i < ASCII_ART.length; i++) console.log(`${COLORS[i]}${ASCII_ART[i]}${REST}`);
 }
 //#endregion
-//#region \0devbox-image-default:/home/runner/work/devbox/devbox/src/agent/image-defaults/.claude/settings.json.mjs
-var settings_json_default = "{\n  \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n  \"env\": {\n    \"CLAUDE_CODE_USE_POWERSHELL_TOOL\": \"0\"\n  },\n  \"attribution\": {\n    \"commit\": \"\",\n    \"pr\": \"\"\n  },\n  \"includeGitInstructions\": false,\n  \"autoMemoryEnabled\": false\n}\n";
-//#endregion
-//#region \0devbox-image-default:/home/runner/work/devbox/devbox/src/agent/image-defaults/.omp/agent/config.yml.mjs
-var config_yml_default = "setupVersion: 2\n\n# Basic\nmodelRoles:\n  default: openai-codex/gpt-5.6-terra:high\n  smol: openai-codex/gpt-5.6-luna:high\n  slow: openai-codex/gpt-5.6-sol:max\n  plan: openai-codex/gpt-5.6-sol:max\nsymbolPreset: unicode\n\n# Theme\ntheme:\n  dark: titanium\n  light: light\ncomposer:\n  shape: claude\n\n# Auto QA\ndev:\n  autoqa: false\n  autoqaConsent: denied\n";
-//#endregion
 //#region src/agent/build.ts
+const AGENT_BUILD_CONTEXT_ASSETS = {
+	instructions: {
+		relativePath: "AGENTS.md",
+		content: "# 協作規範\n\n## 語言\n\n- 一律使用繁體中文台灣用語產生對話及結果\n- 嚴禁使用簡體字，或是繁體字但中國大陸用語\n- 用詞要口語、常見，避免生硬或翻譯腔的詞彙；例如「根因」改用「原因」、「根本原因」、「主要原因」\n\n## 開發規範\n\n### 共用原則\n\n- 優先遵循專案既有的 `AGENTS.md`、文件、設定檔、lockfile、指令與程式碼慣例；專案沒有既有規範時，才使用本文件的預設選擇\n- 優先使用目前環境提供的專用工具；只有在專用工具無法完成工作或需要執行專案指令時，才使用適合的 CLI 工具\n- 執行會修改檔案、安裝套件或變更環境的指令前，確認目前位於預期的工作目錄\n- 可以在目前 workspace 內存取所需的上層目錄；存取 workspace 以外的檔案或目錄前，必須先取得使用者同意\n- 嚴禁執行任何會遞迴刪除根目錄的指令（例如 `rm -rf /`），也不得改寫或規避為效果相同的形式\n- 執行其他可能造成不可逆資料遺失的操作前，必須說明影響並取得使用者明確同意\n\n### JavaScript / TypeScript\n\n- 優先使用專案既有的 Node.js 版本設定與套件管理器\n- 專案未指定套件管理器且不存在 lockfile 時，使用 npm\n- 需要執行專案套件提供的 CLI 時，使用專案既有套件管理器對應的執行方式；使用 npm 時使用 npx\n- 不得擅自更換套件管理器、刪除 lockfile 或產生不同格式的 lockfile\n- TypeScript 格式規則\n  - 陣列型別優先使用 `T[]`，避免使用 `Array<T>`\n  - 字典型物件優先使用 `Record<string, T>`，避免使用 `{ [key: string]: T }`\n- Vue 3 程式碼變更前，先讀取 `/ycs77-vue` skill\n\n### PHP\n\n- 優先使用專案既有的 Composer scripts\n\n### 常見 CLI 工具\n\n- 版本控制操作使用 `git`\n- 所有 Git 操作都必須直接執行 `git` CLI\n- 禁止透過 Eval、JavaScript、Bun、Node.js、Python 或臨時程式碼間接包裝或呼叫 Git 指令\n- GitHub 相關操作優先使用 `gh` CLI\n\n## 安全\n\n- 在任何對話、指令輸出或程式碼中，不得揭露密碼、金鑰、Access Token、API Key 等機密資料\n- 不得讀取或輸出 `.env`、`.env.*` 等可能包含機密資料的檔案；不含真實機密的範本檔案（例如 `.env.example`）除外\n- 開發時需要使用機密資料，應以環境變數名稱或假值代稱，不得嘗試取得實際值\n"
+	},
+	claude: {
+		relativePath: ".claude/settings.json",
+		content: "{\n  \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n  \"env\": {\n    \"CLAUDE_CODE_USE_POWERSHELL_TOOL\": \"0\"\n  },\n  \"attribution\": {\n    \"commit\": \"\",\n    \"pr\": \"\"\n  },\n  \"includeGitInstructions\": false,\n  \"autoMemoryEnabled\": false\n}\n"
+	},
+	omp: {
+		relativePath: ".omp/agent/config.yml",
+		content: "setupVersion: 2\n\n# Basic\nmodelRoles:\n  default: openai-codex/gpt-5.6-terra:high\n  smol: openai-codex/gpt-5.6-luna:high\n  slow: openai-codex/gpt-5.6-sol:max\n  plan: openai-codex/gpt-5.6-sol:max\nsymbolPreset: unicode\n\n# Theme\ntheme:\n  dark: titanium\n  light: light\ncomposer:\n  shape: claude\n\n# Auto QA\ndev:\n  autoqa: false\n  autoqaConsent: denied\n"
+	}
+};
 function createAgentWorkspaceContribution(input) {
 	const agents = input.configuredAgents.map((name) => ({
 		name,
 		recipe: PACKAGED_AGENTS[name]
 	}));
 	const buildContextAssets = selectBuildContextAssets(agents);
-	const skillAgents = agents.filter((agent) => agent.recipe.supportsSkillInstallation).map((agent) => agent.name);
+	const skillAgents = [...new Set(agents.flatMap((agent) => agent.recipe.skillInstallationTarget === void 0 ? [] : [agent.recipe.skillInstallationTarget]))];
 	return {
 		buildContextAssets,
 		dockerignoreEntries: selectDockerignoreEntries(buildContextAssets),
@@ -1690,37 +1606,30 @@ function renderAgentInstallations(agents, buildNodeRuntimeRoot, skillAgents) {
 }
 function selectDockerignoreEntries(assets) {
 	const entries = [];
-	if (assets.some((asset) => asset.relativePath === ".claude/settings.json")) entries.push("!.claude", "!.claude/settings.json");
-	if (assets.some((asset) => asset.relativePath === ".omp/agent/config.yml")) entries.push("!.omp", "!.omp/agent", "!.omp/agent/config.yml");
+	if (assets.some((asset) => asset.relativePath === "AGENTS.md")) entries.push("!AGENTS.md");
+	if (assets.some((asset) => asset.relativePath.startsWith(".claude/"))) entries.push("!.claude", "!.claude/settings.json");
+	if (assets.some((asset) => asset.relativePath.startsWith(".omp/agent/"))) entries.push("!.omp", "!.omp/agent", "!.omp/agent/config.yml");
 	return entries;
 }
 function selectBuildContextAssets(agents) {
 	const assets = [];
-	if (agents.some((agent) => agent.name === "claude-code")) assets.push({
-		relativePath: ".claude/settings.json",
-		content: settings_json_default
-	});
-	if (agents.some((agent) => agent.name === "omp")) assets.push({
-		relativePath: ".omp/agent/config.yml",
-		content: config_yml_default
-	});
+	if (agents.length > 0) assets.push(AGENT_BUILD_CONTEXT_ASSETS.instructions);
+	if (agents.some((agent) => agent.name === "claude-code")) assets.push(AGENT_BUILD_CONTEXT_ASSETS.claude);
+	if (agents.some((agent) => agent.name === "omp")) assets.push(AGENT_BUILD_CONTEXT_ASSETS.omp);
 	return assets;
 }
 function renderAgentAssets(agents) {
 	const hasClaudeCode = agents.some((agent) => agent.name === "claude-code");
+	const hasCodex = agents.some((agent) => agent.name === "codex");
+	const hasAgy = agents.some((agent) => agent.name === "agy");
 	const hasOmp = agents.some((agent) => agent.name === "omp");
-	if (!hasClaudeCode && !hasOmp) return [];
-	const ownershipCommands = [];
+	if (!hasClaudeCode && !hasCodex && !hasAgy && !hasOmp) return [];
 	const lines = ["# Copy AI dotfiles"];
-	if (hasClaudeCode) {
-		lines.push("COPY .claude/settings.json /home/devbox/.claude/settings.json");
-		ownershipCommands.push("chown devbox:devbox /home/devbox/.claude/settings.json");
-	}
-	if (hasOmp) {
-		lines.push("COPY .omp/agent/config.yml /home/devbox/.omp/agent/config.yml");
-		ownershipCommands.push("chown devbox:devbox /home/devbox/.omp/agent", "chown devbox:devbox /home/devbox/.omp/agent/config.yml");
-	}
-	lines.push(`RUN ${ownershipCommands.join(" \\\n    && ")}`, "");
+	if (hasClaudeCode) lines.push("COPY --chown=devbox:devbox .claude/settings.json /home/devbox/.claude/settings.json", "COPY --chown=devbox:devbox AGENTS.md /home/devbox/.claude/CLAUDE.md");
+	if (hasCodex) lines.push("COPY --chown=devbox:devbox AGENTS.md /home/devbox/.codex/AGENTS.md");
+	if (hasAgy) lines.push("COPY --chown=devbox:devbox AGENTS.md /home/devbox/.gemini/GEMINI.md");
+	if (hasOmp) lines.push("COPY --chown=devbox:devbox .omp/agent/config.yml /home/devbox/.omp/agent/config.yml", "COPY --chown=devbox:devbox AGENTS.md /home/devbox/.omp/agent/AGENTS.md");
+	lines.push("");
 	return lines;
 }
 function renderAgentNotifications(agents, notificationsEnabled) {
@@ -1872,7 +1781,7 @@ async function buildWorkspaceUnlocked(input) {
 			kind: "operational",
 			code: "global-configuration-missing",
 			observed: "Global configuration is required before building the Workspace image.",
-			nextAction: "Run devbox config to commit Global configuration before devbox build."
+			nextAction: "Run devbox init to commit Global configuration before devbox build."
 		});
 	}
 	const parsedGlobal = parseGlobalConfiguration(globalSource, catalogCheck.value);
@@ -1892,7 +1801,7 @@ async function buildWorkspaceUnlocked(input) {
 		agent
 	});
 	await mkdir(paths.buildContext, { recursive: true });
-	await seedBuildContextAssets(paths.buildContext, buildContextAssets);
+	await refreshBuildContextAssets(paths.buildContext, buildContextAssets);
 	await Promise.all([
 		writeFile(join(paths.buildContext, "Dockerfile"), dockerfile),
 		writeFile(join(paths.buildContext, ".dockerignore"), renderDockerignore(buildContextAssets, agent.dockerignoreEntries)),
@@ -1972,7 +1881,7 @@ function renderBuildDockerfile(input) {
 	lines.push("WORKDIR /workspace", "USER devbox", "");
 	lines.push(...input.node.sandboxUserSetup);
 	lines.push(...input.agent.installationDockerfileLines);
-	lines.push("USER root", "", "# Copy dotfiles", "COPY .bash_aliases /home/devbox/.bash_aliases", "COPY .gitconfig /home/devbox/.gitconfig", "RUN chown devbox:devbox /home/devbox/.bash_aliases \\", "    && chown devbox:devbox /home/devbox/.gitconfig", "");
+	lines.push("USER root", "", "# Copy dotfiles", "COPY --chown=devbox:devbox .bash_aliases /home/devbox/.bash_aliases", "COPY --chown=devbox:devbox .gitconfig /home/devbox/.gitconfig", "");
 	lines.push(...input.agent.assetDockerfileLines);
 	lines.push(...input.agent.notificationDockerfileLines);
 	lines.push("COPY entrypoint.sh /usr/local/bin/entrypoint.sh", "COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf", "RUN chmod +x /usr/local/bin/entrypoint.sh", "", "ENTRYPOINT [\"/usr/local/bin/entrypoint.sh\"]");
@@ -1989,15 +1898,13 @@ function renderDockerignore(assets, additionalEntries) {
 		...additionalEntries
 	].join("\n")}\n`;
 }
-async function seedBuildContextAssets(buildContext, assets) {
+async function refreshBuildContextAssets(buildContext, assets) {
+	const requiredPaths = new Set(assets.map((asset) => asset.relativePath));
+	for (const asset of Object.values(AGENT_BUILD_CONTEXT_ASSETS)) if (!requiredPaths.has(asset.relativePath)) await rm(join(buildContext, asset.relativePath), { force: true });
 	await Promise.all(assets.map(async (asset) => {
 		const destination = join(buildContext, asset.relativePath);
 		await mkdir(dirname(destination), { recursive: true });
-		try {
-			await writeFile(destination, asset.content, { flag: "wx" });
-		} catch (error) {
-			if (typeof error !== "object" || error === null || !("code" in error) || error.code !== "EEXIST") throw error;
-		}
+		await writeFile(destination, asset.content);
 	}));
 }
 function renderEntrypoint(input) {
@@ -2088,7 +1995,7 @@ function createCli(signal, interactive) {
 			outro("Project is already registered.");
 			return success({});
 		}
-		outro(`Next: run ${c.cyan(c.bold("devbox build"))} to prepare your workspace, then ${c.cyan(c.bold("devbox up"))} to start it.`);
+		outro(result.value.globalConfigurationCreated ? `Next: run ${command("devbox build")} to prepare your workspace, then ${command("devbox up")} to start it.` : `Next: run ${command("devbox up")} to start it.`);
 		return success({});
 	});
 	cli.command("config", "Edit Global or Local configuration for the current Project.").action(async () => {
@@ -2100,7 +2007,7 @@ function createCli(signal, interactive) {
 				prompt
 			});
 			if (!result.ok) return result;
-			outro(result.value.changed ? "Global configuration updated." : "Global configuration was not changed.");
+			outro(result.value.changed ? `Global configuration updated. Run ${command("devbox build")} to rebuild the Workspace image.` : "Global configuration was not changed.");
 			return success({});
 		}
 		const result = await configureLocalProject({
@@ -2119,7 +2026,7 @@ function createCli(signal, interactive) {
 		if (!result.ok) return result;
 		return success({ message: `Built Workspace image: ${result.value.image}` });
 	});
-	cli.command("rm", "Remove the current registered Project and its state.").option("--yes", "Skip the confirmation prompt.").action(async (options = {}) => {
+	cli.command("rm", "Remove the current Project Sandbox and Devbox state.").option("--yes", "Skip the confirmation prompt.").action(async (options = {}) => {
 		if (!interactive && !options.yes) return interactiveFailure("devbox rm requires a TTY or --yes.", "Run devbox rm from a TTY, or pass --yes to confirm removal.");
 		const result = await removeProject({
 			signal,
@@ -2129,22 +2036,6 @@ function createCli(signal, interactive) {
 		if (!result.ok) return result;
 		return success({ message: result.value.removed ? `Removed Project: ${result.value.root}` : "Project removal was not changed." });
 	});
-	cli.command("cleanup", "Remove explicitly selected disposable Devbox state.").option("--missing-projects", "Remove Missing-root Project registrations.").option("--yes", "Skip the confirmation prompt.").action(async (options = {}) => {
-		if (!options.missingProjects) return failure({
-			kind: "usage",
-			code: "cleanup-mode-required",
-			observed: "cleanup requires --missing-projects.",
-			nextAction: "Run devbox cleanup --missing-projects."
-		});
-		if (!interactive && !options.yes) return interactiveFailure("devbox cleanup --missing-projects requires a TTY or --yes.", "Run devbox cleanup --missing-projects from a TTY, or pass --yes to confirm removal.");
-		const result = await cleanupMissingProjects({
-			signal,
-			confirm: prompt.confirm,
-			yes: options.yes
-		});
-		if (!result.ok) return result;
-		return success({ message: result.value.removed ? `Removed Missing-root Projects: ${result.value.roots.join(", ")}` : "No Missing-root Projects were removed." });
-	});
 	for (const [command, description] of [
 		["up", "Start the current Project Sandbox."],
 		["down", "Stop and remove the current Project Sandbox."],
@@ -2163,7 +2054,7 @@ function createCli(signal, interactive) {
 }
 function present(result) {
 	if (!result.ok) {
-		process.stderr.write(`${result.error.observed}\n${result.error.nextAction}\n`);
+		process.stderr.write(`${highlightCommands(result.error.observed)}\n${highlightCommands(result.error.nextAction)}\n`);
 		return result.error.kind === "usage" ? 2 : 1;
 	}
 	if (result.value.message !== void 0) process.stdout.write(`${result.value.message}\n`);
@@ -2196,6 +2087,12 @@ async function main() {
 function isCacError(error) {
 	return error instanceof Error && error.name === "CACError";
 }
+function command(value) {
+	return c.cyan(c.bold(value));
+}
+function highlightCommands(message) {
+	return message.replace(/\bdevbox (?:init|build|config|up|down|stop|sh|rm)\b/g, command);
+}
 function interactiveFailure(observed, nextAction) {
 	return failure({
 		kind: "usage",