teamai-cli 0.26.0 → 0.27.0-beta.1

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:
@@ -88,7 +134,9 @@ teamai projects remove <id>  # remove a project
 
 A member gets the union of their role resources and their active project's
 resources. Admins declare projects in `manifest/projects.yaml` with the commands
-above, each of which opens a PR (`--dry-run` previews). After `projects remove`,
+above, each of which opens a PR. Until #971 lands and restores the guard
+classification, `roles init/add/update/remove` and `projects add/update/remove`
+refuse `--dry-run` before pulling the team repo. After `projects remove`,
 keep the project's content in the team repo until members have pulled: that is
 what lets their next pull clean up the copies they deployed.
 
@@ -150,10 +198,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 +221,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>
@@ -204,8 +213,9 @@ login` run in an interactive shell (see Step 3).
 Claude Code"). Omitting `--agent` gives an interactive picker — select **every AI
 tool already installed** on the machine. Then **report back which agents were set
 up**, in the user's language: name the tools that will now auto-start TeamAI, and
-any detected tool that was skipped and why (e.g. Codex trust-gate,
-CodeBuddy/WorkBuddy by design — see the troubleshooting reference, `"$(teamai skill path core)/references/troubleshooting.md"`).
+any detected tool that was skipped and why (e.g. CodeBuddy/WorkBuddy by design),
+and any installed hooks that still need trust (e.g. Codex with automatic trust
+disabled or unavailable). See the troubleshooting reference, `"$(teamai skill path core)/references/troubleshooting.md"`.
 
 ## Step 6 — Verify with doctor
 
@@ -257,9 +267,12 @@ carries counts + tool names only, on a separate branch of that same repo.)
    URL filled in. The `/teamai` prefix stays as-is; translate the rest:
    `/teamai Help me join my team's TeamAI, repo URL is <URL>`
    Tell them to send the URL + this line to each member.
-3. Remind them (in their language): **new resources appear only after opening a
-   fresh session** in the AI tool. Right after init the skills folder may look
-   empty — that is expected. To sync now, run `teamai pull`.
+3. Remind them (in their language): a member's `teamai init` ends with a pull, so
+   the team's resources are in place when it exits (in project scope, for each
+   tool named with `--agent` or picked in init's tool picker; otherwise a tool's
+   directory fills when the
+   member first opens that tool in the project). Resources the team adds later
+   arrive at the next session start.
 
 ## Step 9 — What's next (guide them, don't just list commands)
 

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

@@ -14,7 +14,14 @@ machine** (all tools)?"*
 
 - **Just this tool** → `--agent <tool>` (use the tool this conversation runs in,
   e.g. `claude`). Shared resources are removed only if it is the last tool using
-  them.
+  them. An instructions file several tools read (CodeBuddy and WorkBuddy share
+  `.codebuddy/rules/teamai-context.md`) is cleaned block by block: a teamai
+  block stays while a remaining tool on that file still writes it, so
+  `--agent workbuddy` keeps that file while CodeBuddy is installed. The team
+  rules in a project's `.codebuddy/rules` are shared the same way. A file an
+  earlier release wrote the blocks to, such as the project `AGENTS.md`, loses
+  its teamai blocks, since no tool reads them there now. A file teamai created
+  goes with its last block; one the user had before stays, even if empty.
 - **Whole machine** → no `--agent` flag.
 
 Reassure them (in their language): *"This only removes things from your computer.
@@ -23,6 +30,8 @@ Your team's repo on the website is untouched — you can rejoin any time with
 
 ## Step 2 — Run it (you run it)
 
+A targeted project exclusion needs the same confirmation even when there are no local files to remove. `--dry-run` and declining confirmation leave the project config unchanged.
+
 Whole machine:
 
 ```bash
@@ -51,7 +60,61 @@ and give it your team repo URL."*
 
 ## Notes
 
+- For OpenCode, uninstall also removes the rules globs teamai added to
+  `instructions` in `opencode.json`, including the relative `rules/*.md` an
+  earlier release wrote in user scope. In a project it removes
+  `.opencode/rules/**/*.md` from `.opencode/opencode.json` and the
+  `.opencode/rules/*.md` an earlier release wrote to the root `opencode.json`,
+  and deletes `.opencode/opencode.json` when nothing else is left in it.
+  The user's own entries stay.
+- Uninstall removes the team-rules block from the file a tool with no rules
+  format reads in user scope (`~/.codex/AGENTS.md`, `~/.zcode/AGENTS.md`,
+  `$DSH_HOME/AGENTS.md`, the OpenClaw workspace `AGENTS.md`,
+  `~/.pi/agent/AGENTS.md`, `~/.joycode/rules.txt`), and the file when teamai
+  created it for the block alone.
+- Uninstall cleans legacy Codex rule copies at the recorded `toolRoots`
+  location, including publishers' bare local filenames, and the copies earlier
+  releases left in a project's `.workbuddy/rules` and `.pi/rules`, in
+  `.openclaw/rules`, `~/.pi/agent/rules` and `~/.joycode/rules`. It keeps
+  edited copies and names them.
+  For a rule the team has
+  removed, it deletes the copy only if its hash matches the recorded delivery.
+  Without that record, it keeps the copy and names it in a warning. Save any
+  changes you need, then delete the copy manually.
+- If an OpenCode config entry cannot be removed, repair its config or permissions
+  and retry the same uninstall command. Uninstall reports failure and keeps
+  its ownership record and shared data directory, even for the last tool.
+- Project uninstall keeps the global Pi and Oh My Pi extensions, Hermes
+  plugin and config, and the Codex family's user-level hooks, which the user
+  scope, the HTTP agent or another project may use, and names them. If none
+  does, run `teamai hooks remove` in the project first: it removes them.
+  Targeted project Codex uninstall keeps project config and records its
+  exclusion, even without local resources. Legacy project hook copies go.
+  User-scope uninstall removes these global channels.
+  The retained adapters respect project exclusions, including cached HTTP
+  prompt injection and HTTP sync. An excluded tool does not download its
+  resources again on the next session start.
+- An enabled, installed Pi, Oh My Pi, Hermes or project Codex also keeps the
+  project's shared state in use without a local tool directory. Uninstalling
+  another tool preserves that state and the remaining tool's instructions.
 - Do **not** delete the team repo on the Git platform — uninstall never touches it,
   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 removes teamai's git hook: the
+  `hook.teamai-post-checkout` / `hook.teamai-post-merge` entries in the repo's git
+  config and the `# >>> teamai git hook` block in `.git/hooks/post-checkout` and
+  `post-merge`. Other hooks stay; a script left with only its shebang is deleted.
+- 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.