tunestra 0.4.0 → 0.6.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as VERSION } from "./src-Bh7d7ERC.mjs";
+import { t as VERSION } from "./src-DTrYA2yZ.mjs";
 import { Command } from "@commander-js/extra-typings";
 import pc from "picocolors";
 import { copyFile, lstat, mkdir, readFile, readdir, readlink, rename, rm, rmdir, stat, symlink, unlink, writeFile } from "node:fs/promises";
@@ -7,6 +7,7 @@ import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } fr
 import { glob } from "tinyglobby";
 import { prettifyError, z } from "zod";
 import { parse, stringify } from "yaml";
+import { homedir } from "node:os";
 import { downloadTemplate } from "giget";
 import { stringify as stringify$1 } from "smol-toml";
 import { createHash } from "node:crypto";
@@ -17,6 +18,10 @@ const PRESET_MANIFEST = "tunestra.preset.yaml";
 const PROJECT_CONFIG = "tunestra.yaml";
 /** Project artifacts: the same layout as a preset. */
 const PROJECT_DIR = ".tunestra";
+/** The personal level of a developer; it is not committed. */
+const LOCAL_CONFIG = "tunestra.local.yaml";
+/** Artifacts of the personal level: the same layout as a preset. */
+const LOCAL_DIR = ".tunestra.local";
 /** Main instructions of a level, and the index that tunestra generates. */
 const INSTRUCTIONS_FILE = "AGENTS.md";
 //#endregion
