teamai-cli 0.26.0 → 0.27.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamai-cli",
-  "version": "0.26.0",
+  "version": "0.27.0-beta.0",
   "description": "TeamAI — Make Every Team AI Native (skill sync + shared knowledge base, powered by Git)",
   "type": "module",
   "bin": {

package/skill-data/core/SKILL.md

@@ -90,6 +90,16 @@ says so and why.)
    session, use the name of **this** tool — do not assume Claude Code or Cursor.
    Some hosts need extra manual steps for hooks — see the troubleshooting
    reference ("Agent-specific caveats").
+5. **Team secrets: the user types the value, you run the CLI.** When the team
+   declares secrets (the session-start context lists them; `teamai env list`
+   shows them), run the CLIs that use them through `teamai env exec -- <command>`,
+   `--` first, so they get this team's value. It is for CLIs, not for starting
+   an agent: a secret named like a model profile's (`ANTHROPIC_*`) overrides it.
+   When a secret is missing, ask the user to run `teamai env set KEY` in their
+   own terminal. Never ask for a value in chat, pass one to `--stdin` or
+   `--secret`, read the files under `~/.teamai/secrets/`, or print one
+   (`teamai env exec -- env` and `printenv` do). Declaring a secret with
+   `teamai env add KEY --secret` takes no value, so you can run it.
 
 ## Daily commands
 
@@ -100,6 +110,7 @@ teamai status      # Show local vs team differences
 teamai doctor      # Diagnose configuration and hook problems
 teamai list        # List resources (skills|rules|docs|env|agents|hooks|mcp)
 teamai recall <q>  # Search what the team has already learned
