teamai-cli 0.26.0 → 0.27.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamai-cli",
-  "version": "0.26.0",
+  "version": "0.27.0-beta.1",
   "description": "TeamAI — Make Every Team AI Native (skill sync + shared knowledge base, powered by Git)",
   "type": "module",
   "bin": {
@@ -81,6 +81,7 @@
     "@types/node": "^20.17.0",
     "@types/semver": "^7.8.0",
     "@vitest/coverage-v8": "^3.2.7",
+    "esbuild": "^0.27.3",
     "fast-check": "^4.10.2",
     "opencode-ai": "1.18.23",
     "oxlint": "1.85.0",

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,107 @@ 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.
+
+In project scope, `init` and `pull` also install a git hook in the repository's
+local git config (`hook.teamai-post-checkout`, `hook.teamai-post-merge`; Git
+2.54+; older Git without `core.hooksPath` gets a marked block in `.git/hooks/`
+scripts, and with it `teamai doctor` advises), beside any `core.hooksPath` manager or `.git/hooks` script. When a
+worktree is created by `git worktree add` or an app that runs checkout hooks, it creates the project roots
+of `enabledAgents` (else the ones the main checkout has) and pulls into it before
+the command returns, from the team clone as last fetched when that was within
+24 h; a full pull then runs in the background. A branch switch does nothing.
+After `git pull` it fetches the team repo (5 s cap, then the background pull) and
+delivers; in single-repo mode it delivers what `git pull` brought, offline. It prints nothing and always
+exits 0; a failure inside it is recorded, and `teamai doctor` names it (`Last git
+hook run failed: ...`) with its fix, as does the next interactive `teamai pull`, once.
+`teamai doctor` also reports whether the hook is installed, and why not.
+`pull --dry-run` says when it would install or update the hook, writing nothing;
+`teamai uninstall` removes only teamai's hook entries and blocks. For hosts that
+skip checkout hooks, prepare the worktree before launch; see the new-worktree
+section in `references/troubleshooting.md`.
+
+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 +228,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

@@ -12,7 +12,7 @@ Generated: do not edit by hand. Regenerate with
 ## Global options
 
 - `-V, --version` — output the version number
-- `--dry-run` — Preview mode, no changes made
+- `--dry-run` — Preview mode, no changes made; a command with no preview exits 1 without running
 - `-v, --verbose` — Verbose output
 
 ## init
@@ -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
 
@@ -243,7 +253,7 @@ Generated: do not edit by hand. Regenerate with
     - `--base-url <url>` — Personal profiles: new gateway root URL
     - `--protocol <protocols>` — Personal profiles: serve models over these protocols too
     - `--model <ids>` — Personal profiles: add model IDs
-  - `teamai models switch <profile>` — Point agents at a model profile (every compatible agent by default)
+  - `teamai models switch [profile]` — Point agents at a model profile (every compatible agent by default); omit the profile to pick one
     - `--agent <name>` — Only switch this agent. Repeatable or comma-separated.
     - `--model <id>` — Default model to select (defaults to the first in the profile)
     - `--dry-run` — Show what would change without writing
@@ -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

@@ -117,12 +117,32 @@ The doc lands in the team's `learnings/` and appears for teammates on their next
 - Teammates receive it automatically on their next session, or via `teamai pull`.
 
 Before listing rules, `push` refreshes copies whose bodies still match a recorded
-sync revision. Copilot's generated `applyTo` header does not count as a local
-edit: unedited old instructions update in native format, including under
-`COPILOT_HOME` in user scope. Genuine local body edits remain push candidates.
+sync revision. The header teamai generates for a tool's own rules format
+(Cursor `.mdc`, JoyCode's own `.mdc`, Copilot `applyTo`, Kiro `inclusion`, Qoder
+`trigger`, CodeBuddy and WorkBuddy `alwaysApply`, Oh My Pi `alwaysApply`/`globs`) does not count as a local edit: unedited old copies update in that
+format, including under `COPILOT_HOME` in user scope. Genuine local body edits remain push candidates.
 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.
+Oh My Pi and Kiro read only the top of their rules directories, so a namespaced
+rule is written flat there (`rules/fe/style.md` as `fe.style.md`); an edit of that file
+pushes back to `rules/fe/style.md`. Push requires a delivery record for the flat copy.
+A personal file with that name is neither refreshed before push nor offered as
+an edit of the team rule.
+If two namespaced rules flatten to the same name, neither is written; `teamai doctor`
+reports the collision even when no other rule reaches that tool. Rename one in the
+team repo, then run `teamai pull`. Doctor also reports team-owned OpenCode globs
+or inline blocks left after the last rule is removed.
+
+A new file in the rules directory of a tool with a rules format of its own
+(Cursor, JoyCode, Copilot, Kiro, Qoder, CodeBuddy, WorkBuddy, Oh My Pi) is the
+member's own rule in that tool's format: push never offers it, and pull leaves
+it. To author a new team rule, write it as a plain `.md` in `.claude/rules/`
+(scope it with `paths:` frontmatter, which teamai renders into each tool's
+format), then run `teamai push`. A YAML comment after an unquoted glob stays
+outside its scope: `paths: **/*.ts # TypeScript files` matches `**/*.ts`, including
+when written as a block-list entry under `paths:`.
 
 ## If push is denied
 

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

@@ -16,8 +16,11 @@ reports before anything else.
 
 This is the #1 onboarding issue. In order:
 
-1. **Open a fresh session.** Resources sync on **session start** via a hook, not
-   at init time. An empty skills folder right after `teamai init` is normal.
+1. **Did init pick this tool?** `teamai init` ends with a pull, but a project-scope
+   init creates only the directories of tools named with `--agent` or picked in
+   its interactive tool picker. Run without a terminal and without `--agent`, it
+   creates none, and a tool's project directory appears when that tool opens a session there. Re-run
+   `teamai init <repo> --agent <tool>` to add the tool and fill it now.
 2. **Sync manually to confirm:**
    ```bash
    teamai pull
@@ -28,15 +31,30 @@ This is the #1 onboarding issue. In order:
    ```bash
    teamai hooks inject
    ```
-4. **Wrong scope?** Project-scope hooks are written to your HOME tool settings
-   (e.g. `~/.claude/settings.json`), not the project folder — that is intentional.
+4. **Wrong scope?** Project-scope built-in hooks are written to your HOME tool
+   settings (e.g. `~/.claude/settings.json`), not the project folder; the team's own
+   hooks for Claude Code and Codex go to the main checkout
+   (`.claude/settings.local.json`, `.codex/hooks.json`). That is intentional.
+   Existing Claude/Codex main-checkout hook files count as installed targets
+   even when HOME and current worktree tool roots are missing. Injection and
+   pull update team hooks and restore HOME built-ins; removal clears managed
+   main-checkout hooks without recreating HOME roots.
+   If Git-hook installation fails after writing agent hooks, `hooks inject`,
+   `init` and self-repo bootstrap still attempt Codex trust. Injection preserves
+   the installation error without reporting overall success. Init reports the
+   error and retains exit code 1 while completing local setup, including HTTP
+   initialization. Bootstrap records the error in the debug log and continues
+   local setup.
+   In project scope, `teamai hooks remove` preserves other projects' gated team
+   hooks in HOME, while removing the shared built-in hooks.
    If you initialized project scope but expected machine-wide resources, re-run
    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 +82,66 @@ 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.
 
+## "Last git hook run failed: ..." / a new worktree lacks team resources
+
+In project scope, teamai's git hook syncs on `git worktree add` and `git pull`
+silently and always exits 0, so its failures surface only here: `teamai doctor`
+names the last one with its fix, and the next interactive `teamai pull` says it
+once. The causes are a team repo fetch that failed or hit the 5 s post-merge
+cap without the background pull finishing it, and another teamai process
+holding the project's sync lock longer than the hook waits, or incomplete resource,
+hook or MCP delivery. Only a complete startup sync clears the recorded failure.
+Run `teamai pull`
+in the checkout (after a stuck pull ends, or once the team repo is reachable);
+`~/.teamai/debug.log` has the details. If doctor reports `Git hook syncs new
+worktrees and git pull` as failing, follow its fix: `teamai pull` installs it.
+Git older than 2.54 has no config hooks: teamai then adds a marked block to
+`.git/hooks/post-checkout` and `post-merge`, unless `core.hooksPath` is set (or a
+hook there is a symlink or not an executable shell script), in which case doctor's fix says to upgrade Git
+or, if the team agrees, to commit its guarded `command -v teamai ... || true`
+line into the manager's post-checkout and post-merge hooks.
+Existing hook contents and permissions stay unchanged; read/write errors propagate
+from `init` and `hooks inject`, and Git-started pulls record them. An unreadable
+project config prevents sync and keeps its reason in `~/.teamai/debug.log`.
+
+Hosts that skip checkout hooks need `teamai pull` in the new checkout before the AI
+tool starts. For Codex CLI 0.160.0, use `git worktree add`, run `teamai pull` there, then
+launch `codex exec -C <worktree>`. Its native `codex exec --worktree` path creates
+the checkout without `post-checkout`, so SessionStart sync arrives after startup
+discovery.
+
+## "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
@@ -109,9 +187,10 @@ broken machine):
 | Tool                  | Hooks status              | Why                                                                 |
 |-----------------------|---------------------------|---------------------------------------------------------------------|
 | 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 |
+| Codex                 | Installed and trusted     | Codex runs only trusted hooks; teamai trusts the ones it writes through `codex app-server`, and `teamai doctor` names any Codex will not run |
+| Cursor                | Installed                 | Also runs `~/.claude/settings.json`. That copy exits only when `~/.cursor/hooks.json` or the project `.cursor/hooks.json` contains `--tool cursor` |
+| Copilot CLI           | Installed in self mode    | Also runs a trusted project's `.claude/settings.json`. That copy exits only when `.github/hooks/teamai.json` contains `--tool copilot`. `COPILOT_CLI` alone does not skip |
+| 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
@@ -127,17 +206,31 @@ step — do not assume auto-sync just works.
 
 ### Codex
 
-Codex gates non-managed hooks behind an explicit **trust** step. `teamai init` /
-`teamai hooks inject` may write the hooks, but Codex won't run them until the user
-trusts them (`teamai doctor` prints a reminder when it detects this). Guide the
-user to trust the teamai hooks in Codex, then reopen a session. Until then, run
-`teamai pull` manually.
+Codex runs a non-managed hook only once it is **trusted**. `teamai init`, `pull`
+and `teamai hooks inject` trust the hooks they write (and, in a project, the main
+checkout, or the current worktree for a bare repository) through `codex app-server`.
+Trust written by a session-start pull applies from the next Codex session. `teamai doctor` names any teamai hook Codex will not
+run. Then: run `teamai pull`; if `codex` is not on PATH or `codexTrustEnabled: false`
+is set in `config.yaml`, guide the user to trust the teamai hooks in Codex `/hooks`,
+then reopen a session. A new linked worktree gets the team hooks from its second
+Codex session (the first creates its `.codex/`). Member hooks with the same command
+are preserved and remain untouched by automatic trust. Codex ownership uses the
+recorded event, position and complete entry. A moved entry is recovered only by a
+unique full-definition match. Legacy records recover only a unique event, matcher
+and command match; `timeout` and `additionalContextLimit` were not recorded.
+Pre-#370 project Codex ownership is imported from the main checkout's
+`.teamai/managed-hooks.json` before reconciliation or direct removal.
+Unrecorded or ambiguous legacy team-hook copies are preserved. Project hook paths follow `toolPaths`;
+Claude uses `settings.local.json` beside its configured settings file. A custom
+Codex path that Codex does not load is reported as `not loaded` by doctor.
 
 ### Cursor
 
-Cursor uses its own hook mechanism and may not receive teamai's hooks yet. If
-`teamai hooks list` shows Cursor without hooks, treat it as a manual-sync tool: run
-`teamai pull` at the start of each session.
+Cursor writes hooks to `~/.cursor/hooks.json` and also runs `~/.claude/settings.json`. `hook-dispatch --tool claude` and team hook commands written for `claude` exit only when `CURSOR_VERSION` is set and `~/.cursor/hooks.json` or `$CURSOR_PROJECT_DIR/.cursor/hooks.json` contains `--tool cursor`. A setup with only Claude has no second copy, so those hooks still run inside Cursor. Claude Code does not set `CURSOR_VERSION`. An already installed team hook picks up the guard on the next `teamai pull` or `teamai hooks inject`. If `teamai hooks list` shows Cursor without hooks, run `teamai pull` at the start of the session.
+
+### Copilot CLI
+
+In self mode, teamai writes hooks into the project, and Copilot CLI runs a trusted project's `.claude/settings.json` as well as its own `.github/hooks/teamai.json`. `hook-dispatch --tool claude` and team hook commands written for `claude` exit only when `COPILOT_PROJECT_DIR` is set and that file contains `--tool copilot`. `COPILOT_CLI` is not a signal: Copilot sets it on every subprocess, including a Claude session started from its shell. Copilot does not run `~/.claude/settings.json`, so this duplicate does not happen outside self mode. Re-run `teamai pull` or `teamai hooks inject` so an already installed team hook picks up the guard.
 
 ### ChatGPT App
 
@@ -161,9 +254,63 @@ 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, OMP**: both a recall the main agent runs and one the
+  `teamai-recall` subagent runs are credited when the main agent opens the doc.
+  On OMP the subagent's recall needs the main session's file on disk, so a
+  `--no-session` run credits only the main agent's own recalls.
+- **Cursor, Copilot CLI, ZCode, 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.
 - `teamai status` shows exactly how local differs from the team repo.
 - Report unexpected behavior at https://github.com/Tencent/teamai-cli/issues
   with the agent name, platform, and the step that failed.
+
+## "Pull left an instruction file unchanged"
+
+If pull reports incomplete TeamAI markers, it keeps the entire file unchanged.
+Fix the named block so it has exactly one start marker followed by one end
+marker, then run `teamai pull` again. Other files can still sync successfully.
+
+Pull keeps retired instruction blocks until every installed tool that wrote the
+file has a working replacement. Repair the named target, extension or plugin
+and run `teamai pull` again. Excluded tools' current and retired files stay
+unchanged and are excluded from doctor's stale-instruction check.
+When a native project file retains a TeamAI block, the session hook skips that
+block, including cached HTTP prompts, until cleanup succeeds. Other blocks
+still reach the hook. Doctor reports malformed markers in retired files;
+repair them before retrying pull.
+If a block's source cannot be resolved, its old block stays even when other
+blocks sync. Repair the source and pull again to complete its migration.
+HTTP prompt commands verify earlier deliveries against the current prompt
+before cleaning shared instructions. Older destination contents do not count;
+culture and recall stay because HTTP prompt commands do not replace them.
+An HTTP prompt sync that cannot clean retired blocks reports a failed ACK and
+keeps its previous cache and manifest for the server's retry.
+OpenClaw HTTP prompts require an existing resolved user workspace, but not an
+existing `AGENTS.md`: the prompt sync creates that file and preserves personal
+text already in it.
+
+OpenCode registration saves ownership before activating a new config entry.
+If the state write fails, repair the state directory's permissions and retry
+`teamai pull`; the entry is not activated without its removal ownership.
+If the config write fails, ownership stays available for retry. Entries the
+member already listed are never claimed.

package/skill-data/setup/SKILL.md

@@ -46,13 +46,17 @@ and create-repo URLs, and the per-provider caveats, and points at
    install. Let `teamai init` set up every AI tool already installed (omitting
    `--agent` gives an interactive picker; select all detected tools). **After init,
    report which agents were set up** — in the user's language, which tools now
-   auto-start TeamAI, and which detected tools were skipped and why (e.g. Codex
-   trust-gate, CodeBuddy design). Verify the real per-tool result with
+   auto-start TeamAI, which detected tools were skipped and why (e.g. CodeBuddy
+   design), and any installed hooks that still need trust (e.g. Codex with
+   automatic trust disabled or unavailable). Verify the real per-tool result with
    `teamai doctor` and `teamai hooks list`.
-3. **After init, resources appear on the NEXT session.** `teamai init` injects a
-   session-start hook that auto-runs `teamai pull`. Empty skills/rules directories
-   right after init are normal; they fill in when the user opens a fresh session in
-   this tool. To sync immediately, run `teamai pull`.
+3. **`teamai init` ends with a pull.** In user scope, and in project scope for each
+   tool named with `--agent` (or picked in init's tool picker when a person runs it
+   in a terminal), the team's skills, rules and MCP servers are in place when init
+   exits; there is no need to run `teamai pull` after it. Run from an agent shell
+   (no terminal), a project-scope init without `--agent` creates no tool directory: a tool's directory appears and
+   fills when the user opens that tool in the project. Init also injects a
+   session-start hook that keeps resources synced from then on.
 4. **Finish with `teamai doctor`.** Every setup or onboarding flow ends by running
    it and resolving what it reports before you call the job done.
 

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
 
@@ -116,11 +126,14 @@ section "Which tools actually get hooks".
 
 ## Step 6 — Confirm the skills actually arrived
 
-Team resources sync on **session start**, so they may be empty right after init.
-To confirm now:
+`teamai init` ends with a pull, so the team's skills, rules and MCP servers are
+already in place in user scope, and in project scope for each tool named with
+`--agent` or picked in init's interactive tool picker. A project-scope init run
+without a terminal and without `--agent` creates no tool directory; a
+tool's directory fills when the user first opens that tool in the project. To
+confirm:
 
 ```bash
-teamai pull        # sync immediately
 teamai list        # see the team skills / rules / docs you now have
 ```