tunestra 0.1.1 → 0.3.0

package/README.md

@@ -9,11 +9,12 @@
 > Tune your AI agents to play as one orchestra.
 
 > [!WARNING]
-> **Early version.** v0.1 supports Claude Code; Codex comes in v0.2. The formats may still
-> change before v1.0.
+> **Early version.** tunestra supports Claude Code and Codex. The formats may still change
+> before v1.0.
 
 tunestra gives Claude Code, Codex and other AI coding agents **one shared source** of rules,
-skills, commands and MCP servers, and generates each agent's native configuration from it.
+skills, commands, MCP servers and environment variables, and generates each agent's native
+configuration from it.
 
 The source is a chain of **presets**, from general to specific:
 
@@ -33,7 +34,7 @@ specific one wins.
 
 ```sh
 npx tunestra init --extends github:<organisation_name>/<presets_repo>/team#v1
-npx tunestra setup    # generates AGENTS.md, CLAUDE.md, .claude/, .agents/, .mcp.json
+npx tunestra setup    # generates AGENTS.md and the configuration of every agent
 ```
 
 `init` creates `tunestra.yaml`:
@@ -41,11 +42,12 @@ npx tunestra setup    # generates AGENTS.md, CLAUDE.md, .claude/, .agents/, .mcp
 ```yaml
 extends:
   - github:<organisation_name>/<presets_repo>/team#v1
-agents: [claude]
+agents: [claude]            # add codex: [claude, codex]
 ```
 
-Commit `tunestra.yaml`, `.tunestra/`, `AGENTS.md` and `CLAUDE.md`. Everything else that
-tunestra generates is listed in `.gitignore` automatically.
+Commit `tunestra.yaml`, `.tunestra/`, `AGENTS.md`, `CLAUDE.md` and, when presets set `env`,
+`.claude/settings.json`. Everything else that tunestra generates is listed in `.gitignore`
+automatically.
 
 ## Principles
 
@@ -86,6 +88,8 @@ overrides:                  # optional: patch inherited MCP servers
     tracker:
       env:
         QUEUE: TEAM
+env:                        # optional: environment variables of the agents
+  MCP_TIMEOUT: 120000
 ```
 
 ### Project: `tunestra.yaml`
@@ -97,7 +101,7 @@ as a preset.
 name: my-service            # optional, defaults to the directory name
 extends:
   - ../presets/team
-agents: [claude]            # v0.1 supports claude
+agents: [claude, codex]     # claude, codex; defaults to [claude]
 exclude: {}
 overrides: {}
 ```
@@ -116,7 +120,7 @@ repository with a relative path, like `../base`. A relative path cannot leave th
 Git is not needed: repositories are downloaded as archives over HTTPS.
 
 For a private repository, set the `TUNESTRA_GIT_TOKEN` environment variable to a token with
-read access. Lockfiles and npm sources are planned for v0.3.
+read access. Lockfiles and npm sources are planned for v0.4.
 
 ## Inheritance
 
@@ -136,6 +140,7 @@ chain once, before both of them.
 | Skill | `name` from `SKILL.md`, otherwise the folder name | replaces it | `exclude.skills` |
 | Command | file name without `.md` | replaces it | `exclude.commands` |
 | MCP server | file name without `.yaml` | replaces it | `exclude.mcp` |
+| Environment variable | name in `env` | replaces it | `exclude.env` |
 
 `overrides.mcp.<key>` patches an inherited server instead of replacing it: `env` and `headers`
 are merged by key (the specific value wins); `command`, `args` and `url` are replaced.
@@ -149,24 +154,65 @@ are merged by key (the specific value wins); `command`, `args` and `url` are rep
 - two levels have the same name;
 - a manifest has an unknown field or a missing required field;
 - `exclude` or `overrides` refers to a key that is not inherited;
-- after a patch, an MCP server has both `command` and `url`, or neither.
+- after a patch, an MCP server has both `command` and `url`, or neither;
+- an `env` value refers to another variable, like `${TOKEN}`: agents do not expand it in
+  their settings, so write the value itself and keep secrets out of presets;
+- `env` sets a variable that Claude Code ignores in project settings (see below).
 
 All problems are reported at once, in the order of the files, so you can fix them in one pass.
 
-## What gets generated (Claude Code)
+## What gets generated
+
+For every agent:
 
 | Path | Content | Committed |
 |---|---|---|
 | `AGENTS.md` | Index: hierarchy, rules, skills, commands, MCP servers | yes |
-| `CLAUDE.md` | `@AGENTS.md` | yes |
 | `.agents/rules/<NN>-<level>-<key>.md` | Rule texts, ordered from specific to general | no |
 | `.agents/skills/<key>/` | Skills | no |
+| `.tunestra/state/` | What tunestra generated last time | no |
+| `.gitignore` | A block between `# >>> tunestra` and `# <<< tunestra` | yes |
+
+### Claude Code
+
+| Path | Content | Committed |
+|---|---|---|
+| `CLAUDE.md` | `@AGENTS.md` | yes |
 | `.claude/rules/tunestra/<NN>-<level>-<key>.md` | Copies of the rules; Claude Code loads them in every session | no |
 | `.claude/skills/<key>` | Symlinks to `.agents/skills/<key>` | no |
 | `.claude/commands/<key>.md` | Commands | no |
 | `.mcp.json` | MCP servers | no |