+teamai env exec -- <cmd>  # Run a CLI with this directory's team env and secrets
 ```
 
 Every other command, every flag, and the flags `--help` hides live in the
@@ -109,6 +120,89 @@ generated reference below. Read it instead of guessing a flag.
 removing stale and local-only documents; an edited doc of a docs namespace you left
 is kept and named. Use a dedicated directory; preview with `--dry-run`.
 
+`teamai pull` keeps a skill, rule or agent copy the user changed since teamai
+delivered it, `--force` included, and names it (`Kept <path>: ...`). To share
+the change, `teamai push`; when pull says the version teamai would deploy has
+changed since, or push says so for that copy, merge that change into the copy first, or the push replaces it. To take the team version instead, delete
+the copy and run `teamai pull --force`. The first pull after upgrading, and a
+new worktree's first pull, still overwrite: nothing is recorded yet.
+
+A team agent (`agents/<name>.yaml`) can set `model: strong`, `model: fast`, or an
+alias the team defines, instead of one tool's model. The team maps each alias per
+tool in `models/aliases.yaml`, in that tool's own model value, with an optional effort:
+
+```yaml
+aliases:
+  strong:
+    claude: { model: opus, effort: high }
+    codex:  { model: gpt-6-sol, effort: high }
+```
+
+`teamai pull` writes the mapped model into each tool's agent file, with the effort
+in that tool's own field: `effort` for the Claude family, CodeBuddy, Qoder and Qoder CN,
+`model_reasoning_effort` for the Codex family, `variant` for OpenCode. Cursor takes
+effort inside its model string (`claude-opus-5[effort=high]`); Copilot, Kiro, WorkBuddy,
+JoyCode, ZCode and OMP take none, and pull warns and drops an effort mapped for them.
+Qoder CN uses the `qoder` entry; only the Claude and Codex variants and Qoder CN inherit
+an entry, so never expect a `claude` model in Qoder or ZCode. A tool the alias does
+not map gets no `model` and uses its default; a concrete model such as `opus` is
+written as is; `tool_extras.<tool>.model` pins one tool and skips the alias. Suggest
+YAML agents: a legacy `agents/<name>.md` is copied as is, so its alias is not resolved.
+Before a team adds its first alias, every member updates teamai: an older CLI writes
+`model: strong` literally, and its push can replace the alias with a concrete model.
+
+A member overrides an entry on their machine in `~/.teamai/models/aliases.yaml`
+(same `aliases:` shape). For one tool it replaces the team's whole entry, effort
+included, and `~` or `default` gives that tool no model and no effort. Order per
+tool: extras model, local entry, team entry, no model. Keys must be `strong`, `fast`
+or a team alias; other names do nothing. One file serves every scope and every team
+with that alias name. An ordinary `teamai pull` applies an edit. In the team file,
+`default` is a literal model value and `~` is an error.
+
+A role or project redefines an alias in `models/<ns>/aliases.yaml`, read where `<ns>`
+is in `resources.models`, like `models/<ns>/models.yaml`. The namespace alias replaces
+the root alias whole (a tool it does not map gets no `model`); the same alias in two
+active namespaces holds alias agents, as a structural error does. A name defined in any
+aliases file of the team repo, active or not, is an alias: with no active definition it
+gives no `model`, and pull warns once per such alias. `teamai doctor` notes an agent's
+alias defined in an inactive namespace; to use it, add `models: [<ns>]` to the role's or
+project's resources, or rename the alias if it was meant as a concrete model id.
+
+A structural error in any aliases file, active or not (bad YAML, a wrong type, a bad alias
+name, an effort without a model, `~` in a team file, keys but no top-level `aliases:`)
+holds every agent with a `model`; one
+in the local file holds only agents whose `model` is an alias. Pull keeps
+their copies and push skips them until the file its warning names is fixed; then an
+ordinary `teamai pull` delivers them. An unknown
+tool key, an unknown option field, or an alias named like `opus` or `inherit` is only
+dropped, with a warning when an agent uses that alias; `gateways` is ignored.
+
+On a tool switched with `teamai models switch`, alias agents get no effort (not even a
+`tool_extras.<tool>` one, unless the extras also pin a `model`), and
+Claude keeps only `opus`, `sonnet` or `haiku` (the switch routes those to the gateway)
+while Codex, OpenCode, CodeBuddy and WorkBuddy get no `model`. No `model` means the
+tool's native inheritance (for Codex, `[agents].default_subagent_model` or the parent's
+model), not the profile's model. Variants such as tclaude are never switched. An ordinary
+`teamai pull` after `models switch` or `models restore` rewrites the affected agents.
+
+On push, an alias agent's model and alias effort are never read as edits: a copy that
+matches the last pull or the current mapping is unedited, and a hand-edited model or
+effort is reported as drift and not pushed (other edits still push), with where to change
+it: the member's override file, the team aliases file the alias comes from, or `teamai models
+restore --agent <tool>` for a switched tool. Writing an alias name in a deployed copy (`model: fast`)
+and pushing proposes `model: <alias>`, except in a tool whose `tool_extras.<tool>.model` pins it,
+where a changed value is drift on that pin. Never tell a user to push a concrete model over an alias.
+
+To answer "why does this tool run this model", run `teamai doctor`. Each alias agent gets
+a note with one line per tool: the model and effort it receives, then `[step: source]`.
+`extras` = `tool_extras.<tool>.model`; `switched` = the tool runs a model profile;
+`local` = the member's override (`tool default (chosen in <path>)` is their `~`/`default`);
+`team` = the team file named; `default` = no model field (alias unmapped for that tool, or
+no active file defines it). A Codex line with no effort means the session's effort carries
+over. A line naming what "the last pull deployed" is fixed by an ordinary `teamai pull`.
+The failing check `Agent model aliases can be resolved` names why agents are held (broken
+aliases file, namespace conflict, unreadable switched-tool settings) and which file to fix.
+
 ## References
 
 In the files below, `{SKILL_DIR}` is the directory `teamai skill path core` prints; a reference file you open on its own writes that directory as `SKILL_DIR` in braces.
@@ -116,7 +210,7 @@ In the files below, `{SKILL_DIR}` is the directory `teamai skill path core` prin
 | File | When to load it |
 |---|---|
 | `{SKILL_DIR}/references/commands.md` | Before using any command not in the daily list, or any flag. Generated from the CLI's own command table, so it cannot drift. |
-| `{SKILL_DIR}/references/troubleshooting.md` | A command fails, a hook does not fire, or a host needs manual steps. |
+| `{SKILL_DIR}/references/troubleshooting.md` | A command fails, a hook does not fire, a host needs manual steps, or a recalled doc got no upvote. |
 | `{SKILL_DIR}/references/contribute-member.md` | A member wants to publish a skill, rule or doc they already have. Any member can, not just admins. |
 
 `teamai skill get core --full` prints this skill with all three references

package/skill-data/core/references/commands.md

@@ -28,7 +28,7 @@ Generated: do not edit by hand. Regenerate with
   - `--no-inherit-user-scope` — Disable user-scope inheritance for this project
   - `--role <id>` — Primary role ID (e.g. hai_dev) for non-interactive setup
   - `--project <ids>` — Active logical project(s) from manifest/projects.yaml (comma-separated); scopes which project resources and learnings this directory syncs. Pass "all" to activate every project the manifest declares (a snapshot taken now)
-  - `--agent <name>` — AI tools to set up (e.g. claude, codex, cursor, codebuddy, workbuddy, dsh). Repeatable or comma-separated. In single-repo mode, selects which tool dirs to create; omit for an interactive picker. Additive on repeated runs.
+  - `--agent <name>` — AI tools to set up (e.g. claude, codex, cursor, codebuddy, workbuddy, dsh). Repeatable or comma-separated. In single-repo mode, selects which tool dirs to create; a custom agent defined only in teamai.yaml's toolPaths also gets its root created here (git-backed init only — an HTTP init has no local teamai.yaml to read custom paths from). Omit for an interactive picker. Additive on repeated runs.
   - `--force` — Overwrite existing config without confirmation
 
 ## push
@@ -193,13 +193,23 @@ Generated: do not edit by hand. Regenerate with
   - `--reveal` — Show env variable values in plaintext (default: masked)
   - `teamai env list` — List team environment variables
     - `--reveal` — Show env variable values in plaintext (default: masked)
-  - `teamai env add <key> <value>` — Add or update a team environment variable
-    - `-d, --description <desc>` — Description for the variable
-    - `--role <ns>` — Write to env/<ns>/env.yaml instead of env/env.yaml
+  - `teamai env add <key> [value]` — Add or update a team environment variable, or declare a secret with --secret
+    - `-d, --description <desc>` — Description for the variable or secret
+    - `--secret` — Declare a secret in env/secrets.yaml: no value, each member sets their own
+    - `--url <url>` — Where a member gets a value for the secret (with --secret)
+    - `--role <ns>` — Write to env/<ns>/ instead of env/ (env.yaml, or secrets.yaml with --secret)
     - `--project <id>` — Write to the project's env namespace (resources.env in manifest/projects.yaml)
-  - `teamai env remove <key>` — Remove a team environment variable
-    - `--role <ns>` — Remove from env/<ns>/env.yaml instead of env/env.yaml
+  - `teamai env remove <key>` — Remove a team environment variable or declared secret
+    - `--secret` — Remove the declared secret only (env/secrets.yaml), for a key env.yaml also sets
+    - `--role <ns>` — Remove from env/<ns>/ instead of env/
     - `--project <id>` — Remove from the project's env namespace (resources.env in manifest/projects.yaml)
+  - `teamai env set <key>` — Set your value for a secret the team declares, or an env variable it sets, for this directory's team, on this machine (prompts without echo)
+    - `--stdin` — Read the value from piped stdin
+    - `--from-env <var>` — Read the value from this environment variable each time it is used; no copy is stored
+    - `--global` — Set a secret for every team on this machine; a value set for a team still wins
+  - `teamai env unset <key>` — Remove your value for a secret or env variable, for this directory's team, from this machine
+    - `--global` — Remove the value set for every team on this machine instead
+  - `teamai env exec <command...>` — Run a command with this directory's team env variables and secrets (put -- before the command)
 
 ## hooks
 
@@ -296,6 +306,7 @@ Generated: do not edit by hand. Regenerate with
 - `teamai recall [query...]` — Search team learnings knowledge base
   - `--depth <level>` — Recall depth: route (entry-points only) | context (module-level, default) | lookup (full graph traversal)
   - `--check` — Relevance precheck only: print RELEVANT/NOT_RELEVANT + top score; no file reads, no upvote
+  - `--caller <name>` (hidden) — Internal, set by the teamai-recall subagent to mark its own runs; do not pass it yourself
   - `teamai recall disable` — Disable automatic knowledge-base recall
   - `teamai recall enable` — Enable automatic knowledge-base recall
   - `teamai recall status` — Show recall feature status
@@ -363,13 +374,13 @@ Generated: do not edit by hand. Regenerate with
 
 ## review
 
-- `teamai review [id]` — Inspect and process .teamai/pending-review.jsonl items
+- `teamai review [id]` — Inspect and process .teamai/pending-review.jsonl items; --dry-run validates apply decisions and previews rejections without writing documents or removing pending items
   - `--apply` — Apply the change for the given id (only for codebase-section)
   - `--reject` — Reject the given id without applying
   - `--reason <msg>` — Reason for reject
   - `--all-apply` — Apply all items at or below --max-risk
   - `--max-risk <level>` — Risk ceiling for --all-apply: high|medium|low (default medium)
-  - `--json` — Machine-readable output
+  - `--json` — Machine-readable output (dry-run decisions include dryRun: true; ok reports validation only)
 
 ## ci
 

package/skill-data/core/references/contribute-member.md

@@ -123,6 +123,7 @@ edit: unedited old instructions update in native format, including under
 Rule pre-sync leaves tools excluded by `enabledAgents` or `disabledAgents` untouched.
 When only team `paths` change, `applyTo` refreshes if the local file still matches
 a recorded version's generated copy; locally edited headers are kept.
+The copies push refreshes are recorded, so a later `teamai pull` still updates them.
 
 ## If push is denied
 

package/skill-data/core/references/troubleshooting.md

@@ -34,9 +34,10 @@ This is the #1 onboarding issue. In order:
    with `--scope user`.
 5. **Tool has no hook surface** (e.g. Gemini CLI, JoyCode): there is no auto-sync;
    run `teamai pull` manually each time.
-6. **Claude Code reads a different directory** (`CLAUDE_CONFIG_DIR` is set).
-   `teamai doctor` reports `Claude Code root matches CLAUDE_CONFIG_DIR` when the
-   directory the variable names is not the one this config syncs to. Re-run
+6. **Claude Code or Codex reads a different directory** (`CLAUDE_CONFIG_DIR` or
+   `CODEX_HOME` is set). `teamai doctor` reports `Claude Code root matches
+   CLAUDE_CONFIG_DIR` / `Codex root matches CODEX_HOME` when the directory the
+   variable names is not the one this config syncs to. Re-run
    `teamai init` from a shell that has the variable exported; it records the root
    and moves the install. If the check says the value cannot be synced to (outside
    your home, or nested deeper than `~/.config/<name>`), fix the variable first.
@@ -64,6 +65,38 @@ This is the #1 onboarding issue. In order:
    `recall` refuses the same way with `Nothing was searched: <file>: <reason>`:
    no team knowledge was searched, so do not report that the team has none.
 
+## "KEY is not set. Run `teamai env set KEY`"
+
+`pull`, `teamai mcp list`, `teamai env list`, `teamai doctor` and
+`teamai env exec` (on stderr) print this for a secret the team declares in
+`env/secrets.yaml` that has no value on this machine, naming the MCP servers
+that need it and where to get one. It is a note, not a failure: `doctor` exits
+as it would without it. The value is the user's: ask them to run
+`teamai env set KEY` in their own terminal (it prompts without echo), then
+`teamai pull` to update the MCP servers; a CLI run through `teamai env exec`
+gets it on its next run. Never ask for the value in chat or pipe one to
+`teamai env set --stdin`. A note that an entry "may hold an old" value means an earlier pull wrote
+it and it stays until a pull finds the value.
+
+`KEY reads VAR, which is not set` means the user's value for KEY is a
+reference to VAR (`--from-env`) and VAR is unset in this environment. Ask the
+user whether to set VAR in their shell or replace the reference with the
+command in the line; do not choose for them.
+
+## "Did not write <tool>'s MCP servers to <file>" / `withheld:`
+
+`pull` prints this, and `teamai mcp list` (`withheld:`) and `teamai doctor`
+report it, when a project MCP config would get a resolved `${VAR}` value that
+git would commit: the file could not be kept out of git first. It is left as
+it was, and an entry an earlier pull wrote stays. The line names the reason and the
+fix. For `git already tracks <file>`, tell the user: `git rm --cached <file>`
+(the file stays on disk), commit that, and rotate the token if the file was
+ever committed with it; then `teamai pull`. Do not run `git rm` or commit for
+them. For an exclude file that is not writable, one another teamai command
+held, or a git error, relay the fix the line gives.
+
+For new HTTP local-agent MCP installs, a failed initial ownership-manifest write leaves the MCP config and Git exclusions unchanged. Retry the install after fixing the manifest write error. A bare Copilot entry beside `mcpServers` is removed only with a matching ownership record proving a completed bare write. Older records without that evidence preserve the bare entry. A bare ownership record cannot claim a same-named member entry under `mcpServers`: updates skip the collision, and removal leaves that keyed entry alone. An unmarked Copilot record needs a matching keyed hash that does not also match the bare entry. Completed writes record `bare: true` or `bare: false`; missing placement remains unproven, including after a failed placement-record write. Existing JSON MCP updates keep the old ownership until the config write completes; a later manifest failure restores the config. `uninstall_mcp` keeps ownership if reading or writing the config fails, and restores the entry if removing its manifest record fails. MCP reconcile also restores all configs written before an ownership-save failure. If restoration fails too, repair the named configs and ownership records before retrying; the error reports both failures, and configs still carrying credentials stay excluded from Git.
+
 ## Permission / access denied
 
 `init`, `pull`, or `push` failing with a permission error usually means the user
@@ -111,7 +144,7 @@ broken machine):
 | Claude Code (`claude`)| Installed                 | Fully supported — this is the main, working path                    |
 | Codex                 | Written but **trust-gated** or skipped | Codex gates non-managed hooks behind an explicit trust step; `teamai doctor` prints a reminder to trust them |
 | Cursor                | Often not written         | Uses its own hook mechanism; broader CLI support is still pending   |
-| CodeBuddy / WorkBuddy | Skipped **by design**     | They only accept versioned plugins (`plugin@version`); teamai writes raw entries into a `hooks` field, which they don't take |
+| CodeBuddy / WorkBuddy | Installed                 | Claude-format hooks in their own `settings.json`                    |
 
 Practical rule: if you set up with `--agent claude`, expect **only** Claude to show
 hooks installed. A tool you are not using, or one that is not a supported hook
@@ -161,6 +194,27 @@ Gemini CLI, JoyCode, and similar tools have no TeamAI-writable hook surface —
 there is no auto-sync. Tell the user to run `teamai pull` manually at the start of
 each session.
 
+## "A recalled doc got no upvote"
+
+A recalled doc is upvoted once per session when the session that ran the recall
+opens it within 24 hours: a file read, a reader command (`cat`, `sed -n`, …), or
+a search whose output shows its lines. Listing the doc does not count, and
+neither does working from the recall subagent's summary alone; only the opt-in
+judge (`TEAMAI_UPVOTE_JUDGE=1`) credits that. `teamai stats` shows each recent
+session's runs, recalled docs and adopted docs. Per agent:
+
+- **Claude Code, Codex (0.134+), CodeBuddy (2.103.1+), WorkBuddy, Qoder,
+  OpenCode**: both a recall the main agent runs and one the `teamai-recall`
+  subagent runs are credited when the main agent opens the doc.
+- **Cursor, Copilot CLI, ZCode, OMP, Pi**: only a recall the main agent runs
+  itself. A subagent's recall is not linked to the main session, and Pi has no
+  TeamAI subagent.
+- **OpenClaw, Hermes, Kiro, JoyCode**: no PostToolUse hook, so recalls never
+  vote.
+
+A read after the session's last Stop is credited at SubagentStop, at Copilot CLI's
+SessionEnd, or at the next `teamai pull`.
+
 ## Still stuck
 
 - Re-run the failing command with `-v` / `--verbose` for detail.

package/skill-data/setup/references/join-member.md

@@ -69,6 +69,15 @@ to add them to the repo.
 
 ## Step 4 — Initialize with the URL (you run it)
 
+Before running `init`, ask whether the user wants to activate any logical
+projects this team repo declares. If `init` lists **Available projects**, show
+the names/IDs and ask which belong to this setup; enter the corresponding
+comma-separated numbers. Press Enter for none only when the user explicitly
+chooses no project. If the IDs are already known, pass `--project id1,id2` to
+skip the picker. For a non-interactive run, ask first and pass `--project`:
+without it, init keeps `projects: []` and prints a `teamai projects set <id>`
+follow-up instead of waiting for a choice.
+
 ```bash
 # this project only (run from inside the project)
 teamai init https://<platform>/<org>/<repo>