@@ -168,6 +173,7 @@ const Agent = {
 //#endregion
 //#region src/init/render-config.ts
 const EXTENDS_EXAMPLE = "#   - github:<owner>/<repo>/<path>#<ref>";
+const LOCAL_EXTENDS_EXAMPLE = "#   - ~/presets/me";
 /** The first tunestra.yaml of a project, with a hint when there are no presets yet. */
 function renderConfig(presets) {
 	const hasPresets = presets.length > 0;
@@ -181,6 +187,23 @@ function renderConfig(presets) {
 		""
 	].join("\n");
 }
+/** The first tunestra.local.yaml, with commented examples of what a personal level can do. */
+function renderLocalConfig(presets) {
+	const hasPresets = presets.length > 0;
+	const presetLines = presets.map((preset) => `  - ${JSON.stringify(preset)}`);
+	return [
+		"# Your personal level of tunestra: only for you, never committed.",
+		"# Personal presets with level: local, from general to specific:",
+		...hasPresets ? ["extends:", ...presetLines] : ["extends: []", LOCAL_EXTENDS_EXAMPLE],
+		"# exclude:",
+		"#   skills: [<skill>]",
+		"# env:",
+		"#   HTTPS_PROXY: http://localhost:3128",
+		"# permissions:",
+		"#   allow: [Bash(make *)]",
+		""
+	].join("\n");
+}
 //#endregion
 //#region src/init/run-init.ts
 const CLAUDE_FILE$1 = "CLAUDE.md";
@@ -251,30 +274,70 @@ async function moveFile(projectDir, from, to) {
 	await rename(fromPath, toPath);
 }
 //#endregion
+//#region src/init/run-init-local.ts
+const LOCAL_RULES_DIR = `${LOCAL_DIR}/rules`;
+/**
+* Creates the personal level in a project that already uses tunestra: tunestra.local.yaml
+* and `.tunestra.local/rules/` for the first personal rule.
+*/
+async function runInitLocal(projectDir, options) {
+	const configPath = join(projectDir, PROJECT_CONFIG);
+	const localPath = join(projectDir, LOCAL_CONFIG);
+	const rulesDir = join(projectDir, LOCAL_RULES_DIR);
+	const hasConfig = await checkExists(configPath);
+	const hasLocal = await checkExists(localPath);
+	const problems = [];
+	if (hasConfig === false) problems.push(`${PROJECT_CONFIG} not found. Run \`tunestra init\` first`);
+	if (hasLocal) problems.push(`${LOCAL_CONFIG} already exists`);
+	if (problems.length > 0) throw createProblemsError(problems);
+	const config = renderLocalConfig(options.presets);
+	await writeFile(localPath, config);
+	await mkdir(rulesDir, { recursive: true });
+	return {
+		steps: [`Created ${LOCAL_CONFIG}`, `Created ${LOCAL_RULES_DIR}/`],
+		warnings: []
+	};
+}
+//#endregion
 //#region src/cli/commands/init.ts
 async function describeInit(projectDir, options) {
-	const report = await runInit(projectDir, options);
-	const check = pc.green("✔");
-	const warningIcon = pc.yellow("⚠");
-	const steps = report.steps.map((step) => `${check} ${step}`);
-	const warnings = report.warnings.map((warning) => `${warningIcon} ${warning}`);
-	const nextStep = options.presets.length > 0 ? "Next: run tunestra setup." : "Next: add presets to extends in tunestra.yaml, then run tunestra setup.";
+	const report = options.local ? await runInitLocal(projectDir, options) : await runInit(projectDir, options);
+	const nextStep = describeNextStep(options);
 	return [
-		...steps,
-		...warnings,
+		...describeReport(report),
 		"",
 		nextStep
 	].join("\n");
 }
+function describeReport(report) {
+	const check = pc.green("✔");
+	const warningIcon = pc.yellow("⚠");
+	const steps = report.steps.map((step) => `${check} ${step}`);
+	const warnings = report.warnings.map((warning) => `${warningIcon} ${warning}`);
+	return [...steps, ...warnings];
+}
+function describeNextStep(options) {
+	const hasPresets = options.presets.length > 0;
+	if (options.local) return "Next: add your rules to .tunestra.local/ or presets to tunestra.local.yaml, then run tunestra setup. setup puts both in .gitignore.";
+	if (hasPresets) return "Next: run tunestra setup.";
+	return "Next: add presets to extends in tunestra.yaml, then run tunestra setup.";
+}
 //#endregion
 //#region src/shared/constants/levels.ts
-/** Levels of a shared preset, from specific to general. */
+/**
+* Levels of a preset, from specific to general. A `local` preset is personal: only the
+* personal level of a developer can extend it.
+*/
 const PresetLevel = {
+	Local: "local",
 	Team: "team",
 	Domain: "domain",
 	Base: "base"
 };
-/** Every level of the chain; the project is the most specific one. */
+/**
+* Every level of the chain. The project is the most specific shared level; the personal
+* `local` level of a developer comes after it.
+*/
 const Level = {
 	Project: "project",
 	...PresetLevel
@@ -284,6 +347,7 @@ const Level = {
 * so that agents read specific rules first: `10-project-architecture.md`.
 */
 const LEVEL_RANK = {
+	[Level.Local]: 0,
 	[Level.Project]: 10,
 	[Level.Team]: 20,
 	[Level.Domain]: 30,
@@ -350,6 +414,7 @@ const excludeSchema = z.strictObject({
 	skills: keys.optional(),
 	commands: keys.optional(),
 	mcp: keys.optional(),
+	subagents: keys.optional(),
 	env: keys.optional(),
 	/** Inherited `allow` and `ask` rules; a `deny` rule cannot be removed. */
 	permissions: keys.optional()
@@ -381,6 +446,15 @@ const projectConfigSchema = z.strictObject({
 	env: envSchema.default({}),
 	permissions: permissionsSchema.default({})
 });
+/** `tunestra.local.yaml`: a level like the project, without the list of agents. */
+const localConfigSchema = z.strictObject({
+	name: z.string().min(1).default("local"),
+	extends: z.array(z.string().min(1)).readonly().default([]),
+	exclude: excludeSchema.default({}),
+	overrides: overridesSchema.default({}),
+	env: envSchema.default({}),
+	permissions: permissionsSchema.default({})
+});
 const mcpServerSchema = z.strictObject({
 	description: z.string().optional(),
 	type: z.enum([
@@ -463,6 +537,15 @@ async function mapSettled(items, map) {
 	throw buildResultsError(results);
 }
 //#endregion
+//#region src/shared/constants/subagents.ts
+/** Reasoning effort of a subagent: the levels that both Claude Code and Codex accept. */
+const SubagentEffort = {
+	Low: "low",
+	Medium: "medium",
+	High: "high",
+	ExtraHigh: "xhigh"
+};
+//#endregion
 //#region src/shared/schemas/frontmatter.ts
 const ruleFrontmatterSchema = z.looseObject({ description: z.string().optional() });
 const skillFrontmatterSchema = z.looseObject({
@@ -470,6 +553,15 @@ const skillFrontmatterSchema = z.looseObject({
 	description: z.string().min(1)
 });
 const commandFrontmatterSchema = z.looseObject({ description: z.string().optional() });
+/** The model names differ between agents, so a subagent sets one for each agent. */
+const subagentModelSchema = z.partialRecord(z.enum(Agent), z.string().min(1));
+/** tunestra writes the files of the agents itself, so it knows every field here. */
+const subagentFrontmatterSchema = z.strictObject({
+	description: z.string().min(1),
+	model: subagentModelSchema.default({}),
+	effort: z.enum(SubagentEffort).optional(),
+	readOnly: z.boolean().default(false)
+});
 //#endregion
 //#region src/presets/frontmatter.ts
 /**
@@ -602,6 +694,28 @@ function findDuplicateSkills(skills, dir) {
 	return problems;
 }
 //#endregion
+//#region src/presets/artifacts/subagents.ts
+/** Subagents live in `agents/`, like in Claude Code and Codex. */
+async function loadSubagents(dir) {
+	return mapSettled(await listFiles(dir, "agents/*.md"), (source) => loadSubagent(dir, source));
+}
+async function loadSubagent(dir, source) {
+	const file = join(dir, source);
+	const { data, body } = parseFrontmatter(await readFile(file, "utf8"), file);
+	const frontmatter = validate(data, subagentFrontmatterSchema, `frontmatter in ${file}`);
+	const key = validate(basename(source, ".md"), skillName, `subagent file ${source}`);
+	if (body.trim().length > 0 === false) throw new TunestraError(`${file} has no instructions: write them after the frontmatter`);
+	return {
+		key,
+		source,
+		description: frontmatter.description,
+		model: frontmatter.model,
+		effort: frontmatter.effort,
+		readOnly: frontmatter.readOnly,
+		body
+	};
+}
+//#endregion
 //#region src/presets/artifacts/load-artifacts.ts
 /** Loads every kind of artifact at the same time and reports the problems of all of them. */
 async function loadArtifacts(dir, presetName) {
@@ -609,19 +723,22 @@ async function loadArtifacts(dir, presetName) {
 	const skillsLoading = loadSkills(dir);
 	const commandsLoading = loadCommands(dir);
 	const mcpLoading = loadMcpServers(dir);
+	const subagentsLoading = loadSubagents(dir);
 	const results = await Promise.allSettled([
 		rulesLoading,
 		skillsLoading,
 		commandsLoading,
-		mcpLoading
+		mcpLoading,
+		subagentsLoading
 	]);
 	if (isEveryFulfilled(results) === false) throw buildResultsError(results);
-	const [rulesResult, skillsResult, commandsResult, mcpResult] = results;
+	const [rulesResult, skillsResult, commandsResult, mcpResult, subagentsResult] = results;
 	return {
 		rules: rulesResult.value,
 		skills: skillsResult.value,
 		commands: commandsResult.value,
-		mcp: mcpResult.value
+		mcp: mcpResult.value,
+		subagents: subagentsResult.value
 	};
 }
 //#endregion
@@ -657,12 +774,12 @@ const PermissionDecision = {
 };
 //#endregion
 //#region src/presets/permissions.ts
-const DECISIONS$1 = Object.values(PermissionDecision);
+const DECISIONS$2 = Object.values(PermissionDecision);
 /** The `permissions` lists of a manifest as one list of rules, in the order of the file. */
 function createPermissionRules(permissions, manifestPath, artifactsDir) {
 	const source = relativePosix(artifactsDir, manifestPath);
 	const rules = [];
-	for (const decision of DECISIONS$1) {
+	for (const decision of DECISIONS$2) {
 		const keys = permissions[decision] ?? [];
 		for (const key of keys) rules.push({
 			key,
@@ -764,6 +881,7 @@ function createDownloadOptions(dir, token) {
 }
 //#endregion
 //#region src/sources/create-source-resolver.ts
+const HOME_PREFIX = "~/";
 function createSourceResolver(projectDir, download = downloadRepository) {
 	const downloads = /* @__PURE__ */ new Map();
 	const repositories = [];
@@ -793,7 +911,7 @@ function createSourceResolver(projectDir, download = downloadRepository) {
 			const repository = await fetchRepository(gitSource);
 			return checkInside(repository, join(repository.root, gitSource.path), ref);
 		}
-		const dir = resolve(fromDir, ref);
+		const dir = resolveLocalPath(ref, fromDir);
 		const repository = findRepository(fromDir);
 		if (repository === void 0) return dir;
 		return checkInside(repository, dir, ref);
@@ -823,6 +941,17 @@ function isInside(root, dir) {
 	const isOtherDrive = isAbsolute(path);
 	return isParent === false && isOtherDrive === false;
 }
+/**
+* A path from `extends`. `~/` starts at the home directory, so that a personal preset can
+* live there; any other path starts at the directory that refers to it.
+*/
+function resolveLocalPath(ref, fromDir) {
+	if (ref.startsWith(HOME_PREFIX)) {
+		const path = ref.slice(2);
+		return resolve(homedir(), path);
+	}
+	return resolve(fromDir, ref);
+}
 //#endregion
 //#region src/chain/check-chain.ts
 /** A level can extend the same or a more general level, never a more specific one. */
@@ -854,7 +983,7 @@ function findDuplicateNames(levels) {
 //#endregion
 //#region src/chain/linearize-chain.ts
 /**
-* Puts the levels in order with a depth-first walk from the project: parents first, in the
+* Puts the levels in order with a depth-first walk from the root: parents first, in the
 * order of `extends`, then the level itself. A level that is reached twice is added once.
 */
 function linearizeChain(graph) {
@@ -876,7 +1005,7 @@ function linearizeChain(graph) {
 		if (level === void 0) return;
 		levels.push(level);
 	};
-	visit(graph.project.dir, []);
+	visit(graph.root.dir, []);
 	return {
 		levels,
 		problems: [...problems]
@@ -916,14 +1045,14 @@ async function loadPreset(dir) {
 //#endregion
 //#region src/chain/load-preset-graph.ts
 /**
-* Loads the presets of the project, then the presets they extend, and so on. Each step loads
+* Loads the presets of the root, then the presets they extend, and so on. Each step loads
 * its presets in parallel; a preset that several levels extend is loaded once.
 */
-async function loadPresetGraph(project, resolver) {
+async function loadPresetGraph(root, resolver) {
 	const levels = /* @__PURE__ */ new Map();
 	const parents = /* @__PURE__ */ new Map();
-	let pending = [project];
-	levels.set(project.dir, project);
+	let pending = [root];
+	levels.set(root.dir, root);
 	while (pending.length > 0) {
 		const dirsToLoad = /* @__PURE__ */ new Set();
 		for (const preset of pending) {
@@ -935,7 +1064,7 @@ async function loadPresetGraph(project, resolver) {
 		for (const preset of pending) levels.set(preset.dir, preset);
 	}
 	return {
-		project,
+		root,
 		levels,
 		parents
 	};
@@ -969,6 +1098,67 @@ async function loadChain(projectDir, options = {}) {
 	};
 }
 //#endregion
+//#region src/presets/load-local.ts
+/** The personal level of the developer, when the project has `tunestra.local.yaml`. */
+async function loadLocal(projectDir) {
+	const root = resolve(projectDir);
+	const configPath = join(root, LOCAL_CONFIG);
+	if (await checkExists(configPath) === false) return;
+	const config = await readYaml(configPath, localConfigSchema, "personal config");
+	const artifactsDir = join(root, LOCAL_DIR);
+	const artifacts = await loadArtifacts(artifactsDir, config.name);
+	const env = createEnvVariables(config.env, configPath, artifactsDir);
+	const permissions = createPermissionRules(config.permissions, configPath, artifactsDir);
+	return {
+		...config,
+		level: Level.Local,
+		description: void 0,
+		dir: root,
+		artifactsDir,
+		remote: void 0,
+		...artifacts,
+		env,
+		permissions
+	};
+}
+//#endregion
+//#region src/chain/load-local-chain.ts
+/**
+* The shared chain with the personal level of the developer and its presets on top, or
+* `undefined` when the project has no `tunestra.local.yaml`.
+*/
+async function loadLocalChain(shared, options = {}) {
+	const local = await loadLocal(shared.project.dir);
+	if (local === void 0) return;
+	const linearization = linearizeChain(await loadPresetGraph(local, createSourceResolver(shared.project.dir, options.download)));
+	const levels = [...shared.levels, ...linearization.levels];
+	const levelProblems = linearization.levels.flatMap(findLocalProblems);
+	const nameProblems = findDuplicateNames(levels);
+	const problems = [
+		...linearization.problems,
+		...levelProblems,
+		...nameProblems
+	];
+	if (problems.length > 0) throw createProblemsError(problems);
+	return {
+		project: shared.project,
+		levels
+	};
+}
+/**
+* A personal level changes only the files that are not committed. Claude Code joins
+* `.claude/settings.local.json` with the committed `.claude/settings.json`, so a personal
+* level can add env and permissions, but cannot remove them.
+*/
+function findLocalProblems(level) {
+	const problems = [];
+	if (level.level !== Level.Local) problems.push(`${level.name} (${level.level}) is extended by the personal level. A personal level can only extend presets with level: local`);
+	const excludesEnv = (level.exclude.env?.length ?? 0) > 0;
+	const excludesPermissions = (level.exclude.permissions?.length ?? 0) > 0;
+	if (excludesEnv || excludesPermissions) problems.push(`${level.name}: a personal level cannot exclude env or permissions, because Claude Code joins .claude/settings.local.json with the committed .claude/settings.json`);
+	return problems;
+}
+//#endregion
 //#region src/generate/describe-source.ts
 /** Files built from the whole chain, like AGENTS.md: there is no single file to edit. */
 const SETUP_SOURCE = "tunestra.yaml and its presets";
@@ -981,6 +1171,139 @@ function describeArtifactSource(projectDir, origin, source) {
 	return relativePosix(projectDir, join(origin.artifactsDir, source));
 }
 //#endregion
+//#region src/shared/utils/markdown.ts
+/**
+* A pipe or a line break inside a cell would break the table.
+*
+* Matches: "|" in "a | b", "\n" and "\r\n" in "line one\nline two"
+*/
+const TABLE_BREAKING_PATTERN = /\||\r?\n/g;
+function renderTable(header, rows) {
+	return [
+		renderRow(header),
+		`|${header.map(() => "---").join("|")}|`,
+		...rows.map(renderRow)
+	].join("\n");
+}
+function renderRow(cells) {
+	return `| ${cells.map(escapeCell).join(" | ")} |`;
+}
+function escapeCell(cell) {
+	return cell.replace(TABLE_BREAKING_PATTERN, replaceTableBreaking);
+}
+function replaceTableBreaking(match) {
+	if (match === "|") return "\\|";
+	return " ";
+}
+//#endregion
+//#region src/generate/describe-origin.ts
+/** For example `team, overrides base` or `base, patched by team`. */
+function describeOrigin(resolved) {
+	const parts = [resolved.origin.level];
+	const hasOverrides = resolved.overrides.length > 0;
+	const isPatched = resolved.patchedBy.length > 0;
+	if (hasOverrides) {
+		const names = joinNames(resolved.overrides);
+		parts.push(`overrides ${names}`);
+	}
+	if (isPatched) {
+		const names = joinNames(resolved.patchedBy);
+		parts.push(`patched by ${names}`);
+	}
+	return parts.join(", ");
+}
+function joinNames(origins) {
+	return origins.map((origin) => origin.name).join(", ");
+}
+//#endregion
+//#region src/generate/local-changes.ts
+const INTRO = `The personal level of this developer (\`${LOCAL_CONFIG}\`) changes the setup in AGENTS.md on this machine only. When this file and AGENTS.md disagree, follow this file.`;
+const TURNED_OFF_INTRO = "These artifacts of AGENTS.md are turned off on this machine.";
+const NO_CHANGES = "The personal level changes nothing yet.";
+const CHANGING = `Edit \`${LOCAL_CONFIG}\` or \`${LOCAL_DIR}/\` and run \`tunestra setup\`.`;
+/**
+* What the personal level adds, overrides and turns off, compared with the committed
+* AGENTS.md. Claude Code reads it after CLAUDE.md as `CLAUDE.local.md`.
+*/
+function renderLocalChanges(shared, local) {
+	const groups = listGroups(shared, local);
+	const changedRows = groups.flatMap(listChangedRows);
+	const turnedOffRows = groups.flatMap(listTurnedOffRows);
+	const sections = [
+		GENERATED_NOTICE,
+		"# Personal setup",
+		INTRO
+	];
+	if (changedRows.length > 0) {
+		const table = renderTable([
+			"Kind",
+			"Name",
+			"Level",
+			"Description"
+		], changedRows);
+		sections.push("## Added and changed", table);
+	}
+	if (turnedOffRows.length > 0) {
+		const table = renderTable(["Kind", "Name"], turnedOffRows);
+		sections.push("## Turned off", TURNED_OFF_INTRO, table);
+	}
+	if ((changedRows.length > 0 || turnedOffRows.length > 0) === false) sections.push(NO_CHANGES);
+	sections.push(CHANGING);
+	return `${sections.join("\n\n")}\n`;
+}
+function listGroups(shared, local) {
+	return [
+		createGroup("Rule", shared.rules, local.rules),
+		createGroup("Skill", shared.skills, local.skills),
+		createGroup("Command", shared.commands.map(labelCommand), local.commands.map(labelCommand)),
+		createGroup("MCP server", shared.mcp, local.mcp),
+		createGroup("Subagent", shared.subagents, local.subagents),
+		createGroup("Variable", shared.env, local.env),
+		createGroup("Permission", shared.permissions.map(labelPermission$1), local.permissions.map(labelPermission$1))
+	];
+}
+function createGroup(kind, shared, local) {
+	return {
+		kind,
+		shared,
+		local
+	};
+}
+function listChangedRows(group) {
+	return group.local.filter((resolved) => resolved.origin.level === Level.Local).map((resolved) => {
+		const origin = describeOrigin(resolved);
+		const description = resolved.artifact.description ?? "";
+		return [
+			group.kind,
+			resolved.artifact.key,
+			origin,
+			description
+		];
+	});
+}
+function listTurnedOffRows(group) {
+	const localKeys = new Set(group.local.map((resolved) => resolved.artifact.key));
+	return group.shared.filter((resolved) => localKeys.has(resolved.artifact.key) === false).map((resolved) => [group.kind, resolved.artifact.key]);
+}
+function labelCommand(resolved) {
+	const artifact = {
+		key: `/${resolved.artifact.key}`,
+		description: resolved.artifact.description
+	};
+	return {
+		...resolved,
+		artifact
+	};
+}
+/** For example `deny Read(./.env)`: the same rule can be in two lists. */
+function labelPermission$1(resolved) {
+	const artifact = { key: `${resolved.artifact.decision} ${resolved.artifact.key}` };
+	return {
+		...resolved,
+		artifact
+	};
+}
+//#endregion
 //#region src/shared/utils/outputs.ts
 function createFileOutput(path, content, source) {
 	return {
@@ -1096,7 +1419,7 @@ function compareByName([a], [b]) {
 //#endregion
 //#region src/agents/claude/settings-json.ts
 const SETTINGS_SCHEMA = "https://json.schemastore.org/claude-code-settings.json";
-const DECISIONS = Object.values(PermissionDecision);
+const DECISIONS$1 = Object.values(PermissionDecision);
 /** The keys that tunestra writes; a file with only these keys is a generated one. */
 const SETTINGS_KEYS = [
 	"$schema",
@@ -1112,10 +1435,23 @@ function renderSettingsJson(settings) {
 	if (hasPermissions) content.permissions = buildPermissionLists(settings.permissions);
 	return `${JSON.stringify(content, null, 2)}\n`;
 }
+/** Every list, empty ones included, for entries that setup adds to a file of people. */
+function buildSettingsEntries(env, permissions) {
+	const envMap = buildEnvMap(env);
+	const lists = buildPermissionLists(permissions);
+	return {
+		env: envMap,
+		permissions: {
+			[PermissionDecision.Allow]: lists[PermissionDecision.Allow] ?? [],
+			[PermissionDecision.Ask]: lists[PermissionDecision.Ask] ?? [],
+			[PermissionDecision.Deny]: lists[PermissionDecision.Deny] ?? []
+		}
+	};
+}
 /** Only the lists that have rules; a rule repeated on several levels is written once. */
 function buildPermissionLists(permissions) {
 	const lists = {};
-	for (const decision of DECISIONS) {
+	for (const decision of DECISIONS$1) {
 		const keys = permissions.filter((resolved) => resolved.artifact.decision === decision).map((resolved) => resolved.artifact.key);
 		const sortedKeys = [...new Set(keys)].toSorted();
 		if (sortedKeys.length > 0) lists[decision] = sortedKeys;
@@ -1123,16 +1459,40 @@ function buildPermissionLists(permissions) {
 	return lists;
 }
 //#endregion
+//#region src/agents/claude/subagent-md.ts
+/** Tools that change files; a read-only subagent keeps the tools that read and search. */
+const WRITING_TOOLS = [
+	"Write",
+	"Edit",
+	"NotebookEdit",
+	"Bash"
+];
+/** `.claude/agents/<name>.md`: the frontmatter of Claude Code and the instructions. */
+function renderSubagentMd(subagent) {
+	const { key, description, model, effort, readOnly, body } = subagent;
+	const frontmatter = {
+		name: key,
+		description
+	};
+	if (typeof model.claude === "string") frontmatter.model = model.claude;
+	if (typeof effort === "string") frontmatter.effort = effort;
+	if (readOnly) frontmatter.disallowedTools = WRITING_TOOLS;
+	return `---\n${stringify(frontmatter)}---\n${body}`;
+}
+//#endregion
 //#region src/agents/claude/claude-adapter.ts
 const CLAUDE_FILE = "CLAUDE.md";
 const RULES_DIR = ".claude/rules/tunestra";
 const SKILLS_DIR = ".claude/skills";
 const COMMANDS_DIR = ".claude/commands";
+const SUBAGENTS_DIR$1 = ".claude/agents";
 const MCP_FILE = ".mcp.json";
 const MCP_SOURCE = "the mcp/ folders of tunestra.yaml and its presets";
 const SETTINGS_FILE = ".claude/settings.json";
 const SETTINGS_SOURCE = "env and permissions in tunestra.yaml and its presets";
 const LOCAL_SETTINGS_FILE = ".claude/settings.local.json";
+const LOCAL_CLAUDE_FILE = "CLAUDE.local.md";
+const LOCAL_SOURCE = `${LOCAL_CONFIG} and ${LOCAL_DIR}/`;
 /**
 * Claude Code reads CLAUDE.md, so it imports AGENTS.md. Rules are copied to `.claude/rules`,
 * which Claude Code loads in every session; a symlink to a directory outside `.claude`
@@ -1142,8 +1502,40 @@ const LOCAL_SETTINGS_FILE = ".claude/settings.local.json";
 */
 const claudeAdapter = {
 	agent: Agent.Claude,
-	plan: planClaude
+	plan: planClaude,
+	planLocal: planClaudeLocal
 };
+/**
+* Claude Code reads `CLAUDE.local.md` after CLAUDE.md, so it says what the personal level
+* changes. Personal env and permissions are added to `.claude/settings.local.json`, which
+* Claude Code applies over the committed settings; the entries of people and of Claude
+* Code itself stay.
+*/
+function planClaudeLocal(context) {
+	const { shared, local } = context;
+	const content = renderLocalChanges(shared, local);
+	const localFile = createFileOutput(LOCAL_CLAUDE_FILE, content, LOCAL_SOURCE);
+	const env = local.env.filter(isFromLocal);
+	const permissions = local.permissions.filter(isFromLocal);
+	if ((env.length > 0 || permissions.length > 0) === false) return {
+		outputs: [localFile],
+		ignoredPaths: [LOCAL_CLAUDE_FILE],
+		merges: []
+	};
+	const entries = buildSettingsEntries(env, permissions);
+	return {
+		outputs: [localFile],
+		ignoredPaths: [LOCAL_CLAUDE_FILE, LOCAL_SETTINGS_FILE],
+		merges: [{
+			path: LOCAL_SETTINGS_FILE,
+			source: LOCAL_SOURCE,
+			entries
+		}]
+	};
+}
+function isFromLocal(resolved) {
+	return resolved.origin.level === Level.Local;
+}
 function planClaude(context) {
 	const { resolution, ruleFiles } = context;
 	const projectDir = resolution.chain.project.dir;
@@ -1156,11 +1548,15 @@ function planClaude(context) {
 		const source = describeArtifactSource(projectDir, command.origin, command.artifact.source);
 		return createFileOutput(path, command.artifact.content, source);
 	});
+	const subagentFiles = resolution.subagents.map((subagent) => {
+		return createFileOutput(`${SUBAGENTS_DIR$1}/${subagent.artifact.key}.md`, renderSubagentMd(subagent.artifact), describeArtifactSource(projectDir, subagent.origin, subagent.artifact.source));
+	});
 	const outputs = [
 		claudeFile,
 		...ruleCopies,
 		...skillLinks,
-		...commandFiles
+		...commandFiles,
+		...subagentFiles
 	];
 	if (resolution.mcp.length > 0) {
 		const mcpJson = renderMcpJson(resolution.mcp);
@@ -1179,10 +1575,12 @@ function planClaude(context) {
 			`${RULES_DIR}/`,
 			`${SKILLS_DIR}/`,
 			`${COMMANDS_DIR}/`,
+			`${SUBAGENTS_DIR$1}/`,
 			MCP_FILE
 		],
 		protectedPaths,
-		notes: []
+		notes: [],
+		merges: []
 	};
 }
 /** Claude Code drops some variables from project settings; setup says so instead. */
@@ -1220,362 +1618,48 @@ function linkSkill(projectDir, skill) {
 	};
 }
 //#endregion
-//#region src/agents/codex/command-skill.ts
-/** Codex starts the skill only when people call it, like a command. */
-const OPENAI_YAML = [
-	GENERATED_HASH_NOTICE,
-	"policy:",
-	"  allow_implicit_invocation: false",
-	""
-].join("\n");
+//#region src/generate/rule-file.ts
 /**
-* Codex has no project commands, so a command becomes a skill with the same name that runs
-* only on `$<name>`. The skill gets `name` and `description`; other frontmatter of the
-* command belongs to Claude Code.
+* `<rank>-<level>-<key>.md`, so that a plain sort puts specific rules first. Level
+* instructions become `instructions`, with the preset name when it differs from the level.
 */
-function planCommandSkill(projectDir, command) {
-	const { key, description, body } = command.artifact;
-	const dir = `${AGENTS_SKILLS_DIR}/${key}`;
-	const source = describeArtifactSource(projectDir, command.origin, command.artifact.source);
-	const frontmatter = {
-		name: key,
-		description: description ?? `The /${key} command`
-	};
-	const skill = `---\n${stringify(frontmatter)}---\n${body}`;
-	const skillPath = `${dir}/SKILL.md`;
-	const policyPath = `${dir}/agents/openai.yaml`;
-	return [createFileOutput(skillPath, skill, source), createFileOutput(policyPath, OPENAI_YAML, source)];
-}
-//#endregion
-//#region src/agents/codex/config-toml.ts
-/** Starts and ends a multi-line literal string, where TOML escapes nothing. */
-const LITERAL_DELIMITER = "'''";
-/**
-* Control characters that a TOML literal string cannot hold. Tab and line feed are allowed;
-* a carriage return is in the list, because only `\r\n` would be valid.
-*
-* Matches:        "\u0000", "\r", "\u001B" (escape), "\u007F" (delete)
-* Does not match: "\t", "\n", "é", "→"
-*/
-const CONTROL_CHARACTER_PATTERN = /[\u0000-\u0008\u000B-\u001F\u007F]/;
-/**
-* `.codex/config.toml`: the rules as `developer_instructions`, which Codex adds to every
-* session, the environment of the commands that Codex runs, and the MCP servers. The rules
-* are a literal string, so that people can read them.
-*/
-function renderConfigToml(config) {
-	const parts = [GENERATED_HASH_NOTICE];
-	if (typeof config.instructions === "string") {
-		const line = renderInstructions$1(config.instructions);
-		parts.push(line);
-	}
-	const tables = {};
-	const hasEnv = config.env.length > 0;
-	const hasServers = config.servers.length > 0;
-	if (hasEnv) tables.shell_environment_policy = { set: buildEnvMap(config.env) };
-	if (hasServers) {
-		const entries = config.servers.map((server) => {
-			const serverConfig = convertMcpConfig(server.artifact.config);
-			return [server.artifact.key, serverConfig];
-		});
-		tables.mcp_servers = Object.fromEntries(entries);
-	}
-	if (hasEnv || hasServers) {
-		const text = stringify$1(tables).trimEnd();
-		parts.push(text);
-	}
-	return `${parts.join("\n\n")}\n`;
-}
-function renderInstructions$1(text) {
-	const hasDelimiter = text.includes(LITERAL_DELIMITER);
-	const hasControlCharacter = CONTROL_CHARACTER_PATTERN.test(text);
-	if (hasDelimiter || hasControlCharacter) return stringify$1({ developer_instructions: text });
-	return `developer_instructions = ${LITERAL_DELIMITER}\n${text}${LITERAL_DELIMITER}`;
-}
-/** Codex picks the transport by `command` or `url` and has no `type`. */
-function convertMcpConfig(config) {
-	const { type: _type, headers, ...server } = config;
-	if (headers === void 0) return server;
-	return {
-		...server,
-		http_headers: headers
-	};
-}
-//#endregion
-//#region src/agents/codex/exec-rules.ts
-/** A Bash rule of Claude Code with a specifier: `Bash(npm test *)`. */
-const BASH_RULE_START = "Bash(";
-const BASH_RULE_END = ")";
-/**
-* Shell syntax and wildcards that a Codex prefix rule cannot express.
-*
-* Matches:        "npm test && rm", "echo $HOME", "git * --force", "ls > out", "say 'hi'"
-* Does not match: "npm test", "git push --force", "rm -rf"
-*/
-const SHELL_SYNTAX_PATTERN = /["'`$\\|&;<>(){}*?[\]~]/;
-const WHITESPACE_PATTERN = /\s+/;
-/** A trailing ` *` or the older `:*` means "this command with any arguments". */
-const ANY_ARGUMENTS_SUFFIXES = [" *", ":*"];
-/**
-* Codex names for the decisions it gets. `allow` stays out: in Codex it runs a command
-* outside the sandbox without asking, which is more than an `allow` rule of Claude Code means.
-*/
-const CODEX_DECISIONS = {
-	[PermissionDecision.Deny]: "forbidden",
-	[PermissionDecision.Ask]: "prompt"
-};
-/**
-* The words of a Bash rule that Codex can match by prefix, or `undefined` when it cannot.
-* A rule without a wildcard becomes a prefix too: for `deny` and `ask` this is stricter.
-*/
-function convertBashRule(rule) {
-	if ((rule.startsWith(BASH_RULE_START) && rule.endsWith(BASH_RULE_END)) === false) return;
-	const specifier = rule.slice(5, -1);
-	const suffix = ANY_ARGUMENTS_SUFFIXES.find((ending) => specifier.endsWith(ending));
-	const command = typeof suffix === "string" ? specifier.slice(0, -suffix.length) : specifier;
-	if (SHELL_SYNTAX_PATTERN.test(command)) return;
-	const words = command.trim().split(WHITESPACE_PATTERN);
-	if (words.every((word) => word.length > 0)) return words;
-}
-function hasCodexDecision(decision) {
-	return decision in CODEX_DECISIONS;
-}
-function createExecRule(resolved, decision, pattern) {
-	return {
-		pattern,
-		decision: CODEX_DECISIONS[decision],
-		justification: `${resolved.artifact.key}: ${decision} from ${resolved.origin.name}`
-	};
-}
-/** `.codex/rules/tunestra.rules` in the Starlark format of Codex. */
-function renderExecRules(rules) {
-	const blocks = rules.map(renderExecRule);
-	return `${[GENERATED_HASH_NOTICE, ...blocks].join("\n\n")}\n`;
-}
-/** JSON strings are valid Starlark strings. */
-function renderExecRule(rule) {
-	const pattern = rule.pattern.map((word) => JSON.stringify(word)).join(", ");
-	const decision = JSON.stringify(rule.decision);
-	const justification = JSON.stringify(rule.justification);
-	return [
-		"prefix_rule(",
-		`    pattern = [${pattern}],`,
-		`    decision = ${decision},`,
-		`    justification = ${justification},`,
-		")"
-	].join("\n");
-}
-//#endregion
-//#region src/agents/codex/codex-adapter.ts
-const CONFIG_FILE = ".codex/config.toml";
-const CONFIG_SOURCE = "the rules/ and mcp/ folders and env of tunestra.yaml and its presets";
-const EXEC_RULES_FILE = ".codex/rules/tunestra.rules";
-const EXEC_RULES_SOURCE = "permissions in tunestra.yaml and its presets";
-const INSTRUCTIONS_INTRO = "Rules of this project, ordered from specific to general. When two rules conflict, follow the one that comes first.";
-const TRUST_NOTE = "Codex reads .codex/ only in a trusted project: trust the project when Codex asks.";
-/**
-* Codex reads AGENTS.md and the skills in `.agents/skills` by itself. Rules go to
-* `developer_instructions` in `.codex/config.toml`, because Codex does not follow the links
-* in AGENTS.md; MCP servers and env go to the same file. Commands become skills, and
-* permission rules for shell commands become `.codex/rules/tunestra.rules`.
-*/
-const codexAdapter = {
-	agent: Agent.Codex,
-	plan: planCodex
-};
-function planCodex(context) {
-	const { resolution, ruleFiles } = context;
-	const projectDir = resolution.chain.project.dir;
-	const notes = [];
-	const outputs = [];
-	const commandSkills = resolution.commands.filter((command) => {
-		if (skillName.safeParse(command.artifact.key).success) return true;
-		notes.push(`Codex skips the command "${command.artifact.key}": a skill name needs lowercase letters, digits and single hyphens.`);
-		return false;
-	}).flatMap((command) => planCommandSkill(projectDir, command));
-	outputs.push(...commandSkills);
-	const configFile = planConfigFile(ruleFiles, resolution.mcp.filter((server) => {
-		if (server.artifact.config.type === "sse") {
-			notes.push(`Codex skips the MCP server "${server.artifact.key}": Codex does not support SSE.`);
-			return false;
-		}
-		return true;
-	}), resolution.env);
-	const execRules = planExecRules(resolution.permissions);
-	const ignoredPaths = [];
-	notes.push(...execRules.notes);
-	if (typeof configFile === "object") {
-		outputs.push(configFile);
-		ignoredPaths.push(CONFIG_FILE);
-	}
-	if (typeof execRules.file === "object") {
-		outputs.push(execRules.file);
-		ignoredPaths.push(EXEC_RULES_FILE);
-	}
-	if (ignoredPaths.length > 0) notes.push(TRUST_NOTE);
-	return {
-		outputs,
-		ignoredPaths,
-		protectedPaths: [],
-		notes
-	};
-}
-/**
-* `deny` and `ask` rules for Bash commands become prefix rules of Codex. Codex has no rules
-* for files, the web or MCP tools, and `allow` would mean more in Codex, so those are skipped.
-*/
-function planExecRules(permissions) {
-	const execRules = [];
-	const skippedRules = [];
-	const allowRules = [];
-	for (const resolved of permissions) {
-		const { key, decision } = resolved.artifact;
-		if (hasCodexDecision(decision) === false) {
-			allowRules.push(key);
-			continue;
-		}
-		const pattern = convertBashRule(key);
-		if (pattern === void 0) {
-			skippedRules.push(key);
-			continue;
-		}
-		const execRule = createExecRule(resolved, decision, pattern);
-		execRules.push(execRule);
-	}
-	const notes = [];
-	const hasSkippedRules = skippedRules.length > 0;
-	const hasAllowRules = allowRules.length > 0;
-	if (hasSkippedRules) {
-		const rules = skippedRules.join(", ");
-		notes.push(`Codex skips permission rules that it cannot enforce: ${rules}. Codex rules match only the start of a shell command.`);
-	}
-	if (hasAllowRules) {
-		const rules = allowRules.join(", ");
-		notes.push(`Codex skips allow rules: ${rules}. In Codex, an allowed command runs outside the sandbox without asking.`);
-	}
-	if (execRules.length > 0) {
-		const content = renderExecRules(execRules);
-		return {
-			file: createFileOutput(EXEC_RULES_FILE, content, EXEC_RULES_SOURCE),
-			notes
-		};
-	}
-	return {
-		file: void 0,
-		notes
-	};
-}
-function planConfigFile(ruleFiles, servers, env) {
-	const hasRules = ruleFiles.length > 0;
-	const hasServers = servers.length > 0;
-	const hasEnv = env.length > 0;
-	if (hasRules === false && hasServers === false && hasEnv === false) return;
-	const content = renderConfigToml({
-		instructions: hasRules ? renderInstructions(ruleFiles) : void 0,
-		servers,
-		env
-	});
-	return createFileOutput(CONFIG_FILE, content, CONFIG_SOURCE);
-}
-/** The rule files as they are, with the header that names the source of each. */
-function renderInstructions(ruleFiles) {
-	const rules = ruleFiles.map((file) => file.content.trimEnd());
-	return `${[INSTRUCTIONS_INTRO, ...rules].join("\n\n")}\n`;
-}
-//#endregion
-//#region src/agents/adapters.ts
-/** Every supported agent. */
-const AGENT_ADAPTERS = {
-	[Agent.Claude]: claudeAdapter,
-	[Agent.Codex]: codexAdapter
-};
-//#endregion
-//#region src/shared/utils/markdown.ts
-/**
-* A pipe or a line break inside a cell would break the table.
-*
-* Matches: "|" in "a | b", "\n" and "\r\n" in "line one\nline two"
-*/
-const TABLE_BREAKING_PATTERN = /\||\r?\n/g;
-function renderTable(header, rows) {
-	return [
-		renderRow(header),
-		`|${header.map(() => "---").join("|")}|`,
-		...rows.map(renderRow)
-	].join("\n");
-}
-function renderRow(cells) {
-	return `| ${cells.map(escapeCell).join(" | ")} |`;
-}
-function escapeCell(cell) {
-	return cell.replace(TABLE_BREAKING_PATTERN, replaceTableBreaking);
-}
-function replaceTableBreaking(match) {
-	if (match === "|") return "\\|";
-	return " ";
-}
-//#endregion
-//#region src/generate/describe-origin.ts
-/** For example `team, overrides base` or `base, patched by team`. */
-function describeOrigin(resolved) {
-	const parts = [resolved.origin.level];
-	const hasOverrides = resolved.overrides.length > 0;
-	const isPatched = resolved.patchedBy.length > 0;
-	if (hasOverrides) {
-		const names = joinNames(resolved.overrides);
-		parts.push(`overrides ${names}`);
-	}
-	if (isPatched) {
-		const names = joinNames(resolved.patchedBy);
-		parts.push(`patched by ${names}`);
-	}
-	return parts.join(", ");
-}
-function joinNames(origins) {
-	return origins.map((origin) => origin.name).join(", ");
-}
-//#endregion
-//#region src/generate/rule-file.ts
-/**
-* `<rank>-<level>-<key>.md`, so that a plain sort puts specific rules first. Level
-* instructions become `instructions`, with the preset name when it differs from the level.
-*/
-function buildRuleFileName(rule) {
-	const rank = LEVEL_RANK[rule.origin.level];
-	const slug = buildRuleSlug(rule);
-	return `${rank}-${rule.origin.level}-${slug}.md`;
-}
-/** The rule text with a header that tells where it comes from and what it overrides. */
-function renderRuleFile(rule) {
-	const sourceFile = join(rule.origin.artifactsDir, rule.artifact.source);
-	const sourcePath = relativePosix(rule.origin.dir, sourceFile);
-	const levelLine = renderLevelLine(rule);
-	return [
-		`${GENERATED_MARKER} from ${rule.origin.name}:${sourcePath}. Do not edit. -->`,
-		levelLine,
-		"",
-		rule.artifact.body
-	].join("\n");
-}
-function buildRuleSlug(rule) {
-	const instructionsKey = buildInstructionsKey(rule.origin.name);
-	const isInstructions = rule.artifact.key === instructionsKey;
-	const isNamedAsLevel = rule.origin.name === rule.origin.level;
-	if (isInstructions === false) return rule.artifact.key;
-	if (isNamedAsLevel) return "instructions";
-	return `instructions-${rule.origin.name}`;
-}
-/** For example `> Level: team, preset: team. Overrides: base.` */
-function renderLevelLine(rule) {
-	const line = `> Level: ${rule.origin.level}, preset: ${rule.origin.name}.`;
-	if (rule.overrides.length > 0) return `${line} Overrides: ${joinNames(rule.overrides)}.`;
-	return line;
+function buildRuleFileName(rule) {
+	const rank = String(LEVEL_RANK[rule.origin.level]).padStart(2, "0");
+	const slug = buildRuleSlug(rule);
+	return `${rank}-${rule.origin.level}-${slug}.md`;
+}
+/** The rule text with a header that tells where it comes from and what it overrides. */
+function renderRuleFile(rule) {
+	const sourceFile = join(rule.origin.artifactsDir, rule.artifact.source);
+	const sourcePath = relativePosix(rule.origin.dir, sourceFile);
+	const levelLine = renderLevelLine(rule);
+	return [
+		`${GENERATED_MARKER} from ${rule.origin.name}:${sourcePath}. Do not edit. -->`,
+		levelLine,
+		"",
+		rule.artifact.body
+	].join("\n");
+}
+function buildRuleSlug(rule) {
+	const instructionsKey = buildInstructionsKey(rule.origin.name);
+	const isInstructions = rule.artifact.key === instructionsKey;
+	const isNamedAsLevel = rule.origin.name === rule.origin.level;
+	if (isInstructions === false) return rule.artifact.key;
+	if (isNamedAsLevel) return "instructions";
+	return `instructions-${rule.origin.name}`;
+}
+/** For example `> Level: team, preset: team. Overrides: base.` */
+function renderLevelLine(rule) {
+	const line = `> Level: ${rule.origin.level}, preset: ${rule.origin.name}.`;
+	if (rule.overrides.length > 0) return `${line} Overrides: ${joinNames(rule.overrides)}.`;
+	return line;
 }
 //#endregion
 //#region src/generate/index-sections.ts
 const HIERARCHY_INTRO = "Instructions are ordered from specific to general. When two instructions conflict, follow the one from the higher level in this list.";
 const RULES_INTRO = "Always follow these rules. Claude Code and Codex load them automatically; other agents should read them before starting work.";
 const SKILLS_INTRO = "Use a skill when the task matches its description.";
+const SUBAGENTS_INTRO = "Hand a task to a subagent when the task matches its description.";
 const ENV_INTRO = "Agents set these variables in every session, also for the commands they run. The values are in the presets.";
 const CHANGING_SECTION = [
 	"## Changing this setup",
@@ -1678,6 +1762,21 @@ function renderMcpServers(servers) {
 		];
 	})));
 }
+function renderSubagents(subagents) {
+	const table = renderTable([
+		"Subagent",
+		"Level",
+		"When to use"
+	], subagents.map((subagent) => {
+		const origin = describeOrigin(subagent);
+		return [
+			subagent.artifact.key,
+			origin,
+			subagent.artifact.description
+		];
+	}));
+	return renderSection("Subagents", SUBAGENTS_INTRO, table);
+}
 function renderEnv(env) {
 	const table = renderTable(["Variable", "Level"], env.map((variable) => {
 		const origin = describeOrigin(variable);
@@ -1685,76 +1784,446 @@ function renderEnv(env) {
 	}));
 	return renderSection("Environment", ENV_INTRO, table);
 }
-/** The project shows its config file; a preset shows its git reference or its path. */
-function describeLevelSource(chain, level) {
-	if (level.dir === chain.project.dir) return PROJECT_CONFIG;
-	if (typeof level.remote === "string") return level.remote;
-	return relativePosix(chain.project.dir, level.dir);
+/** The project and the personal level show their config files; a preset shows its git reference or its path. */
+function describeLevelSource(chain, level) {
+	if (level.dir === chain.project.dir) return level.level === Level.Local ? LOCAL_CONFIG : PROJECT_CONFIG;
+	if (typeof level.remote === "string") return level.remote;
+	return relativePosix(chain.project.dir, level.dir);
+}
+function renderSection(title, intro, table) {
+	const heading = `## ${title}`;
+	if (intro === void 0) return [
+		heading,
+		"",
+		table
+	].join("\n");
+	return [
+		heading,
+		"",
+		intro,
+		"",
+		table
+	].join("\n");
+}
+//#endregion
+//#region src/generate/agents-index.ts
+/**
+* AGENTS.md: an index of the setup, not the rules themselves. It lists the levels, every
+* rule, skill, command, MCP server and subagent, where each comes from and where its file is.
+*/
+function renderAgentsIndex(resolution) {
+	const title = `# AI agent context: ${resolution.chain.project.name}`;
+	const hierarchy = renderHierarchy(resolution.chain);
+	const sections = [
+		GENERATED_NOTICE,
+		title,
+		hierarchy
+	];
+	const hasRules = resolution.rules.length > 0;
+	const hasSkills = resolution.skills.length > 0;
+	const hasCommands = resolution.commands.length > 0;
+	const hasMcpServers = resolution.mcp.length > 0;
+	const hasSubagents = resolution.subagents.length > 0;
+	const hasEnv = resolution.env.length > 0;
+	if (hasRules) {
+		const rules = renderRules(resolution.rules);
+		sections.push(rules);
+	}
+	if (hasSkills) {
+		const skills = renderSkills(resolution.skills);
+		sections.push(skills);
+	}
+	if (hasCommands) {
+		const commands = renderCommands(resolution.commands, resolution.chain.project.agents);
+		sections.push(commands);
+	}
+	if (hasMcpServers) {
+		const servers = renderMcpServers(resolution.mcp);
+		sections.push(servers);
+	}
+	if (hasSubagents) {
+		const subagents = renderSubagents(resolution.subagents);
+		sections.push(subagents);
+	}
+	if (hasEnv) {
+		const env = renderEnv(resolution.env);
+		sections.push(env);
+	}
+	sections.push(CHANGING_SECTION);
+	return `${sections.join("\n\n")}\n`;
+}
+//#endregion
+//#region src/agents/codex/command-skill.ts
+/** Codex starts the skill only when people call it, like a command. */
+const OPENAI_YAML = [
+	GENERATED_HASH_NOTICE,
+	"policy:",
+	"  allow_implicit_invocation: false",
+	""
+].join("\n");
+/**
+* Codex has no project commands, so a command becomes a skill with the same name that runs
+* only on `$<name>`. The skill gets `name` and `description`; other frontmatter of the
+* command belongs to Claude Code.
+*/
+function planCommandSkill(projectDir, command) {
+	const { key, description, body } = command.artifact;
+	const dir = `${AGENTS_SKILLS_DIR}/${key}`;
+	const source = describeArtifactSource(projectDir, command.origin, command.artifact.source);
+	const frontmatter = {
+		name: key,
+		description: description ?? `The /${key} command`
+	};
+	const skill = `---\n${stringify(frontmatter)}---\n${body}`;
+	const skillPath = `${dir}/SKILL.md`;
+	const policyPath = `${dir}/agents/openai.yaml`;
+	return [createFileOutput(skillPath, skill, source), createFileOutput(policyPath, OPENAI_YAML, source)];
+}
+//#endregion
+//#region src/agents/codex/toml-text.ts
+/** Starts and ends a multi-line literal string, where TOML escapes nothing. */
+const LITERAL_DELIMITER = "'''";
+/**
+* Control characters that a TOML literal string cannot hold. Tab and line feed are allowed;
+* a carriage return is in the list, because only `\r\n` would be valid.
+*
+* Matches:        "\u0000", "\r", "\u001B" (escape), "\u007F" (delete)
+* Does not match: "\t", "\n", "é", "→"
+*/
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u0008\u000B-\u001F\u007F]/;
+/**
+* A key with a long text, like `developer_instructions`. The text is a literal string, so
+* that people can read it; a text that a literal string cannot hold is escaped.
+*/
+function renderTomlText(key, text) {
+	const hasDelimiter = text.includes(LITERAL_DELIMITER);
+	const hasControlCharacter = CONTROL_CHARACTER_PATTERN.test(text);
+	if (hasDelimiter || hasControlCharacter) return stringify$1({ [key]: text });
+	return `${key} = ${LITERAL_DELIMITER}\n${text}${LITERAL_DELIMITER}`;
+}
+//#endregion
+//#region src/agents/codex/config-toml.ts
+/**
+* `.codex/config.toml`: the rules as `developer_instructions`, which Codex adds to every
+* session, the environment of the commands that Codex runs, and the MCP servers. The rules
+* are a literal string, so that people can read them.
+*/
+function renderConfigToml(config) {
+	const parts = [GENERATED_HASH_NOTICE];
+	if (typeof config.instructions === "string") {
+		const line = renderTomlText("developer_instructions", config.instructions);
+		parts.push(line);
+	}
+	const tables = {};
+	const hasEnv = config.env.length > 0;
+	const hasServers = config.servers.length > 0;
+	if (hasEnv) tables.shell_environment_policy = { set: buildEnvMap(config.env) };
+	if (hasServers) {
+		const entries = config.servers.map((server) => {
+			const serverConfig = convertMcpConfig(server.artifact.config);
+			return [server.artifact.key, serverConfig];
+		});
+		tables.mcp_servers = Object.fromEntries(entries);
+	}
+	if (hasEnv || hasServers) {
+		const text = stringify$1(tables).trimEnd();
+		parts.push(text);
+	}
+	return `${parts.join("\n\n")}\n`;
+}
+/** Codex picks the transport by `command` or `url` and has no `type`. */
+function convertMcpConfig(config) {
+	const { type: _type, headers, ...server } = config;
+	if (headers === void 0) return server;
+	return {
+		...server,
+		http_headers: headers
+	};
+}
+//#endregion
+//#region src/agents/codex/exec-rules.ts
+/** A Bash rule of Claude Code with a specifier: `Bash(npm test *)`. */
+const BASH_RULE_START = "Bash(";
+const BASH_RULE_END = ")";
+/**
+* Shell syntax and wildcards that a Codex prefix rule cannot express.
+*
+* Matches:        "npm test && rm", "echo $HOME", "git * --force", "ls > out", "say 'hi'"
+* Does not match: "npm test", "git push --force", "rm -rf"
+*/
+const SHELL_SYNTAX_PATTERN = /["'`$\\|&;<>(){}*?[\]~]/;
+const WHITESPACE_PATTERN = /\s+/;
+/** A trailing ` *` or the older `:*` means "this command with any arguments". */
+const ANY_ARGUMENTS_SUFFIXES = [" *", ":*"];
+/**
+* Codex names for the decisions it gets. `allow` stays out: in Codex it runs a command
+* outside the sandbox without asking, which is more than an `allow` rule of Claude Code means.
+*/
+const CODEX_DECISIONS = {
+	[PermissionDecision.Deny]: "forbidden",
+	[PermissionDecision.Ask]: "prompt"
+};
+/**
+* The words of a Bash rule that Codex can match by prefix, or `undefined` when it cannot.
+* A rule without a wildcard becomes a prefix too: for `deny` and `ask` this is stricter.
+*/
+function convertBashRule(rule) {
+	if ((rule.startsWith(BASH_RULE_START) && rule.endsWith(BASH_RULE_END)) === false) return;
+	const specifier = rule.slice(5, -1);
+	const suffix = ANY_ARGUMENTS_SUFFIXES.find((ending) => specifier.endsWith(ending));
+	const command = typeof suffix === "string" ? specifier.slice(0, -suffix.length) : specifier;
+	if (SHELL_SYNTAX_PATTERN.test(command)) return;
+	const words = command.trim().split(WHITESPACE_PATTERN);
+	if (words.every((word) => word.length > 0)) return words;
+}
+function hasCodexDecision(decision) {
+	return decision in CODEX_DECISIONS;
+}
+function createExecRule(resolved, decision, pattern) {
+	return {
+		pattern,
+		decision: CODEX_DECISIONS[decision],
+		justification: `${resolved.artifact.key}: ${decision} from ${resolved.origin.name}`
+	};
+}
+/** `.codex/rules/tunestra.rules` in the Starlark format of Codex. */
+function renderExecRules(rules) {
+	const blocks = rules.map(renderExecRule);
+	return `${[GENERATED_HASH_NOTICE, ...blocks].join("\n\n")}\n`;
 }
-function renderSection(title, intro, table) {
-	const heading = `## ${title}`;
-	if (intro === void 0) return [
-		heading,
-		"",
-		table
-	].join("\n");
+/** JSON strings are valid Starlark strings. */
+function renderExecRule(rule) {
+	const pattern = rule.pattern.map((word) => JSON.stringify(word)).join(", ");
+	const decision = JSON.stringify(rule.decision);
+	const justification = JSON.stringify(rule.justification);
 	return [
-		heading,
-		"",
-		intro,
-		"",
-		table
+		"prefix_rule(",
+		`    pattern = [${pattern}],`,
+		`    decision = ${decision},`,
+		`    justification = ${justification},`,
+		")"
 	].join("\n");
 }
 //#endregion
-//#region src/generate/agents-index.ts
+//#region src/agents/codex/subagent-toml.ts
 /**
-* AGENTS.md: an index of the setup, not the rules themselves. It lists the levels, every
-* rule, skill, command and MCP server, where each comes from and where its file is.
+* Codex has no read-only mode for a subagent: it can turn off the shell, but the subagent
+* still edits files with patches. So the instructions ask it not to.
 */
-function renderAgentsIndex(resolution) {
-	const title = `# AI agent context: ${resolution.chain.project.name}`;
-	const hierarchy = renderHierarchy(resolution.chain);
-	const sections = [
-		GENERATED_NOTICE,
-		title,
-		hierarchy
+const READ_ONLY_INSTRUCTION = "Do not create, edit or delete files.";
+/**
+* `.codex/agents/<name>.toml`. Codex gives a subagent the sandbox, the permissions and the
+* MCP servers of the main session, so the file has only the model and the instructions.
+*/
+function renderSubagentToml(subagent) {
+	const { key, description, model, effort, readOnly, body } = subagent;
+	const fields = {
+		name: key,
+		description
+	};
+	if (typeof model.codex === "string") fields.model = model.codex;
+	if (typeof effort === "string") fields.model_reasoning_effort = effort;
+	const instructions = readOnly ? `${READ_ONLY_INSTRUCTION}\n\n${body}` : body;
+	const parts = [
+		GENERATED_HASH_NOTICE,
+		stringify$1(fields).trimEnd(),
+		renderTomlText("developer_instructions", instructions)
 	];
-	const hasRules = resolution.rules.length > 0;
-	const hasSkills = resolution.skills.length > 0;
-	const hasCommands = resolution.commands.length > 0;
-	const hasMcpServers = resolution.mcp.length > 0;
-	const hasEnv = resolution.env.length > 0;
-	if (hasRules) {
-		const rules = renderRules(resolution.rules);
-		sections.push(rules);
+	if (readOnly) parts.push(stringify$1({ features: { shell_tool: false } }).trimEnd());
+	return `${parts.join("\n\n")}\n`;
+}
+//#endregion
+//#region src/agents/codex/codex-adapter.ts
+const CONFIG_FILE = ".codex/config.toml";
+const CONFIG_SOURCE = "the rules/ and mcp/ folders and env of tunestra.yaml and its presets";
+const EXEC_RULES_FILE = ".codex/rules/tunestra.rules";
+const EXEC_RULES_SOURCE = "permissions in tunestra.yaml and its presets";
+const SUBAGENTS_DIR = ".codex/agents";
+const OVERRIDE_FILE = "AGENTS.override.md";
+const OVERRIDE_SOURCE = `${LOCAL_CONFIG}, ${LOCAL_DIR}/ and the levels in ${INSTRUCTIONS_FILE}`;
+const INSTRUCTIONS_INTRO = "Rules of this project, ordered from specific to general. When two rules conflict, follow the one that comes first.";
+const TRUST_NOTE = "Codex reads .codex/ only in a trusted project: trust the project when Codex asks.";
+/**
+* Codex reads AGENTS.md and the skills in `.agents/skills` by itself. Rules go to
+* `developer_instructions` in `.codex/config.toml`, because Codex does not follow the links
+* in AGENTS.md; MCP servers and env go to the same file. Commands become skills, and
+* permission rules for shell commands become `.codex/rules/tunestra.rules`. Subagents go
+* to `.codex/agents`.
+*/
+const codexAdapter = {
+	agent: Agent.Codex,
+	plan: planCodex,
+	planLocal: planCodexLocal
+};
+function planCodex(context) {
+	const { resolution, ruleFiles } = context;
+	const projectDir = resolution.chain.project.dir;
+	const notes = [];
+	const outputs = [];
+	const commandSkills = resolution.commands.filter((command) => {
+		if (skillName.safeParse(command.artifact.key).success) return true;
+		notes.push(`Codex skips the command "${command.artifact.key}": a skill name needs lowercase letters, digits and single hyphens.`);
+		return false;
+	}).flatMap((command) => planCommandSkill(projectDir, command));
+	outputs.push(...commandSkills);
+	const servers = resolution.mcp.filter((server) => {
+		if (server.artifact.config.type === "sse") {
+			notes.push(`Codex skips the MCP server "${server.artifact.key}": Codex does not support SSE.`);
+			return false;
+		}
+		return true;
+	});
+	const subagentFiles = resolution.subagents.map((subagent) => {
+		return createFileOutput(`${SUBAGENTS_DIR}/${subagent.artifact.key}.toml`, renderSubagentToml(subagent.artifact), describeArtifactSource(projectDir, subagent.origin, subagent.artifact.source));
+	});
+	const readOnlySubagents = resolution.subagents.filter((subagent) => subagent.artifact.readOnly).map((subagent) => subagent.artifact.key);
+	const hasReadOnlySubagents = readOnlySubagents.length > 0;
+	outputs.push(...subagentFiles);
+	if (hasReadOnlySubagents) {
+		const names = readOnlySubagents.join(", ");
+		notes.push(`Codex cannot make subagents read-only: ${names}. It turns off their shell and asks them not to edit files.`);
 	}
-	if (hasSkills) {
-		const skills = renderSkills(resolution.skills);
-		sections.push(skills);
+	const configFile = planConfigFile(ruleFiles, servers, resolution.env);
+	const execRules = planExecRules(resolution.permissions);
+	const ignoredPaths = [];
+	notes.push(...execRules.notes);
+	if (typeof configFile === "object") {
+		outputs.push(configFile);
+		ignoredPaths.push(CONFIG_FILE);
 	}
-	if (hasCommands) {
-		const commands = renderCommands(resolution.commands, resolution.chain.project.agents);
-		sections.push(commands);
+	if (typeof execRules.file === "object") {
+		outputs.push(execRules.file);
+		ignoredPaths.push(EXEC_RULES_FILE);
 	}
-	if (hasMcpServers) {
-		const servers = renderMcpServers(resolution.mcp);
-		sections.push(servers);
+	if (subagentFiles.length > 0) ignoredPaths.push(`${SUBAGENTS_DIR}/`);
+	if (ignoredPaths.length > 0) notes.push(TRUST_NOTE);
+	return {
+		outputs,
+		ignoredPaths,
+		protectedPaths: [],
+		notes,
+		merges: []
+	};
+}
+/**
+* Codex reads `AGENTS.override.md` instead of AGENTS.md in the same folder, so the file
+* holds the whole index with the personal level.
+*/
+function planCodexLocal(context) {
+	const index = renderAgentsIndex(context.local);
+	return {
+		outputs: [createFileOutput(OVERRIDE_FILE, index, OVERRIDE_SOURCE)],
+		ignoredPaths: [OVERRIDE_FILE],
+		merges: []
+	};
+}
+/**
+* `deny` and `ask` rules for Bash commands become prefix rules of Codex. Codex has no rules
+* for files, the web or MCP tools, and `allow` would mean more in Codex, so those are skipped.
+*/
+function planExecRules(permissions) {
+	const execRules = [];
+	const skippedRules = [];
+	const allowRules = [];
+	for (const resolved of permissions) {
+		const { key, decision } = resolved.artifact;
+		if (hasCodexDecision(decision) === false) {
+			allowRules.push(key);
+			continue;
+		}
+		const pattern = convertBashRule(key);
+		if (pattern === void 0) {
+			skippedRules.push(key);
+			continue;
+		}
+		const execRule = createExecRule(resolved, decision, pattern);
+		execRules.push(execRule);
 	}
-	if (hasEnv) {
-		const env = renderEnv(resolution.env);
-		sections.push(env);
+	const notes = [];
+	const hasSkippedRules = skippedRules.length > 0;
+	const hasAllowRules = allowRules.length > 0;
+	if (hasSkippedRules) {
+		const rules = skippedRules.join(", ");
+		notes.push(`Codex skips permission rules that it cannot enforce: ${rules}. Codex rules match only the start of a shell command.`);
 	}
-	sections.push(CHANGING_SECTION);
-	return `${sections.join("\n\n")}\n`;
+	if (hasAllowRules) {
+		const rules = allowRules.join(", ");
+		notes.push(`Codex skips allow rules: ${rules}. In Codex, an allowed command runs outside the sandbox without asking.`);
+	}
+	if (execRules.length > 0) {
+		const content = renderExecRules(execRules);
+		return {
+			file: createFileOutput(EXEC_RULES_FILE, content, EXEC_RULES_SOURCE),
+			notes
+		};
+	}
+	return {
+		file: void 0,
+		notes
+	};
+}
+function planConfigFile(ruleFiles, servers, env) {
+	const hasRules = ruleFiles.length > 0;
+	const hasServers = servers.length > 0;
+	const hasEnv = env.length > 0;
+	if (hasRules === false && hasServers === false && hasEnv === false) return;
+	const content = renderConfigToml({
+		instructions: hasRules ? renderInstructions(ruleFiles) : void 0,
+		servers,
+		env
+	});
+	return createFileOutput(CONFIG_FILE, content, CONFIG_SOURCE);
+}
+/** The rule files as they are, with the header that names the source of each. */
+function renderInstructions(ruleFiles) {
+	const rules = ruleFiles.map((file) => file.content.trimEnd());
+	return `${[INSTRUCTIONS_INTRO, ...rules].join("\n\n")}\n`;
 }
 //#endregion
+//#region src/agents/adapters.ts
+/** Every supported agent. */
+const AGENT_ADAPTERS = {
+	[Agent.Claude]: claudeAdapter,
+	[Agent.Codex]: codexAdapter
+};
+//#endregion
 //#region src/generate/plan-setup.ts
 /**
-* Builds every output without touching the disk: the shared files that any agent can read
-* (AGENTS.md, `.agents/`), then the native files of each agent of the project.
+* Builds every output without touching the disk. Without a personal level, it is the plan
+* of the shared chain. With one, the committed files still come from the shared chain, so
+* that they are the same for the whole team; the other files come from the chain with the
+* personal level, and every agent adds the files that tell it about the personal level.
 */
-function planSetup(resolution) {
+function planSetup(shared, local) {
+	const sharedPlan = planChain(shared);
+	if (local === void 0) return finishPlan(sharedPlan);
+	const localPlan = planChain(local);
+	const committedPaths = sharedPlan.protectedPaths;
+	const sharedOutputs = sharedPlan.outputs.filter((output) => committedPaths.includes(output.path));
+	const localOutputs = localPlan.outputs.filter((output) => localPlan.protectedPaths.includes(output.path) === false);
+	const outputs = [...sharedOutputs, ...localOutputs];
+	const ignoredPaths = [...localPlan.ignoredPaths];
+	const merges = [];
+	const context = {
+		shared,
+		local
+	};
+	for (const agent of local.chain.project.agents) {
+		const agentPlan = AGENT_ADAPTERS[agent].planLocal(context);
+		outputs.push(...agentPlan.outputs);
+		ignoredPaths.push(...agentPlan.ignoredPaths);
+		merges.push(...agentPlan.merges);
+	}
+	return finishPlan({
+		outputs,
+		ignoredPaths,
+		protectedPaths: committedPaths,
+		notes: localPlan.notes,
+		merges
+	});
+}
+/** The shared files that any agent can read (AGENTS.md, `.agents/`), then each agent. */
+function planChain(resolution) {
 	const projectDir = resolution.chain.project.dir;
 	const index = renderAgentsIndex(resolution);
 	const indexFile = createFileOutput(INSTRUCTIONS_FILE, index, SETUP_SOURCE);
@@ -1779,14 +2248,30 @@ function planSetup(resolution) {
 		protectedPaths.push(...agentPlan.protectedPaths);
 		notes.push(...agentPlan.notes);
 	}
-	ignoredPaths.push(`${STATE_DIR}/`);
-	const problems = findPathConflicts(outputs);
-	if (problems.length > 0) throw createProblemsError(problems);
 	return {
 		outputs,
 		ignoredPaths,
 		protectedPaths,
-		notes
+		notes,
+		merges: []
+	};
+}
+/**
+* The sources of the personal level are always ignored, so that nobody commits them by
+* mistake; so is the state.
+*/
+function finishPlan(plan) {
+	const ignoredPaths = [
+		...plan.ignoredPaths,
+		LOCAL_CONFIG,
+		`${LOCAL_DIR}/`,
+		`${STATE_DIR}/`
+	];
+	const problems = findPathConflicts(plan.outputs);
+	if (problems.length > 0) throw createProblemsError(problems);
+	return {
+		...plan,
+		ignoredPaths
 	};
 }
 function planRuleFile(projectDir, rule) {
@@ -1830,6 +2315,7 @@ const ArtifactKind = {
 	Skills: "skills",
 	Commands: "commands",
 	Mcp: "mcp",
+	Subagents: "subagents",
 	Env: "env"
 };
 //#endregion
@@ -2024,6 +2510,7 @@ function applyInheritance(chain) {
 	const skills = inheritArtifacts(chain.levels, ArtifactKind.Skills, (level) => level.skills);
 	const commands = inheritArtifacts(chain.levels, ArtifactKind.Commands, (level) => level.commands);
 	const mcp = inheritArtifacts(chain.levels, ArtifactKind.Mcp, (level) => level.mcp, patchMcpServers);
+	const subagents = inheritArtifacts(chain.levels, ArtifactKind.Subagents, (level) => level.subagents);
 	const env = inheritArtifacts(chain.levels, ArtifactKind.Env, (level) => level.env);
 	const permissions = inheritPermissions(chain.levels);
 	const problems = [
@@ -2031,6 +2518,7 @@ function applyInheritance(chain) {
 		...skills.problems,
 		...commands.problems,
 		...mcp.problems,
+		...subagents.problems,
 		...env.problems,
 		...permissions.problems
 	];
@@ -2041,6 +2529,7 @@ function applyInheritance(chain) {
 		skills: skills.artifacts,
 		commands: commands.artifacts,
 		mcp: mcp.artifacts,
+		subagents: subagents.artifacts,
 		env: env.artifacts,
 		permissions: permissions.artifacts
 	};
@@ -2049,9 +2538,20 @@ function applyInheritance(chain) {
 //#region src/shared/schemas/state.ts
 const fileRecordSchema = z.strictObject({ hash: z.string() });
 const symlinkRecordSchema = z.strictObject({ target: z.string() });
+const ruleList = z.array(z.string()).readonly();
+const settingsEntriesSchema = z.strictObject({
+	env: z.record(z.string(), z.string()),
+	permissions: z.strictObject({
+		allow: ruleList,
+		ask: ruleList,
+		deny: ruleList
+	})
+});
 const stateSchema = z.strictObject({
 	version: z.literal(1),
-	outputs: z.record(z.string(), z.union([fileRecordSchema, symlinkRecordSchema]))
+	outputs: z.record(z.string(), z.union([fileRecordSchema, symlinkRecordSchema])),
+	/** Older states have no merges. */
+	merges: z.record(z.string(), settingsEntriesSchema).default({})
 });
 //#endregion
 //#region src/state/read-state.ts
@@ -2060,15 +2560,16 @@ async function readState(projectDir) {
 	const file = join(projectDir, STATE_FILE);
 	const content = await readFileIfExists(file);
 	if (content === void 0) return createEmptyState();
-	return validate(parseJson$1(content, file), stateSchema, `state file ${file}. Delete it and run tunestra setup again`);
+	return validate(parseJson$2(content, file), stateSchema, `state file ${file}. Delete it and run tunestra setup again`);
 }
 function createEmptyState() {
 	return {
 		version: 1,
-		outputs: {}
+		outputs: {},
+		merges: {}
 	};
 }
-function parseJson$1(content, file) {
+function parseJson$2(content, file) {
 	try {
 		return JSON.parse(content);
 	} catch (error) {
@@ -2116,16 +2617,21 @@ async function removeSymlink(path) {
 async function writeState(projectDir, state) {
 	const file = join(projectDir, STATE_FILE);
 	const dir = dirname(file);
-	const entries = Object.keys(state.outputs).sort().map((path) => [path, state.outputs[path]]);
-	const outputs = Object.fromEntries(entries);
+	const outputs = sortByKey(state.outputs);
+	const merges = sortByKey(state.merges);
 	const content = {
 		version: state.version,
-		outputs
+		outputs,
+		merges
 	};
 	const text = `${JSON.stringify(content, null, 2)}\n`;
 	await mkdir(dir, { recursive: true });
 	await writeFile(file, text);
 }
+function sortByKey(record) {
+	const sorted = Object.entries(record).toSorted(([left], [right]) => left < right ? -1 : 1);
+	return Object.fromEntries(sorted);
+}
 //#endregion
 //#region src/sync/remove-outputs.ts
 /** Removes stale outputs, then the directories that they leave empty. */
@@ -2188,10 +2694,10 @@ async function createRecord(output) {
 * object has no keys that tunestra could own, so the result is `undefined`.
 */
 async function findForeignKeys(path, ownedKeys) {
-	const data = parseJson(await readFile(path, "utf8"));
+	const data = parseJson$1(await readFile(path, "utf8"));
 	if (isKeyValueMap(data)) return Object.keys(data).filter((key) => ownedKeys.includes(key) === false);
 }
-function parseJson(text) {
+function parseJson$1(text) {
 	try {
 		return JSON.parse(text);
 	} catch (error) {
@@ -2300,6 +2806,117 @@ function createStaleCheck(path, isRemovable, warning) {
 	};
 }
 //#endregion
+//#region src/sync/merge-settings.ts
+const DECISIONS = Object.values(PermissionDecision);
+/**
+* The settings of people with the entries of setup: the entries from the last setup are
+* taken out, the new ones are added. A variable that someone changed after setup wrote it
+* is theirs now and stays. Other keys keep their order.
+*/
+function mergeSettings(current, previous, next) {
+	const result = { ...current };
+	const env = mergeEnv(current.env, previous, next);
+	const permissions = mergePermissions(current.permissions, previous, next);
+	setOrDelete(result, "env", env);
+	setOrDelete(result, "permissions", permissions);
+	return result;
+}
+function mergeEnv(current, previous, next) {
+	const env = isKeyValueMap(current) ? { ...current } : {};
+	const previousEnv = previous?.env ?? {};
+	const previousEntries = Object.entries(previousEnv);
+	for (const [name, value] of previousEntries) if (env[name] === value) delete env[name];
+	const nextEnv = next?.env ?? {};
+	return {
+		...env,
+		...nextEnv
+	};
+}
+function mergePermissions(current, previous, next) {
+	const permissions = isKeyValueMap(current) ? { ...current } : {};
+	for (const decision of DECISIONS) {
+		const list = permissions[decision];
+		const rules = Array.isArray(list) ? list : [];
+		const previousRules = previous?.permissions[decision] ?? [];
+		const nextRules = next?.permissions[decision] ?? [];
+		const keptRules = rules.filter((rule) => previousRules.includes(rule) === false);
+		const addedRules = nextRules.filter((rule) => keptRules.includes(rule) === false);
+		setOrDelete(permissions, decision, [...keptRules, ...addedRules]);
+	}
+	return permissions;
+}
+/** An empty list or object is left out, as if nobody had written it. */
+function setOrDelete(target, key, value) {
+	const isEmptyList = Array.isArray(value) && value.length === 0;
+	const isEmptyRecord = isKeyValueMap(value) && Object.keys(value).length === 0;
+	if (isEmptyList || isEmptyRecord) {
+		delete target[key];
+		return;
+	}
+	target[key] = value;
+}
+//#endregion
+//#region src/sync/plan-merges.ts
+/**
+* Adds the entries of every merge to its file and takes the entries of the last setup out,
+* also from files that this setup does not merge into any more. Reads the disk only.
+*/
+async function planMerges(projectDir, merges, previous) {
+	const paths = new Set(merges.map((merge) => merge.path));
+	const stalePaths = Object.keys(previous).filter((path) => paths.has(path) === false);
+	const nextSteps = merges.map((merge) => ({
+		path: merge.path,
+		source: merge.source,
+		next: merge.entries
+	}));
+	const staleSteps = stalePaths.map((path) => ({
+		path,
+		source: "the last setup",
+		next: void 0
+	}));
+	const results = await mapSettled([...nextSteps, ...staleSteps], (step) => planMerge(projectDir, step, previous));
+	const writes = results.map((result) => result.write).filter((write) => write !== void 0);
+	const removals = results.map((result) => result.removal).filter((removal) => removal !== void 0);
+	const recordEntries = merges.map((merge) => [merge.path, merge.entries]);
+	return {
+		writes,
+		removals,
+		records: Object.fromEntries(recordEntries)
+	};
+}
+async function planMerge(projectDir, step, previous) {
+	const content = await readFileIfExists(join(projectDir, step.path));
+	const current = content === void 0 ? {} : parseSettings(content, step.path);
+	const merged = mergeSettings(current, previous[step.path], step.next);
+	const isEmpty = Object.keys(merged).length === 0;
+	const isUnchanged = JSON.stringify(merged) === JSON.stringify(current);
+	if (isEmpty) return {
+		write: void 0,
+		removal: content === void 0 ? void 0 : step.path
+	};
+	if (isUnchanged && content !== void 0) return {
+		write: void 0,
+		removal: void 0
+	};
+	const json = JSON.stringify(merged, null, 2);
+	return {
+		write: createFileOutput(step.path, `${json}\n`, step.source),
+		removal: void 0
+	};
+}
+function parseSettings(content, path) {
+	const data = parseJson(content, path);
+	if (isKeyValueMap(data) === false) throw new TunestraError(`${path} is not a JSON object, so setup cannot add its settings. Fix or delete it and run tunestra setup again`);
+	return data;
+}
+function parseJson(content, path) {
+	try {
+		return JSON.parse(content);
+	} catch (error) {
+		throw new TunestraError(`${path} is not valid JSON: ${getErrorMessage(error)}. Fix or delete it and run tunestra setup again`);
+	}
+}
+//#endregion
 //#region src/sync/plan-sync.ts
 /** Reads the disk, but writes nothing; problems of every output are reported together. */
 async function planSync(projectDir, plan, previous) {
@@ -2312,16 +2929,18 @@ async function planSync(projectDir, plan, previous) {
 	const outputPaths = new Set(paths);
 	const staleEntries = Object.entries(previous.outputs).filter(([path]) => outputPaths.has(path) === false);
 	const outputChecks = await mapSettled(plan.outputs, (output) => checkOutput(output, context));
+	const mergePlan = await planMerges(projectDir, plan.merges, previous.merges);
 	const staleChecks = await mapSettled(staleEntries, ([path, record]) => checkStaleOutput(projectDir, path, record));
-	const removals = staleChecks.filter((check) => check.isRemovable).map((check) => check.path);
+	const removals = [...staleChecks.filter((check) => check.isRemovable).map((check) => check.path), ...mergePlan.removals];
 	const warnings = [...outputChecks, ...staleChecks].map((check) => check.warning).filter(isString);
 	const recordEntries = outputChecks.map((check) => [check.path, check.record]);
 	const state = {
 		version: 1,
-		outputs: Object.fromEntries(recordEntries)
+		outputs: Object.fromEntries(recordEntries),
+		merges: mergePlan.records
 	};
 	return {
-		outputs: plan.outputs,
+		outputs: [...plan.outputs, ...mergePlan.writes],
 		removals,
 		warnings,
 		state
@@ -2375,8 +2994,11 @@ async function updateGitignoreFile(projectDir, paths) {
 */
 async function runSetup(projectDir, options) {
 	const chain = await loadChain(projectDir);
-	const resolution = applyInheritance(chain);
-	const plan = planSetup(resolution);
+	const localChain = await loadLocalChain(chain);
+	const sharedResolution = applyInheritance(chain);
+	const localResolution = localChain === void 0 ? void 0 : applyInheritance(localChain);
+	const resolution = localResolution ?? sharedResolution;
+	const plan = planSetup(sharedResolution, localResolution);
 	const previous = await readState(chain.project.dir);
 	const sync = await planSync(chain.project.dir, plan, previous);
 	const report = {
@@ -2400,6 +3022,7 @@ function describeResolution(resolution) {
 		describeSection("Skills", resolution.skills, projectDir),
 		describeSection("Commands", resolution.commands, projectDir),
 		describeSection("MCP servers", resolution.mcp, projectDir),
+		describeSection("Subagents", resolution.subagents, projectDir),
 		describeSection("Environment", resolution.env, projectDir),
 		describeSection("Permissions", permissions, projectDir)
 	].filter((section) => section.length > 0).join("\n\n");
@@ -2497,25 +3120,26 @@ async function removeGitignoreBlockFile(projectDir) {
 async function runUninstall(projectDir, options) {
 	const state = await readState(projectDir);
 	const checks = await mapSettled(Object.entries(state.outputs), ([path, record]) => checkStaleOutput(projectDir, path, record));
-	const removals = checks.filter((check) => check.isRemovable).map((check) => check.path);
-	const warnings = checks.map((check) => check.warning).filter(isString);
-	if (options.dryRun) return {
+	const removable = checks.filter((check) => check.isRemovable);
+	const mergePlan = await planMerges(projectDir, [], state.merges);
+	const removals = [...removable.map((check) => check.path), ...mergePlan.removals];
+	const report = {
 		removals,
-		warnings
+		updates: mergePlan.writes.map((write) => write.path),
+		warnings: checks.map((check) => check.warning).filter(isString)
 	};
+	if (options.dryRun) return report;
 	const stateDir = join(projectDir, STATE_DIR);
 	const tunestraDir = join(projectDir, PROJECT_DIR);
 	await removeOutputs(projectDir, removals);
+	await writeOutputs(projectDir, mergePlan.writes);
 	await removeGitignoreBlockFile(projectDir);
 	await rm(stateDir, {
 		recursive: true,
 		force: true
 	});
 	await removeDirIfEmpty(tunestraDir);
-	return {
-		removals,
-		warnings
-	};
+	return report;
 }
 //#endregion
 //#region src/cli/commands/uninstall.ts
@@ -2526,12 +3150,14 @@ async function describeUninstall(projectDir, options) {
 	const count = report.removals.length;
 	if (options.dryRun) {
 		const removals = report.removals.map((path) => `  remove  ${path}`);
-		lines.push(...removals, "", "Nothing was removed (--dry-run).");
+		const updates = report.updates.map((path) => `  update  ${path}`);
+		lines.push(...removals, ...updates, "", "Nothing was removed (--dry-run).");
 		return lines.join("\n");
 	}
 	const check = pc.green("✔");
 	lines.push(`${check} Removed ${count} generated files and the tunestra block in .gitignore.`);
-	lines.push("tunestra.yaml and .tunestra/ are kept: they are your sources.");
+	for (const path of report.updates) lines.push(`Took the settings of tunestra out of ${path}; your settings stay.`);
+	lines.push("tunestra.yaml, tunestra.local.yaml and their folders are kept: they are your sources.");
 	return lines.join("\n");
 }
 //#endregion
@@ -2554,9 +3180,12 @@ async function runCommand(action) {
 //#endregion
 //#region src/cli/index.ts
 const program = new Command().name("tunestra").description("Tune your AI agents to play as one orchestra.").version(VERSION);
-program.command("init").description("Create tunestra.yaml and move hand-written AGENTS.md and CLAUDE.md to .tunestra/").option("--extends <presets...>", "presets to extend, from general to specific", []).action(async (options) => {
+program.command("init").description("Create tunestra.yaml and move hand-written AGENTS.md and CLAUDE.md to .tunestra/").option("--extends <presets...>", "presets to extend, from general to specific", []).option("--local", "create only your personal level: tunestra.local.yaml and .tunestra.local/", false).action(async (options) => {
 	const projectDir = process.cwd();
-	const initOptions = { presets: options.extends };
+	const initOptions = {
+		presets: options.extends,
+		local: options.local
+	};
 	await runCommand(() => describeInit(projectDir, initOptions));
 });
 program.command("setup").description("Generate agent configuration from tunestra.yaml and its presets").option("--dry-run", "show the plan without writing files", false).option("-v, --verbose", "show where every artifact comes from", false).action(async (options) => {