-| `.tunestra/state/` | What tunestra generated last time | no |
-| `.gitignore` | A block between `# >>> tunestra` and `# <<< tunestra` | yes |
+| `.claude/settings.json` | `env`, when presets set it | yes |
+
+`.claude/settings.json` is shared by the team, so tunestra writes it and you commit it. Keep
+your personal settings in `.claude/settings.local.json` or `~/.claude/settings.json`. A
+`.claude/settings.json` with other keys, like `hooks` or `model`, stops setup and asks you to
+move them; a file with only `$schema` and `env` is replaced with a warning, for example in a
+fresh clone where `.tunestra/state/` does not exist yet.
+
+Claude Code applies project `env` after you trust the folder. It ignores some variables in
+project settings: the ones that turn telemetry on or choose where it goes
+(`CLAUDE_CODE_ENABLE_TELEMETRY`, `OTEL_*_EXPORTER`, `OTEL_EXPORTER_OTLP_*` and others), and
+the ones that choose its own directories (`HOME`, `XDG_*`, `CLAUDE_CONFIG_DIR`). setup stops
+on them, because they would not work; set them in managed settings, `~/.claude/settings.json`
+or your shell. Values that turn telemetry off, like `OTEL_LOGS_EXPORTER: none`, are allowed.
+
+### Codex
+
+Codex reads `AGENTS.md` and `.agents/skills/` by itself. It does not follow the links in
+`AGENTS.md`, so tunestra gives it the rule texts in its config.
+
+| Path | Content | Committed |
+|---|---|---|
+| `.codex/config.toml` | `developer_instructions` with every rule, from specific to general, `[shell_environment_policy] set` with `env`, and `[mcp_servers]` | no |
+| `.agents/skills/<command>/` | Each command as a skill that runs only when you call it: `$release-notes` | no |
+
+Codex reads `.codex/config.toml` only in a trusted project: trust the project when Codex asks.
+Codex gets `env` as the environment of the commands it runs; it does not change how Codex
+itself works, and Codex ignores telemetry settings in a project.
+Codex has no `type` for MCP servers and does not support SSE: an SSE server is skipped with a
+note, and `headers` become `http_headers`. tunestra owns the whole `.codex/config.toml`; keep
+your personal Codex settings in `~/.codex/config.toml`.
 
 `<NN>` orders rules from specific to general: `10` project, `20` team, `30` domain, `40` base.
 Level instructions get the key `instructions`, and the preset name when it differs from the
@@ -180,7 +226,9 @@ Every generated rule starts with its origin:
 > Level: team, preset: team. Overrides: base.
 ```
 
-Skills and commands are copied as is: their frontmatter must stay on the first line.
+Skills and commands are copied as is: their frontmatter must stay on the first line. For
+Codex, a command gets only `name` and `description` in its frontmatter; other fields, like
+`argument-hint`, are for Claude Code.
 
 ## Running setup again
 
@@ -214,14 +262,15 @@ and tells you where to move their text.
 
 | Release | Scope |
 |---|---|
-| v0.1 | Inheritance for Claude Code (this document) |
-| v0.2 | Codex |
-| v0.3 | Spaces, npm sources, lockfile |
-| v0.4 | `required` / `locked` policies, CI check |
-| v0.5 | Hooks |
-| v0.6 | LLM gateway, permissions |
-| v0.7 | Local plugins |
-| v0.8 | Isolated remote plugins |
+| v0.1 | Inheritance for Claude Code |
+| v0.2 | Codex (this document) |
+| v0.3 | `env`, then permissions, subagents and a personal `local` level |
+| v0.4 | Spaces, npm sources, lockfile |
+| v0.5 | `required` / `locked` policies, CI check |
+| v0.6 | Hooks |
+| v0.7 | LLM gateway |
+| v0.8 | Local plugins |
+| v0.9 | Isolated remote plugins |
 
 ## License
 

package/dist/cli.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
-import { t as VERSION } from "./src-Dmt0_5_W.mjs";
+import { t as VERSION } from "./src-BNeh64fK.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";
 import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
 import { glob } from "tinyglobby";
 import { prettifyError, z } from "zod";
-import { parse } from "yaml";
+import { parse, stringify } from "yaml";
 import { downloadTemplate } from "giget";
+import { stringify as stringify$1 } from "smol-toml";
 import { createHash } from "node:crypto";
 //#region src/shared/constants/files.ts
 /** Preset manifest, in the root of every preset. */
@@ -32,6 +33,11 @@ const OutputKind = {
 /** First line of every generated markdown file; tunestra recognizes its files by it. */
 const GENERATED_MARKER = "<!-- Generated by tunestra";
 const GENERATED_NOTICE = `${GENERATED_MARKER}. Do not edit: change the sources and run \`tunestra setup\`. -->`;