@@ -93,13 +102,14 @@ teamai init --http https://your-team-host/api --token <api-key>
 This is a read-only consumer mode — `push` / `contribute` are not available, but
 skills and rules still sync.
 
-**Claude Code kept in a different directory (`CLAUDE_CONFIG_DIR`):** `init` records
-that directory (as `toolRoots.claude` in the local config) and syncs every Claude
-path there, so run `init` from a shell that has the variable exported. Re-running
-`init` after changing it moves the install (the old root's hooks, managed MCP
-servers and delivered model credentials are removed; its skills and rules are left
-and named in the output). To end the relocation, run `init` once with the variable
-set but blank: `CLAUDE_CONFIG_DIR= teamai init …`.
+**Claude Code or Codex kept in a different directory (`CLAUDE_CONFIG_DIR`,
+`CODEX_HOME`):** `init` records that directory (as `toolRoots.claude` /
+`toolRoots.codex` in the local config) and syncs every path of that tool there,
+so run `init` from a shell that has the variable exported. Re-running `init` after
+changing it moves the install (the old root's hooks and managed MCP servers are
+removed, and for Claude Code its delivered model credentials; its skills and rules
+are left and named in the output). To end the relocation, run `init` once with the
+variable set but blank: `CLAUDE_CONFIG_DIR= teamai init …` or `CODEX_HOME= teamai init …`.
 
 ## Step 5 — Verify with doctor
 

