@firatcand/roster 1.0.0 → 1.0.1

package/bin/roster.js

@@ -10,6 +10,7 @@ import { z } from "zod";
 import { createHash, randomBytes } from "node:crypto";
 import YAML, { parse } from "yaml";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
 //#region src/lib/paths.ts
 function findRosterRoot() {
 	const here = dirname(fileURLToPath(import.meta.url));
@@ -99,12 +100,13 @@ var RosterError = class extends Error {
 function isRosterError(err) {
 	return err instanceof RosterError;
 }
-function permissionError(targetPath, cause) {
+function permissionError(targetPath, cause, scope) {
 	const syscall = cause.syscall ? ` (${cause.syscall})` : "";
+	const remedy = scope === "project" ? `  Check filesystem permissions on the workspace, or run: chmod -R u+w ${targetPath}` : `  Re-run with sudo, or run: sudo chown -R "$USER" ${targetPath}`;
 	return new RosterError({
 		header: `${chalk.red.bold("roster:")} permission denied`,
 		body: `  ${cause.code ?? "EACCES"}${syscall} writing ${targetPath}`,
-		remedy: `  Re-run with sudo, or run: sudo chown -R "$USER" ${targetPath}`,
+		remedy,
 		exitCode: 1
 	});
 }
@@ -170,6 +172,32 @@ function userCancelledInstall() {
 		exitCode: 2
 	});
 }
+function workspaceRequiredError(cwd) {
+	return new RosterError({
+		header: `${chalk.red.bold("roster:")} project-level install requires a roster workspace`,
+		body: [`  CWD: ${cwd}`, `  Expected: config/project.yaml (created by ${chalk.bold("roster init")})`].join("\n"),
+		remedy: [
+			`  Either:`,
+			`    - cd into a roster workspace, or`,
+			`    - re-run with ${chalk.bold("--scope user")} to install to your home directory.`
+		].join("\n"),
+		exitCode: 2
+	});
+}
+function toolsNotDetectedError(requestedKeys, detectedKeys) {
+	const missing = requestedKeys.filter((k) => !detectedKeys.includes(k));
+	const detectedLabel = detectedKeys.length === 0 ? "(none)" : detectedKeys.join(", ");
+	return new RosterError({
+		header: `${chalk.red.bold("roster:")} requested tool${missing.length === 1 ? "" : "s"} not detected: ${missing.join(", ")}`,
+		body: [`  --tool requested: ${requestedKeys.join(", ")}`, `  detected on this machine: ${detectedLabel}`].join("\n"),
+		remedy: [
+			`  Either:`,
+			`    - install the missing tool${missing.length === 1 ? "" : "s"} first, or`,
+			`    - drop the missing key${missing.length === 1 ? "" : "s"} from ${chalk.bold("--tool")}.`
+		].join("\n"),
+		exitCode: 3
+	});
+}
 function linuxClaudeUnsupportedError() {
 	return new RosterError({
 		header: `${chalk.red.bold("roster:")} Claude Desktop scheduling is not available on Linux`,
@@ -460,7 +488,7 @@ async function prepareTargetForWrite(targetPath, kind, logger, confirm) {
 	}
 	return true;
 }
-async function copyOne(srcPath, targetPath, kind, logger, confirm) {
+async function copyOne(srcPath, targetPath, kind, logger, confirm, scope) {
 	try {
 		if (!await prepareTargetForWrite(targetPath, kind, logger, confirm)) return false;
 		await copy(srcPath, targetPath, {
@@ -469,17 +497,17 @@ async function copyOne(srcPath, targetPath, kind, logger, confirm) {
 		});
 		return true;
 	} catch (err) {
-		if (isEacces(err)) throw permissionError(targetPath, err);
+		if (isEacces(err)) throw permissionError(targetPath, err, scope);
 		throw err;
 	}
 }
-async function writeRenderedOne(targetPath, contents, kind, logger, confirm) {
+async function writeRenderedOne(targetPath, contents, kind, logger, confirm, scope) {
 	try {
 		if (!await prepareTargetForWrite(targetPath, kind, logger, confirm)) return false;
 		writeFileSync(targetPath, contents);
 		return true;
 	} catch (err) {
-		if (isEacces(err)) throw permissionError(targetPath, err);
+		if (isEacces(err)) throw permissionError(targetPath, err, scope);
 		throw err;
 	}
 }
@@ -496,7 +524,7 @@ async function installToTool(tool, opts) {
 		await ensureDir(tool.skillsTarget);
 		if (tool.agentsTarget) await ensureDir(tool.agentsTarget);
 	} catch (err) {
-		if (isEacces(err)) throw permissionError(tool.skillsTarget, err);
+		if (isEacces(err)) throw permissionError(tool.skillsTarget, err, opts.scope);
 		throw err;
 	}
 	let skillsCount = 0;
@@ -514,7 +542,7 @@ async function installToTool(tool, opts) {
 			const renderedSkillMd = join(targetPath, "SKILL.md");
 			assertWithinRoot(targetPath, tool.configRoot, "skill targetPath");
 			info(chalk.dim(`  + skill ${dirent.name} -> ${targetPath}`));
-			if (await copyOne(srcPath, targetPath, "skill", logger, confirm)) {
+			if (await copyOne(srcPath, targetPath, "skill", logger, confirm, opts.scope)) {
 				renderSkillFrontmatter(renderedSkillMd, tool.key);
 				skillsCount++;
 			}
@@ -543,15 +571,15 @@ async function installToTool(tool, opts) {
 					throw err;
 				}
 				info(chalk.dim(`  + agent ${dirent.name} -> ${tomlTarget}`));
-				const wroteToml = await writeRenderedOne(tomlTarget, rendered.toml, "agent", logger, confirm);
-				const wrotePersona = await writeRenderedOne(personaTarget, rendered.personaBody, "agent persona", logger, confirm);
+				const wroteToml = await writeRenderedOne(tomlTarget, rendered.toml, "agent", logger, confirm, opts.scope);
+				const wrotePersona = await writeRenderedOne(personaTarget, rendered.personaBody, "agent persona", logger, confirm, opts.scope);
 				if (wroteToml && wrotePersona) agentsCount++;
 				continue;
 			}
 			const targetPath = join(tool.agentsTarget, dirent.name);
 			assertWithinRoot(targetPath, tool.configRoot, "agent targetPath");
 			info(chalk.dim(`  + agent ${dirent.name} -> ${targetPath}`));
-			if (await copyOne(srcPath, targetPath, "agent", logger, confirm)) agentsCount++;
+			if (await copyOne(srcPath, targetPath, "agent", logger, confirm, opts.scope)) agentsCount++;
 		}
 	}
 	return {
@@ -569,19 +597,46 @@ const KNOWN_TOOL_KEYS = [
 	"gemini"
 ];
 const TOOL_LIST$1 = KNOWN_TOOL_KEYS.join(" | ");
+const SCOPE_LIST$1 = "(project | user)";
 function isToolKey(value) {
 	return KNOWN_TOOL_KEYS.includes(value);
 }
+function isScope$1(value) {
+	return value === "project" || value === "user";
+}
+function parseToolValue(value) {
+	const parts = value.split(",").map((s) => s.trim());
+	if (parts.some((p) => p.length === 0)) return {
+		ok: false,
+		message: `--tool received an empty value (check for stray commas)`
+	};
+	const keys = [];
+	for (const part of parts) {
+		if (!isToolKey(part)) return {
+			ok: false,
+			message: `unknown tool '${part}'; expected one of: ${TOOL_LIST$1}`
+		};
+		if (!keys.includes(part)) keys.push(part);
+	}
+	return {
+		ok: true,
+		keys
+	};
+}
 function parseInstallArgs(args) {
 	let silent = false;
 	let verbose = false;
+	let yes = false;
 	let all = false;
 	let toolValue = null;
 	let toolFlagSeen = false;
+	let scopeValue = null;
+	let scopeFlagSeen = false;
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
 		if (arg === "--silent") silent = true;
 		else if (arg === "--verbose") verbose = true;
+		else if (arg === "--yes" || arg === "-y") yes = true;
 		else if (arg === "--all") all = true;
 		else if (arg === "--tool") {
 			toolFlagSeen = true;
@@ -600,57 +655,150 @@ function parseInstallArgs(args) {
 				message: `--tool requires a tool name (${TOOL_LIST$1})`
 			};
 			toolValue = value;
+		} else if (arg === "--scope") {
+			scopeFlagSeen = true;
+			const next = args[i + 1];
+			if (next === void 0 || next.startsWith("-")) return {
+				kind: "err",
+				message: `--scope requires a value: ${SCOPE_LIST$1}`
+			};
+			scopeValue = next;
+			i++;
+		} else if (arg.startsWith("--scope=")) {
+			scopeFlagSeen = true;
+			const value = arg.slice(8);
+			if (value === "") return {
+				kind: "err",
+				message: `--scope requires a value: ${SCOPE_LIST$1}`
+			};
+			scopeValue = value;
 		}
 	}
 	if (all && toolFlagSeen) return {
 		kind: "err",
 		message: "flags --all and --tool are mutually exclusive"
 	};
+	let scope = null;
+	if (scopeFlagSeen) {
+		if (scopeValue === null || !isScope$1(scopeValue)) return {
+			kind: "err",
+			message: `unknown scope '${scopeValue ?? ""}'; expected one of: ${SCOPE_LIST$1}`
+		};
+		scope = scopeValue;
+	}
+	let target;
 	if (toolFlagSeen && toolValue !== null) {
-		if (!isToolKey(toolValue)) return {
+		const parsed = parseToolValue(toolValue);
+		if (!parsed.ok) return {
 			kind: "err",
-			message: `unknown tool '${toolValue}'; expected one of: ${TOOL_LIST$1}`
+			message: parsed.message
 		};
-		return {
-			kind: "ok",
-			silent,
-			verbose,
-			target: {
-				mode: "tool",
-				key: toolValue
-			}
+		target = {
+			mode: "tools",
+			keys: parsed.keys
 		};
-	}
-	if (all) return {
+	} else if (all) target = { mode: "all" };
+	else target = { mode: "interactive" };
+	return {
 		kind: "ok",
 		silent,
 		verbose,
-		target: { mode: "all" }
+		yes,
+		scope,
+		target
 	};
+}
+//#endregion
+//#region src/lib/install-scope.ts
+function detectWorkspace(cwd) {
+	return existsSync(join(cwd, "config", "project.yaml"));
+}
+function defaultScopeForContext(workspaceExists) {
+	return workspaceExists ? "project" : "user";
+}
+function projectPathsFor(toolKey, workspaceRoot, hasAgents) {
+	const agentsPath = (root) => hasAgents ? join(workspaceRoot, root, "agents") : null;
+	switch (toolKey) {
+		case "claude": return {
+			configRoot: join(workspaceRoot, ".claude"),
+			skillsTarget: join(workspaceRoot, ".claude", "skills"),
+			agentsTarget: agentsPath(".claude")
+		};
+		case "codex": return {
+			configRoot: join(workspaceRoot, ".codex"),
+			skillsTarget: join(workspaceRoot, ".codex", "skills"),
+			agentsTarget: agentsPath(".codex")
+		};
+		case "gemini": return {
+			configRoot: join(workspaceRoot, ".gemini"),
+			skillsTarget: join(workspaceRoot, ".gemini", "extensions"),
+			agentsTarget: agentsPath(".gemini")
+		};
+	}
+}
+function toolForScope(tool, scope, workspaceRoot) {
+	if (scope === "user") return tool;
+	if (workspaceRoot === void 0) throw new Error("toolForScope: workspaceRoot is required when scope is \"project\"");
+	const hasAgents = tool.agentsTarget !== null;
+	const paths = projectPathsFor(tool.key, workspaceRoot, hasAgents);
 	return {
-		kind: "ok",
-		silent,
-		verbose,
-		target: { mode: "interactive" }
+		...tool,
+		...paths
 	};
 }
 //#endregion
 //#region src/lib/doctor-args.ts
+const SCOPE_LIST = "(project | user)";
+function isScope(value) {
+	return value === "project" || value === "user";
+}
 function parseDoctorArgs(args) {
 	let json = false;
 	let silent = false;
 	let fix = false;
 	let dryRun = false;
-	for (const arg of args) if (arg === "--json") json = true;
-	else if (arg === "--silent") silent = true;
-	else if (arg === "--fix") fix = true;
-	else if (arg === "--dry-run") dryRun = true;
+	let scopeValue = null;
+	let scopeFlagSeen = false;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--json") json = true;
+		else if (arg === "--silent") silent = true;
+		else if (arg === "--fix") fix = true;
+		else if (arg === "--dry-run") dryRun = true;
+		else if (arg === "--scope") {
+			scopeFlagSeen = true;
+			const next = args[i + 1];
+			if (next === void 0 || next.startsWith("-")) return {
+				kind: "err",
+				message: `--scope requires a value: ${SCOPE_LIST}`
+			};
+			scopeValue = next;
+			i++;
+		} else if (arg.startsWith("--scope=")) {
+			scopeFlagSeen = true;
+			const value = arg.slice(8);
+			if (value === "") return {
+				kind: "err",
+				message: `--scope requires a value: ${SCOPE_LIST}`
+			};
+			scopeValue = value;
+		}
+	}
+	let scope = null;
+	if (scopeFlagSeen) {
+		if (scopeValue === null || !isScope(scopeValue)) return {
+			kind: "err",
+			message: `unknown scope '${scopeValue ?? ""}'; expected one of: ${SCOPE_LIST}`
+		};
+		scope = scopeValue;
+	}
 	return {
 		kind: "ok",
 		json,
 		silent,
 		fix,
-		dryRun
+		dryRun,
+		scope
 	};
 }
 const KEBAB_RE$1 = /^[a-z0-9]+(-[a-z0-9]+)*$/;
@@ -2716,7 +2864,7 @@ async function executeInit(opts) {
 	const totalChanged = filesWritten.length + filesUpdated.length + filesLinked.length;
 	if (!silent) {
 		info("");
-		info(`${chalk.green("✓")} Initialized ${chalk.bold(projectName)} in ${opts.cwd}`);
+		info(`${chalk.green("✓")} Initialized roster workspace ${chalk.bold(`'${projectName}'`)} in ${opts.cwd} ${chalk.dim("(current directory)")}`);
 		if (totalChanged > 8) info(chalk.dim(`Files: ${totalChanged} written/linked`));
 		else {
 			const changed = [
@@ -2729,7 +2877,7 @@ async function executeInit(opts) {
 		for (const w of warnings) info(chalk.yellow(w));
 		if (gitInitialized) info(chalk.dim("Git: initialized .git/"));
 		info("");
-		info(`${chalk.dim("Next: ")}${chalk.bold("open in Claude Code")}${chalk.dim(" and run ")}${chalk.bold("/chief-of-staff audit-repo")}`);
+		info(`${chalk.dim("Next: ")}you are already in this directory — ${chalk.bold("open Claude Code here")}${chalk.dim(" and run ")}${chalk.bold("/chief-of-staff audit-repo")}`);
 	}
 	return {
 		status: "ok",
@@ -3151,7 +3299,7 @@ function validateSchedulesInCwd(cwd) {
 }
 //#endregion
 //#region src/lib/dotenv-parse.ts
-const KEY_RE = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*/;
+const KEY_RE$1 = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*/;
 function parseEnvFile(content) {
 	const out = /* @__PURE__ */ new Map();
 	if (content.charCodeAt(0) === 65279) content = content.slice(1);
@@ -3159,7 +3307,7 @@ function parseEnvFile(content) {
 		const trimmed = rawLine.replace(/^\s+/, "");
 		if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
 		const candidate = trimmed.startsWith("export ") ? trimmed.slice(7).replace(/^\s+/, "") : trimmed;
-		const m = candidate.match(KEY_RE);
+		const m = candidate.match(KEY_RE$1);
 		if (m === null) continue;
 		const key = m[1];
 		const parsed = parseValue(candidate.slice(m[0].length));
@@ -3244,6 +3392,376 @@ function isWindows() {
 	return getPlatform() === "win32";
 }
 //#endregion
+//#region src/lib/agent-config-schema.ts
+const AGENT_RE = /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/;
+const ENV_VAR_RE = /^[A-Z][A-Z0-9_]*$/;
+const FORBIDDEN_FS_PREFIXES = [
+	"/Users/",
+	"/home/",
+	"/etc/",
+	"/var/",
+	"/tmp/",
+	"/opt/"
+];
+const workspaceRootedPath = z.string().refine((p) => p.startsWith("/") && !FORBIDDEN_FS_PREFIXES.some((pfx) => p.startsWith(pfx)), { message: "must be a workspace-root-relative path starting with '/' (rejected: literal absolute fs paths /Users/ /home/ /etc/ /var/ /tmp/ /opt/)" });
+const toolBindingSchema = z.object({
+	env_var: z.string().regex(ENV_VAR_RE, { message: "env_var: must be SCREAMING_SNAKE_CASE" }),
+	required: z.boolean()
+}).strict();
+const agentConfigSchema = z.object({
+	agent: z.string().regex(AGENT_RE, { message: "agent: must match '<function>/<agent>' with kebab-case segments" }),
+	plans_dir: z.string().min(1),
+	guideline_refs: z.record(z.string().min(1), workspaceRootedPath).nullish(),
+	tools: z.record(z.string().min(1), toolBindingSchema).nullish()
+}).strict();
+function isInsideRoot(root, p) {
+	const rel = relative(root, p);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+function loadAgentConfig(workspaceRoot, agentPath) {
+	if (!AGENT_RE.test(agentPath)) return {
+		ok: false,
+		errors: [{
+			kind: "invalid-agent-path",
+			message: `agentPath '${agentPath}' must match '<function>/<agent>' with kebab-case segments`
+		}]
+	};
+	let realRoot;
+	try {
+		realRoot = realpathSync(workspaceRoot);
+	} catch (err) {
+		return {
+			ok: false,
+			errors: [{
+				kind: "missing-file",
+				message: `workspaceRoot '${workspaceRoot}' not accessible: ${err.message}`,
+				path: workspaceRoot
+			}]
+		};
+	}
+	const configPath = join(realRoot, agentPath, "config.yaml");
+	let raw;
+	try {
+		raw = readFileSync(configPath, "utf8");
+	} catch (err) {
+		const e = err;
+		if (e.code === "ENOENT") return {
+			ok: false,
+			errors: [{
+				kind: "missing-file",
+				message: `config.yaml not found at ${configPath}`,
+				path: configPath
+			}]
+		};
+		return {
+			ok: false,
+			errors: [{
+				kind: "missing-file",
+				message: `failed to read ${configPath}: ${e.message}`,
+				path: configPath
+			}]
+		};
+	}
+	let doc;
+	try {
+		doc = YAML.parse(raw);
+	} catch (err) {
+		return {
+			ok: false,
+			errors: [{
+				kind: "yaml-parse",
+				message: `YAML parse error in ${configPath}: ${err.message}`,
+				path: configPath
+			}]
+		};
+	}
+	const parsed = agentConfigSchema.safeParse(doc);
+	if (!parsed.success) return {
+		ok: false,
+		errors: parsed.error.issues.map((issue) => ({
+			kind: "schema",
+			message: issue.message,
+			path: issue.path.length > 0 ? issue.path.join(".") : void 0
+		}))
+	};
+	const config = parsed.data;
+	const errors = [];
+	if (config.agent !== agentPath) errors.push({
+		kind: "agent-field-mismatch",
+		message: `agent field '${config.agent}' does not match agentPath argument '${agentPath}'`,
+		path: "agent"
+	});
+	const refs = config.guideline_refs ?? {};
+	for (const [key, ref] of Object.entries(refs)) {
+		const wantsDirectory = ref.endsWith("/");
+		const stripped = ref.replace(/^\/+/, "");
+		const absolute = resolve(realRoot, stripped);
+		if (!isInsideRoot(realRoot, absolute)) {
+			errors.push({
+				kind: "ref-escapes-workspace",
+				message: `guideline_refs.${key}: '${ref}' escapes outside workspace root after resolution`,
+				path: `guideline_refs.${key}`,
+				ref
+			});
+			continue;
+		}
+		let realAbsolute;
+		try {
+			realAbsolute = realpathSync(absolute);
+		} catch (err) {
+			const e = err;
+			if (e.code === "ENOENT") errors.push({
+				kind: "ref-not-found",
+				message: `guideline_refs.${key}: '${ref}' resolves to ${absolute} which does not exist`,
+				path: `guideline_refs.${key}`,
+				ref
+			});
+			else errors.push({
+				kind: "ref-not-found",
+				message: `guideline_refs.${key}: realpath ${absolute} failed: ${e.message}`,
+				path: `guideline_refs.${key}`,
+				ref
+			});
+			continue;
+		}
+		if (!isInsideRoot(realRoot, realAbsolute)) {
+			errors.push({
+				kind: "ref-escapes-workspace",
+				message: `guideline_refs.${key}: '${ref}' resolves via symlink to ${realAbsolute} outside workspace root`,
+				path: `guideline_refs.${key}`,
+				ref
+			});
+			continue;
+		}
+		let stat;
+		try {
+			stat = statSync(realAbsolute);
+		} catch (err) {
+			errors.push({
+				kind: "ref-not-found",
+				message: `guideline_refs.${key}: stat ${realAbsolute} failed: ${err.message}`,
+				path: `guideline_refs.${key}`,
+				ref
+			});
+			continue;
+		}
+		if (wantsDirectory && !stat.isDirectory()) errors.push({
+			kind: "ref-shape-mismatch",
+			message: `guideline_refs.${key}: '${ref}' ends with '/' but ${realAbsolute} is not a directory`,
+			path: `guideline_refs.${key}`,
+			ref
+		});
+		else if (!wantsDirectory && !stat.isFile()) errors.push({
+			kind: "ref-shape-mismatch",
+			message: `guideline_refs.${key}: '${ref}' has no trailing '/' but ${realAbsolute} is not a regular file (add '/' if you meant a directory)`,
+			path: `guideline_refs.${key}`,
+			ref
+		});
+	}
+	if (errors.length > 0) return {
+		ok: false,
+		errors
+	};
+	return {
+		ok: true,
+		config,
+		refsChecked: Object.keys(refs).length
+	};
+}
+//#endregion
+//#region src/lib/env-merge.ts
+function resolveAgentEnv(workspaceRoot, agentPath) {
+	const workspace = tryReadAndParse(join(workspaceRoot, ".env"));
+	const agent = tryReadAndParse(join(workspaceRoot, agentPath, ".env"));
+	const out = {};
+	for (const [k, v] of workspace) {
+		if (v.length === 0) continue;
+		out[k] = v;
+	}
+	for (const [k, v] of agent) if (v.length === 0) delete out[k];
+	else out[k] = v;
+	return out;
+}
+function tryReadAndParse(path) {
+	try {
+		return parseEnvFile(readFileSync(path, "utf8"));
+	} catch {
+		return /* @__PURE__ */ new Map();
+	}
+}
+//#endregion
+//#region src/lib/doctor-agent-env-audit.ts
+const SKIP_TOP$1 = new Set([
+	"roster",
+	"node_modules",
+	"plans",
+	"spec",
+	"docs",
+	"bin",
+	"lib",
+	"skills",
+	"agents",
+	"templates",
+	"test",
+	"src"
+]);
+function collectAgentEnvFiles(cwd) {
+	const out = [];
+	let topEntries;
+	try {
+		topEntries = readdirSync(cwd);
+	} catch {
+		return [];
+	}
+	for (const top of topEntries) {
+		if (top.startsWith(".")) continue;
+		if (SKIP_TOP$1.has(top)) continue;
+		const topDir = join(cwd, top);
+		let topSt;
+		try {
+			topSt = statSync(topDir);
+		} catch {
+			continue;
+		}
+		if (!topSt.isDirectory()) continue;
+		const topEnv = join(topDir, ".env");
+		try {
+			if (statSync(topEnv).isFile()) out.push(topEnv);
+		} catch {}
+		let agents;
+		try {
+			agents = readdirSync(topDir);
+		} catch {
+			continue;
+		}
+		for (const agent of agents) {
+			if (agent.startsWith(".")) continue;
+			const agentDir = join(topDir, agent);
+			let aSt;
+			try {
+				aSt = statSync(agentDir);
+			} catch {
+				continue;
+			}
+			if (!aSt.isDirectory()) continue;
+			const envPath = join(agentDir, ".env");
+			let eSt;
+			try {
+				eSt = statSync(envPath);
+			} catch {
+				continue;
+			}
+			if (!eSt.isFile()) continue;
+			out.push(envPath);
+		}
+	}
+	return out;
+}
+const KEY_RE = /^([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+function findLastLineForKey(rawContent, key) {
+	let content = rawContent;
+	if (content.charCodeAt(0) === 65279) content = content.slice(1);
+	const lines = content.split(/\r?\n/);
+	let lastMatch = null;
+	for (let i = 0; i < lines.length; i++) {
+		const trimmed = (lines[i] ?? "").replace(/^\s+/, "");
+		if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
+		const m = (trimmed.startsWith("export ") ? trimmed.slice(7).replace(/^\s+/, "") : trimmed).match(KEY_RE);
+		if (m === null) continue;
+		if (m[1] === key) lastMatch = i + 1;
+	}
+	return lastMatch;
+}
+function auditAgentEnvRedundancy(cwd) {
+	let workspaceMap;
+	try {
+		workspaceMap = parseEnvFile(readFileSync(join(cwd, ".env"), "utf8"));
+	} catch {
+		return {
+			status: "ok",
+			items: []
+		};
+	}
+	const items = [];
+	for (const envPath of collectAgentEnvFiles(cwd)) {
+		let raw;
+		try {
+			raw = readFileSync(envPath, "utf8");
+		} catch {
+			continue;
+		}
+		const agentMap = parseEnvFile(raw);
+		for (const [key, value] of agentMap) {
+			const wsValue = workspaceMap.get(key);
+			if (wsValue === void 0) continue;
+			if (wsValue !== value) continue;
+			const line = findLastLineForKey(raw, key);
+			if (line === null) continue;
+			items.push({
+				agentEnvPath: relative(cwd, envPath),
+				line,
+				key
+			});
+		}
+	}
+	items.sort((a, b) => {
+		if (a.agentEnvPath !== b.agentEnvPath) return a.agentEnvPath.localeCompare(b.agentEnvPath);
+		return a.line - b.line;
+	});
+	return {
+		status: items.length === 0 ? "ok" : "warn",
+		items
+	};
+}
+function removeLineForKey(absPath, oneBasedLine, expectedKey, expectedValue, dryRun) {
+	let raw;
+	try {
+		raw = readFileSync(absPath, "utf8");
+	} catch (err) {
+		return {
+			kind: "error",
+			message: err.message
+		};
+	}
+	const hadTrailingNewline = raw.length > 0 && raw.charCodeAt(raw.length - 1) === 10;
+	const newline = /\r\n/.test(raw) ? "\r\n" : "\n";
+	const lines = raw.split(/\r?\n/);
+	const effectiveLineCount = hadTrailingNewline ? lines.length - 1 : lines.length;
+	if (oneBasedLine < 1 || oneBasedLine > effectiveLineCount) return {
+		kind: "changed",
+		reason: "line out of range"
+	};
+	const targetLine = lines[oneBasedLine - 1] ?? "";
+	const trimmed = targetLine.replace(/^\s+/, "");
+	const m = (trimmed.startsWith("export ") ? trimmed.slice(7).replace(/^\s+/, "") : trimmed).match(KEY_RE);
+	if (m === null || m[1] !== expectedKey) return {
+		kind: "changed",
+		reason: "line no longer declares expected key"
+	};
+	const parsedAtLine = parseEnvFile(targetLine).get(expectedKey);
+	if (parsedAtLine === void 0 || parsedAtLine !== expectedValue) return {
+		kind: "changed",
+		reason: "line value no longer matches workspace"
+	};
+	if (dryRun) return { kind: "would-remove" };
+	const next = lines.slice(0, oneBasedLine - 1).concat(lines.slice(oneBasedLine)).join(newline);
+	let mode = 384;
+	try {
+		mode = statSync(absPath).mode & 511;
+	} catch {}
+	const tmpPath = absPath + ".tmp." + String(process.pid);
+	try {
+		writeFileSync(tmpPath, next, { mode });
+		renameSync(tmpPath, absPath);
+	} catch (err) {
+		return {
+			kind: "error",
+			message: err.message
+		};
+	}
+	return { kind: "removed" };
+}
+//#endregion
 //#region src/lib/doctor-secrets-audit.ts
 function formatMode(mode) {
 	return "0" + (mode & 511).toString(8).padStart(3, "0");
@@ -3275,85 +3793,142 @@ function auditEnvPermissions(cwd) {
 		autoFixable: true
 	};
 }
-const VAR_REF_RE = /\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g;
-function extractVarRefs(content) {
-	const out = /* @__PURE__ */ new Map();
-	const lines = content.split(/\r?\n/);
-	for (let i = 0; i < lines.length; i++) {
-		const line = lines[i];
-		for (const m of line.matchAll(VAR_REF_RE)) {
-			const key = m[1] ?? m[2] ?? "";
-			if (key.length === 0) continue;
-			const list = out.get(key);
-			if (list) list.push(i + 1);
-			else out.set(key, [i + 1]);
-		}
-	}
-	return out;
+function classifyAgentEnvMode(modeBits) {
+	if (modeBits === 384) return "ok";
+	if ((modeBits & 18) !== 0) return "fail";
+	return "warn";
 }
-const SKIP_TOP = new Set([
-	"roster",
-	"node_modules",
-	"plans",
-	"spec",
-	"docs",
-	"bin",
-	"lib",
-	"skills",
-	"agents",
-	"templates",
-	"test",
-	"src"
-]);
-function collectConfigYamls(cwd) {
+function listAgentDirs(cwd) {
 	const out = [];
 	let topEntries;
 	try {
 		topEntries = readdirSync(cwd);
 	} catch {
-		return [];
+		return out;
 	}
 	for (const top of topEntries) {
 		if (top.startsWith(".")) continue;
 		if (SKIP_TOP.has(top)) continue;
-		const fnDir = join(cwd, top);
-		let st;
+		const topDir = join(cwd, top);
+		let topStat;
 		try {
-			st = statSync(fnDir);
+			topStat = statSync(topDir);
 		} catch {
 			continue;
 		}
-		if (!st.isDirectory()) continue;
-		let agents;
+		if (!topStat.isDirectory()) continue;
+		out.push(topDir);
+		let children;
 		try {
-			agents = readdirSync(fnDir);
+			children = readdirSync(topDir);
 		} catch {
 			continue;
 		}
-		for (const agent of agents) {
-			if (agent.startsWith(".")) continue;
-			const projectsDir = join(fnDir, agent, "projects");
-			let projects;
+		for (const child of children) {
+			if (child.startsWith(".")) continue;
+			const childDir = join(topDir, child);
+			let childStat;
 			try {
-				projects = readdirSync(projectsDir);
+				childStat = statSync(childDir);
 			} catch {
 				continue;
 			}
-			for (const project of projects) {
-				if (project.startsWith(".")) continue;
-				const configDir = join(projectsDir, project, "config");
-				let configFiles;
-				try {
-					configFiles = readdirSync(configDir);
-				} catch {
-					continue;
-				}
-				for (const f of configFiles) if (f.endsWith(".yaml") || f.endsWith(".yml")) out.push(join(configDir, f));
-			}
+			if (!childStat.isDirectory()) continue;
+			out.push(childDir);
+		}
+	}
+	return out;
+}
+function auditAgentEnvPermissions(cwd) {
+	if (isWindows()) return {
+		status: "skip-platform",
+		reason: "win32-mode-bits-not-portable"
+	};
+	const items = [];
+	let aggregate = "ok";
+	for (const agentDir of listAgentDirs(cwd)) {
+		const envPath = join(agentDir, ".env");
+		let st;
+		try {
+			st = statSync(envPath);
+		} catch {
+			continue;
+		}
+		if (!st.isFile()) continue;
+		const modeBits = st.mode & 511;
+		const mode = formatMode(st.mode);
+		const agentPath = relative(cwd, agentDir);
+		const cls = classifyAgentEnvMode(modeBits);
+		if (cls === "ok") items.push({
+			status: "ok",
+			agentPath,
+			envPath,
+			mode
+		});
+		else if (cls === "warn") {
+			items.push({
+				status: "warn",
+				agentPath,
+				envPath,
+				mode,
+				expected: "0600",
+				autoFixable: true
+			});
+			if (aggregate === "ok") aggregate = "warn";
+		} else {
+			items.push({
+				status: "fail",
+				agentPath,
+				envPath,
+				mode,
+				expected: "0600",
+				autoFixable: true
+			});
+			aggregate = "fail";
+		}
+	}
+	return {
+		status: aggregate,
+		items
+	};
+}
+const VAR_REF_RE = /\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g;
+function extractVarRefs(content) {
+	const out = /* @__PURE__ */ new Map();
+	const lines = content.split(/\r?\n/);
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		for (const m of line.matchAll(VAR_REF_RE)) {
+			const key = m[1] ?? m[2] ?? "";
+			if (key.length === 0) continue;
+			const list = out.get(key);
+			if (list) list.push(i + 1);
+			else out.set(key, [i + 1]);
 		}
 	}
 	return out;
 }
+const SKIP_TOP = new Set([
+	"roster",
+	"node_modules",
+	"plans",
+	"spec",
+	"docs",
+	"bin",
+	"lib",
+	"skills",
+	"agents",
+	"templates",
+	"test",
+	"src",
+	"config",
+	"guidelines",
+	"logs",
+	"scripts"
+]);
+function collectConfigYamls(cwd) {
+	return listV1AgentPaths(cwd).map((rel) => join(cwd, rel, "config.yaml"));
+}
 const SHELL_VARS = new Set([
 	"HOME",
 	"PATH",
@@ -3528,20 +4103,203 @@ function auditPromptLeak(cwd, schedules) {
 		items
 	};
 }
+const AGENT_SEGMENT_RE = /^[a-z][a-z0-9-]*$/;
+function listV1AgentPaths(cwd) {
+	const out = [];
+	let topEntries;
+	try {
+		topEntries = readdirSync(cwd);
+	} catch {
+		return [];
+	}
+	for (const top of topEntries) {
+		if (top.startsWith(".")) continue;
+		if (SKIP_TOP.has(top)) continue;
+		if (!AGENT_SEGMENT_RE.test(top)) continue;
+		const fnDir = join(cwd, top);
+		let st;
+		try {
+			st = statSync(fnDir);
+		} catch {
+			continue;
+		}
+		if (!st.isDirectory()) continue;
+		const topCfg = join(fnDir, "config.yaml");
+		let topIsLeafAgent = false;
+		try {
+			if (statSync(topCfg).isFile()) {
+				out.push(top);
+				topIsLeafAgent = true;
+			}
+		} catch {}
+		if (topIsLeafAgent) continue;
+		let children;
+		try {
+			children = readdirSync(fnDir);
+		} catch {
+			continue;
+		}
+		for (const child of children) {
+			if (child.startsWith(".")) continue;
+			if (!AGENT_SEGMENT_RE.test(child)) continue;
+			const agentDir = join(fnDir, child);
+			let agentSt;
+			try {
+				agentSt = statSync(agentDir);
+			} catch {
+				continue;
+			}
+			if (!agentSt.isDirectory()) continue;
+			const cfg = join(agentDir, "config.yaml");
+			try {
+				if (statSync(cfg).isFile()) out.push(top + "/" + child);
+			} catch {
+				continue;
+			}
+		}
+	}
+	out.sort();
+	return out;
+}
+function auditAgentEnvRefs(cwd) {
+	const errors = [];
+	const warns = [];
+	for (const agent of listV1AgentPaths(cwd)) {
+		const loaded = loadAgentConfig(cwd, agent);
+		if (!loaded.ok) continue;
+		const tools = loaded.config.tools ?? {};
+		const resolved = resolveAgentEnv(cwd, agent);
+		for (const [binding, t] of Object.entries(tools)) {
+			if (Object.prototype.hasOwnProperty.call(resolved, t.env_var)) continue;
+			const miss = {
+				agent,
+				binding,
+				key: t.env_var,
+				required: t.required
+			};
+			if (t.required) errors.push(miss);
+			else warns.push(miss);
+		}
+	}
+	return {
+		status: errors.length > 0 ? "fail" : warns.length > 0 ? "warn" : "ok",
+		errors,
+		warns
+	};
+}
 function runSecretsAudit(opts) {
 	const envPermissions = auditEnvPermissions(opts.cwd);
+	const agentEnvPermissions = auditAgentEnvPermissions(opts.cwd);
 	const envKeyReferences = auditEnvKeyReferences(opts.cwd);
 	const templateSecretLiterals = auditTemplateSecretLiterals(opts.rosterRoot);
 	const promptLeak = auditPromptLeak(opts.cwd, opts.schedules);
+	const agentEnvRefs = auditAgentEnvRefs(opts.cwd);
+	const agentEnvRedundancy = auditAgentEnvRedundancy(opts.cwd);
+	const envOk = envPermissions.status === "ok" || envPermissions.status === "absent" || envPermissions.status === "skip-platform";
+	const agentEnvOk = agentEnvPermissions.status !== "fail";
 	return {
-		ok: (envPermissions.status === "ok" || envPermissions.status === "absent" || envPermissions.status === "skip-platform") && envKeyReferences.status === "ok" && templateSecretLiterals.status === "ok",
+		ok: envOk && agentEnvOk && envKeyReferences.status === "ok" && templateSecretLiterals.status === "ok" && agentEnvRefs.errors.length === 0,
 		envPermissions,
+		agentEnvPermissions,
 		envKeyReferences,
 		templateSecretLiterals,
-		promptLeak
+		promptLeak,
+		agentEnvRefs,
+		agentEnvRedundancy
 	};
 }
 //#endregion
+//#region src/lib/agent-env-fix-prompt.ts
+async function confirmAndDeleteRedundantLines(items, cwd, deps, dryRun) {
+	const out = {
+		deleted: [],
+		failed: [],
+		skipped: [],
+		nonTtySkipped: false
+	};
+	if (items.length === 0) return out;
+	if (!deps.isTTY) {
+		out.nonTtySkipped = true;
+		return out;
+	}
+	let workspaceMap = /* @__PURE__ */ new Map();
+	try {
+		workspaceMap = parseEnvFile(readFileSync(join(cwd, ".env"), "utf8"));
+	} catch {}
+	const rl = createInterface({
+		input: deps.stdin,
+		output: deps.stdout,
+		terminal: false
+	});
+	let stdinClosed = false;
+	rl.once("close", () => {
+		stdinClosed = true;
+	});
+	try {
+		for (const item of items) {
+			const absPath = join(cwd, item.agentEnvPath);
+			const label = `${item.agentEnvPath}:${item.line} ${item.key}`;
+			if (stdinClosed) {
+				out.skipped.push(`${label}: stdin closed`);
+				continue;
+			}
+			deps.stdout.write(`Delete ${label}? [y/N] `);
+			const answer = await readOneLine(rl);
+			if (answer === null) {
+				stdinClosed = true;
+				out.skipped.push(`${label}: stdin closed`);
+				continue;
+			}
+			const normalized = answer.trim().toLowerCase();
+			if (normalized !== "y" && normalized !== "yes") {
+				out.skipped.push(label);
+				continue;
+			}
+			const expectedValue = workspaceMap.get(item.key);
+			if (expectedValue === void 0) {
+				out.failed.push({
+					what: label,
+					error: "workspace .env no longer declares this key"
+				});
+				continue;
+			}
+			const result = removeLineForKey(absPath, item.line, item.key, expectedValue, dryRun);
+			if (result.kind === "removed") out.deleted.push(`${label}: removed`);
+			else if (result.kind === "would-remove") out.deleted.push(`${label}: would remove (dry-run)`);
+			else if (result.kind === "changed") out.failed.push({
+				what: label,
+				error: `file changed (${result.reason})`
+			});
+			else out.failed.push({
+				what: label,
+				error: result.message
+			});
+		}
+	} finally {
+		rl.close();
+	}
+	return out;
+}
+function readOneLine(rl) {
+	return new Promise((resolve) => {
+		let settled = false;
+		const onLine = (line) => {
+			if (settled) return;
+			settled = true;
+			rl.off("close", onClose);
+			resolve(line);
+		};
+		const onClose = () => {
+			if (settled) return;
+			settled = true;
+			rl.off("line", onLine);
+			resolve(null);
+		};
+		rl.once("line", onLine);
+		rl.once("close", onClose);
+	});
+}
+//#endregion
 //#region src/lib/codex-preflight.ts
 function readAuthJson(codexHome) {
 	const authPath = join(codexHome, "auth.json");
@@ -4512,7 +5270,29 @@ function runSchedulingDriftAudit(opts) {
 }
 //#endregion
 //#region src/commands/doctor.ts
-function tildify$4(path) {
+function listSkillDirNames(target) {
+	try {
+		return readdirSync(target, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+	} catch {
+		return [];
+	}
+}
+function detectShadowCollisions(workspaceRoot) {
+	const collisions = [];
+	for (const userTool of allTools()) {
+		const projectTool = toolForScope(userTool, "project", workspaceRoot);
+		const userNames = new Set(listSkillDirNames(userTool.skillsTarget));
+		const projectNames = listSkillDirNames(projectTool.skillsTarget);
+		for (const name of projectNames) if (userNames.has(name)) collisions.push({
+			tool: userTool.key,
+			skillName: name,
+			userPath: join(userTool.skillsTarget, name),
+			projectPath: join(projectTool.skillsTarget, name)
+		});
+	}
+	return collisions;
+}
+function tildify$3(path) {
 	const home = homedir();
 	return path.startsWith(home) ? "~" + path.slice(home.length) : path;
 }
@@ -4553,7 +5333,7 @@ function workspaceLabel(status) {
 function renderSchedulingSection(report) {
 	if (report.files.length === 0) return [];
 	const lines = [""];
-	lines.push(`Scheduling  ${tildify$4(report.cwd)}`);
+	lines.push(`Scheduling  ${tildify$3(report.cwd)}`);
 	for (const file of report.files) if (file.status === "pass") {
 		const entryWord = file.entryCount === 1 ? "entry" : "entries";
 		lines.push(`  ${chalk.green("✓")} ${file.relativePath}   ${chalk.dim("OK")} ${chalk.dim(`(${file.entryCount} ${entryWord})`)}`);
@@ -4566,7 +5346,7 @@ function renderSchedulingSection(report) {
 function renderWorkspaceSection(audit) {
 	if (!audit.contextMdExists && audit.items.length === 0) return [];
 	const lines = [""];
-	lines.push(`Workspace  ${tildify$4(audit.cwd)}`);
+	lines.push(`Workspace  ${tildify$3(audit.cwd)}`);
 	if (audit.contextMdExists) lines.push(`  ${chalk.green("✓")} CONTEXT.md   ${chalk.dim("present")}`);
 	else lines.push(`  ${chalk.red("✗")} CONTEXT.md   ${chalk.red("MISSING")}`);
 	for (const item of audit.items) {
@@ -4593,7 +5373,7 @@ const NO_FIX_REQUESTED = Object.freeze({
 	fixed: [],
 	failed: []
 });
-function runFixes(cwd, workspace, envPerms, dryRun = false) {
+function runFixes(cwd, workspace, envPerms, agentEnvPerms, dryRun = false) {
 	const fixed = [];
 	const failed = [];
 	const applied = true;
@@ -4630,12 +5410,142 @@ function runFixes(cwd, workspace, envPerms, dryRun = false) {
 			error: err.message
 		});
 	}
+	if (agentEnvPerms.status === "warn" || agentEnvPerms.status === "fail") for (const item of agentEnvPerms.items) {
+		if (item.status === "ok") continue;
+		const label = `${item.agentPath}/.env`;
+		if (dryRun) {
+			fixed.push(`${label}: would chmod 0600`);
+			continue;
+		}
+		try {
+			chmodSync(item.envPath, 384);
+			fixed.push(`${label}: chmod 0600`);
+		} catch (err) {
+			failed.push({
+				what: label,
+				error: err.message
+			});
+		}
+	}
 	return {
 		applied,
 		fixed,
 		failed
 	};
 }
+function uniqueKeysFromRefs(refs) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const m of [...refs.errors, ...refs.warns]) {
+		const list = byKey.get(m.key);
+		if (list) list.push(m);
+		else byKey.set(m.key, [m]);
+	}
+	return Array.from(byKey.entries()).sort(([a], [b]) => a.localeCompare(b)).map(([key, refs]) => ({
+		key,
+		refs
+	}));
+}
+function appendKeysToEnvFile(cwd, keys) {
+	const envPath = join(cwd, ".env");
+	const added = [];
+	const skipped = [];
+	let existing = "";
+	let hadFile = false;
+	try {
+		existing = readFileSync(envPath, "utf8");
+		hadFile = true;
+	} catch {}
+	let existingKeys = /* @__PURE__ */ new Set();
+	try {
+		existingKeys = new Set(parseEnvKeys(existing));
+	} catch {}
+	const newLines = [];
+	for (const key of keys) {
+		if (existingKeys.has(key)) {
+			skipped.push(key);
+			continue;
+		}
+		newLines.push(`${key}=`);
+		added.push(key);
+	}
+	if (newLines.length === 0) return {
+		added,
+		skipped
+	};
+	let body = existing;
+	if (body.length > 0 && !body.endsWith("\n")) body += "\n";
+	body += newLines.join("\n") + "\n";
+	writeFileSync(envPath, body, { encoding: "utf8" });
+	if (!hadFile && !isWindows()) try {
+		chmodSync(envPath, 384);
+	} catch {}
+	return {
+		added,
+		skipped
+	};
+}
+async function defaultAgentEnvPrompt(uniqueKeys) {
+	const { checkbox } = await import("@inquirer/prompts");
+	return checkbox({
+		message: "Select env keys to append to /.env (empty value — fill in after):",
+		choices: uniqueKeys.map(({ key, refs }) => {
+			return {
+				value: key,
+				name: `${key}  ${refs.some((r) => r.required) ? "(required)" : "(optional)"}  ← ${refs.map((r) => r.agent).join(", ")}`
+			};
+		})
+	});
+}
+async function applyAgentEnvFix(cwd, refs, opts) {
+	const fixed = [];
+	const failed = [];
+	const uniqueKeys = uniqueKeysFromRefs(refs);
+	if (uniqueKeys.length === 0) return {
+		fixed,
+		failed
+	};
+	if (opts.dryRun) {
+		for (const { key, refs: agents } of uniqueKeys) {
+			const agentList = agents.map((r) => r.agent).join(", ");
+			fixed.push(`/.env: would append ${key}= ${chalk.dim(`(referenced by ${agentList})`)}`);
+		}
+		return {
+			fixed,
+			failed
+		};
+	}
+	let selected;
+	try {
+		selected = await (opts.prompt ?? defaultAgentEnvPrompt)(uniqueKeys);
+	} catch (err) {
+		failed.push({
+			what: "/.env (interactive prompt)",
+			error: err.message
+		});
+		return {
+			fixed,
+			failed
+		};
+	}
+	if (selected.length === 0) return {
+		fixed,
+		failed
+	};
+	try {
+		const { added, skipped } = appendKeysToEnvFile(cwd, selected);
+		for (const k of added) fixed.push(`/.env: appended ${k}=`);
+		for (const k of skipped) fixed.push(`/.env: ${k} already present (skipped)`);
+	} catch (err) {
+		failed.push({
+			what: "/.env",
+			error: err.message
+		});
+	}
+	return {
+		fixed,
+		failed
+	};
+}
 function renderFixSection(outcome) {
 	if (!outcome.applied) return [];
 	if (outcome.fixed.length === 0 && outcome.failed.length === 0) return [];
@@ -4707,10 +5617,15 @@ function renderSafetySection(audit) {
 }
 function renderSecretsSection(audit) {
 	const env = audit.envPermissions;
+	const agentEnv = audit.agentEnvPermissions;
 	const refs = audit.envKeyReferences;
 	const templates = audit.templateSecretLiterals;
 	const leak = audit.promptLeak;
-	if ((env.status === "absent" || env.status === "skip-platform") && refs.status === "ok" && templates.status === "ok" && leak.status === "ok") return [];
+	const agentRefs = audit.agentEnvRefs;
+	const redundancy = audit.agentEnvRedundancy;
+	const noEnv = env.status === "absent" || env.status === "skip-platform";
+	const agentEnvClean = agentEnv.status === "skip-platform" || agentEnv.status === "ok" && agentEnv.items.length === 0;
+	if (noEnv && agentEnvClean && refs.status === "ok" && templates.status === "ok" && leak.status === "ok" && agentRefs.status === "ok" && redundancy.status === "ok") return [];
 	const lines = [""];
 	lines.push(chalk.bold("Secrets"));
 	if (env.status === "ok") lines.push(`  ${chalk.green("✓")} .env permissions  ${chalk.dim("OK")} ${chalk.dim(`(${env.mode})`)}`);
@@ -4718,6 +5633,28 @@ function renderSecretsSection(audit) {
 		lines.push(`  ${chalk.red("✗")} .env permissions  ${chalk.red("FAIL")} ${chalk.dim(`(got ${env.mode}, expected ${env.expected})`)}`);
 		lines.push(`      ${chalk.dim("→ Run `roster doctor --fix` to chmod 0600.")}`);
 	} else if (env.status === "skip-platform") lines.push(`  ${chalk.dim("-")} .env permissions  ${chalk.dim("SKIPPED")} ${chalk.dim("(windows mode bits not portable)")}`);
+	if (agentEnv.status === "ok" && agentEnv.items.length > 0) lines.push(`  ${chalk.green("✓")} agent .env perms  ${chalk.dim("OK")} ${chalk.dim(`(${agentEnv.items.length} agent .env${agentEnv.items.length === 1 ? "" : "s"})`)}`);
+	else if (agentEnv.status === "warn") {
+		const warnCount = agentEnv.items.filter((i) => i.status === "warn").length;
+		lines.push(`  ${chalk.yellow("!")} agent .env perms  ${chalk.yellow("WARN")} ${chalk.dim(`(${warnCount} agent .env${warnCount === 1 ? "" : "s"} not 0600)`)}`);
+		for (const item of agentEnv.items.slice(0, 10)) {
+			if (item.status === "ok") continue;
+			lines.push(`      ${chalk.yellow("-")} ${item.agentPath}/.env ${chalk.dim(`(got ${item.mode}, expected 0600)`)}`);
+		}
+		lines.push(`      ${chalk.dim("→ Run `roster doctor --fix` to chmod 0600.")}`);
+	} else if (agentEnv.status === "fail") {
+		const failCount = agentEnv.items.filter((i) => i.status === "fail").length;
+		const warnCount = agentEnv.items.filter((i) => i.status === "warn").length;
+		const detail = failCount === 1 ? "1 world-writable" : `${failCount} world-writable`;
+		const extra = warnCount > 0 ? `, ${warnCount} other not 0600` : "";
+		lines.push(`  ${chalk.red("✗")} agent .env perms  ${chalk.red("FAIL")} ${chalk.dim(`(${detail}${extra})`)}`);
+		for (const item of agentEnv.items.slice(0, 10)) {
+			if (item.status === "ok") continue;
+			const marker = item.status === "fail" ? chalk.red("-") : chalk.yellow("-");
+			lines.push(`      ${marker} ${item.agentPath}/.env ${chalk.dim(`(got ${item.mode}, expected 0600)`)}`);
+		}
+		lines.push(`      ${chalk.dim("→ Run `roster doctor --fix` to chmod 0600.")}`);
+	} else if (agentEnv.status === "skip-platform") lines.push(`  ${chalk.dim("-")} agent .env perms  ${chalk.dim("SKIPPED")} ${chalk.dim("(windows mode bits not portable)")}`);
 	if (refs.status === "fail") {
 		lines.push(`  ${chalk.red("✗")} env-key refs       ${chalk.red("FAIL")} ${chalk.dim(`(${refs.missing.length} unreferenced)`)}`);
 		for (const m of refs.missing.slice(0, 10)) {
@@ -4733,6 +5670,28 @@ function renderSecretsSection(audit) {
 		lines.push(`  ${chalk.yellow("!")} prompt-leak       ${chalk.yellow("WARN")} ${chalk.dim(`(${leak.items.length} reference${leak.items.length === 1 ? "" : "s"})`)}`);
 		for (const item of leak.items.slice(0, 5)) lines.push(`      ${chalk.yellow("-")} ${item.schedule}: ${item.reference} ${chalk.dim("in " + item.file + ":" + item.line)}`);
 	}
+	if (agentRefs.status === "fail" || agentRefs.status === "warn") {
+		const e = agentRefs.errors.length;
+		const w = agentRefs.warns.length;
+		const counts = [];
+		if (e > 0) counts.push(`${e} error${e === 1 ? "" : "s"}`);
+		if (w > 0) counts.push(`${w} warn${w === 1 ? "" : "s"}`);
+		const tag = agentRefs.status === "fail" ? chalk.red("FAIL") : chalk.yellow("WARN");
+		const symbol = agentRefs.status === "fail" ? chalk.red("✗") : chalk.yellow("!");
+		lines.push(`  ${symbol} agent-env-refs    ${tag} ${chalk.dim(`(${counts.join(", ")})`)}`);
+		for (const m of agentRefs.errors.slice(0, 10)) lines.push(`      ${chalk.red("-")} ${m.agent}: ${m.key} ${chalk.dim(`(tools.${m.binding}, required)`)}`);
+		if (agentRefs.errors.length > 10) lines.push(`      ${chalk.dim(`… (${agentRefs.errors.length - 10} more errors)`)}`);
+		for (const m of agentRefs.warns.slice(0, 5)) lines.push(`      ${chalk.yellow("-")} ${m.agent}: ${m.key} ${chalk.dim(`(tools.${m.binding}, optional)`)}`);
+		if (agentRefs.warns.length > 5) lines.push(`      ${chalk.dim(`… (${agentRefs.warns.length - 5} more warns)`)}`);
+		if (e > 0 || w > 0) lines.push(`      ${chalk.dim("→ Run `roster doctor --fix` to append missing keys to /.env.")}`);
+	}
+	if (redundancy.status === "warn") {
+		const n = redundancy.items.length;
+		lines.push(`  ${chalk.yellow("!")} agent .env redundancy  ${chalk.yellow("WARN")} ${chalk.dim(`(${n} entr${n === 1 ? "y" : "ies"})`)}`);
+		for (const item of redundancy.items.slice(0, 10)) lines.push(`      ${chalk.yellow("-")} ${item.agentEnvPath}:${item.line}  ${item.key} ${chalk.dim("matches workspace .env")}`);
+		if (n > 10) lines.push(`      ${chalk.dim(`… (${n - 10} more)`)}`);
+		lines.push(`      ${chalk.dim("→ Run `roster doctor --fix` to prompt removal of redundant lines.")}`);
+	}
 	return lines;
 }
 function renderStaleFiresSection(stale) {
@@ -4774,12 +5733,13 @@ function renderSchedulingDriftSection(audit) {
 	}
 	return lines;
 }
-function renderText$1(results, summary, workarounds) {
+function renderText$1(results, summary, workarounds, scope) {
 	const lines = [""];
 	lines.push(chalk.bold("roster doctor"));
+	lines.push(chalk.dim(`Install scope: ${scope} (${scope === "project" ? "workspace-local" : "home directory"})`));
 	for (const r of results) {
 		lines.push("");
-		lines.push(`${chalk.bold(r.toolName)} ${chalk.dim(tildify$4(r.configRoot))}`);
+		lines.push(`${chalk.bold(r.toolName)} ${chalk.dim(tildify$3(r.configRoot))}`);
 		for (const item of r.items) {
 			const kindCol = chalk.dim(item.kind.padEnd(5));
 			const nameCol = item.name.padEnd(22);
@@ -4803,8 +5763,38 @@ function renderText$1(results, summary, workarounds) {
 	}
 	return lines;
 }
-function executeDoctor(opts) {
-	const detected = detectTools();
+function renderShadowSection(shadows) {
+	if (shadows.length === 0) return [];
+	const lines = [""];
+	lines.push(chalk.bold("Shadow collisions") + chalk.dim(` (${shadows.length})`));
+	lines.push(chalk.dim("  Same skill installed at both scopes. The user-scope copy wins;"));
+	lines.push(chalk.dim("  the workspace skill is silently ignored. Remove one."));
+	for (const s of shadows) {
+		lines.push(`  ${chalk.yellow("!")} ${chalk.bold(s.skillName)} ${chalk.dim("(")}${s.tool}${chalk.dim(")")}`);
+		lines.push(`      user:    ${tildify$3(s.userPath)}`);
+		lines.push(`      project: ${s.projectPath}`);
+	}
+	return lines;
+}
+function renderInteractiveFixSection(outcome) {
+	if (!(outcome.deleted.length > 0 || outcome.failed.length > 0 || outcome.skipped.length > 0 || outcome.nonTtySkipped)) return [];
+	const lines = [""];
+	lines.push(chalk.bold("agent .env redundancy --fix"));
+	if (outcome.nonTtySkipped) {
+		lines.push(`  ${chalk.dim("-")} skipped — re-run \`roster doctor --fix\` in an interactive terminal`);
+		return lines;
+	}
+	for (const f of outcome.deleted) lines.push(`  ${chalk.green("✓")} ${f}`);
+	for (const f of outcome.skipped) lines.push(`  ${chalk.dim("-")} ${f}: kept`);
+	for (const f of outcome.failed) lines.push(`  ${chalk.red("✗")} ${f.what}: ${f.error}`);
+	return lines;
+}
+async function executeDoctor(opts) {
+	const workspaceExists = detectWorkspace(opts.cwd);
+	const effectiveScope = opts.scope ?? defaultScopeForContext(workspaceExists);
+	const userScopeTools = detectTools();
+	const detected = effectiveScope === "project" ? allTools().map((t) => toolForScope(t, "project", opts.cwd)).filter((t) => existsSync(t.configRoot)) : userScopeTools;
+	const shadows = workspaceExists ? detectShadowCollisions(opts.cwd) : [];
 	const sources = {
 		skills: join(ROSTER_ROOT, "skills"),
 		agents: join(ROSTER_ROOT, "agents")
@@ -4837,11 +5827,8 @@ function executeDoctor(opts) {
 	const workarounds = computeWorkarounds(results);
 	let workspaceFinal = workspace;
 	const initialEnvPerms = auditEnvPermissions(opts.cwd);
+	const initialAgentEnvPerms = auditAgentEnvPermissions(opts.cwd);
 	let fixOutcome = NO_FIX_REQUESTED;
-	if (opts.fix) {
-		fixOutcome = runFixes(opts.cwd, workspace, initialEnvPerms, opts.dryRun);
-		if (!opts.dryRun && fixOutcome.fixed.length > 0) workspaceFinal = auditWorkspace(opts.cwd);
-	}
 	const schedulesForLeak = listAllScheduleEntries(opts.cwd);
 	const codexHomeOverride = process.env["ROSTER_CODEX_HOME"];
 	const safety = runSafetyAudit({
@@ -4852,20 +5839,70 @@ function executeDoctor(opts) {
 		env: process.env,
 		...codexHomeOverride !== void 0 && codexHomeOverride !== "" ? { codexHome: codexHomeOverride } : {}
 	});
-	const secrets = runSecretsAudit({
+	const initialSecrets = runSecretsAudit({
 		cwd: opts.cwd,
 		rosterRoot: ROSTER_ROOT,
 		schedules: schedulesForLeak
 	});
+	if (opts.fix) {
+		fixOutcome = runFixes(opts.cwd, workspace, initialEnvPerms, initialAgentEnvPerms, opts.dryRun);
+		const refs = initialSecrets.agentEnvRefs;
+		const anyMissing = refs.errors.length > 0 || refs.warns.length > 0;
+		const canInteract = !opts.json && process.stdin.isTTY === true;
+		if (anyMissing) if (opts.dryRun) {
+			const out = await applyAgentEnvFix(opts.cwd, refs, { dryRun: true });
+			fixOutcome.fixed.push(...out.fixed);
+			fixOutcome.failed.push(...out.failed);
+		} else if (canInteract) {
+			const out = await applyAgentEnvFix(opts.cwd, refs, { dryRun: false });
+			fixOutcome.fixed.push(...out.fixed);
+			fixOutcome.failed.push(...out.failed);
+		} else {
+			const reason = opts.json ? "interactive prompt suppressed under --json" : "no TTY (non-interactive shell)";
+			fixOutcome.failed.push({
+				what: "/.env (agent-env-refs)",
+				error: `--fix skipped: ${reason}. Rerun in an interactive shell to append missing keys.`
+			});
+		}
+		if (!opts.dryRun && fixOutcome.fixed.length > 0) workspaceFinal = auditWorkspace(opts.cwd);
+	}
+	const secrets = opts.fix && !opts.dryRun && fixOutcome.fixed.length > 0 ? runSecretsAudit({
+		cwd: opts.cwd,
+		rosterRoot: ROSTER_ROOT,
+		schedules: schedulesForLeak
+	}) : initialSecrets;
 	const schedulingDrift = runSchedulingDriftAudit({
 		cwd: opts.cwd,
 		homeDir: home
 	});
 	const allOk = results.every((r) => r.ok) && workspaceFinal.ok && scheduling.ok && safety.ok && secrets.ok && schedulingDrift.ok;
+	if (!opts.json && !opts.silent) {
+		for (const line of renderText$1(results, summary, workarounds, effectiveScope)) console.log(line);
+		for (const line of renderShadowSection(shadows)) console.log(line);
+		for (const line of renderWorkspaceSection(workspaceFinal)) console.log(line);
+		for (const line of renderSchedulingSection(scheduling)) console.log(line);
+		for (const line of renderSchedulingDriftSection(schedulingDrift)) console.log(line);
+		for (const line of renderStaleFiresSection(schedulingDrift.staleFires)) console.log(line);
+		for (const line of renderSafetySection(safety)) console.log(line);
+		for (const line of renderSecretsSection(secrets)) console.log(line);
+		for (const line of renderFixSection(fixOutcome)) console.log(line);
+	}
+	let interactiveOutcome = null;
+	if (opts.fix && secrets.agentEnvRedundancy.items.length > 0) {
+		const isTTY = !opts.silent && !opts.json && (process.stdin.isTTY ?? false);
+		interactiveOutcome = await confirmAndDeleteRedundantLines(secrets.agentEnvRedundancy.items, opts.cwd, {
+			isTTY,
+			stdin: process.stdin,
+			stdout: process.stdout
+		}, opts.dryRun);
+		if (!opts.json && !opts.silent) for (const line of renderInteractiveFixSection(interactiveOutcome)) console.log(line);
+	}
 	if (opts.json) {
 		const payload = {
 			ok: allOk,
 			rosterVersion: getPackageVersion(),
+			scope: effectiveScope,
+			shadows,
 			tools: results,
 			summary,
 			workspace: workspaceFinal,
@@ -4874,20 +5911,11 @@ function executeDoctor(opts) {
 			safety,
 			secrets,
 			scheduling_drift: schedulingDrift,
-			fix: fixOutcome
+			fix: fixOutcome,
+			interactive_fix: interactiveOutcome
 		};
 		console.log(JSON.stringify(payload, null, 2));
-	} else if (!opts.silent) {
-		for (const line of renderText$1(results, summary, workarounds)) console.log(line);
-		for (const line of renderWorkspaceSection(workspaceFinal)) console.log(line);
-		for (const line of renderSchedulingSection(scheduling)) console.log(line);
-		for (const line of renderSchedulingDriftSection(schedulingDrift)) console.log(line);
-		for (const line of renderStaleFiresSection(schedulingDrift.staleFires)) console.log(line);
-		for (const line of renderSafetySection(safety)) console.log(line);
-		for (const line of renderSecretsSection(secrets)) console.log(line);
-		for (const line of renderFixSection(fixOutcome)) console.log(line);
-		if (opts.dryRun) console.log(chalk.dim(opts.fix ? "--dry-run: nothing applied; lines above are what `--fix` would have done." : "--dry-run: read-only audit; pass `--fix` to preview repairs."));
-	}
+	} else if (!opts.silent && opts.dryRun) console.log(chalk.dim(opts.fix ? "--dry-run: nothing applied; lines above are what `--fix` would have done." : "--dry-run: read-only audit; pass `--fix` to preview repairs."));
 	return allOk ? 0 : 1;
 }
 //#endregion
@@ -5152,7 +6180,7 @@ function buildListReport(cwd, now = /* @__PURE__ */ new Date()) {
 		warnings
 	};
 }
-function tildify$3(path) {
+function tildify$2(path) {
 	return path;
 }
 function fmtTs$1(d) {
@@ -5169,7 +6197,7 @@ function lastStatusCell(row) {
 function renderListText(report) {
 	const lines = [""];
 	lines.push(chalk.bold("roster schedule list"));
-	lines.push(chalk.dim(`cwd: ${tildify$3(report.cwd)}`));
+	lines.push(chalk.dim(`cwd: ${tildify$2(report.cwd)}`));
 	if (report.rows.length === 0) {
 		lines.push("");
 		lines.push(chalk.dim("(no schedules registered)"));
@@ -5911,7 +6939,7 @@ async function executeRun(opts) {
 //#endregion
 //#region src/commands/schedule.ts
 const READONLY_DRYRUN_LINE = chalk.dim("--dry-run: read-only command; nothing would be written.");
-function tildify$2(path) {
+function tildify$1(path) {
 	const home = homedir();
 	return path.startsWith(home) ? "~" + path.slice(home.length) : path;
 }
@@ -5921,7 +6949,7 @@ function countTotalErrors(report) {
 function renderText(report) {
 	const lines = [""];
 	lines.push(chalk.bold("roster schedule validate"));
-	lines.push(chalk.dim(`cwd: ${tildify$2(report.cwd)}`));
+	lines.push(chalk.dim(`cwd: ${tildify$1(report.cwd)}`));
 	if (report.files.length === 0) {
 		lines.push("");
 		lines.push(chalk.dim("No roster/<function>/schedules.yaml files found."));
@@ -6592,14 +7620,14 @@ function installHook(host) {
 }
 //#endregion
 //#region src/commands/hooks.ts
-function tildify$1(path) {
+function tildify(path) {
 	const home = homedir();
 	return path.startsWith(home) ? "~" + path.slice(home.length) : path;
 }
 function summarize(result) {
 	const hostLabel = result.host === "claude" ? "Claude Code" : "Codex CLI";
-	if (result.status === "installed") return `${chalk.green("✓")} ${chalk.bold(hostLabel)} — SessionStart hook → ${tildify$1(result.configFile)}`;
-	if (result.status === "already-present") return `${chalk.dim("·")} ${chalk.bold(hostLabel)} — SessionStart hook already installed (${tildify$1(result.configFile)})`;
+	if (result.status === "installed") return `${chalk.green("✓")} ${chalk.bold(hostLabel)} — SessionStart hook → ${tildify(result.configFile)}`;
+	if (result.status === "already-present") return `${chalk.dim("·")} ${chalk.bold(hostLabel)} — SessionStart hook already installed (${tildify(result.configFile)})`;
 	return `${chalk.yellow("⚠")} ${chalk.bold(hostLabel)} — skipped: ${result.reason ?? "host not detected"}`;
 }
 function hostsForTarget(target) {
@@ -7763,9 +8791,12 @@ const SUBCOMMANDS = new Set([
 	"migrate",
 	"pending"
 ]);
-function tildify(path) {
+function displayPath(path, cwd) {
 	const home = homedir();
-	return path.startsWith(home) ? "~" + path.slice(home.length) : path;
+	if (path.startsWith(home)) return "~" + path.slice(home.length);
+	const rel = relative(cwd, path);
+	if (!rel.startsWith("..") && !rel.startsWith("/")) return "./" + rel;
+	return path;
 }
 function printBanner(version) {
 	console.log();
@@ -7798,8 +8829,10 @@ function printHelp(version) {
 		`  -v, --version                ${chalk.dim("Print version and exit")}`,
 		`  --silent                     ${chalk.dim("Suppress non-error output (install)")}`,
 		`  --verbose                    ${chalk.dim("Log each file path written (install)")}`,
-		`  --all                        ${chalk.dim("Install to every detected tool (install)")}`,
-		`  --tool <name>                ${chalk.dim("Install to a single tool: claude | codex | gemini (install)")}`,
+		`  --all                        ${chalk.dim("Install to every detected tool (alias of --tool all) (install)")}`,
+		`  --tool <name[,name...]>      ${chalk.dim("Install to one or more tools: claude | codex | gemini (install)")}`,
+		`  --scope <project|user>       ${chalk.dim("Install at workspace-local or home-dir scope (install)")}`,
+		`  --yes, -y                    ${chalk.dim("Skip prompts; use safe defaults (install)")}`,
 		`  --tool <name>                ${chalk.dim("Required scheduler tool: claude | codex (schedule install)")}`,
 		`  --migrate                    ${chalk.dim("Upgrade pre-CONTEXT.md workspace, preserving CLAUDE.md content (init)")}`,
 		`  --json                       ${chalk.dim("Emit machine-readable JSON (doctor, schedule validate)")}`,
@@ -7835,23 +8868,28 @@ function toolHints(tools) {
 		installLink: t.installLink
 	}));
 }
-function summarizeInstall(tool, result) {
-	const skillsLine = `${result.skillsCount} skills → ${tildify(result.skillsTarget)}`;
-	const agentsLine = result.agentsTarget ? `${result.agentsCount} agents → ${tildify(result.agentsTarget)}` : `${result.agentsCount} agents → (n/a)`;
+function summarizeInstall(tool, result, cwd) {
+	const skillsLine = `${result.skillsCount} skills → ${displayPath(result.skillsTarget, cwd)}`;
+	const agentsLine = result.agentsTarget ? `${result.agentsCount} agents → ${displayPath(result.agentsTarget, cwd)}` : `${result.agentsCount} agents → (n/a)`;
 	return `${chalk.green("✓")} ${chalk.bold(tool.name)} — ${skillsLine}, ${agentsLine}`;
 }
-async function promptForTools(detected) {
-	if (detected.length === 1) return detected;
+async function promptForTools(detected, undetected) {
+	if (detected.length === 1 && undetected.length === 0) return detected;
 	const { checkbox, confirm } = await import("@inquirer/prompts");
+	const choices = [...detected.map((t) => ({
+		name: t.name,
+		value: t.key,
+		checked: true
+	})), ...undetected.map((t) => ({
+		name: t.name,
+		value: t.key,
+		disabled: "(not detected)"
+	}))];
 	let selectedKeys;
 	try {
 		selectedKeys = await checkbox({
 			message: "Install roster into which AI tools?",
-			choices: detected.map((t) => ({
-				name: t.name,
-				value: t.key,
-				checked: true
-			}))
+			choices
 		});
 	} catch {
 		return null;
@@ -7867,10 +8905,31 @@ async function promptForTools(detected) {
 			return null;
 		}
 		if (exitAnyway) return null;
-		return promptForTools(detected);
+		return promptForTools(detected, undetected);
 	}
 	return detected.filter((t) => selectedKeys.includes(t.key));
 }
+async function promptForScope(workspaceExists, cwd) {
+	const { select } = await import("@inquirer/prompts");
+	const projectHint = workspaceExists ? `workspace-local — skills land in ${displayPath(join(cwd, ".<tool>"), cwd)}/skills/` : "workspace-local — REQUIRES roster init (config/project.yaml not found here)";
+	try {
+		return await select({
+			message: "Install at which scope?",
+			choices: [{
+				name: "project",
+				value: "project",
+				description: projectHint
+			}, {
+				name: "user",
+				value: "user",
+				description: "home directory — skills land in ~/.<tool>/, visible to every Claude Code project on this machine"
+			}],
+			default: workspaceExists ? "project" : "user"
+		});
+	} catch {
+		return null;
+	}
+}
 async function runInstall(args) {
 	const parsed = parseInstallArgs(args);
 	if (parsed.kind === "err") throw new RosterError({
@@ -7879,39 +8938,58 @@ async function runInstall(args) {
 		remedy: `  Run ${chalk.bold("roster --help")} for usage.`,
 		exitCode: 1
 	});
-	const { silent, verbose, target } = parsed;
+	const { silent, verbose, yes, scope: requestedScope, target } = parsed;
 	const version = getPackageVersion();
 	if (!silent) printBanner(version);
+	const cwd = process.cwd();
+	const isTTY = process.stdin.isTTY === true;
+	const workspaceExists = detectWorkspace(cwd);
+	const nonInteractive = yes || !isTTY;
 	const detected = detectTools();
-	if (detected.length === 0) throw noToolsError(toolHints(allTools()));
 	let targetTools;
-	if (target.mode === "all") targetTools = detected;
-	else if (target.mode === "tool") {
-		const match = detected.find((t) => t.key === target.key);
-		if (!match) throw new RosterError({
-			header: `${chalk.red.bold("roster:")} ${target.key} not detected on this machine`,
-			body: `  --tool ${target.key} was requested, but no ${target.key} install was found.`,
-			remedy: `  Install it first, or omit ${chalk.bold("--tool")} to install to all detected tools.`,
-			exitCode: 3
-		});
-		targetTools = [match];
-	} else targetTools = await promptForTools(detected);
-	if (targetTools === null) throw userCancelledInstall();
+	if (target.mode === "all") {
+		if (detected.length === 0) throw noToolsError(toolHints(allTools()));
+		targetTools = detected;
+	} else if (target.mode === "tools") {
+		const detectedKeys = detected.map((t) => t.key);
+		if (target.keys.filter((k) => !detectedKeys.includes(k)).length > 0) throw toolsNotDetectedError(target.keys, detectedKeys);
+		targetTools = detected.filter((t) => target.keys.includes(t.key));
+	} else {
+		if (detected.length === 0) throw noToolsError(toolHints(allTools()));
+		if (nonInteractive) targetTools = detected;
+		else {
+			const picked = await promptForTools(detected, allTools().filter((t) => !detected.some((d) => d.key === t.key)));
+			if (picked === null) throw userCancelledInstall();
+			targetTools = picked;
+		}
+	}
+	let scope;
+	if (requestedScope !== null) scope = requestedScope;
+	else if (nonInteractive) scope = defaultScopeForContext(workspaceExists);
+	else {
+		const picked = await promptForScope(workspaceExists, cwd);
+		if (picked === null) throw userCancelledInstall();
+		scope = picked;
+	}
+	if (scope === "project" && !workspaceExists) throw workspaceRequiredError(cwd);
 	const skillsSrc = join(ROSTER_ROOT, "skills");
 	const agentsSrc = join(ROSTER_ROOT, "agents");
-	const confirmFn = target.mode !== "interactive" ? async () => false : void 0;
+	const confirmFn = nonInteractive ? async () => false : void 0;
 	for (const tool of targetTools) {
-		const result = await installToTool(tool, {
+		const scopedTool = scope === "project" ? toolForScope(tool, "project", cwd) : tool;
+		const result = await installToTool(scopedTool, {
 			skills: skillsSrc,
 			agents: agentsSrc,
 			silent: !verbose,
+			scope,
 			...confirmFn ? { confirm: confirmFn } : {}
 		});
-		if (!silent) console.log(summarizeInstall(tool, result));
+		if (!silent) console.log(summarizeInstall(scopedTool, result, cwd));
 	}
 	if (!silent) {
 		console.log();
-		console.log(`${chalk.dim("Next: ")}${chalk.bold("roster init")}${chalk.dim(" to scaffold a workspace.")}`);
+		if (scope === "project") console.log(`${chalk.dim("Next: ")}${chalk.bold("open Claude Code (or your AI tool) in this directory")}${chalk.dim(" — skills are workspace-local.")}`);
+		else console.log(`${chalk.dim("Next: ")}${chalk.bold("roster init")}${chalk.dim(" to scaffold a workspace, then re-run install at project scope.")}`);
 	}
 	return 0;
 }
@@ -8072,7 +9150,7 @@ async function runHooks(args) {
 		exitCode: 1
 	});
 }
-function runDoctor(args) {
+async function runDoctor(args) {
 	const parsed = parseDoctorArgs(args);
 	if (parsed.kind === "err") throw new RosterError({
 		header: `${chalk.red.bold("roster:")} ${parsed.message}`,
@@ -8080,12 +9158,13 @@ function runDoctor(args) {
 		remedy: `  Run ${chalk.bold("roster --help")} for usage.`,
 		exitCode: 1
 	});
-	const code = executeDoctor({
+	const code = await executeDoctor({
 		json: parsed.json,
 		silent: parsed.silent,
 		fix: parsed.fix,
 		dryRun: parsed.dryRun,
-		cwd: process.cwd()
+		cwd: process.cwd(),
+		scope: parsed.scope
 	});
 	if (code === 3 && !parsed.json) throw noToolsError(toolHints(allTools()));
 	return code;
@@ -8111,7 +9190,7 @@ async function main() {
 	if (isSubcommand(first)) {
 		if (first === "install") return runInstall(rest);
 		if (first === "init") return await runInit(rest);
-		if (first === "doctor") return runDoctor(rest);
+		if (first === "doctor") return await runDoctor(rest);
 		if (first === "schedule") return await runSchedule(rest);
 		if (first === "review") return await runReview(rest);
 		if (first === "hooks") return await runHooks(rest);