+/** The same marker for generated TOML and YAML files, where a comment starts with `#`. */
+const GENERATED_HASH_MARKER = "# Generated by tunestra";
+const GENERATED_HASH_NOTICE = `${GENERATED_HASH_MARKER}. Do not edit: change the sources and run \`tunestra setup\`.`;
+/** Every marker that tunestra puts on the first line of a generated file. */
+const GENERATED_MARKERS = [GENERATED_MARKER, GENERATED_HASH_MARKER];
 /** Shared output that any agent can read. */
 const AGENTS_DIR = ".agents";
 /** Rules for every agent, ordered from specific to general by their file names. */
@@ -155,7 +161,10 @@ async function removeDirIfEmpty(dir) {
 //#endregion
 //#region src/shared/constants/agents.ts
 /** Agents that tunestra generates configuration for. */
-const Agent = { Claude: "claude" };
+const Agent = {
+	Claude: "claude",
+	Codex: "codex"
+};
 //#endregion
 //#region src/init/render-config.ts
 const EXTENDS_EXAMPLE = "#   - github:<owner>/<repo>/<path>#<ref>";
@@ -294,12 +303,48 @@ function isKeyValueMap(value) {
 //#region src/shared/schemas/preset.ts
 const keys = z.array(z.string().min(1)).readonly();
 const stringMap = z.record(z.string(), z.string());
-const skillName = z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "Use lowercase letters, digits and single hyphens").max(64);
+/**
+* Agent Skills naming rule; the name also becomes a directory name.
+*
+* Valid:   "code-review", "storybook", "v2"
+* Invalid: "Code-Review" (uppercase), "code--review" or "-review" (wrong hyphens), "../../etc"
+*/
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+* A name of an environment variable.
+*
+* Valid:   "MCP_TIMEOUT", "http_proxy", "_PRIVATE"
+* Invalid: "1PASSWORD" (starts with a digit), "MY-VAR" (hyphen), "" (empty)
+*/
+const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* A reference to another variable, which agents do not expand in their settings.
+*
+* Matches:        "${TOKEN}", "Bearer ${TOKEN}"
+* Does not match: "$TOKEN", "price: 5$", "{TOKEN}"
+*/
+const ENV_REFERENCE_PATTERN = /\$\{[^}]*\}/;
+/** YAML reads `MCP_TIMEOUT: 120000` as a number; agents need every value as text. */
+const envValue = z.union([
+	z.string(),
+	z.number(),
+	z.boolean()
+]).transform(String).refine((value) => ENV_REFERENCE_PATTERN.test(value) === false, { message: `Agents do not expand \${…} in their settings: write the value itself, and keep secrets out of presets` });
+const envSchema = z.record(z.string(), envValue).superRefine((env, context) => {
+	const names = Object.keys(env);
+	for (const name of names) if (ENV_NAME_PATTERN.test(name) === false) context.addIssue({
+		code: "custom",
+		message: `"${name}" is not a variable name: use letters, digits and "_", and do not start with a digit`,
+		path: [name]
+	});
+});
+const skillName = z.string().regex(SKILL_NAME_PATTERN, "Use lowercase letters, digits and single hyphens").max(64);
 const excludeSchema = z.strictObject({
 	rules: keys.optional(),
 	skills: keys.optional(),
 	commands: keys.optional(),
-	mcp: keys.optional()
+	mcp: keys.optional(),
+	env: keys.optional()
 });
 const mcpPatchSchema = z.strictObject({
 	command: z.string().optional(),
@@ -315,14 +360,16 @@ const presetManifestSchema = z.strictObject({
 	description: z.string().optional(),
 	extends: z.array(z.string().min(1)).readonly().default([]),
 	exclude: excludeSchema.default({}),
-	overrides: overridesSchema.default({})
+	overrides: overridesSchema.default({}),
+	env: envSchema.default({})
 });
 const projectConfigSchema = z.strictObject({
 	name: z.string().min(1).optional(),
 	extends: z.array(z.string().min(1)).readonly().default([]),
 	agents: z.array(z.enum(Agent)).min(1).readonly().default([Agent.Claude]),
 	exclude: excludeSchema.default({}),
-	overrides: overridesSchema.default({})
+	overrides: overridesSchema.default({}),
+	env: envSchema.default({})
 });
 const mcpServerSchema = z.strictObject({
 	description: z.string().optional(),
@@ -446,13 +493,14 @@ async function loadCommands(dir) {
 async function loadCommand(dir, source) {
 	const file = join(dir, source);
 	const content = await readFile(file, "utf8");
-	const { data } = parseFrontmatter(content, file);
+	const { data, body } = parseFrontmatter(content, file);
 	const frontmatter = validate(data, commandFrontmatterSchema, `frontmatter in ${file}`);
 	return {
 		key: basename(source, ".md"),
 		source,
 		description: frontmatter.description,
-		content
+		content,
+		body
 	};
 }
 //#endregion
@@ -567,6 +615,26 @@ async function loadArtifacts(dir, presetName) {
 	};
 }
 //#endregion
+//#region src/shared/utils/paths.ts
+/** Generated files always use `/`, so they are the same on every system. */
+function toPosixPath(path) {
+	return path.split(sep).join("/");
+}
+function relativePosix(from, to) {
+	return toPosixPath(relative(from, to));
+}
+//#endregion
+//#region src/presets/env.ts
+/** The `env` map of a manifest as artifacts, in the order of the file. */
+function createEnvVariables(env, manifestPath, artifactsDir) {
+	const source = relativePosix(artifactsDir, manifestPath);
+	return Object.entries(env).map(([key, value]) => ({
+		key,
+		source,
+		value
+	}));
+}
+//#endregion
 //#region src/presets/load-project.ts
 async function loadProject(dir) {
 	const root = resolve(dir);
@@ -577,6 +645,7 @@ async function loadProject(dir) {
 	const name = config.name ?? folderName;
 	const artifactsDir = join(root, PROJECT_DIR);
 	const artifacts = await loadArtifacts(artifactsDir, name);
+	const env = createEnvVariables(config.env, configPath, artifactsDir);
 	return {
 		...config,
 		name,
@@ -585,19 +654,11 @@ async function loadProject(dir) {
 		dir: root,
 		artifactsDir,
 		remote: void 0,
-		...artifacts
+		...artifacts,
+		env
 	};
 }
 //#endregion
-//#region src/shared/utils/paths.ts
-/** Generated files always use `/`, so they are the same on every system. */
-function toPosixPath(path) {
-	return path.split(sep).join("/");
-}
-function relativePosix(from, to) {
-	return toPosixPath(relative(from, to));
-}
-//#endregion
 //#region src/sources/parse-git-source.ts
 /**
 * A reference to a preset in a git repository.
@@ -799,13 +860,15 @@ async function loadPreset(dir) {
 	if (await checkExists(manifestPath) === false) throw new TunestraError(`${root} is not a preset: ${PRESET_MANIFEST} is missing`);
 	const manifest = await readYaml(manifestPath, presetManifestSchema, "preset manifest");
 	const artifacts = await loadArtifacts(root, manifest.name);
+	const env = createEnvVariables(manifest.env, manifestPath, root);
 	return {
 		...manifest,
 		description: manifest.description,
 		dir: root,
 		artifactsDir: root,
 		remote: void 0,
-		...artifacts
+		...artifacts,
+		env
 	};
 }
 //#endregion
@@ -886,6 +949,87 @@ function createFileOutput(path, content, source) {
 	};
 }
 //#endregion
+//#region src/agents/claude/ignored-env.ts
+/**
+* Variables that Claude Code drops from project settings, because a repository should not
+* control them: https://code.claude.com/docs/en/settings-reference#variables-claude-code-ignores-in-env
+*/
+const IGNORED_NAMES = /* @__PURE__ */ new Set([
+	"CLAUDE_CONFIG_DIR",
+	"CLAUDE_CODE_TMPDIR",
+	"HOME",
+	"TMPDIR",
+	"TMP",
+	"TEMP",
+	"SystemRoot",
+	"ComSpec",
+	"ProgramData",
+	"LOCALAPPDATA",
+	"PATHEXT",
+	"PSModulePath",
+	"OTEL_LOG_RAW_API_BODIES",
+	"ENABLE_BETA_TRACING_DETAILED",
+	"BETA_TRACING_ENDPOINT",
+	"CLAUDE_CODE_ENABLE_TELEMETRY",
+	"CLAUDE_CODE_ENHANCED_TELEMETRY_BETA",
+	"ENABLE_ENHANCED_TELEMETRY_BETA",
+	"OTEL_LOGS_EXPORTER",
+	"OTEL_METRICS_EXPORTER",
+	"OTEL_TRACES_EXPORTER",
+	"OTEL_LOG_USER_PROMPTS",
+	"OTEL_LOG_ASSISTANT_RESPONSES",
+	"OTEL_LOG_TOOL_CONTENT",
+	"OTEL_LOG_TOOL_DETAILS",
+	"OTEL_EXPORTER_PROMETHEUS_HOST",
+	"OTEL_EXPORTER_PROMETHEUS_PORT",
+	"CLAUDE_CODE_PROCESS_WRAPPER",
+	"CLAUDE_CODE_SYNC_SKILLS",
+	"CLAUDE_CODE_SYNC_PLUGINS",
+	"CLAUDE_CODE_PLUGIN_CACHE_DIR",
+	"CLAUDE_CODE_PLUGIN_SEED_DIR",
+	"CLAUDE_CODE_OAUTH_TOKEN",
+	"CLAUDE_CODE_OAUTH_REFRESH_TOKEN",
+	"CLAUDE_CODE_OAUTH_SCOPES",
+	"CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS",
+	"CLAUDE_CODE_DISABLE_ATTACHMENTS",
+	"CLAUDE_CODE_DISABLE_FILE_MENTIONS",
+	"CLAUDE_CODE_REMOTE",
+	"CLAUDE_CODE_ACCOUNT_UUID",
+	"CLAUDE_CODE_MESSAGING_SOCKET",
+	"CLAUDE_CODE_MESSAGING_TOKEN",
+	"CLAUDE_CODE_PROJECT_DIR_NAME",
+	"CLAUDE_CODE_RESTRICTED",
+	"CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY",
+	"CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT",
+	"CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT",
+	"CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT",
+	"CLAUDE_CODE_DISABLE_MOUNTED_DRIVE_RM_PROMPT",
+	"CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS",
+	"CLAUDE_CODE_WARN_DISK_FREE_GIB",
+	"CLAUDE_CODE_WARN_MEMORY_FREE_GIB"
+]);
+/**
+* Families of ignored variables.
+*
+* Matches:        "XDG_CONFIG_HOME", "ProgramFiles(x86)", "CLAUDE_AX_SCREEN_READER",
+*                 "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_METRICS_HEADERS"
+* Does not match: "MCP_TIMEOUT", "OTEL_EXPORTER_OTLP_TIMEOUT", "OTEL_SERVICE_NAME"
+*/
+const IGNORED_NAME_PATTERN = /^(XDG_|ProgramFiles|CLAUDE_AX_|OTEL_EXPORTER_OTLP_(\w+_)?(ENDPOINT|HEADERS|PROTOCOL|CERTIFICATE|CLIENT_KEY|INSECURE)$)/;
+/** Values that turn telemetry off: Claude Code applies them even from project settings. */
+const OFF_VALUES = {
+	OTEL_LOGS_EXPORTER: ["none"],
+	OTEL_METRICS_EXPORTER: ["none"],
+	OTEL_TRACES_EXPORTER: ["none"],
+	OTEL_LOG_USER_PROMPTS: ["0", "false"],
+	OTEL_LOG_TOOL_CONTENT: ["0", "false"],
+	OTEL_LOG_TOOL_DETAILS: ["0", "false"]
+};
+function isIgnoredByClaude(name, value) {
+	if ((OFF_VALUES[name] ?? []).includes(value)) return false;
+	return IGNORED_NAMES.has(name) || IGNORED_NAME_PATTERN.test(name);
+}
+//#endregion
 //#region src/agents/claude/mcp-json.ts
 /** `.mcp.json` in the shape Claude Code reads: `{ "mcpServers": { "<key>": config } }`. */
 function renderMcpJson(servers) {
@@ -894,6 +1038,32 @@ function renderMcpJson(servers) {
 	return `${JSON.stringify(content, null, 2)}\n`;
 }
 //#endregion
+//#region src/shared/utils/env.ts
+/**
+* The variables as a plain map, sorted by name so that the generated file and its diff stay
+* the same on every machine.
+*/
+function buildEnvMap(env) {
+	const sortedEntries = env.map((variable) => [variable.artifact.key, variable.artifact.value]).toSorted(compareByName);
+	return Object.fromEntries(sortedEntries);
+}
+/** By code points, not by locale; names are unique, so two entries are never equal. */
+function compareByName([a], [b]) {
+	return a < b ? -1 : 1;
+}
+//#endregion
+//#region src/agents/claude/settings-json.ts
+const SETTINGS_SCHEMA = "https://json.schemastore.org/claude-code-settings.json";
+/** The keys that tunestra writes; a file with only these keys is a generated one. */
+const SETTINGS_KEYS = ["$schema", "env"];
+function renderSettingsJson(env) {
+	const variables = buildEnvMap(env);
+	return `${JSON.stringify({
+		$schema: SETTINGS_SCHEMA,
+		env: variables
+	}, null, 2)}\n`;
+}
+//#endregion
 //#region src/agents/claude/claude-adapter.ts
 const CLAUDE_FILE = "CLAUDE.md";
 const RULES_DIR = ".claude/rules/tunestra";
@@ -901,10 +1071,15 @@ const SKILLS_DIR = ".claude/skills";
 const COMMANDS_DIR = ".claude/commands";
 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 in tunestra.yaml and its presets";
+const LOCAL_SETTINGS_FILE = ".claude/settings.local.json";
 /**
 * 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`
-* would need an approval. Skills are symlinks to the shared `.agents/skills`.
+* would need an approval. Skills are symlinks to the shared `.agents/skills`. Environment
+* variables go to `.claude/settings.json`, which the team commits; `settings.local.json`
+* stays for personal settings.
 */
 const claudeAdapter = {
 	agent: Agent.Claude,
@@ -933,6 +1108,12 @@ function planClaude(context) {
 		const mcpFile = createFileOutput(MCP_FILE, mcpJson, MCP_SOURCE);
 		outputs.push(mcpFile);
 	}
+	const protectedPaths = [CLAUDE_FILE];
+	if (resolution.env.length > 0) {
+		const settingsFile = planSettingsFile(resolution.env);
+		outputs.push(settingsFile);
+		protectedPaths.push(SETTINGS_FILE);
+	}
 	return {
 		outputs,
 		ignoredPaths: [
@@ -941,7 +1122,23 @@ function planClaude(context) {
 			`${COMMANDS_DIR}/`,
 			MCP_FILE
 		],
-		protectedPaths: [CLAUDE_FILE]
+		protectedPaths,
+		notes: []
+	};
+}
+/** Claude Code drops some variables from project settings; setup says so instead. */
+function planSettingsFile(env) {
+	const problems = env.filter((variable) => isIgnoredByClaude(variable.artifact.key, variable.artifact.value)).map((variable) => `${variable.origin.name}: env sets ${variable.artifact.key}, but Claude Code ignores it in project settings. Set it in managed settings, ~/.claude/settings.json or your shell`);
+	if (problems.length > 0) throw createProblemsError(problems);
+	const content = renderSettingsJson(env);
+	const file = createFileOutput(SETTINGS_FILE, content, SETTINGS_SOURCE);
+	const ownership = {
+		keys: SETTINGS_KEYS,
+		otherKeysTarget: `${LOCAL_SETTINGS_FILE} or ~/.claude/settings.json`
+	};
+	return {
+		...file,
+		ownership
 	};
 }
 function copyRule(ruleFile) {
@@ -961,9 +1158,159 @@ 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");
+/**
+* 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/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/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 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/config.toml 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 go to the same file. Commands become skills.
+*/
+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);
+	if (configFile === void 0) return {
+		outputs,
+		ignoredPaths: [],
+		protectedPaths: [],
+		notes
+	};
+	outputs.push(configFile);
+	notes.push(TRUST_NOTE);
+	return {
+		outputs,
+		ignoredPaths: [CONFIG_FILE],
+		protectedPaths: [],
+		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; Codex comes in v0.2. */
-const AGENT_ADAPTERS = { [Agent.Claude]: claudeAdapter };
+/** Every supported agent. */
+const AGENT_ADAPTERS = {
+	[Agent.Claude]: claudeAdapter,
+	[Agent.Codex]: codexAdapter
+};
 //#endregion
 //#region src/shared/utils/markdown.ts
 /**
@@ -1049,8 +1396,9 @@ function renderLevelLine(rule) {
 //#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 loads them automatically; other agents should read them before starting work.";
+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 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",
 	"",
@@ -1111,8 +1459,8 @@ function renderSkills(skills) {
 	}));
 	return renderSection("Skills", SKILLS_INTRO, table);
 }
-function renderCommands(commands) {
-	return renderSection("Commands", void 0, renderTable([
+function renderCommands(commands, agents) {
+	const table = renderTable([
 		"Command",
 		"Level",
 		"Description"
@@ -1124,7 +1472,18 @@ function renderCommands(commands) {
 			origin,
 			description
 		];
-	})));
+	}));
+	const hints = agents.map(describeCommandCall).filter(isString);
+	if (hints.length > 0) return renderSection("Commands", hints.join(" "), table);
+	return renderSection("Commands", void 0, table);
+}
+/** How to call a command in the agent, when it is not the usual `/<name>`. */
+function describeCommandCall(agent) {
+	switch (agent) {
+		case Agent.Claude: return;
+		case Agent.Codex: return "In Codex, a command is a skill with the same name: call it as `$<name>`.";
+		default: throw new TunestraError(`Unknown agent: ${agent}`);
+	}
 }
 function renderMcpServers(servers) {
 	return renderSection("MCP servers", void 0, renderTable([
@@ -1141,6 +1500,13 @@ function renderMcpServers(servers) {
 		];
 	})));
 }
+function renderEnv(env) {
+	const table = renderTable(["Variable", "Level"], env.map((variable) => {
+		const origin = describeOrigin(variable);
+		return [variable.artifact.key, origin];
+	}));
+	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;
@@ -1180,6 +1546,7 @@ function renderAgentsIndex(resolution) {
 	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);
@@ -1189,13 +1556,17 @@ function renderAgentsIndex(resolution) {
 		sections.push(skills);
 	}
 	if (hasCommands) {
-		const commands = renderCommands(resolution.commands);
+		const commands = renderCommands(resolution.commands, resolution.chain.project.agents);
 		sections.push(commands);
 	}
 	if (hasMcpServers) {
 		const servers = renderMcpServers(resolution.mcp);
 		sections.push(servers);
 	}
+	if (hasEnv) {
+		const env = renderEnv(resolution.env);
+		sections.push(env);
+	}
 	sections.push(CHANGING_SECTION);
 	return `${sections.join("\n\n")}\n`;
 }
@@ -1218,6 +1589,7 @@ function planSetup(resolution) {
 	];
 	const ignoredPaths = [`${AGENTS_DIR}/`];
 	const protectedPaths = [INSTRUCTIONS_FILE];
+	const notes = [];
 	const context = {
 		resolution,
 		ruleFiles
@@ -1227,6 +1599,7 @@ function planSetup(resolution) {
 		outputs.push(...agentPlan.outputs);
 		ignoredPaths.push(...agentPlan.ignoredPaths);
 		protectedPaths.push(...agentPlan.protectedPaths);
+		notes.push(...agentPlan.notes);
 	}
 	ignoredPaths.push(`${STATE_DIR}/`);
 	const problems = findPathConflicts(outputs);
@@ -1234,7 +1607,8 @@ function planSetup(resolution) {
 	return {
 		outputs,
 		ignoredPaths,
-		protectedPaths
+		protectedPaths,
+		notes
 	};
 }
 function planRuleFile(projectDir, rule) {
@@ -1269,12 +1643,16 @@ function findPathConflicts(outputs) {
 }
 //#endregion
 //#region src/shared/constants/artifacts.ts
-/** Kinds of artifacts; the values match the folder-based fields of a preset and of `exclude`. */
+/**
+* Kinds of artifacts; the values match the fields of a preset and of `exclude`. Environment
+* variables come from the manifest, the other kinds from folders.
+*/
 const ArtifactKind = {
 	Rules: "rules",
 	Skills: "skills",
 	Commands: "commands",
-	Mcp: "mcp"
+	Mcp: "mcp",
+	Env: "env"
 };
 //#endregion
 //#region src/inheritance/inherit-artifacts.ts
@@ -1412,11 +1790,13 @@ 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 env = inheritArtifacts(chain.levels, ArtifactKind.Env, (level) => level.env);
 	const problems = [
 		...rules.problems,
 		...skills.problems,
 		...commands.problems,
-		...mcp.problems
+		...mcp.problems,
+		...env.problems
 	];
 	if (problems.length > 0) throw createProblemsError(problems);
 	return {
@@ -1424,7 +1804,8 @@ function applyInheritance(chain) {
 		rules: rules.artifacts,
 		skills: skills.artifacts,
 		commands: commands.artifacts,
-		mcp: mcp.artifacts
+		mcp: mcp.artifacts,
+		env: env.artifacts
 	};
 }
 //#endregion
@@ -1442,7 +1823,7 @@ async function readState(projectDir) {
 	const file = join(projectDir, STATE_FILE);
 	const content = await readFileIfExists(file);
 	if (content === void 0) return createEmptyState();
-	return validate(parseJson(content, file), stateSchema, `state file ${file}. Delete it and run tunestra setup again`);
+	return validate(parseJson$1(content, file), stateSchema, `state file ${file}. Delete it and run tunestra setup again`);
 }
 function createEmptyState() {
 	return {
@@ -1450,7 +1831,7 @@ function createEmptyState() {
 		outputs: {}
 	};
 }
-function parseJson(content, file) {
+function parseJson$1(content, file) {
 	try {
 		return JSON.parse(content);
 	} catch (error) {
@@ -1564,6 +1945,24 @@ async function createRecord(output) {
 	}
 }
 //#endregion
+//#region src/sync/find-foreign-keys.ts
+/**
+* The top-level keys of a JSON file that are not in `ownedKeys`. A file that is not a JSON
+* 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"));
+	if (isKeyValueMap(data)) return Object.keys(data).filter((key) => ownedKeys.includes(key) === false);
+}
+function parseJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		if (error instanceof SyntaxError) return;
+		throw error;
+	}
+}
+//#endregion
 //#region src/sync/inspect-path.ts
 async function inspectPath(path) {
 	const type = await getPathType(path);
@@ -1576,11 +1975,16 @@ async function inspectPath(path) {
 		return {
 			type,
 			hash: hashContent(content),
-			isMarked: content.subarray(0, 26).toString("utf8") === GENERATED_MARKER
+			isMarked: hasGeneratedMarker(content)
 		};
 	}
 	return { type };
 }
+function hasGeneratedMarker(content) {
+	return GENERATED_MARKERS.some((marker) => {
+		return content.subarray(0, marker.length).toString("utf8") === marker;
+	});
+}
 /** A file matches a record by its hash, a symlink by its target. */
 function matchesRecord(entry, record) {
 	if (entry.type === PathType.File && "hash" in record) return entry.hash === record.hash;
@@ -1602,9 +2006,21 @@ async function checkOutput(output, context) {
 	const isRecorded = typeof previousRecord === "object";
 	const isReplaceable = disk.type === PathType.File || disk.type === PathType.Symlink;
 	if (isRecorded && isReplaceable) return createCheck(output, record, `${output.path} was edited by hand; tunestra replaced it. Edit ${output.source} instead`);
+	const ownership = output.kind === OutputKind.File ? output.ownership : void 0;
+	if (typeof ownership === "object" && disk.type === PathType.File) return createCheck(output, record, await checkOwnedJson(path, output, ownership));
 	if (context.protectedPaths.includes(output.path)) throw new TunestraError(`${output.path} was written by hand, and setup would overwrite it. Move its text to .tunestra/AGENTS.md or to a rule in .tunestra/rules/, then delete ${output.path} and run tunestra setup again`);
 	throw new TunestraError(`${output.path} already exists, and tunestra did not create it. Move it away and run tunestra setup again`);
 }
+/** Takes over a JSON file with only the keys that tunestra writes; other keys stop setup. */
+async function checkOwnedJson(path, output, ownership) {
+	const foreignKeys = await findForeignKeys(path, ownership.keys);
+	if (foreignKeys === void 0) throw new TunestraError(`${output.path} is not a JSON object, and setup would overwrite it. Fix or delete it and run tunestra setup again`);
+	if (foreignKeys.length > 0) {
+		const keys = foreignKeys.join(", ");
+		throw new TunestraError(`${output.path} has settings that tunestra does not write: ${keys}. Move them to ${ownership.otherKeysTarget}, then run tunestra setup again`);
+	}
+	return `${output.path} had only the settings that tunestra writes; tunestra replaced it. Edit ${output.source} instead`;
+}
 /**
 * Nothing to lose: the path is empty, already has the new content, still has what tunestra
 * wrote last time, or is a generated markdown file whose record was lost.
@@ -1728,6 +2144,7 @@ async function runSetup(projectDir, options) {
 	const sync = await planSync(chain.project.dir, plan, previous);
 	const report = {
 		resolution,
+		plan,
 		sync
 	};
 	if (options.dryRun) return report;
@@ -1744,7 +2161,8 @@ function describeResolution(resolution) {
 		describeSection("Rules", resolution.rules, projectDir),
 		describeSection("Skills", resolution.skills, projectDir),
 		describeSection("Commands", resolution.commands, projectDir),
-		describeSection("MCP servers", resolution.mcp, projectDir)
+		describeSection("MCP servers", resolution.mcp, projectDir),
+		describeSection("Environment", resolution.env, projectDir)
 	].filter((section) => section.length > 0).join("\n\n");
 }
 function describeSection(title, artifacts, projectDir) {
@@ -1772,28 +2190,39 @@ function measureColumn(rows, column) {
 //#region src/cli/commands/setup.ts
 async function describeSetup(projectDir, options) {
 	const report = await runSetup(projectDir, options);
-	const summary = describeSync(report.sync, options);
+	const summary = describeSync(report.plan, report.sync, options);
 	if (options.verbose) return `${describeResolution(report.resolution)}
 
 ${summary}`;
 	return summary;
 }
-function describeSync(sync, options) {
+function describeSync(plan, sync, options) {
 	const warningIcon = pc.yellow("⚠");
 	const lines = sync.warnings.map((warning) => `${warningIcon} ${warning}`);
+	const noteIcon = pc.cyan("ℹ");
+	const notes = plan.notes.map((note) => `${noteIcon} ${note}`);
 	const writeCount = sync.outputs.length;
 	const removeCount = sync.removals.length;
 	if (options.dryRun) {
 		const writes = sync.outputs.map((output) => `  write   ${output.path}`);
 		const removals = sync.removals.map((path) => `  remove  ${path}`);
-		lines.push(...writes, ...removals, "", "Nothing was written (--dry-run).");
+		lines.push(...writes, ...removals, ...notes, "", "Nothing was written (--dry-run).");
 		return lines.join("\n");
 	}
 	const check = pc.green("✔");
+	const committedFiles = joinList(plan.protectedPaths);
 	lines.push(`${check} Generated ${writeCount} files, removed ${removeCount} stale files.`);
-	lines.push("Commit AGENTS.md and CLAUDE.md; the rest is in .gitignore.");
+	lines.push(...notes);
+	lines.push(`Commit ${committedFiles}; the rest is in .gitignore.`);
 	return lines.join("\n");
 }
+/** For example `AGENTS.md, CLAUDE.md and .claude/settings.json`. */
+function joinList(items) {
+	const last = items.at(-1) ?? "";
+	const rest = items.slice(0, -1);
+	if (rest.length === 0) return last;
+	return `${rest.join(", ")} and ${last}`;
+}
 //#endregion
 //#region src/uninstall/remove-gitignore-block.ts
 /** A .gitignore that had only the tunestra block is removed, because tunestra created it. */

package/dist/index.mjs

@@ -1 +1 @@
-export { t as VERSION } from "./src-Dmt0_5_W.mjs";
+export { t as VERSION } from "./src-BNeh64fK.mjs";

package/dist/{src-Dmt0_5_W.mjs → src-BNeh64fK.mjs}

@@ -1,5 +1,5 @@
 //#endregion
 //#region src/index.ts
-const VERSION = "0.1.1";
+const VERSION = "0.3.0";
 //#endregion
 export { VERSION as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunestra",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Tune your AI agents to play as one orchestra: one source of rules, skills, commands and MCP servers for Claude Code, Codex and more.",
   "keywords": [
     "ai",
@@ -44,7 +44,13 @@
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
     "check": "npm run typecheck && npm run lint && npm run test && npm run build",
-    "prepublishOnly": "npm run check"
+    "prepublishOnly": "npm run check",
+    "changeset": "changeset",
+    "version-packages": "changeset version && npm install --package-lock-only",
+    "release": "changeset publish"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "engines": {
     "node": ">=22.18"
@@ -54,12 +60,14 @@
     "commander": "^15.0.0",
     "giget": "^3.3.1",
     "picocolors": "^1.1.1",
+    "smol-toml": "^1.9.1",
     "tinyglobby": "^0.2.17",
     "yaml": "^2.9.1",
     "zod": "^4.6.7"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
+    "@changesets/cli": "^3.0.3",
     "@types/node": "^22.20.5",
     "@vitest/coverage-v8": "^5.0.5",
     "tsdown": "^0.23.1",