package/skill-data/setup/references/manage-admin.md

@@ -31,12 +31,58 @@ run `teamai pull`).
 ```bash
 teamai mcp list        # team MCP servers + per-tool install status
 teamai mcp inject      # push team MCP servers into every AI tool's config
+teamai mcp remove --dry-run # preview removal without changing tool configs or managed records
 teamai mcp remove      # remove teamai-managed MCP servers
 ```
 
 MCP definitions travel with the team repo like skills/rules — edit, then the
 members pick them up on sync.
 
+A server with a `${VAR}` the tool cannot expand itself gets the resolved value
+written into its project config (`.mcp.json`, `.cursor/mcp.json`, ...). Before
+that write, teamai lists the file in the clone's `.git/info/exclude`, inside a
+`# [teamai:mcp-exclude:start]` block; the committed `.gitignore` is never touched.
+A file under a symlinked directory is listed and checked where the write lands
+(`.cursor/` linking to `config/`: `/config/mcp.json`); a symlink at the file
+itself is replaced by the write.
+When it cannot (git already tracks the file, a rule in the member's git ignore
+files re-includes it, `.git/info` is not writable, the exclude file is held by
+another teamai command, or git errors), it leaves the file as it was, warns, and
+`teamai mcp list` shows `withheld: <tool> — <reason>. <fix>`. Apply the fix it
+names (a tracked file: `git rm --cached <file>` and rotate the token; a
+re-including rule such as `!/.mcp.json`: remove it), then run `teamai pull`. A pull or `teamai mcp remove` takes a line out
+once its file no longer holds a resolved value; `teamai uninstall` does so in
+every worktree. A file written under a `toolPaths.<tool>.mcpProject` the team
+later changes or removes stays listed until it is deleted or holds no server;
+for one an older teamai wrote, the first pull finds the path in the team repo's
+history of `teamai.yaml`, or among the built-in paths teamai has since changed
+(not one the same tool maps today), and lists it while it holds any server; one
+git tracks is recorded instead and listed once the member runs `git rm --cached`
+on it. `teamai doctor` checks those paths until that pull. A file written for a
+tool the team moved elsewhere (recorded, or found in that history), that another
+tool still maps, stays listed while it holds a server that tool did not write,
+one of the member's own included. The built-in location of a tool the team drops
+from `toolPaths` or moves elsewhere stays listed while it holds any server; one
+another tool maps today (CodeBuddy's `.mcp.json`, which Claude maps) while it
+holds a server that tool did not write. A file two tools map, with no pull on
+this version having recorded it, needs a `managed-mcp.json` record from each of
+them. While a worktree has no `managed-mcp.json` at all (lost, or before its
+first pull), an untracked config holding a server no record claims is listed,
+and that server noted: it keeps the line until it leaves the file. So is the
+file of a tool `managed-mcp.json` has no record for, when a pull writes that
+tool's first record (its record lost, or teamai's first delivery to it). While that
+note cannot be written (another teamai command holds the record), the line stays
+until a later pull writes it. A Copilot project config's bare top-level servers
+still count once another tool writes `mcpServers` into the file. On an HTTP-backed
+team the local agent's `install_mcp` lists a project config before writing a
+server with any header, env value, argument or URL (only a bare stdio command is not), fails the install when it cannot, and only
+`teamai uninstall` takes that line out. The next sync or `teamai pull` in the
+workspace also lists a file an older local agent wrote a credential into; `teamai doctor` checks those files too.
+
+### Pi MCP delivery
+
+Pi 0.99.0+ receives stdio and streamable HTTP servers through the existing MCP commands and `teamai pull`; SSE is skipped. User scope writes `~/.pi/agent/mcp.json`, project scope writes `.pi/mcp.json` (Pi requires project trust). TeamAI keeps Pi's default codemode exposure and converts timeout milliseconds to seconds. Relocated Pi agent directories (`PI_CODING_AGENT_DIR` / `PI_CONFIG_DIR`) are unsupported. Local exposure/enabled edits on managed servers survive until the team definition changes; doctor reports differences from the team entry. Extensions that replace `/mcp` must be removed to use Pi's built-in MCP.
+
 ## Invite a member
 
 There is **no CLI invite flag.** Inviting is done on the Git platform's website:
@@ -150,10 +196,12 @@ teamai push                                 # share the updated teamai.yaml
 
 ```bash
 teamai env list              # what reaches this directory, each with its namespace (values masked)
-teamai env list --reveal     # show values in plaintext
+teamai env list --reveal     # show variable values in plaintext (never a secret's)
 teamai env add <KEY> <VALUE> # add or update in env/env.yaml
 teamai env add <KEY> <VALUE> --project <id>   # or --role <ns>: in that namespace's env/<ns>/env.yaml (warns if nothing declares <ns>)
 teamai env remove <KEY>      # remove (same --role / --project)
+teamai env add <KEY> --secret -d "<what it is for>" --url <where to get one>   # declare a secret in env/secrets.yaml, no value (same --role / --project)
+teamai env remove <KEY> --secret   # remove a declared secret (plain `env remove` does too when env.yaml does not set <KEY>)
 teamai remove mcp <name>     # root mcp/mcp.yaml if it has the name, else the one namespace file; --role / --project pick a namespace
 ```
 
@@ -171,17 +219,38 @@ and push it with git. `teamai doctor` lists each override.
   state is kept. Fix the file the warning names. A hooks or MCP file with none of
   its top-level keys (`server:` for `servers:`) counts as one that does not parse.
 - Per-entry `projects:` (and `roles:` on env) no longer works: such an entry reaches
