feat(env): team-declared secrets with member-local values (#875)

docs/designs/data-directory-layout.md

@@ -439,6 +439,9 @@ every checkout, so that is where they live now:
 ├── reports-wt/                                (the side-branch locks sit beside them)
 ├── pending-learnings/                         pendingLearningsDir → <dataHome>/pending-learnings
 └── workspaces/<managedMcpWorkspaceId(root)>/
+    ├── managed-mcp.json                       managedMcpManifestPath, one per checkout
+    ├── managed-mcp-files.json                 resolvedMcpFilesPath: project MCP configs teamai may have written a resolved ${VAR} to, and whether
+    │                                          the paths earlier teamai.yaml revisions mapped were read; one of those git tracks is marked tracked (#882)
     └── search-index.json                      getProjectSearchIndexPath, one per checkout
 <checkout>/.teamai/                            one per checkout: committed knowledge, knowledge-wt/
 ```
@@ -655,8 +658,8 @@ the other repository, and `recall` rebuilds a missing index. `uninstall` lists,
 how many unpublished learnings each queue in the data home holds, set-aside ones
 included, so the member can publish or copy them first.
 
-Every checkout keeps its `workspaces/<id>/` (search index, managed MCP,
-resource cache) in the shared data home. A full `pull` removes those of
+Every checkout keeps its `workspaces/<id>/` (search index, managed MCP and
+the MCP configs it wrote a resolved value to, resource cache) in the shared data home. A full `pull` removes those of
 checkouts `git worktree list` no longer shows; the fast path does not list
 worktrees.
 
@@ -905,3 +908,29 @@ user finds partitions safe to `rm -rf` by hand.
 `teamai migrate` / `gc` / `--revert` commands; cross-project shared team-repo clone.
 Downgrade to an older teamai after
 P1 migration is not supported (`.teamai.bak/` is the manual rollback path).
+
+## Team secret values (#875)
+
+A member's values for their teams' declared secrets live in `~/.teamai/secrets/`,
+a class-A2 (machine-level) directory: `teams/<hash>.json`, one file per
+team repo, named by the full SHA-256 hex digest (64 characters, never shortened) of the team repo URL in `~/.teamai/config.yaml` (never
+`teamai.yaml`'s `repo:`), without the team name, so renaming `team:` keeps the values;
+the hash covers the URL's scheme (the ssh forms count as one; https and http are two),
+ssh user, host, non-default port and path (an scp-style path not starting with `/` or `~`
+is in the user's home, as `ssh://host/~/path`; `ssh://host/path` is from the root), so an
+scp path in the home and the `ssh://` path from the root, two ssh users' repos on one host, two
+repos on one host with different ports, or repos behind http and https, get different files,
+and `machine.json`, the values set with `teamai env set --global` for every team.
+Every scope that uses the same team, and every worktree of it, reads the same file.
+Each entry records whether it is a secret's value or the member's value for an
+`env.yaml` variable (`kind`), so one is never used as the other.
+It never goes to a partition or to `<dataHome>`, which in single-repo mode is inside
+the business repo, and it is not `~/.teamai/env`, which is already the user scope's
+env backup file. Files are written atomically with mode `0600`. Uninstalling a
+project scope removes only its partition, so the values stay; uninstalling the user
+scope removes `~/.teamai` and them with it. See [Team secrets](team-secrets.md#storage).
+
+Beside each scope's `env.sh`, in `<dataHome>`, `env.sh.exports.json` records what
+that `env.sh` has exported: per key, a SHA-256 of `KEY=VALUE` for the last 20
+values, never a value, mode `0600`. It is machine data like `env.sh` and is
+removed with it. See [Team secrets](team-secrets.md#resolution).

docs/designs/management-backend.md

@@ -50,7 +50,8 @@ plane accepts identity-bound events with separate retention and write permission
 | `skills/` | SkillsHandler, namespaces and marketplace metadata | Resource bundles with immutable files, dependencies and generated marketplace views |
 | `rules/` | RulesHandler and enforced-rule selection | Versioned rules with separately enforced policy constraints |
 | `docs/` | DocsHandler and indexed documentation | Versioned documents, authorized materialization and recall indexing |
-| `env/env.yaml` | EnvHandler, local overrides and environment injection | Non-secret templates plus secret references; secret resolution has separate authorization |
+| `env/env.yaml` | EnvHandler, local overrides and environment injection; values in plaintext | Non-secret templates plus secret references; secret resolution has separate authorization |
+| `env/secrets.yaml` | Secret declarations with no value ([team secrets](team-secrets.md)); v1 resolves each member's value on their machine | Secret references; the encrypted secret service below stays future work |
 | `agents/` | AgentsHandler and tool-format conversion | Versioned agent definitions rendered through the existing tool adapters |
 | `hooks/hooks.yaml` | HooksHandler plus hook reconciliation; no general per-item push | Reviewed declarative hooks, client consent and typed validation |
 | `mcp/mcp.yaml` | McpHandler plus MCP reconciliation; direct YAML editing for contributions | Reviewed server definitions, transport policy and secret references |

docs/designs/management-backend.zh-CN.md

@@ -43,7 +43,8 @@
 | `skills/` | SkillsHandler、命名空间及 marketplace 元数据 | 不可变文件和依赖组成的资源包，派生 marketplace 视图 |
 | `rules/` | RulesHandler 及强制规则选择 | 版本化规则，并单独执行强制策略约束 |
 | `docs/` | DocsHandler 及文档索引 | 版本化文档、授权物化及召回索引 |
-| `env/env.yaml` | EnvHandler、本地覆盖和环境注入 | 非密钥模板及密钥引用，解析密钥时单独授权 |
+| `env/env.yaml` | EnvHandler、本地覆盖和环境注入；值为明文 | 非密钥模板及密钥引用，解析密钥时单独授权 |
+| `env/secrets.yaml` | 只声明、不含值的密钥（[团队密钥](team-secrets.zh-CN.md)）；v1 在每个成员的机器上解析其值 | 密钥引用；下文的加密密钥服务仍属未来工作 |
 | `agents/` | AgentsHandler 及工具格式转换 | 版本化 agent 定义，复用现有工具适配器渲染 |
 | `hooks/hooks.yaml` | HooksHandler 及 hook 协调，不支持通用逐项 push | 可审核的声明式 hooks、客户端同意及类型验证 |
 | `mcp/mcp.yaml` | McpHandler 及 MCP 协调，贡献通过直接编辑 YAML 完成 | 可审核的服务定义、transport 策略及密钥引用 |

docs/designs/model-profiles.md

@@ -20,6 +20,8 @@ Model profiles let a team publish one gateway catalog that every supported agent
 
 A key is either stored or referenced as an environment variable; it is never accepted as a command-line argument. `0600` is not encryption. The team-key file name is a hash of the repository identity; the sanitized `teamai.yaml` team name plays no part in it, so renaming the team never orphans the keys. When no repository identity exists at all (no usable remote, URL, or `repo:` claim), the name hashes the team slug with the path instead — there is nothing repository-shaped to key on, and the slug keeps differently named teams that share a checkout path apart. While the hash-only file does not exist yet, a legacy `<slug>-<hash>.json` from an older version is read where it lies — nothing is renamed — and the next save writes the hash-only name. A legacy file under a repository-bound digest (a URL, a URL-shaped `repo:` claim or remote) carries its host in the identity, so it is read by digest alone; a legacy file under a **provider-ambiguous** digest (a path-shaped `repo:` claim, a provider-relative remote, a bare alias, or no repository identity) names no single repository — the old name scheme never encoded the provider, so two providers' same-named teams hash the same file, and the slug cannot prove ownership across providers. Such a file is never read by a silent rule: the CLI surfaces it once and the user explicitly adopts the exact `<slug>-<hash>` identity for this checkout, after which the read happens and the next save migrates the keys to the provider-qualified hash-only name. Non-interactive and `--dry-run` runs never adopt: they report the file and leave it unread. Switch records under a provider-ambiguous identity are never claimed either — the old name never encoded the provider, so no slug (not even this checkout's exact slug) proves ownership: a GitHub and a GitCode team both named `Alpha` on the bare claim `acme/widgets` share the identical `alpha-<digest>` form. No machine-global record is ever used as proof, because a store shared by every checkout on the machine would equally belong to a foreign team; the explicit adoption of the values file re-establishes this team's presence, and its switched agents are re-recorded by the next `models switch` under the provider-qualified identity. Repository-bound switch records still match by digest alone. The identity is recorded with each `team:` switch so `pull` only re-applies the current team's profiles. Inside it, each key is stored under `team:<id>@<origin>`; see [Namespaces and key binding](#namespaces-and-key-binding).
 
+Model profile keys are not [team secrets](team-secrets.md): `teamai env set` does not configure them, `env/secrets.yaml` cannot declare one, and the two stores share code, not files.
+
 ## Catalog and protocols
 
 ```yaml

docs/designs/model-profiles.zh-CN.md

@@ -20,6 +20,8 @@
 
 密钥要么保存在本地，要么引用环境变量，不接受命令行参数传入。`0600` 并非加密。团队密钥文件名只是仓库身份的哈希，`teamai.yaml` 中的团队名不参与其中，因此重命名团队不会导致密钥失效。当完全不存在仓库身份（可用的 remote、URL 或 `repo:` claim 都没有）时，文件名改为哈希团队 slug 与路径的组合——此时没有任何仓库形态的信息可以依赖，靠 slug 区分共享同一检出路径、名字不同的团队；旧版本遗留的 `<团队名>-<哈希>.json` 会在纯哈希文件尚不存在时被原位读取，不做任何改名，下一次保存才会写入纯哈希文件名。在 provider 可确定的 digest（URL 或 URL 形态的 `repo:` claim/remote）下写出的遗留文件，identity 自带主机，直接按 digest 读取；在 **provider 不明确** 的 digest（形如 `owner/repo` 的 `repo:` claim、provider 相对的 remote、裸 alias，或没有仓库身份）下写出的遗留文件既不指向唯一仓库——旧命名从未编码 provider，两个 provider 的同名团队会哈希出同一个文件，slug 无法在 provider 之间证明归属。这类文件绝不按静默规则读取：CLI 会展示一次，由用户显式确认采用这个确切的 `<团队名>-<哈希>` identity 后才读取，随后下一次保存会把密钥迁移到 provider 限定的纯哈希文件名下。非交互与 `--dry-run` 运行一律不采用：只报告该文件并保持不读。provider 不明确 identity 下的 switch 记录同样绝不采用——旧命名从未编码 provider，任何 slug（即使与本 checkout 完全相同的 slug）都无法证明归属：GitHub 与 GitCode 上都叫 `Alpha`、裸 claim 同为 `acme/widgets` 的两支团队会共享完全相同的 `alpha-<digest>` 形式。绝不把任何机器级记录当作归属证明，因为同一机器上被各 checkout 共享的记录对别的团队同样成立；只有对遗留 values 文件的显式采用才能重新确立本团队的存在，其已切换的 agent 随后通过下一次 `models switch` 以 provider 限定的 identity 重新记录。provider 可确切的 switch 记录仍按 digest 直接匹配。每次切换 `team:` 配置时也会记录这个身份，`pull` 只会重新应用当前团队的配置。文件内每个密钥保存在 `team:<id>@<origin>` 下，见 [Namespace 与密钥绑定](#namespace-与密钥绑定)。
 
+模型配置的密钥不是[团队密钥](team-secrets.zh-CN.md)：`teamai env set` 不配置它们，`env/secrets.yaml` 也不能声明它们，两者只共享代码、不共享文件。
+
 ## 目录与协议
 
 ```yaml

docs/designs/multi-project-management.md

@@ -241,6 +241,7 @@ directory's projects list under `resources.<type>`.
 | Type | `resources:` key | Replaced by name | Two active namespaces, one name |
 |---|---|---|---|
 | env | `env` | variable `key` | conflict |
+| secrets (`env/<ns>/secrets.yaml`, [#875](team-secrets.md)) | `env` | secret `key` | conflict |
 | hooks | `hooks` | hook `id` | conflict |
 | mcp | `mcp` | server `name` (`command`, `args`, `env` and `tools:` together) | conflict |
 | models | `models` | profile `id` | conflict |
@@ -266,7 +267,8 @@ active, the next pull delivers the root item again and removes items that only
 the namespace had; for env, hooks and MCP that happens on an `Already synced`
 pull too, and `env.sh` is regenerated from the resolved set even when
 `env/env.yaml` is missing or declares nothing. MCP `${VAR}` lookup reads the same
-resolved env set.
+resolved env set, with the member's value for this team (`teamai env set KEY`)
+first; the environment no longer overrides a team variable ([Team secrets](team-secrets.md#variables)).
 
 Skills keep one difference: in role/project mode the root `skills/` stays the tag
 catalog and is not delivered by default. A root skill that arrives through a
@@ -320,13 +322,14 @@ copy is not a duplicate: each copy that passes the role filter is delivered, as
 | Type | Effect of a failure |
 |---|---|
 | env | `env.sh` and the shell profile keep what they had |
+| secrets | the declared secrets are not resolved, and `env.sh`, the env backup and the MCP servers keep what they had; `teamai env list` and `teamai doctor` fail naming the file |
 | hooks | installed team hooks and the managed-hooks record stay as they are. The built-in hooks are still installed in each tool that misses one (a tool with all of them is not rewritten), so a first install gets the session-start pull that heals it: with the root file's `builtin:` overrides whenever `hooks/hooks.yaml` parses (a broken namespace file or a clash does not hide them), and when the root file itself does not parse, with their defaults and only in a tool that has no teamai hook yet. `teamai init` and bootstrap say the team hooks were not installed; `teamai hooks inject` exits 1 |
 | mcp | no tool's MCP config changes |
 | models | no switched agent is updated; `teamai models` commands fail with the same message; `teamai push` refuses any invalid models file, active or not |
 | skills, agents | that type is neither installed nor swept; the other types and the search index still sync |
 | rules, claudemd, docs, learnings | no conflict case |
 
-For env, hooks, MCP and models the warning is also written to
+For env, secrets, hooks, MCP and models the warning is also written to
 `~/.teamai/debug.log`, so a silent session-start pull leaves a trace. This
 replaces two earlier behaviours: an invalid hooks or MCP file reconciled to the
 empty set and removed every managed entry, and a skills or agents collision
@@ -450,8 +453,9 @@ a root one is written to its namespace file, never to the root. The agents
 source order is active namespace, then this machine's placement record, then the
 shared root; in role/project mode a same-stem root file no longer withdraws the
 placement record (legacy mode still does). The skills push scan uses role ∪
-project namespaces, and `push` picks up a change to any `env/<ns>/env.yaml`.
-`teamai env add|remove` take `--role` / `--project`. `teamai remove mcp <name>`
+project namespaces, and `push` picks up a change to any `env/<ns>/env.yaml` or `env/<ns>/secrets.yaml`.
+`teamai env add|remove` take `--role` / `--project`, and `--secret` for that namespace's `secrets.yaml`.
+`teamai remove mcp <name>`
 removes from the root file when it defines the name, otherwise from the one
 namespace file that does, and asks for `--role` / `--project` only when several
 namespace files and not the root define it, and removes nothing by a bare name