teamai-cli 0.27.0-beta.0 → 0.27.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamai-cli",
-  "version": "0.27.0-beta.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

@@ -127,6 +127,24 @@ changed since, or push says so for that copy, merge that change into the copy fi
 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:

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
@@ -253,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

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

@@ -117,13 +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,8 +31,22 @@ 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;
@@ -65,6 +82,34 @@ 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
@@ -142,8 +187,9 @@ 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   |
+| 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
@@ -160,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
 
@@ -204,9 +264,11 @@ 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
+  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
@@ -221,3 +283,34 @@ SessionEnd, or at the next `teamai pull`.
 - `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

@@ -126,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
 ```
 

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

@@ -134,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.
 

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

@@ -213,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
 
@@ -266,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,10 +60,51 @@ 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