-  nobody. `roles:` on hooks and MCP still filters for one more minor release. Pull
-  and `teamai doctor` name the namespace file each entry belongs in; move it there.
+  nobody. `roles:` on hooks and MCP still filters for one more minor release. Pull,
+  the list commands (`teamai env list`, `teamai mcp list`, `teamai hooks list`,
+  `teamai list <env|hooks|mcp> --source repo`), `teamai status` and
+  `teamai doctor` name the namespace file each entry belongs in; move it there.
+  When `teamai env add` updates a variable carrying either removed key, it keeps
+  the key and warns that pull will not deliver the variable, naming that file.
 - An env, hook or MCP entry with a key its schema does not know (a mistyped `role:`)
-  also reaches nobody. Pull and `teamai doctor` name the file, entry and key; correct
-  the key or remove it. A key a later teamai version adds is unknown to an older one,
-  so upgrade every member before the team uses a new entry key.
+  also reaches nobody. Pull, the list commands, `teamai status` and
+  `teamai doctor` name the file, entry and key; correct the key or remove it.
+  A key a later teamai version adds is unknown to an older one, so upgrade every
+  member before the team uses a new entry key.
 - Team model profiles work the same way: `models/<ns>/models.yaml`, declared under
   `resources.models`, replaces the root profile with the same `id` for members who
   have `<ns>` active. A member's API key is bound to the profile's gateway origin:
   when an override points at another host, their pull leaves the agent alone and
   asks them to run `teamai models switch team:<id>` to set the key for it.
