Proposal: declare team secrets in the repo, keep their values on each machine, for MCP servers and CLIs #875

Proposed:

• Separate file. teamai env add and env remove rewrite env.yaml with only its variables: list, so a member on an older CLI editing env would drop a secrets: key in the same file. Older CLIs read only env/env.yaml and env/<ns>/env.yaml, so they ignore env/secrets.yaml entirely. A variable without a value isn't an option either: it fails the schema, and with it the whole env resolution for every member on an older CLI.
• Storage. Values live in files of their own under ~/.teamai/secrets/ (~/.teamai/env is already the user scope's env backup), apart from model profile keys: machine.json for the machine, and teams/<hash>.json per team repo, keyed by the same repository-identity hash teamai models configure uses, but without the team's display name, so renaming team: in teamai.yaml doesn't orphan anyone's values. A team used from several projects or worktrees then needs one env set. Each entry is either a literal value or the name of a variable to read (--from-env). They always live under ~/.teamai, never in the scope's data directory, since in single-repo mode that sits inside the business repo. Files are written atomically with mode 0600, like the model key files.
• Model profile keys. They stay where they are. api_key: ${API_KEY} in models/models.yaml is a slot per profile, not a variable: every profile uses the same placeholder, and its key is bound to the profile and its gateway's origin (feat(projects): extend project isolation to knowledge/docs/agents/env/hooks/mcp #707). It is written into each agent's machine-wide config, so it can't differ per directory. teamai models configure keeps storing it under ~/.teamai/models/. env set doesn't configure it, and env/secrets.yaml can't declare it. models configure --from-env VAR still reads only the process environment, not a value set with env set. The two share code, not files: the model key files are parsed strictly, so a secret entry there would break every models command on an older CLI.
• env exec. It resolves the scope from the current directory with detectProjectConfig, by git anchors, so every worktree of a project resolves to that project, and falls back to the user scope. Then it runs the command with the inherited environment, overlaid with this scope's variables and secrets resolved in the order above, so a GITLAB_HOST exported for another team doesn't leak in. It writes no value to disk. A variable or secret named like one a model profile writes (ANTHROPIC_*) overrides that profile for the command, so env exec is for CLIs, not for starting an agent.
• Outside a scope. env exec in a directory with no teamai scope runs the command with the inherited environment and says on stderr that no scope was found. Machine values aren't applied there, since no team declares which keys the command needs.
• Workflows (Discussion: Workflow Runtime Integration #818). A workflow step that lists requires: { env: [GITHUB_TOKEN] } refers to the key declared here and resolves it in the same order. The step declared that it needs the key, so a missing one fails the run before it starts, instead of warning as env exec does. In CI there is nothing under ~/.teamai, so the value comes from the job's environment, the last step of the order. No value is written to run history or sent to an executor.
• Telling the agent. An agent that runs gh without env exec silently uses whatever account its environment has. When the scope declares secrets, the session-start hook adds one line to the agent's context through additionalContext, the way the MR hint does, listing each key with its description and saying to run those CLIs through teamai env exec --. Agents without a SessionStart hook get the same rule from the core skill.
• Keeping the entry. The session-start pull inherits the agent's environment, so a secret that only lives in the member's shell is there for one pull and gone for the next. Today a missing ${VAR} removes the managed entry. For a declared secret, a pull that can't find it keeps the entry as it is, the way a file that doesn't parse changes nothing today, and the way a model profile keeps an agent's settings when a pull can't see its --from-env variable. The entry is removed only when its server leaves mcp.yaml. A rotated or removed secret then keeps the old value until a pull finds the new one, and doctor says so. Variables that aren't declared as secrets keep today's behaviour.
• Not in env.sh. Secrets are never written to env.sh. It is sourced by every shell, is written with the default umask, and the profile loads one scope at a time (env: a project pull drops the user scope's env block from the shell profile #876). env exec covers the per-scope case, and a member who wants the token in every shell already has it in their environment.
• Same key twice. A key declared as a secret and also set as a variable in env.yaml resolves as a secret, and the repo value is ignored. pull and doctor warn about it. An older CLI keeps using the variable, so nobody loses the server while the team removes the value.
• env set checks. In a scope, env set accepts only keys that scope declares as secrets or receives as variables, and --global only secrets. env set --global outside any scope accepts any valid key name and notes that no team declares it yet, so a member can set a token they reuse across teams ahead of time.
• No migration. A team that committed a token has to rotate it, since git history keeps it. The docs say so, and that's all v1 does about it.
• Agents. The agent skills say that an agent never asks for a secret value in chat, never passes one through --stdin, never reads the values file, and never prints or quotes a secret. When doctor, pull, mcp list or env exec report a missing secret, the agent asks the member to run teamai env set KEY in their own terminal. Declaring a secret with env add --secret is safe for an agent, since it has no value.
• Docs and skills. docs/usage-guide.* (including its MCP Secrets paragraph, which says the environment wins), docs/product-overview.*, a link from docs/designs/model-profiles.* to the new design doc for Model profile keys, docs/designs/multi-project-management.md and docs/designs/management-backend.* in both languages; skill-data/core for members, including when to use env exec; skill-data/setup/references/manage-admin.md for admins; skill-data/core/references/commands.md regenerated. No README change.
• Still reachable. The resolved value is still written in plaintext to each tool's MCP config, as today (new files are created 0600). A command under env exec gets it in its environment, so an agent that runs teamai env exec -- env can read it; the skills forbid it, but nothing enforces it. An agent that can run gh with a token can already do whatever the token allows. This keeps secrets out of git, not away from the member's machine or the agent it runs.
• Not bound to a server. A secret reaches whatever server mcp.yaml names, as ${VAR} does today. Unlike model profile keys (feat(projects): extend project isolation to knowledge/docs/agents/env/hooks/mcp #707), it isn't tied to a host, so whoever can change mcp.yaml or add a namespace decides where members' tokens go. Whoever can push to the team repo already ships hooks that run on every member's machine, so v1 accepts this and the docs say so.
• Rejected. Writing secrets into each agent's config (Claude settings.json env, .claude/settings.local.json): only Claude injects them, and the value would sit in plaintext inside the business repo's directory. A used_by field: description already says which tool uses the key, and the field would drive no behaviour. A hook that rewrites the agent's commands to add env exec: it depends on each agent and means parsing shell commands.
• Code seams. Team key files and the { value } | { env } shape: getTeamValuesPath and resolveProfile in src/models/profile.ts. MCP variable table: buildVarTable in src/mcp-reconcile.ts. Session context: the additionalContext merge in src/hook-dispatch.ts, as src/mr-hint.ts uses it. Scope for a directory: detectProjectConfig in src/config.ts.
• Prior art. Executor keeps credentials apart from app source and lets a member keep a work and a personal account for the same service. This takes the part that fits a git-backed tool. Inside teamai, the models channel already declares api_key: ${API_KEY} in the repo and keeps the value on each machine, per team. Secrets reuse that shape, not its files; see Model profile keys.

Decided for v1, open to feedback until the spec is merged:

• doctor warns, it doesn't fail, when a delivered MCP server needs a missing secret.
• The link field is url.
• The command is env exec.