+- Secrets are declared with no value in `env/secrets.yaml` or `env/<ns>/secrets.yaml`
+  (active through `resources.env`; a namespace entry replaces the root entry with the
+  same key): a `secrets:` list of `key`, optional `description` and optional `url`
+  (where a member gets one). Never put a value there: `teamai env add <KEY> --secret`
+  takes none and rejects one. Declare with it or edit the file in the team repo;
+  `teamai push` picks it up. Each member sets their own value with `teamai env set KEY`
+  in their terminal (`--global` for every team on their machine; a team value still
+  wins). `teamai env list` shows each secret as `team`, `global`, `environment`,
+  `missing` or `unreadable` and never shows a value, `--reveal` included. The `description` is what
+  agents see: the session-start hook lists each declared key with it and tells the
+  agent to run the CLIs that need them through `teamai env exec --`, so say which
+  tool or server uses the key. As the agent, run `teamai env add <KEY> --secret`
+  yourself and leave the value to each member's own terminal. A key declared as a secret
+  and also set in `env.yaml` is a secret: its `env.yaml` value is not delivered. A
+  secrets file that does not parse keeps `env.sh` and MCP servers as they were, and
+  `teamai doctor` fails a check naming the file.
 - Have every member upgrade before declaring `env`, `hooks`, `mcp`, `models` or `docs` in a
   manifest: teamai 0.25.0 and the 0.26.0 betas reject those keys and their pull stops.
 

package/skill-data/setup/references/setup-admin.md

@@ -165,6 +165,15 @@ suggested form `TeamAi-<team-name>`.)
 
 Use the **full URL**, never `owner/repo`:
 
+Ask whether the user wants to activate any logical projects this team repo
+declares. If `init` lists **Available projects**, show the names/IDs and ask
+which belong to this setup; enter the corresponding comma-separated numbers.
+Press Enter for none only when the user explicitly chooses no project. If the
+IDs are already known, pass `--project id1,id2` to skip the picker. For a
+non-interactive run, ask first and pass `--project`: without it, init keeps
+`projects: []` and prints a `teamai projects set <id>` follow-up instead of
+waiting for a choice.
+
 ```bash
 # project scope (default) — run from inside the project directory
 teamai init https://<platform>/<org>/<repo-name>

package/skill-data/setup/references/uninstall.md

@@ -55,3 +55,16 @@ and give it your team repo URL."*
   and neither should you.
 - If the user only wants to stop auto-sync for one tool but keep TeamAI otherwise,
   that is the `--agent <tool>` form, not a full uninstall.
+- In a project, uninstall also takes teamai's lines out of `.git/info/exclude`
+  (the `# [teamai:mcp-exclude:start]` block) for MCP configs it proves hold no
+  resolved `${VAR}` value. A line names the path a write lands in: for a config
+  under a symlinked directory, the link's target (`/config/mcp.json` for
+  `.cursor/` linking to `config/`). For one it cannot prove clean (including one written
+  under a `toolPaths` mapping since changed, at the built-in location of a tool
+  the team dropped or moved that no other tool maps, or in a nested repository's
+  linked worktree, that still holds servers, and one written for a tool since moved
+  (or at its built-in location) that another tool maps, holding a server that tool
+  did not write) it keeps the line
+  and warns, naming the file and why: have the user remove teamai's servers from
+  that file, then delete the line (with the last one, the block's markers). Do not
+  delete a kept line while its file still holds a token.