teamai-cli/CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

## [Unreleased]

### 💥 Breaking Changes

- An env variable, hook or MCP server with a key its schema does not know, such as a misspelled `role:` or a hand-added `notes:`, is no longer delivered to anyone: the key used to be dropped silently, so a misspelled restriction shipped the entry to every member. `teamai pull`, the list commands, `teamai status` and `teamai doctor` name the file, the entry and the key. `teamai env add` also warns when it updates a variable carrying the unknown key; it, `teamai env remove` and `teamai remove mcp` keep the key when they rewrite the file. A key that a later version adds to these entries is unknown to this one too, so an entry that uses it is not delivered to a member still on this version: upgrade every member before the team uses a new entry key, as for a new `resources:` key (for [#822](https://github.com/Tencent/teamai-cli/issues/822)).
- `manifest/projects.yaml` and `manifest/roles.yaml` now reject a resource namespace that is not a single path segment, as a project id already had to be (the id keeps its own narrower ASCII rule). A namespace becomes a directory component (`skills/<namespace>/`, `agents/<namespace>/`, `learnings/<namespace>/`), so `../evil`, `a/b`, `C:evil`, a bare `..`, any name with a trailing `.` or space — which Win32 strips, making `.. ` arrive as `..` and `frontend.` as `frontend` — and a Windows device name such as `CON` or `COM1` under `resources:` no longer parse; the error names the offending entry. Nothing else is rejected: a namespace that is a plain directory name still parses, non-ASCII names and names with a space included. A manifest that fails to parse now reports the offending entry on one line (`Invalid projects manifest: projects.0.resources.skills.1: ...`) instead of dumping a raw validation object. Two namespaces of one resource type that differ only by case (`frontend`, `Frontend`) are rejected too, within a manifest and between the two, since they name one directory on Windows and macOS. A manifest that ships any of these — a device name, a trailing `.`, a case-only pair — parsed before and fails every pull now; rename the directory and the entry together.
- **Upgrade every member before a team declares a new axis.** `resources:` in `manifest/roles.yaml` and `manifest/projects.yaml` accepts `env`, `hooks`, `mcp`, `models` and `docs`, but teamai 0.25.0 and the 0.26.0 betas reject a `resources:` key they do not know, so a team that declares one breaks pull for every member still on those versions. From this version on, an unknown `resources:` key prints one warning naming the role or project and the key, and the scope syncs as if the key were absent; `teamai roles` and `teamai projects` keep the key when they save the manifest. `teamai roles|projects add/update --namespaces` never write the new keys, so nothing declares them until an admin does by hand (for [#707](https://github.com/Tencent/teamai-cli/issues/707)).
- Per-entry scoping of env variables, hooks and MCP servers gives way to namespace files (see Features). `projects:` on an `env/env.yaml` variable, a `hooks/hooks.yaml` hook or an `mcp/mcp.yaml` server, and `roles:` on an env variable, existed only in the 0.26.0 betas and are removed: such an entry now reaches nobody, and pull, the list commands and status warn with the namespace file to move it to, one per listed id, so a project-only value never falls through to the whole team. `teamai env add` also warns when it updates an existing variable carrying either removed key, and preserves the key. `roles:` on hooks and MCP servers, which 0.25.0 shipped, is deprecated: it keeps filtering for one more minor release as 0.25.0 did, a name repeated in one file under different `roles:` included, pull warns once per run and `teamai doctor` has a check, both naming every target file. There is no automatic migration; move each entry into the file the warning names and drop the key. A member with no role in a team with `roles.yaml` received every `roles:`-scoped hook and server; once they move into `hooks/<ns>/` or `mcp/<ns>/`, that member no longer does (for [#707](https://github.com/Tencent/teamai-cli/issues/707)).
- Each tool reads only its own `tool_extras.<tool>` from a YAML agent. Qoder, Qoder CN, ZCode and OMP used to receive `tool_extras.claude` and ignore their own key, which `teamai push` wrote their edits to, so an edit never reached them; a team that relied on Claude extras reaching these tools moves those fields to `tool_extras.qoder`, `tool_extras.qoder-cn`, `tool_extras.zcode` or `tool_extras.omp`. tclaude and tcodex read `tool_extras.tclaude` and `tool_extras.tcodex` and fill the fields those lack from `tool_extras.claude` and `tool_extras.codex`, and `teamai push` writes their edits to their own key instead of the Claude or Codex one. The first ordinary pull after updating re-renders a copy an older CLI wrote this way when that CLI recorded delivering it and the member has not changed it since; any other copy is left as it is until the team next changes the agent (for [#830](https://github.com/Tencent/teamai-cli/issues/830)).
- **Upgrade every member before a team introduces model aliases.** An older CLI ignores `models/aliases.yaml` and writes `model: strong` into every tool as is, a model no tool knows, and its `teamai push` reads a model changed in a deployed copy as an edit, so it can replace `model: strong` in the team's agent with a concrete model such as `opus`. Have everyone update first, then add `models/aliases.yaml` and move agents to an alias. TeamAI does not check versions; the first ordinary pull after a member updates replaces a literal `model: strong` with the resolved model (for [#830](https://github.com/Tencent/teamai-cli/issues/830)).

### ✨ Features

- A YAML agent can set `model: strong`, `model: fast`, or an alias the team defines in an optional `models/aliases.yaml`, which maps each alias per tool to that tool's own model value and an optional effort. `teamai pull` writes the mapped model into every tool's agent file, and the effort into that tool's own field: `effort` for Claude, claude-internal, tclaude, CodeBuddy, Qoder and Qoder CN, `model_reasoning_effort` for Codex, codex-internal and tcodex, `variant` for OpenCode. Cursor receives its model string as written, so its bracket form (`claude-opus-5[effort=high]`) carries the effort; Copilot receives the first entry as one model string. Copilot, Cursor, Kiro, WorkBuddy, JoyCode, ZCode and OMP get no effort field: an effort mapped for them is dropped, and pull warns once, naming the alias and the tool. The `-internal` and `t` variants use the `claude` or `codex` entry and Qoder CN the `qoder` entry unless the alias has their own key; no other tool inherits one. A tool the alias does not map, or any tool when the team has no aliases file, gets no `model` field and runs on its default, never a literal `strong`. `tool_extras.<tool>.model` skips the alias for that tool, and an extras effort alone overrides the alias's effort. A `model` that is not a string now makes the agent fail to parse; a legacy `.md` agent whose `model` is an alias is copied as is with a warning. While `models/aliases.yaml` cannot be read, pull holds every agent that sets a `model`, since the file may define any name, and push skips them. Pull records the model each agent copy received, so an ordinary pull applies a changed resolution even when the team repo has not moved, which fixes an agent an older CLI wrote with `model: strong` as is, and delivers a copy that is missing; a copy the member edited is kept, and that pull names it with how to take the new model. Pull warns when an alias an agent resolved through is removed, also where the alias gave a tool no model field (for [#830](https://github.com/Tencent/teamai-cli/issues/830)).
- A member overrides a team model alias on their own machine in `~/.teamai/models/aliases.yaml`, in the same `aliases:` shape. An entry replaces the team's whole entry for that tool, effort included, and `~` or `default` gives the tool no model field and no effort; only `tool_extras.<tool>.model` wins over it. Keys are `strong`, `fast` or an alias the team defines, so a member can map `strong` before the team has an aliases file, and any other name has no effect. The file applies in every scope and to every team using that alias name, and an ordinary pull applies an edit to it. While it cannot be read, pull holds the agents whose `model` is an alias, naming the file, and push skips them; since the file can make no name an alias, agents with a concrete model are delivered and pushed as usual. In the team file, `default` is written as a model value and `~` is an error. When pull keeps an edited copy whose deployed version changed, it now says `the version teamai would deploy there ... has changed since` instead of blaming the team, since the change may be the member's override (for [#830](https://github.com/Tencent/teamai-cli/issues/830)).
- On a tool switched with `teamai models switch`, an agent whose `model` is an alias no longer sends an account model to the gateway: Claude keeps a resolved `opus`, `sonnet` or `haiku`, which the switch routes to gateway models, and drops any other model; Codex, OpenCode, CodeBuddy and WorkBuddy get no `model` field, so they use their native inheritance (for Codex, `[agents].default_subagent_model` or the parent session's model), not the profile's model. No switched tool gets an effort, the alias's or one set in `tool_extras.<tool>`, unless `tool_extras.<tool>` also pins a model. `tool_extras.<tool>.model`, a concrete `model` and a member's `~`/`default` are unchanged, and claude-internal, tclaude, codex-internal and tcodex are never treated as switched. A tool counts as switched only while its live settings path matches the recorded switch and still holds what TeamAI wrote, the checks `models restore` makes, so a stale record for another `CODEX_HOME` or `CLAUDE_CONFIG_DIR` has no effect. An ordinary pull after `models switch` or `models restore` rewrites the affected agents. While the switch records or a switched tool's settings cannot be read, pull holds alias agents in the tools concerned and says why (for [#830](https://github.com/Tencent/teamai-cli/issues/830)).
- `teamai push` keeps model aliases intact. For an agent whose `model` is an alias, a copy whose model and effort match what the last pull wrote or what a pull would write now is unedited, so pushing before pulling an alias change reports nothing. Push never proposes a concrete `model` over the alias and never writes the alias's effort into `tool_extras`, so adding an unrelated field no longer pins the effort. A hand-edited model or effort is reported as drift and left out, in `--dry-run` too, with where to make the change instead: the member's override file, the team's `models/aliases.yaml`, or `teamai models restore --agent <tool>` for a switched tool; the agent's other edits still push, and editing two tools no longer skips the agent over their different models. Writing an alias name in a deployed copy proposes `model: <alias>`. A new agent pushed from a tool's directory keeps its literal model. Push's warning about a kept copy whose deployed version changed now says `The version teamai would deploy at <path> ... has changed` instead of blaming the team, and for an agent it ignores a change of the model resolution alone, which push does not replace (for [#830](https://github.com/Tencent/teamai-cli/issues/830)).
- A broken model aliases file never changes anyone's models. A structural error in `models/aliases.yaml` or `~/.teamai/models/aliases.yaml` (YAML that does not parse, a wrong type, a bad alias name, an effort without a model, `~` in the team file, top-level keys but no `aliases:`, such as a misspelled `alias:`) makes `teamai pull` keep every agent with a `model` as deployed, deploy none of them anew and leave their recorded models alone, with a warning naming the file, and once the file is fixed an ordinary pull delivers them, including ones it never deployed and team changes that arrived meanwhile (a pull that holds an agent, on an unchanged team repo too, says so and does not count the team revision as synced, so the next one syncs in full, and sends no `pull` webhook; `teamai pull --dry-run` names the agents it would hold); `teamai push` skips those agents with the reason and pushes the rest. While it lasts, inactive-namespace cleanup leaves the root agent a held namespace agent replaces in place. A tool key teamai does not know, an option field other than `model` and `effort`, and an alias named like a tool's own model alias (`opus`, `sonnet`, `haiku`, `fable`, `inherit`, `default`, `auto`, `lite`) are dropped with a warning and the rest of the file applies; `gateways` inside an alias is ignored silently. Pull now prints an aliases warning only when it delivers an agent that uses that alias, for a tool entry only to that tool, instead of on every pull (for [#830](https://github.com/Tencent/teamai-cli/issues/830)).
- Model aliases can be scoped: `models/<ns>/aliases.yaml`, read where `<ns>` is active in `resources.models`, replaces the root alias of the same name whole for members with that namespace active. The same alias in two active namespaces holds agents with a `model` field, naming both files, as a structural error does. A name defined in any aliases file of the team repo, active or not, is an alias, so an agent whose alias only an inactive namespace defines gets no `model` field instead of the name written literally, and a member's local entry for it applies. Pull warns once per such alias, naming its files, and says to activate the namespace or, if the name was meant as a concrete model such as `gpt-5-codex`, to rename the alias; a structural error in any of these files holds alias agents too. Pull records which file each agent copy's model came from, and pull warnings and push drift name that file. `teamai doctor` notes an alias that agents you receive use when a namespace not active for you defines it (for [#830](https://github.com/Tencent/teamai-cli/issues/830)).
- `teamai doctor` shows how each agent's model alias resolved: per agent that uses an alias and per installed tool, the model and effort the tool receives and the step that decided it (`extras`, `switched`, `local`, `team`, `default`) with its source file, as notes. A member's `~`/`default` reads `tool default (chosen in <path>)`, a Codex-family model without effort says the session's effort carries over, and a line names what the last pull deployed when that differs. Every aliases entry this CLI drops is a note too. A new failing check, `Agent model aliases can be resolved`, names the reason, file and held agents while a structural error in any aliases file, a namespace conflict or an unreadable switched tool's settings holds agents; it also runs after an interactive pull. `Every team agent reaches a tool` no longer counts held agents, and `Agents delivered to <tool>` lists a copy that only carries the previous resolution as `model changed since the last pull`, which a plain `teamai pull` fixes, so it does not fail the check. Pull now names the agents it holds for one reason in a single warning and leaves them out of `Synced N agents` (for [#830](https://github.com/Tencent/teamai-cli/issues/830)).
- Env variables, hooks and MCP servers are scoped the way skills and agents are. `env/<ns>/env.yaml`, `hooks/<ns>/hooks.yaml` and `mcp/<ns>/mcp.yaml` reach only members whose role or directory's project lists `<ns>` under `resources.env`, `resources.hooks` or `resources.mcp`; the root files still reach everyone. A namespace entry replaces the root entry of the same variable `key`, hook `id` or server `name`, whole: an MCP override carries its own `command`, `args`, `env` and `tools:`, and one without `tools:` reaches every tool. When a namespace stops being active the next pull, `Already synced` included, restores the root entries it overrode and removes the ones only it had; `env.sh` is rewritten even when `env/env.yaml` is missing or declares nothing, and MCP `${VAR}` reads the same resolved variables. `teamai env add` and `teamai env remove` take `--role <ns>` / `--project <id>` to edit a namespace file (`--role` warns when no role or project declares the namespace; neither edits a file that does not parse, and `--project` changes nothing when the team repo cannot be refreshed), `teamai push` picks up a change to any `env/<ns>/env.yaml`, and `teamai remove mcp <name>` removes from the root file when it defines the name, otherwise from the one namespace file that does, asking for `--role` / `--project` only when several do, and removing nothing by a bare name the root file does not define while an MCP file does not parse; a flag that names a file that does not parse says so instead of reporting the name as not found. `teamai env list`, `teamai mcp list`, `teamai hooks list` and `teamai list <env|hooks|mcp> --source repo` show each entry's namespace and whether it overrides the root, and `teamai status` and `teamai doctor` count per namespace. A hooks or MCP file that cannot be resolved makes `teamai hooks inject` and `teamai mcp inject` exit 1 instead of reporting success, and hooks or model profiles that cannot be resolved fail `teamai doctor`'s `Team hooks can be resolved` or `Team model profiles can be resolved`, where `teamai status` points. A declared namespace matches its directory case-folded, as docs namespaces do, so `env/Checkout/` serves `env: [checkout]` on Linux too, and `--role` / `--project` write into that directory. So a checkout project can point `API_BASE` or a shared MCP server at its own backend under the same name (for [#707](https://github.com/Tencent/teamai-cli/issues/707)).
- An item in an active namespace replaces the root item of the same name for skills, agents, rules and CLAUDE.md fragments too, so contradictory versions are no longer delivered side by side. An agent in `agents/<ns>/` replaces the root agent of the same stem instead of failing the pull, and deactivating the namespace brings the root agent back; a root file of the same stem no longer withdraws a placement record. `rules/<ns>/<name>.md` replaces `rules/<name>.md`, in Hermes' `SOUL.md` block too; deeper paths replace nothing. In the rule directories shared with a member's own rules (JoyCode, OMP, Pi, Copilot), the replaced root copy is removed while it is what teamai delivered, now or at the last pull, and an edited copy is kept and named on each pull. `claudemd/<ns>/<name>.md` replaces `claudemd/<name>.md` in the managed block. A root skill received through a tag is replaced by an active namespace skill of the same name; root skills are still not delivered by default in role or project mode, and among tag matches the root skill wins over one in an inactive namespace. Installing a skill removes the files that another team version of it has and the new one lacks, when they match that version byte for byte, so switching between versions leaves nothing of the other behind, while a file you added or edited stays; one at a path another version has is named on each pull. `teamai push` writes an edit of a replacing item back to its namespace and never to the root, and the skills push scan covers project namespaces as well as role ones. `teamai recall` indexes the skills and rules you receive rather than every one in the repo, so a replaced root rule or a rule of an inactive namespace is not returned. Two namespace rules or CLAUDE.md files of one name are both delivered, since each keeps its own place. A replacement that cannot be used replaces nothing: a skill directory without `SKILL.md` is not delivered (pull names it), and while an agent file does not parse the agent it would replace stays installed. `teamai doctor` lists every replacement as a note, in `--json` under `notes`; without roles or projects nothing changes, and the notes list each name the team repo defines more than once. Keep content a project may override at the root: a namespace item never gives way, so a rule in `rules/common/` is delivered beside a project's rule of the same name (for [#707](https://github.com/Tencent/teamai-cli/issues/707)).
- `docs/<ns>/` can be scoped: once any role or project lists `<ns>` under `resources.docs`, those docs reach only the members who have that namespace active. A `docs/<dir>/` that no role or project lists stays shared, so existing subdirectories keep reaching everyone. When the namespace stops being active, the next pull removes the local copies that still match the team file byte for byte, now or in an earlier team commit, and keeps an edited one, naming it. The docs mirror of `sharing.docs.localDir` copies only the docs a member receives and never removes such an edited copy. `teamai recall` and `teamai doctor`'s `Team docs delivered` follow the same filter, and doctor does not report a kept copy as stale. `team-codebase` cannot be a docs namespace, since `docs/team-codebase/` is the legacy codebase output; a manifest that declares it fails to load (for [#707](https://github.com/Tencent/teamai-cli/issues/707)).
- Team model profiles can be scoped: `models/<ns>/models.yaml`, declared under `resources.models`, replaces the root profile of the same `id` for members with that namespace active. Agents switched to `team:<id>` follow the override on the next pull and return to the root profile when it deactivates; a profile that existed only in a namespace you left keeps your agent settings, and pull says it `is no longer active in your namespaces`. A stored team API key is bound to the profile `id` and the origin (scheme, host, port) of its `base_url`, so an override never sends your key to another gateway: when a profile moves to an origin you have no key for, pull leaves the agents switched to it alone and prints ``Run `teamai models switch team:<id>` to set a key for it.``, and the key for the first gateway is kept for when you leave the namespace. The same applies when the team moves the root profile to another origin, with or without roles and projects, so each member runs the switch once per new gateway. Model profiles exist only in the 0.26.0 betas, so no stable release is affected. A key stored by a beta is bound once, at the first command or pull that reads it: to the gateway TeamAI last wrote it into for your agents, or, if no agent was switched to that profile, to the root profile's current gateway. If the team moved the root profile to another origin since your agent was switched, pull leaves that agent alone and asks for the switch, rather than sending the old key to the new host. `teamai models list` shows the file each team profile comes from, and `teamai push` refuses any invalid models file (for [#707](https://github.com/Tencent/teamai-cli/issues/707)).
- Built-in skill content ships inside the npm package and is printed by the installed CLI: `teamai skill get <core|setup|wiki|share> [--full] [--all]`, `teamai skill path <name>` for the directory holding a skill's scripts, and `teamai skill list --json` for the catalog. Agents receive one file, `skills/teamai/SKILL.md`, a discovery stub that points at those commands, so what an agent reads always matches the CLI version it is running. `teamai pull` removes the `team-wiki-codebase`, `teamai-share-learnings` and `teamai/references/*.md` trees earlier releases copied into every agent directory, removing only files whose content a release shipped (an edited file, or a member's own skill under an old name, stays), archiving each removed file under `~/.teamai/removed-skills/<run>/…` first, and keeping any directory that holds a member's own file; `teamai uninstall` removes only the packaged files from CLI-owned skill directories by the same rule. `share` is served only while recall is on and the team source is writable (not a read-only HTTP one), and the end-of-session share reminder is withheld until then too. The served workflows are English; learning and knowledge-base documents are still written in Simplified Chinese, and an existing knowledge base keeps its file names and headings. The legacy names still resolve as aliases (for [#678](https://github.com/Tencent/teamai-cli/issues/678), [#730](https://github.com/Tencent/teamai-cli/issues/730)).

- `teamai doctor` now checks what landed for every resource, not only skills and docs. `Rules delivered to <tool>` and `Agents delivered to <tool>` ask the resource handler where an item lands — a rule's filename and content change per tool, an agent's destination comes from its render and its `targets:` — and compare a delivered rule with the bytes the handler renders for that tool, so a `.mdc` whose `globs` drifted from the team rule's `paths:` is reported rather than passing on the presence of its frontmatter keys. An agent is compared with the bytes its render produces, so a copy left behind by an older spec is reported rather than counted as delivered. `Every team agent reaches a tool` names an agent that renders for no installed tool, and is reported whenever a tool is installed to receive agents, including when no agent renders anywhere. Two tools do not read a rules directory and get a check each: `Team rules are active in opencode` fails when `opencode.json` stops listing the glob that makes the delivered `.md` files load at all, and `Team rules are inlined in Hermes SOUL.md` compares the managed block of `SOUL.md` with what the team rules inline to. `MCP servers delivered to <tool>` compares each server the team resolves for a tool with the entry in that tool's own config — the entry, not the name, since reconciliation leaves an entry teamai does not own alone, so an unrelated server under a team name holds the key while the team's definition never arrives — and names any the reconcile skipped with its reason, so an unresolved `${VAR}` is reported with the variable instead of being mentioned once during a pull and never again. An `mcp.yaml` that does not parse is reported as `Team MCP servers can be read` rather than read as a team shipping no MCP at all. `Env variables injected in shell profile` stops at the marker comment no longer: it checks that `env/env.yaml` parses and declares its variables under `variables:` (an explicit `variables: []` is an empty configuration and fails nothing), that each reached `env.sh` with the declared value — read back through the generator's own inverse, so a multiline value quoted across several lines is matched rather than reported stale — and that the injected block would actually load it. The two expensive registries, rules and agents, are built for `teamai doctor` only, so the checks at the end of a pull keep their budget (for [#624](https://github.com/Tencent/teamai-cli/issues/624)).
- A manual `teamai pull` ends by running the `teamai doctor` checks and printing each one that failed, with its fix. It prints nothing when they all pass, the exit code is unchanged, and the SessionStart hook path (`--silent`) and `--dry-run` run no checks, so session startup is untouched. Provider authentication checks are left to `teamai doctor`: the pull just used the provider. So is any check that pull already reported in its own words on that run — the queued-learnings warning is not immediately repeated as a check telling you to run the pull you just ran. A check the pull stayed silent about is still printed (for [#598](https://github.com/Tencent/teamai-cli/issues/598)).
- `teamai doctor` now checks what landed, not only the plumbing. `Skills delivered to <tool>` compares the skills your roles, tag subscriptions and exclusions resolve to against each installed tool's directory, reporting a skill that never arrived separately from one that arrived unreadable (`SKILL.md` missing, unparseable frontmatter, or a `name` that does not match the directory, which keeps the agent from discovering it). `Team docs delivered` does the same for the docs bundle against `sharing.docs.localDir`. `<tool> is installed` fails when `enabledAgents` lists a tool with no directory here, instead of skipping it silently, and reports an installed one as passing so `--json` carries an entry either way. Resolving a skill's destination without a team copy to compare against no longer warns about a Codex shared-directory conflict, so a read-only `doctor` stops reporting one for copies the pull treats as identical. The installed check asks the same resolver the sync uses, so OpenClaw is judged at its workspace directory rather than its tool root. `Team docs delivered` requires each expected document to be a readable file, not merely a name that exists. And a pull that found a scope locked by another process runs no checks at the end, since they would read a clone that process may have mid-write (for [#598](https://github.com/Tencent/teamai-cli/issues/598)).
- `teamai remove` accepts `--force` to skip its confirmation prompt, spelled the same way as `teamai uninstall --force`. Without a TTY the prompt answers itself with no, so this is the only way to remove a resource from a script or a test (for [#591](https://github.com/Tencent/teamai-cli/issues/591)).
- MCP servers in `mcp/mcp.yaml` and hooks in `hooks/hooks.yaml` accept an optional `roles:` list and ship only to members holding one of those roles; a role change removes the previous role's entries on the next pull, and `teamai mcp list` / `teamai hooks list` show the restriction (for [#563](https://github.com/Tencent/teamai-cli/issues/563)).
- Agents can be scoped by role or project: `agents/<namespace>/` ships only to members whose `roles.yaml` / `projects.yaml` entry lists that namespace under a new optional `agents:` key, and a role change removes the previous namespaces' agents on the next pull (for [#563](https://github.com/Tencent/teamai-cli/issues/563)).
- First-class Kiro support: skills, steering rules, JSON subagents with CLI `agentSpawn` session-start hooks, and MCP sync to `.kiro/` (for [#500](https://github.com/Tencent/teamai-cli/issues/500)).
- Multi-project management: `role` and `project` together resolve resource namespaces, and project-private learnings are isolated ([#426](https://github.com/Tencent/teamai-cli/pull/426), for [#375](https://github.com/Tencent/teamai-cli/issues/375)).
- Data partitions auto-migrate a legacy `.teamai`, resume interrupted migrations, smoke-check the clone, and keep a git-ignored backup ([#439](https://github.com/Tencent/teamai-cli/pull/439), for [#374](https://github.com/Tencent/teamai-cli/issues/374)).
- Teams add their own course-correction words via `sharing.intervention.correctionKeywords` in `teamai.yaml`. The built-in list still covers only Chinese, English and Japanese, so corrections typed in other languages count only once the team configures them. The `UserPromptSubmit` hook now stores a `correction` flag on each dashboard prompt event (for [#564](https://github.com/Tencent/teamai-cli/issues/564)).
- `teamai init <repo> --provider <name>` uses the named provider instead of detecting one, so a member of a team on self-hosted GitLab can join with `--provider git` and their existing Git authentication, without `GITLAB_TOKEN`. The choice is saved in that machine's local config and takes precedence over the team's `teamai.yaml` `provider` for PR/MR creation and for `teamai doctor`'s provider checks; an existing `teamai.yaml` is unchanged, so other members keep the team's provider, and a `teamai.yaml` that `init` creates records the provider `init` would detect without the flag rather than `git`, and stops with a `GITLAB_URL` hint on an unconfigured self-hosted GitLab. `--provider gitlab` on a host that is not the configured `GITLAB_URL` or `TEAMAI_GITLAB_HOST` stops with a hint instead of sending the token to gitlab.com. With `git`, `teamai push` pushes the branch and leaves the merge request to be opened on the Git host, exiting non-zero as it does for a `provider: git` team repo. Re-running `init` without `--provider` returns to auto-detection. The value must be one of `tgit`, `github`, `cnb`, `gitlab`, `gitcode` or `git`, and `--provider` cannot be combined with `--http` (for [#789](https://github.com/Tencent/teamai-cli/issues/789)).
- Pi Coding Agent can use team model profiles, so `teamai models switch` reaches it like every other supported agent. TeamAI writes one provider into `~/.pi/agent/models.json`, keyed by the profile ref and labelled with its `name`, holding every catalog model. Pi resolves the api and the URL per model, so that one provider covers a catalog spanning all three protocols; a model served over several protocols is registered once, preferring an OpenAI one, and declaring a model such as `claude-opus-4-8` in an `anthropic`-only group pins it to Anthropic Messages. The key is the profile ref rather than the bare `id`, which is unique only within one catalog file, so a root and a namespace profile sharing an id do not overwrite one another. A key configured from the environment is written as `$VAR`, Pi's own indirection, so no secret lands in the file, and a member's other providers in the same file are never touched — a switch over one TeamAI already wrote is not a collision, while a first switch refuses a provider the member already has under that ref. Pi's `settings.json` is left alone, so the default model stays the member's choice, as Claude's `/model` pick already is, and `PI_CODING_AGENT_DIR` is honored the way `CODEX_HOME` is. `teamai models restore` puts the file back, removing the key the last switch created even when the team has since re-pointed the profile at a different ref, and restoring without `--agent` now covers Pi too.

### 🐛 Bug Fixes

- Team rules reach Codex, `codex-internal` and `tcodex`. Pull used to copy them to `.codex/rules/<name>.md`, which Codex does not read, and `teamai doctor` reported them delivered. In user scope they now go into a team-rules block of the tool's own `AGENTS.md` (`~/.codex/AGENTS.md`), beside the culture, shared-instructions and recall blocks. In a project the session-start hook adds the project's rules and those blocks to each session, and to a spawned subagent through a new `SubagentStart` entry, with `additionalContextLimit: 0` so Codex keeps them whole; pull leaves the project `AGENTS.md`, which other tools read too, unchanged. Pull removes the `.md` copies earlier pulls left in `.codex/rules/`, keeping an edited one with a warning. Pull and uninstall keep a removed rule's legacy copy unless it matches its recorded delivery hash; a missing record proves nothing about local edits. A path-scoped rule is rendered without frontmatter after an `Applies to files matching: <globs>` line, in Hermes' `SOUL.md` too. `teamai doctor` checks the user-scope block and, in a project, both hook entries' limit. The public Codex asks once to approve the changed teamai hooks (for [#938](https://github.com/Tencent/teamai-cli/issues/938)).
- `teamai pull` names the skills it removes because they are no longer delivered here, in one line, instead of a `debug` line calling them excluded and a summary that says `No resources to sync`. Picking a role or project, or an admin adding `manifest/projects.yaml`, takes root skills away, since the root `skills/` is then the tag catalog; the line then says that `teamai tags subscribe <tag>` brings one back. A namespace skill removed because its namespace is no longer active is named too. The usage guide and the multi-project design no longer say a member with no project still gets `common` or every root item (for [#911](https://github.com/Tencent/teamai-cli/issues/911)).
- `teamai pull` keeps the `teamai tags subscribe <tag>` recovery line when the skill directory it removes is byte-identical to an inactive namespace copy: that copy made the namespace cleanup phase remove the directory first, and the hint was lost, because pull inferred whether a root skill had left from which phase did the removing. The hint now follows the repo — it appears exactly when the team repo holds the removed skill at the root, the copy a tag delivers — so a namespace-only skill removed on deactivation is still named without the hint. The usage guide no longer says a member with no role gets no skills at all, in English or Chinese: root skills still arrive through a tag (review of [#917](https://github.com/Tencent/teamai-cli/pull/917)).
- `teamai pull` keeps a skill, rule or agent you changed since teamai delivered it instead of overwriting it, and names it: `Kept <path>: you changed it since teamai delivered it`, with a warning when the team version has changed since, which `teamai push` repeats for that copy, since the SessionStart pull is silent. Pull records the sha256 of what it writes at each path in the checkout's record, and the pre-push sync records its writes too, so a copy counts as changed only against that record; a skill counts as one copy, and files only you added do not count. The copies of other tools still update. `--force` keeps these copies, `--dry-run` prints `Would keep <path>`, and a copy of an item the team removed stays when you changed it. To take the team version, delete your copy and run `teamai pull --force`. There is no record before the first full pull on this version, or in a new worktree, so that pull overwrites as before. A file you added to a skill at a path another team version of it has is no longer named on every pull, and `teamai doctor` no longer fails a rules or agents check, or points at `teamai pull --force`, for a kept copy: it lists one as `changed by you (kept by pull)` beside any other problem (for [#822](https://github.com/Tencent/teamai-cli/issues/822)).
- On macOS, the git commands behind pull, push, reports and learnings publishing no longer wait on a PATH search each time they run. teamai spawned `git` by name, and on macOS that lookup costs a few milliseconds for each PATH entry ahead of git's directory: 30-67 ms per call with a typical PATH, while git itself takes about 8 ms. teamai now runs the `git` that lookup would pick by its absolute path, found once and again whenever PATH changes or that `git` is gone or no longer executable, and only once a `git --version` by that path starts. On macOS 26 an up-to-date `teamai pull` drops from 1.3 s to 0.4 s with a 42-entry PATH, and from 2.0 s to 0.4 s with the PATH an npm script gives; macOS 27 no longer shows the lookup cost. Windows, a PATH with an empty or relative entry, a first `git` on PATH that does not start (a missing interpreter, no execute permission), and the few one-off git calls outside these paths (provider clone, version and user probes) keep the bare-name spawn (for [#868](https://github.com/Tencent/teamai-cli/issues/868)).
- On Node 24, `teamai codebase --extract`, and the `teamai import` and CI extract paths that run it, no longer abort with `Fatal process out of memory: Zone` on a repository with `.swift` files. V8's optimizing Wasm compiler (nodejs/node#63421) ran out of memory on the tree-sitter grammars, so the AST track now keeps them on V8's baseline tier on Node 24 and later. That also cuts the TypeScript grammar's peak memory there from about 1.4 GB to about 0.1 GB, for a parse about 1.6x slower; Node 20 and 22 are unchanged (for [#860](https://github.com/Tencent/teamai-cli/issues/860)).
- `teamai remove mcp ambiguous` removes a server named `ambiguous` from `mcp/mcp.yaml`. The name matched the value `remove` used internally to mean "refused", so the command printed `Nothing was removed.`, exited 1, and gave no reason (for [#862](https://github.com/Tencent/teamai-cli/issues/862)).
- When `TEAMAI_GITLAB_HOST` and `GITLAB_URL` name different hosts, GitLab commands stop with an error naming both, before any request. A repo on `TEAMAI_GITLAB_HOST` was detected as GitLab while every API call, the token included, went to `GITLAB_URL`. An invalid `GITLAB_URL` is now reported as such by `init` instead of as a failed GitLab login (for [#789](https://github.com/Tencent/teamai-cli/issues/789)).
- A misspelled top-level key in `mcp/mcp.yaml` or `hooks/hooks.yaml` (`server:` for `servers:`, `hook:` for `hooks:`) no longer removes every installed team MCP server or hook: such a file read as empty. It now fails like a file that does not parse, so pull keeps what is installed, and pull and `teamai doctor` name the file, the keys found and the key expected. An extra top-level key beside `servers:` or `hooks:` is still ignored (for [#822](https://github.com/Tencent/teamai-cli/issues/822)).
- The closing line of `teamai recall` output is in English (for [#822](https://github.com/Tencent/teamai-cli/issues/822)).
- The dashboard event log no longer drops events to a compaction race. `~/.teamai/dashboard/events.jsonl` is appended by every dashboard hook on the machine, and compaction shrank it by a lock-free read → filter → temp-file → rename, so an event appended between the rewrite's read and its rename was overwritten and lost: the dashboard's sessions, interventions and prompt counts under-counted until the next rebuild. Every writer that may modify the file now takes `events.jsonl.lock` (the `acquireLock` retry the usage file took for the same lost update, [#803](https://github.com/Tencent/teamai-cli/issues/803)): a hook append waits up to ~250 ms, inside its foreground budget, and one that gives up records its line in an `events.pending-<uuid>.jsonl` side file that the next lock holder folds into the file before it writes, so an event is late, never gone; the line's `pendingId` keeps a fold from appending a side file twice, identical events in separate side files are both kept, and the id stays in the raw file — a compaction keeps it too, as the usage file's rewrite does — until the side file itself is gone, while no reader ever sees it. Side files fold in their events' own time order, and a compaction classifies sessions in time order as every reader does, so a side file that outlived newer appends cannot place an older event after them and re-mark a live session stopped. A compaction that finds the log below its threshold and no side files to fold still runs lock-free, so the common case costs one read and no lock. A rewrite waits up to ~5 s for a peer's rewrite and skips — leaving the file as it is for the next compaction — when a live holder outlasts the wait, and a lock whose owner is gone is reclaimed (for [#804](https://github.com/Tencent/teamai-cli/issues/804)).
- A broken team file no longer wipes or downgrades what a member has installed. An `mcp/mcp.yaml` or `hooks/hooks.yaml` that did not parse reconciled to an empty set and removed every team MCP server or hook from every tool, and two active namespaces defining one skill or agent aborted the pull for the whole scope, skipping rules, env, docs and cleanup. Now a file in the active set that does not parse or cannot be read, a name repeated inside one file, or one name in two active namespaces stops only that resource type for the run: env keeps `env.sh`, hooks and MCP keep their entries (the built-in hooks, with the session-start pull, are still installed where missing: with the root hooks file's `builtin:` overrides when it parses, and otherwise with their defaults only in a tool that has none yet; `teamai init` says the team hooks were not installed), model profiles leave switched agents alone, skills and agents keep what is installed, and every other type still syncs. The warning names the file or both files and the fix, and for env, hooks, MCP and models is also written to `~/.teamai/debug.log` for session-start pulls (for [#707](https://github.com/Tencent/teamai-cli/issues/707)).
- In single-repo (`kind: self`) mode, every checkout of the business repo now publishes learnings and reports. The `teamai-learnings` and `teamai-reports` checkouts and the queue of unpublished learnings lived in each checkout's own `.teamai/`, and git checks a branch out in one worktree only, so the first checkout to create them locked every other one out (`'teamai-learnings' is already used by worktree`), and a learning queued in a linked worktree was deleted with it by a plain `git worktree remove`. They now live in the project partition that every checkout shares, and the search index is kept per checkout, so `recall` no longer serves another checkout's index with paths into it. On upgrade, `init`, `pull`, `push`, `contribute` and `import --from-mr` migrate a checkout's old install, moving its queue into the partition without overwriting anything (or into `pending-learnings.self` when another checkout has since switched the project to another kind; an old git-mode install beside the knowledge of a switch to single-repo mode goes to `.teamai.bak`, its queue to `pending-learnings.git`); `contribute` and `import --from-mr` stop, saving nothing, while that data cannot move out of the checkout; and the first command that needs a side-branch checkout removes the old one from `.teamai/`; one with uncommitted changes is kept, a warning names it and says what to do, and `recall maintenance` and `recall promote` stop until then, while another command holds the learnings or reports lock, and when a checkout cannot be created, naming the cause. A git-mode install of the same project uses the same partition paths, so a checkout that belongs to the other repository is refused, never reused or removed, with the command that clears it, and so is one whose repository was moved or deleted; its votes are not counted, `init` deletes the search indexes built for the old repository, learnings the old install still had queued are set aside in `pending-learnings.<old kind>` rather than published by the new one (and in `pending-learnings.<kind>-<repo>` when `init` points an install at another team repository of the same kind, which on `main` published them to the new one; the same repository written another way keeps them, [#823](https://github.com/Tencent/teamai-cli/issues/823) item 13), and `uninstall` lists every unpublished queue before it asks. (for [#808](https://github.com/Tencent/teamai-cli/issues/808)).
- A scope's usage file no longer grows without bound where it is never reported: an http source, a team with `usageReport: false`, or a remote that rejects every push. `teamai pull` keeps its newest 5,000 events, so `teamai stats` still shows recent usage there, the local file being its only source. In a reporting scope whose report does not complete while it holds more than 5,000 events, the dropped events were never reported. The cap runs after the report has removed the events it sent, so it cannot shift that removal onto events not yet reported, and a file at or below the cap is not rewritten. Hook appends, the report's truncate and the cap now share one lock beside the usage file, and a rewrite goes through a temp file that keeps the file's mode, so a rewrite no longer loses an event recorded while it runs, nor the file on a kill or a full disk. A hook that cannot take the lock within ~250 ms records its event in a `*.pending-<id>.jsonl` file beside it, which the next lock holder appends; a rewrite that cannot take it within ~5 s leaves the file as it is. A pending file gets no wider mode than the usage file (owner-only while there is none), and an in-workspace `.teamai/.gitignore` ignores the lock, a rewrite's temp copy and the pending files; `pull` and `push` add those entries to an existing single-repo one, and the first pending file or rewrite adds them to an existing project-scope one (for [#788](https://github.com/Tencent/teamai-cli/issues/788)).
- `teamai stats` no longer counts a session twice, and no longer counts another project's sessions. Its dashboard section added the whole machine's local `events.jsonl` metrics to the scope's already-reported totals from the team repo, so every session that a `pull` had reported — and that stays in the event log until compaction — was counted once by the team total and once again locally, and sessions whose `cwd` belonged to a different project were added to this scope's as well. It now filters the event log the way `teamai pull` reports it (only the sessions recorded in the current scope, see #785) and adds only what that scope has not reported yet, derived from the same per-scope `reported-*` snapshots the report path advances — so the local figure agrees with the team's instead of exceeding it. When the reported totals could not be read at all (no stats file, an unreadable one, a reports worktree that is not there), or when they exist but hold nothing yet, nothing is subtracted — a snapshot can name a session the team file never received, so a non-empty team total is what licenses trusting them, and a session the member can see happening is never hidden. The per-repo and by-hour breakdowns read that same filtered log, so they stay inside the scope; they answer a different question from the headline — what this machine's retained event log holds, per repo — and both the headings and the `--by-repo` / `--by-time` flag descriptions now name that source instead of presenting them as a split of the headline (for [#768](https://github.com/Tencent/teamai-cli/issues/768)).
- The data-partition migration no longer retires a legacy `<repo>/.teamai/` while the partition's `config.yaml` cannot be read. `teamai init`, `pull` and `push` took a partition config that merely existed as a finished migration and renamed the legacy directory to `.teamai.bak`, although it held the only config that still loaded. A partition `config.yaml` that is empty or cannot be opened, does not parse, does not validate, or is not `scope: project` now leaves the legacy directory in place and names the file to fix; once it is fixed, the next of those commands retires it as before. A partition directory whose `config.yaml` was moved aside is no longer replaced by a fresh copy of the legacy directory, which deleted what the partition held; the migration waits and says to restore the file or move the directory aside (for [#797](https://github.com/Tencent/teamai-cli/issues/797)).
- `teamai recall <query>` searches nothing in a project whose config exists but cannot be read, and says why. Detection skipped the broken file and searched whatever loaded next: the user scope, or a legacy `.teamai/` behind a broken partition that may belong to another team, whose knowledge was returned and whose documents got recalled counts. It now prints ``Nothing was searched: <file>: <reason>. Fix the file, or move it aside and run `teamai init` to write a new one.`` and exits 1, and `recall --check` does the same instead of printing `NOT_RELEVANT`, which told the recall subagent the team had no knowledge. The `teamai-recall` subagent a pull from this release deploys relays that line to the member, telling the main conversation to move the file or re-run `teamai init` only with their consent. (for [#796](https://github.com/Tencent/teamai-cli/issues/796)).
- `teamai pull` syncs nothing in a project whose config exists but cannot be read, and says why. Detection skipped the broken file and pulled whatever loaded next: the user scope, or a legacy `.teamai/` behind a broken partition that may belong to another team, whose skills, rules and docs were deployed and to which the project's usage was reported. It now prints ``Nothing was synced: <file>: <reason>. Fix the file, or move it aside and run `teamai init` to write a new one.`` and exits 1. A session start there runs no pull, seeds no agent directory and stashes no package hint; `teamai pull --silent`, which hooks from before `hook-dispatch` still run, prints nothing, writes the reason to `~/.teamai/debug.log` and exits 1. This is the rule team hooks and usage follow since [#748](https://github.com/Tencent/teamai-cli/issues/748) (for [#784](https://github.com/Tencent/teamai-cli/issues/784)).
- The legacy `teamai dashboard-report` command no longer records dashboard events in a directory that never set up teamai. A current install writes only `teamai hook-dispatch`, whose dashboard-report handler declares `requiresConfig` and is dropped when no config resolves for the hook's `cwd`; the old subcommand stayed ungated, so a hook left behind by an earlier install kept recording events for every project it fired in, and those sessions were then reported by whichever scope pulled next. It now applies the same gate `teamai contribute-check` was given, asked about the session's `cwd` — or, for a host that sends none, the directory the hook runs in (for [#768](https://github.com/Tencent/teamai-cli/issues/768)).
- The lock behind `pull`, `push`, the reports and learnings worktrees, learnings publishing, migration, self-mode bootstrap and the update check no longer hands one lock to two live processes. Reclaiming a stale lock renamed over whatever file was there once it had judged the lock stale, and it judged live locks stale: one that had just been released (and could be re-created by a third process before the rename), one whose owner had created it but not yet written it, one owned by a process running as another user (for example a `sudo teamai` run), and one it could not read. Under 16 processes contending on one lock, about 1% of acquisitions overlapped another holder, enough for two pulls to report the same usage twice. Now only a lock whose owner is provably gone is reclaimed; a lock that vanished gets one more exclusive create, and a new lock is published with its content already in place (written to a temp file, then hard-linked to the lock name; a filesystem without hard links falls back to the previous create). A lock that names no owner (empty, partly written, unreadable) is never reclaimed: if a crash left one, `pull` and `push` report busy until it is removed, and a warning names the file. Migration skips the lock's temporary files, which a contending pull creates and removes while the copy runs. With the change, the same stress run shows no overlap (for [#760](https://github.com/Tencent/teamai-cli/issues/760)).
- Team hooks stay out of projects that never set up teamai. A project-scope install puts its hooks in the home directory, so they fire in every project on the machine, and with no config for the directory they used to run anyway: the end-of-session share reminder (shown there even with recall off, a case a configured team never sees), the TodoWrite recall nudge, and the local recording of sessions and skill usage that a later report from another project pushed to its team. A handler that needs a team now declares `requiresConfig`, and the dispatcher drops it when neither a project nor a user config resolves for the hook's `cwd`; only machine-level work runs there (CLI update check, session-start pull, local agent, package hints the pull stashed). A config that exists but fails to parse reads the same way, so it withholds team prompts rather than running all of them, and for team hooks and skill usage an unreadable project config never falls back to the user scope, nor to a lower-priority project config such as a legacy `.teamai/` behind a broken partition. A host that sends no `cwd` (OpenClaw) resolves the project from the directory it runs the hook in, a `cwd` that no longer exists resolves to the user scope instead of failing the hook, and the legacy `teamai contribute-check` command that older installs still call follows the same rule (for [#748](https://github.com/Tencent/teamai-cli/issues/748)).
- Every team hook handler now works in the scope `hook-dispatch` resolved for the hook's `cwd`. The team correction keywords, votes and webhooks read their config again from the directory the hook process ran in, so when that `cwd` no longer existed (a deleted worktree) and the host started the hook inside another project, that project's keywords were applied, the session's votes were recorded under its member and pushed to its team, and its webhooks fired. The background handlers (session-start pull, webhooks, update check) also run again when that `cwd` no longer exists: on macOS and Linux their detached process was started in it, so the start failed silently and none of them ran. It now starts in the temp directory, as on Windows (for [#752](https://github.com/Tencent/teamai-cli/issues/752)).
- Votes stay with the team of the scope they were cast in. Every scope used to record into one `~/.teamai/votes/<user>.yaml`, so a vote cast in one project (by `teamai recall feedback`, a recall search, or a Stop hook whose push failed) was pushed to the team of whichever scope synced next. Votes now go to the data directory of the scope that resolves for the session's directory (`<dataHome>/votes/` for a project, `~/.teamai/user-votes/` for the user scope), and the Stop hook, the pull report, `teamai recall feedback` and the knowledge-base vote view each read only that scope's votes. Since a scope's file starts empty, `teamai recall feedback --negative` also counts the upvotes that scope's team already holds, so a doc upvoted before the upgrade can still be lowered. In a project whose config cannot be read, `teamai recall feedback` records nothing and exits 1 instead of recording into the user scope, a recall search records no recalled count, and the knowledge-base report names the broken file instead of showing the user scope's votes. Votes in `~/.teamai/votes/` name no project, whether an earlier release left them there or writes them again after a rollback, so this release never reads or pushes them; the team's `votes/<user>.yaml` keeps its format (for [#787](https://github.com/Tencent/teamai-cli/issues/787)).
- Skill usage stays with the team of the project it was recorded in. Every scope used to append to one `~/.teamai/usage.jsonl`, so whichever project pulled next reported every project's skills to its own team, including skills that exist only in an unrelated private repo. Usage now goes to the data directory of the scope that resolves for the session's directory (`<dataHome>/usage.jsonl`: the project partition, or `<repo>/.teamai` for an install not yet migrated to one, and `~/.teamai/user-usage.jsonl` for the user scope), each report reads and truncates only its own file, and `teamai stats` shows the current scope's usage. Events in `~/.teamai/usage.jsonl` name no project, whether an earlier release left them there or writes them again after a rollback, so they are never read or reported. Stats already pushed are not rewritten (for [#748](https://github.com/Tencent/teamai-cli/issues/748)).
- `teamai init` no longer hangs without a terminal. When the provider had no session it spawned `gh auth login --web` (or `gf auth login`, `cnb login`) with inherited stdio and waited for a browser device flow that nobody could complete, about five minutes for GitHub, then exited with the provider's error and no hint of the missing credential. Each login now refuses up front when the run is not interactive and names the credential to prepare (`GITHUB_TOKEN` / `GH_TOKEN`, `CNB_TOKEN`, or for TGit a prior `gf auth login`, since a `TGIT_TOKEN` PAT is REST-API-only and cannot clone). A run is non-interactive when stdin is not a TTY or when `CI` or `TEAMAI_NONINTERACTIVE` is set, so an agent sandbox with a pseudo-terminal can declare itself unattended, and every prompt in the CLI follows the same rule. `git` also runs with its prompts closed in that case — `GIT_TERMINAL_PROMPT=0`, `GIT_ASKPASS=echo` and `GCM_INTERACTIVE=never`, each only where the caller set nothing — so a missing clone credential fails at once instead of waiting on a terminal prompt or an askpass or credential-manager dialog. `ssh` keeps its own settings: its batch flag is only reachable through `GIT_SSH_COMMAND`, which would override each repository's `core.sshCommand` (for [#711](https://github.com/Tencent/teamai-cli/issues/711)).
- A `manifest/roles.yaml` that exists but does not parse now fails the pull for that scope instead of warning and syncing with no role filter at all, for a member with no role as much as for one with a role. The same applies to `init` and `push`, which each fell back to a guess at the namespaces when any error came out of the loader. The legacy role migration skips with a warning instead of failing, so every command, `pull` included, still loads the config and can fetch the fixed manifest; until it can run, the member holds no role rather than every role, so hooks and MCP servers scoped by `roles:` reach them no more than skills do. For a member with no active project that fallback meant an unfiltered sync, so a broken manifest delivered every namespace it was written to gate. Only an absent manifest still means "this team does not use roles"; an unreadable or empty file is an error, as it now is for `manifest/projects.yaml` too. `push` stops at its scan for such a manifest (exit 2) even with `--role <ns>`, since the scan needs it to tell which namespaces are the member's.
- `teamai members list` and `teamai projects members` read the roster registered before the reports switch, so a team upgrading past the orphan-branch split no longer sees "No team members registered" while its `members/` still lives on the default branch. The default-branch copy becomes a read-only inherited root, the way learnings' already was: listed in union with the `teamai-reports` copy, with the branch copy winning when the same file exists on both; nothing is copied or deleted, and a cold `members list` still does not publish the reports branch. Member registration merges against the inherited copy too, so a re-init keeps the original `registeredAt` and projects. Fixes [#735](https://github.com/Tencent/teamai-cli/issues/735).
- Cache GC now rejects partial integers such as `12abc`, decimals, zero and unsafe integers for `--max-bytes` and `--stale-days` before deleting anything. An invalid `TEAMAI_CACHE_MAX_BYTES` value falls back to the default 5 GB limit instead of using a numeric prefix.
- Each scope reports only the dashboard sessions recorded in it. Every scope read one machine-wide event log and picked its sessions out by the `cwd` they started in, so a user-scope pull reported every project's sessions to the user team, a project never reported its Copilot sessions (teamai does not record Copilot's `cwd`), and a session started under a symlinked path (or `/tmp` for `/private/tmp` on macOS) never matched its project. Each event now records a key (a hash, so no path is stored) of the data directory of the scope `hook-dispatch` resolved, and a report keeps only its own scope's. A session in a directory that resolves to no project (a subdirectory of a non-git project, a git submodule or nested clone) is the user scope's, as for skill usage. A session is reported once, whole, by the scope it started in, even after a `cd` into another project: its Stop carries the whole transcript's totals, so reporting its later part elsewhere would count them twice. A session ends with its session end or process exit (a process exit recorded right after its session end is the same session), so a later session that reuses its ID (Copilot's fallback ID is the parent process ID) is attributed and counted on its own, even when an earlier release reported that ID for another scope. Events recorded by an earlier release go to the scope their `cwd` resolves to now (a nested clone under a project is not the project's); events with no `cwd`, or one removed since, are reported by no one. The usage guide explains how to remove by hand a skill an earlier release reported into `stats/<user>.yaml` from another project (for [#785](https://github.com/Tencent/teamai-cli/issues/785)).
- Each scope keeps its own snapshots of the dashboard sessions it already reported. They were machine-wide and keyed by session ID, so a session ID reused in another scope (Copilot's fallback ID is the parent process ID) was taken as already reported there and sent nothing. Each scope now keeps its own (`<dataHome>/dashboard/reported-*.json`, and `~/.teamai/dashboard/user-reported-*.json` for the user scope), seeded the first time from the shared `~/.teamai/dashboard/reported-*.json`, so the first report after the upgrade sends nothing already reported. The shared file is no longer written; after a rollback an earlier release writes it again, and only a scope not yet seeded reads it (for [#786](https://github.com/Tencent/teamai-cli/issues/786)).
- Usage reporting scopes sessions by path on Windows too. The project/user scope filter compared an event's `cwd` against `projectRoot` with a hard-coded `/` separator, so on Windows only a session started in the project root itself matched: every session started in a subdirectory was dropped from the project team's report and counted in the user scope's instead, which is the isolation the usage guide promises. Windows paths are also compared case-insensitively, so a drive letter or a directory name spelled with different case in the two sources no longer leaks a project session into the user scope. POSIX paths keep their own rules: case-sensitive, and a `\` in a filename stays part of the name.
- `teamai tags subscribe` and `teamai tags unsubscribe` now invalidate the pull revision cache, as `teamai skill exclude` already does, so the next `teamai pull` applies the new subscriptions instead of reporting "Already synced" when the team repo has not changed.
- `teamai pull` now deletes a tombstoned agent under all three render extensions, so the Codex `.toml` and Kiro `.json` copies of a removed agent no longer survive on other machines. The cleanup also runs when the team repo rev is unchanged, so an upgrade reaches machines that already pulled the tombstone with an older CLI. `teamai remove agents <name>` also honours `enabledAgents` and no longer deletes from excluded tools. Fixes [#576](https://github.com/Tencent/teamai-cli/issues/576).
- `teamai remove rules <name>` and `teamai remove skills <name>` now honour `enabledAgents` and leave excluded tools untouched, matching the whitelist `teamai pull` already applies when it cleans up a tombstoned resource. Fixes [#590](https://github.com/Tencent/teamai-cli/issues/590).
- `teamai pull` and `teamai mcp inject` no longer write team MCP servers into installed tools outside `enabledAgents` or listed in `disabledAgents`, the same gate skills, rules, agents and hooks already use. Servers injected before the upgrade are left in place, and `teamai uninstall` still removes them.
- `teamai import --cache-status` and `--cache-gc` now expose their existing JSON output through the CLI `--json` option.
- Course-correction matching normalizes prompts and keywords to Unicode NFC, so composed and decomposed accents match. Stored prompt summaries and the 60-second correction window are unchanged. Fixes [#573](https://github.com/Tencent/teamai-cli/issues/573).
- Course-correction detection matches keywords in space-separated scripts as whole words, so Spanish "segundo" no longer counts as `undo` (for [#564](https://github.com/Tencent/teamai-cli/issues/564)).
- `teamai doctor` no longer assumes TGit before initialization and now exits with code 1 when any diagnostic check fails.
- MCP `requires` is resolved from `PATH` (including Windows `PATHEXT`), so `teamai mcp inject` no longer skips servers such as `uvx` on Windows ([#540](https://github.com/Tencent/teamai-cli/pull/540), for [#539](https://github.com/Tencent/teamai-cli/issues/539)).
- The GitHub and CNB providers resolve their CLI to a launchable absolute path and start it through cross-spawn, so on Windows they no longer answer "installed" while every call fails silently ([#520](https://github.com/Tencent/teamai-cli/pull/520)).
- `enabledAgents` now also gates CLI builtin deploy, CLAUDE.md-class injects, and last-pull skip-sync targets, so an already-installed tool outside the whitelist is not written to ([#510](https://github.com/Tencent/teamai-cli/issues/510)).
- `teamai status` counts rule files in subdirectories recursively ([#437](https://github.com/Tencent/teamai-cli/pull/437)).
- Codex Stop-phase contribution hints are deferred to the next prompt, so the host no longer rejects `additionalContext` ([#441](https://github.com/Tencent/teamai-cli/pull/441)).
- Agent version detection launches the agent CLI through cross-spawn, so on Windows an npm-installed agent CLI such as `codebuddy`, `claude` or `openclaw` (a `.cmd` shim) reports its version instead of an empty `agent_version`.

### 📝 Documentation

- Align the public usage guides, drop internal-only details, and cover the missing commands and configuration ([#442](https://github.com/Tencent/teamai-cli/pull/442)).
- Document `teamai projects` in the bilingual READMEs as the lead distribution control, including learnings isolation ([#490](https://github.com/Tencent/teamai-cli/pull/490), for [#487](https://github.com/Tencent/teamai-cli/issues/487)).

## [0.23.0](https://github.com/Tencent/teamai-cli/compare/v0.22.0...v0.23.0) (2026-09-08)

### ✨ Features

- Declarative team package management with npm and Claude plugin adapters, team distribution, install hints, and doctor checks; the shipped entry point is `teamai packages install` ([#380](https://github.com/Tencent/teamai-cli/pull/380), [#428](https://github.com/Tencent/teamai-cli/pull/428)).
- First-class Qoder and JoyCode support that preserves personal rules and native metadata ([#420](https://github.com/Tencent/teamai-cli/pull/420), [#413](https://github.com/Tencent/teamai-cli/pull/413)).
- ClawPro model configs can be synced, applied, and reported per tool ([#393](https://github.com/Tencent/teamai-cli/pull/393)).
- `contribute` supports Japanese course-correction prompts, and `sharing.contributeHint.enabled` turns the share hint off ([#431](https://github.com/Tencent/teamai-cli/pull/431), [#432](https://github.com/Tencent/teamai-cli/pull/432)).
- Plugin install commands substitute any scalar field ([#400](https://github.com/Tencent/teamai-cli/pull/400)).

### 🔧 Refactoring

- Project data moves into the `~/.teamai/projects/<slug>/` partition, unifying machine data, state, resource cache, and the worktree ownership model ([#397](https://github.com/Tencent/teamai-cli/pull/397), [#402](https://github.com/Tencent/teamai-cli/pull/402), [#406](https://github.com/Tencent/teamai-cli/pull/406)).
- The top-level `install` command from the prereleases is now `packages install` ([#428](https://github.com/Tencent/teamai-cli/pull/428)).

### 🐛 Bug Fixes

- Partition migration adds scope locks, clone race protection, a per-worktree MCP manifest, uninstall cleanup, and legacy ownership migration ([#414](https://github.com/Tencent/teamai-cli/pull/414), [#417](https://github.com/Tencent/teamai-cli/pull/417)).
- Fix project-scope recall configuration and the self-mode maintenance report paths and refresh ([#398](https://github.com/Tencent/teamai-cli/pull/398), [#401](https://github.com/Tencent/teamai-cli/pull/401)).
- Plugin install commands run with Bash, and an unclosed YAML frontmatter delimiter now warns ([#399](https://github.com/Tencent/teamai-cli/pull/399), [#409](https://github.com/Tencent/teamai-cli/pull/409)).
- Agent changes are compared using rendered native content, and commits in isolated worktrees skip repository hooks ([#411](https://github.com/Tencent/teamai-cli/pull/411), [#422](https://github.com/Tencent/teamai-cli/pull/422)).
- Codex token snapshots are kept per rollout, partial reports preserve existing counters, and MCP inventory is scoped to the current tool ([#423](https://github.com/Tencent/teamai-cli/pull/423), [#429](https://github.com/Tencent/teamai-cli/pull/429), [#433](https://github.com/Tencent/teamai-cli/pull/433)).
- push/pull unit tests no longer share the real `.sync-lock`, removing the parallel Vitest race ([#438](https://github.com/Tencent/teamai-cli/pull/438)).

### 📝 Documentation

- Align README and the usage guide with the product architecture, trim the agent instructions, and add Contributors ([#412](https://github.com/Tencent/teamai-cli/pull/412), [#415](https://github.com/Tencent/teamai-cli/pull/415), [#430](https://github.com/Tencent/teamai-cli/pull/430), [#434](https://github.com/Tencent/teamai-cli/pull/434)).

## [0.22.0](https://github.com/Tencent/teamai-cli/compare/v0.21.0...v0.22.0) (2026-09-02)

### ✨ Features

- Add the GitCode provider ([#376](https://github.com/Tencent/teamai-cli/pull/376)).
- Team-controlled commit co-author attribution across AI tools ([#365](https://github.com/Tencent/teamai-cli/pull/365)).
- Dashboard gains a knowledge base health report and collects CodeBuddy `toolReject`/`toolError` friction ([#368](https://github.com/Tencent/teamai-cli/pull/368), [#336](https://github.com/Tencent/teamai-cli/pull/336)).
- The wiki engine adds a WASM tree-sitter AST track for the code knowledge graph ([#304](https://github.com/Tencent/teamai-cli/pull/304)).
- The data layout gains an atomic lock and separates `projectAnchor` from `workspaceRoot` ([#387](https://github.com/Tencent/teamai-cli/pull/387)).

### 🐛 Bug Fixes

- Cursor rules are written as `.mdc` with derived frontmatter, and stale per-tool agent siblings are cleaned up ([#345](https://github.com/Tencent/teamai-cli/pull/345), [#349](https://github.com/Tencent/teamai-cli/pull/349)).
- Fix the project-scope doctor env path and Cursor SessionStart workspace root resolution ([#348](https://github.com/Tencent/teamai-cli/pull/348), [#353](https://github.com/Tencent/teamai-cli/pull/353)).
- push updates the open PR instead of opening duplicates, and `--skill` keeps other resources' open-PR records ([#350](https://github.com/Tencent/teamai-cli/pull/350), [#359](https://github.com/Tencent/teamai-cli/pull/359)).
- `import --dir` runs reconcile and deep enrichment, and init always deploys `team-wiki-codebase` ([#362](https://github.com/Tencent/teamai-cli/pull/362), [#358](https://github.com/Tencent/teamai-cli/pull/358)).
- hook-dispatch no longer blocks on a tty prompt, injection scope is unified, and project hooks are isolated across a shared home ([#366](https://github.com/Tencent/teamai-cli/pull/366), [#370](https://github.com/Tencent/teamai-cli/pull/370), [#377](https://github.com/Tencent/teamai-cli/pull/377)).
- pull reconciles a diverged team-repo clone without data loss ([#367](https://github.com/Tencent/teamai-cli/pull/367)).
- SKILL.md frontmatter handles CRLF, BOM, object values, and malformed metadata ([#378](https://github.com/Tencent/teamai-cli/pull/378), [#383](https://github.com/Tencent/teamai-cli/pull/383)).
- Fix vote/contribute hints clobbering each other, clipped KB Health labels, and repeated ClawPro binding prompts in worktrees ([#384](https://github.com/Tencent/teamai-cli/pull/384), [#389](https://github.com/Tencent/teamai-cli/pull/389), [#392](https://github.com/Tencent/teamai-cli/pull/392)).

### 🔧 CI/CD

- npm publishing moves to trusted publishing ([#381](https://github.com/Tencent/teamai-cli/pull/381)).

## [0.21.0](https://github.com/Tencent/teamai-cli/compare/v0.20.0...v0.21.0) (2026-08-27)

### ✨ Features

- Support generic private Git hosts and a GitLab provider for self-hosted instances ([#301](https://github.com/Tencent/teamai-cli/pull/301), [#307](https://github.com/Tencent/teamai-cli/pull/307)).
- OpenCode syncs skills, rules, subagents, and MCP in both scopes, and receives hooks as a native plugin ([#306](https://github.com/Tencent/teamai-cli/pull/306), [#326](https://github.com/Tencent/teamai-cli/pull/326)).
- Add DeepSeek Harness as a supported agent ([#319](https://github.com/Tencent/teamai-cli/pull/319)).
- local-agent can install and uninstall MCP servers over the HTTP sync channel ([#290](https://github.com/Tencent/teamai-cli/pull/290)).

### 🐛 Bug Fixes

- Harden Git/GitLab credentials: reject embedded credentials, keep the PAT out of clone URLs and MR fetches, and align the clone timeout ([#308](https://github.com/Tencent/teamai-cli/pull/308), [#314](https://github.com/Tencent/teamai-cli/pull/314)).
- Resolve the user home and the built-in agents directory consistently on Windows ([#309](https://github.com/Tencent/teamai-cli/pull/309), [#310](https://github.com/Tencent/teamai-cli/pull/310), [#324](https://github.com/Tencent/teamai-cli/pull/324)).
- Fix silent capability loss when upgrading from old versions, verify a cached clone's remote before reuse, and run `gf auth` from a neutral cwd ([#311](https://github.com/Tencent/teamai-cli/pull/311), [#329](https://github.com/Tencent/teamai-cli/pull/329), [#312](https://github.com/Tencent/teamai-cli/pull/312)).
- push carries `teamai.yaml` and role-scoped skill changes; pull preserves role isolation for tag subscriptions, keeps pending source config, and syncs newly available agent targets ([#323](https://github.com/Tencent/teamai-cli/pull/323), [#338](https://github.com/Tencent/teamai-cli/pull/338), [#337](https://github.com/Tencent/teamai-cli/pull/337), [#340](https://github.com/Tencent/teamai-cli/pull/340), [#343](https://github.com/Tencent/teamai-cli/pull/343)).
- uninstall removes managed agents and OpenClaw skills, and the "no workspace dir" warning is silenced when OpenClaw is absent ([#339](https://github.com/Tencent/teamai-cli/pull/339), [#347](https://github.com/Tencent/teamai-cli/pull/347)).
- Fix the invalid OpenCode agent configuration generated when recall is enabled ([#344](https://github.com/Tencent/teamai-cli/pull/344)).

### 🔒 Security

- Patch runtime advisories in `simple-git` and `js-yaml` ([#316](https://github.com/Tencent/teamai-cli/pull/316)).

### 🔧 CI/CD

- Prereleases publish to their own dist-tag and never to `latest` ([#317](https://github.com/Tencent/teamai-cli/pull/317)).

## [0.20.0](https://github.com/Tencent/teamai-cli/compare/v0.19.0...v0.20.0) (2026-08-20)

### ✨ Features

- Single-repo mode: a business repository can act as the team repository ([#292](https://github.com/Tencent/teamai-cli/pull/292)).
- recall expands keywords bilingually for cross-language retrieval ([#302](https://github.com/Tencent/teamai-cli/pull/302)).

### 🐛 Bug Fixes

- recall reports per-term coverage, and scoring defects, body truncation, and duplicate results are fixed ([#289](https://github.com/Tencent/teamai-cli/pull/289), [#297](https://github.com/Tencent/teamai-cli/pull/297), [#298](https://github.com/Tencent/teamai-cli/pull/298)).
- Guard the self/single-repo report flow against resetting the business repository ([#299](https://github.com/Tencent/teamai-cli/pull/299)).
- Fix the OpenClaw skill path, manifest enrichment import paths, and container agent id/version detection ([#295](https://github.com/Tencent/teamai-cli/pull/295), [#293](https://github.com/Tencent/teamai-cli/pull/293), [#291](https://github.com/Tencent/teamai-cli/pull/291)).
- TGit clone/fetch must use an OAuth token, never a REST-only PAT ([#287](https://github.com/Tencent/teamai-cli/pull/287)).

## [0.19.0](https://github.com/Tencent/teamai-cli/compare/v0.18.0...v0.19.0) (2026-08-06)

### 💥 Breaking Changes

- `teamai init` defaults to project scope and accepts the repository as a positional argument; user scope now requires `--scope user` ([#256](https://github.com/Tencent/teamai-cli/pull/256)).

### ✨ Features

- The local-agent sync/ack channel installs and uninstalls session hooks and runs `uninstall_teamai` ([#238](https://github.com/Tencent/teamai-cli/pull/238), [#249](https://github.com/Tencent/teamai-cli/pull/249), [#265](https://github.com/Tencent/teamai-cli/pull/265)).
- Add Hermes agent sync, hooks, and configuration support ([#269](https://github.com/Tencent/teamai-cli/pull/269)).
- Opt-in inheritance of user-scope resources while keeping scopes isolated by default ([#281](https://github.com/Tencent/teamai-cli/pull/281)).

### 🐛 Bug Fixes

- Simplify project-scope hook injection and dispatch, and skip injection safely when `/bin/sh` is absent ([#272](https://github.com/Tencent/teamai-cli/pull/272), [#274](https://github.com/Tencent/teamai-cli/pull/274)).
- WorkBuddy ephemeral directories no longer re-prompt for binding, and prompts are deduplicated per session ([#270](https://github.com/Tencent/teamai-cli/pull/270), [#271](https://github.com/Tencent/teamai-cli/pull/271)).
- Stop the command loop after uninstall, detect empty hooks residue, and improve recall's CJK inference, relevance threshold, and query quality ([#273](https://github.com/Tencent/teamai-cli/pull/273), [#276](https://github.com/Tencent/teamai-cli/pull/276), [#278](https://github.com/Tencent/teamai-cli/pull/278)).
- Share hints explain the friction that triggered them, and `codebase` drops a stale flag, stale help text, and Chinese strings ([#282](https://github.com/Tencent/teamai-cli/pull/282), [#268](https://github.com/Tencent/teamai-cli/pull/268)).

### ⚡ Performance

- Tighten the hook STDIN timeout, add error guards, and move pull to the background ([#275](https://github.com/Tencent/teamai-cli/pull/275)).

## [0.18.0](https://github.com/Tencent/teamai-cli/compare/v0.17.7...v0.18.0) (2026-07-30)

### ✨ Features

- Add the `mcp` resource: team-declared MCP servers merge into each AI tool's native format, with `teamai mcp list/inject/remove` ([#252](https://github.com/Tencent/teamai-cli/pull/252)).
- `teamai uninstall --agent <tool>` uninstalls a single tool and records the disabled state persistently ([#244](https://github.com/Tencent/teamai-cli/pull/244)).
- local-agent reads a unified `cmds[]` from the sync response ([#261](https://github.com/Tencent/teamai-cli/pull/261)).

### 🐛 Bug Fixes

- MR import tolerates malformed learning frontmatter, and workspace paths are normalized on case-insensitive filesystems ([#241](https://github.com/Tencent/teamai-cli/pull/241), [#243](https://github.com/Tencent/teamai-cli/pull/243)).
- Git-provider-only hints no longer leak to HTTP users or users without a matching remote, and total foreground hook time is bounded ([#247](https://github.com/Tencent/teamai-cli/pull/247), [#248](https://github.com/Tencent/teamai-cli/pull/248)).
- uninstall removes MCP servers before deleting the manifest and lists the removed servers in the summary ([#253](https://github.com/Tencent/teamai-cli/pull/253), [#254](https://github.com/Tencent/teamai-cli/pull/254)).
- `teamai list` covers every resource type, and env values are masked unless `--reveal` is passed ([#255](https://github.com/Tencent/teamai-cli/pull/255)).
- Improve project-scope MCP secret resolution, `requires` command validation, and remote server formats; GUI IDEs receive resolved variable values ([#258](https://github.com/Tencent/teamai-cli/pull/258), [#259](https://github.com/Tencent/teamai-cli/pull/259), [#262](https://github.com/Tencent/teamai-cli/pull/262), [#263](https://github.com/Tencent/teamai-cli/pull/263)).

## [0.17.7](https://github.com/Tencent/teamai-cli/compare/v0.17.6...v0.17.7) (2026-07-27)

### 💥 Breaking Changes

- Complete the move to the teamwiki knowledge graph, removing the old domains subsystem, legacy aggregate/codebase-lint, the hidden `domains drift` command, obsolete flags, and the old CI sync template ([#225](https://github.com/Tencent/teamai-cli/pull/225)).

### ✨ Features

- Add `teamai recall --check`, a side-effect-free relevance pre-check ([#234](https://github.com/Tencent/teamai-cli/pull/234)).
- codebase recall results include `Sources:` anchors to the source files ([#240](https://github.com/Tencent/teamai-cli/pull/240)).
- The local-agent binding prompt is enabled by default ([#237](https://github.com/Tencent/teamai-cli/pull/237)).

### 🐛 Bug Fixes

- pull still refreshes the CLAUDE.md recall block on the "Already synced" fast path ([#223](https://github.com/Tencent/teamai-cli/pull/223)).
- hooks inject/remove no longer create root directories for tools that are not installed, and a non-Git team repo directory is re-cloned ([#224](https://github.com/Tencent/teamai-cli/pull/224), [#236](https://github.com/Tencent/teamai-cli/pull/236)).

### ⚡ Performance

- PostToolUse local-agent sync runs in the background ([#231](https://github.com/Tencent/teamai-cli/pull/231)).

## [0.17.6](https://github.com/Tencent/teamai-cli/compare/v0.17.5...v0.17.6) (2026-07-22)

### 🐛 Bug Fixes

- Fix duplicate binding cards in the CloudStudio sandbox while keeping the workspace binding prompt ([#220](https://github.com/Tencent/teamai-cli/pull/220)).
- Reported workspaces are attributed to the AI tool that installed them, and tool root directories are created before installing workspace resources ([#221](https://github.com/Tencent/teamai-cli/pull/221), [#222](https://github.com/Tencent/teamai-cli/pull/222)).

## [0.17.5](https://github.com/Tencent/teamai-cli/compare/v0.17.4...v0.17.5) (2026-07-22)

### ✨ Features

- `teamai stats` adds `--by-repo` and `--by-time`, and `teamai session save` stores and pushes session summaries ([#193](https://github.com/Tencent/teamai-cli/pull/193), [#192](https://github.com/Tencent/teamai-cli/pull/192)).
- Add the CNB Git provider with interactive login and headless `CNB_TOKEN` auth ([#208](https://github.com/Tencent/teamai-cli/pull/208)).
- local-agent re-runs plugins when the backend-supplied commands change ([#209](https://github.com/Tencent/teamai-cli/pull/209)).

### 🐛 Bug Fixes

- Correct the TGit REST auth scheme and standardize on `TGIT_TOKEN` ([#210](https://github.com/Tencent/teamai-cli/pull/210), [#212](https://github.com/Tencent/teamai-cli/pull/212)).
- push clears its timeout timer, and CodeBuddy hooks no longer keep the event loop alive ([#211](https://github.com/Tencent/teamai-cli/pull/211), [#214](https://github.com/Tencent/teamai-cli/pull/214), [#218](https://github.com/Tencent/teamai-cli/pull/218)).
- The source manifest stores a Git baseline so imports are genuinely incremental ([#215](https://github.com/Tencent/teamai-cli/pull/215)).
- Workspace-scope resources install into project directories and are reported as a full snapshot ([#216](https://github.com/Tencent/teamai-cli/pull/216), [#219](https://github.com/Tencent/teamai-cli/pull/219)).

## [0.17.4](https://github.com/Tencent/teamai-cli/compare/v0.17.3...v0.17.4) (2026-07-20)

### ✨ Features

- The Stop hook asks for a citation when recall ran but no document was declared as used ([#181](https://github.com/Tencent/teamai-cli/pull/181)).
- local-agent installs, updates, runs, and uninstalls backend plugins, including path mapping ([#185](https://github.com/Tencent/teamai-cli/pull/185), [#186](https://github.com/Tencent/teamai-cli/pull/186), [#187](https://github.com/Tencent/teamai-cli/pull/187)).
- Add per-user skill exclusion in local config, applied during pull ([#194](https://github.com/Tencent/teamai-cli/pull/194)).
- Add secret redaction, and `contribute` scores contribution value from session friction ([#191](https://github.com/Tencent/teamai-cli/pull/191), [#204](https://github.com/Tencent/teamai-cli/pull/204)).
- local-agent workspace binding targets a project instead of a group ([#203](https://github.com/Tencent/teamai-cli/pull/203)).

### 🐛 Bug Fixes

- uninstall cleans the built-in recall agent, rule, and skills, and `agent_type` variants are normalized before reporting ([#183](https://github.com/Tencent/teamai-cli/pull/183), [#188](https://github.com/Tencent/teamai-cli/pull/188)).
- Avoid opening a duplicate import MR when only metadata changed ([#190](https://github.com/Tencent/teamai-cli/pull/190)).

## [0.17.3](https://github.com/Tencent/teamai-cli/compare/v0.17.2...v0.17.3) (2026-07-14)

### ✨ Features

- Add the HTTP local-agent lifecycle, project binding prompt, and WorkBuddy/CodeBuddy support ([#152](https://github.com/Tencent/teamai-cli/pull/152)).
- Git users can attach HTTP report/sync/ack sources via `source add-http/remove-http/list` ([#168](https://github.com/Tencent/teamai-cli/pull/168)).
- Add backend request logging, an update cache, a WorkBuddy hook timeout, and a binding-prompt toggle ([#166](https://github.com/Tencent/teamai-cli/pull/166), [#172](https://github.com/Tencent/teamai-cli/pull/172)).

### 🐛 Bug Fixes

- Fix the paths that prevented `contribute-check` hints from firing ([#160](https://github.com/Tencent/teamai-cli/pull/160)).
- Fix local-agent ids, install paths, resource naming, installed-resource scanning, version reporting, and log identity ([#161](https://github.com/Tencent/teamai-cli/pull/161), [#162](https://github.com/Tencent/teamai-cli/pull/162), [#167](https://github.com/Tencent/teamai-cli/pull/167), [#169](https://github.com/Tencent/teamai-cli/pull/169), [#170](https://github.com/Tencent/teamai-cli/pull/170), [#171](https://github.com/Tencent/teamai-cli/pull/171)).
- Scope resource install, uninstall, and hook injection strictly to the requesting tool, and fix hook routing and empty `hook_event_name` handling ([#174](https://github.com/Tencent/teamai-cli/pull/174), [#176](https://github.com/Tencent/teamai-cli/pull/176), [#177](https://github.com/Tencent/teamai-cli/pull/177), [#179](https://github.com/Tencent/teamai-cli/pull/179)).

### 🔧 Refactoring

- Remove the deprecated `/repo` HTTP team repository snapshot path ([#180](https://github.com/Tencent/teamai-cli/pull/180)).

## [0.17.2](https://github.com/Tencent/teamai-cli/compare/v0.17.1...v0.17.2) (2026-07-07)

### 🐛 Bug Fixes

- The team knowledge recall rule relaxes from `MUST` to `SHOULD` with three explicit skip conditions, and the TodoWrite reminder is softened to match ([#158](https://github.com/Tencent/teamai-cli/pull/158)).

## [0.17.1](https://github.com/Tencent/teamai-cli/compare/v0.17.0...v0.17.1) (2026-07-06)

### ✨ Features

- Knowledge base dual-count voting and automated maintenance: adoption detection, multi-device sync, confidence updates, promotion, and pruning ([#137](https://github.com/Tencent/teamai-cli/pull/137)).
- `teamai init --agent <name>` limits hook injection to the given tools and accumulates across runs ([#155](https://github.com/Tencent/teamai-cli/pull/155)).

### 🐛 Bug Fixes

- Coding CI triggers on `main`, and the default Vitest timeout is raised to reduce CI flakiness ([#149](https://github.com/Tencent/teamai-cli/pull/149), [#150](https://github.com/Tencent/teamai-cli/pull/150)).

## [0.17.0](https://github.com/Tencent/teamai-cli/compare/v0.16.9...v0.17.0) (2026-07-03)

### ✨ Features

- Add `teamai hooks list`, and unify team-declared and built-in hooks into one data model and reconcile flow ([#62](https://github.com/Tencent/teamai-cli/pull/62), [#65](https://github.com/Tencent/teamai-cli/pull/65)).
- Build a deterministic codebase knowledge pipeline, plus deep-enrich, graph-aware recall, and the `team-wiki-codebase` skill ([#55](https://github.com/Tencent/teamai-cli/pull/55), [#56](https://github.com/Tencent/teamai-cli/pull/56)).
- Support a git-free HTTP team source with API keys, machine identity, and hooks-driven agent status reporting ([#68](https://github.com/Tencent/teamai-cli/pull/68)).
- Dashboard and stats add Human Intervention, prompt counts, and token usage ([#70](https://github.com/Tencent/teamai-cli/pull/70), [#78](https://github.com/Tencent/teamai-cli/pull/78), [#122](https://github.com/Tencent/teamai-cli/pull/122)).
- Isolate user scope when project scope is installed, and add `tclaude`/`tcodex` plus native Codex hooks ([#77](https://github.com/Tencent/teamai-cli/pull/77), [#64](https://github.com/Tencent/teamai-cli/pull/64), [#103](https://github.com/Tencent/teamai-cli/pull/103)).
- Recall becomes progressive route → context → lookup retrieval with G-document routing and multi-hop analysis ([#102](https://github.com/Tencent/teamai-cli/pull/102)).
- MR import supports incremental updates from a facts cache, and import gains structured progress and English-only output ([#112](https://github.com/Tencent/teamai-cli/pull/112), [#117](https://github.com/Tencent/teamai-cli/pull/117)).
- Recall can be toggled by a team default with a local override ([#126](https://github.com/Tencent/teamai-cli/pull/126)).

### 🐛 Bug Fixes

- Fix TGit argument quoting, CodeBuddy tool-name normalization, batch import races, and path traversal ([#60](https://github.com/Tencent/teamai-cli/pull/60), [#66](https://github.com/Tencent/teamai-cli/pull/66), [#67](https://github.com/Tencent/teamai-cli/pull/67), [#74](https://github.com/Tencent/teamai-cli/pull/74)).
- Fix batches of recall, knowledge graph, reconcile, and scope isolation defects ([#91](https://github.com/Tencent/teamai-cli/pull/91), [#97](https://github.com/Tencent/teamai-cli/pull/97), [#98](https://github.com/Tencent/teamai-cli/pull/98)).
- Fix Dashboard prompt/token counts and duplicate dispatch, and fix project-scope usage/digest reporting ([#105](https://github.com/Tencent/teamai-cli/pull/105), [#107](https://github.com/Tencent/teamai-cli/pull/107), [#108](https://github.com/Tencent/teamai-cli/pull/108), [#109](https://github.com/Tencent/teamai-cli/pull/109), [#111](https://github.com/Tencent/teamai-cli/pull/111), [#118](https://github.com/Tencent/teamai-cli/pull/118)).
- doctor, init, hooks, and built-in skill deployment skip targets that are absent or disabled ([#116](https://github.com/Tencent/teamai-cli/pull/116), [#128](https://github.com/Tencent/teamai-cli/pull/128), [#135](https://github.com/Tencent/teamai-cli/pull/135)).
- Version comparison handles prerelease identifiers correctly ([#147](https://github.com/Tencent/teamai-cli/pull/147)).

### 🔧 Refactoring

- Decommission the old `teamai-wiki` skill and the `wiki/` resource type ([#90](https://github.com/Tencent/teamai-cli/pull/90)).
- Remove the auto-recall PostToolUse hook in favor of the `teamai-recall` subagent ([#106](https://github.com/Tencent/teamai-cli/pull/106)).

## [0.16.9](https://github.com/Tencent/teamai-cli/compare/v0.16.8...v0.16.9) (2026-06-25)

### ✨ Features

- Add `teamai ci extract-mr`: extract learning and codebase suggestions from an MR/PR, with comment, write, and reaction-based rejection modes ([#36](https://github.com/Tencent/teamai-cli/pull/36), [#39](https://github.com/Tencent/teamai-cli/pull/39)).
- `teamai doctor` adds `gh` CLI install and login checks for the GitHub provider ([#45](https://github.com/Tencent/teamai-cli/pull/45)).

### 🐛 Bug Fixes

- `uninstall` cleans every TeamAI section from CLAUDE.md ([#33](https://github.com/Tencent/teamai-cli/pull/33)).
- Values written to `env.sh` are shell-quoted ([#40](https://github.com/Tencent/teamai-cli/pull/40)).
- Remove project-scope hooks left behind in user-level tool settings ([#44](https://github.com/Tencent/teamai-cli/pull/44)).

## [0.16.8](https://github.com/Tencent/teamai-cli/compare/v0.16.7...v0.16.8) (2026-06-18)

### ✨ Features

- Add knowledge import and codebase maintenance covering local directories, workspaces, MR/PR, iWiki, repository lists, and organization-wide imports ([#28](https://github.com/Tencent/teamai-cli/pull/28)).
- Add the `agents` resource and the built-in `teamai-recall` subagent, plus TodoWrite and merged-MR hints ([#28](https://github.com/Tencent/teamai-cli/pull/28)).
- `contribute-check` adds knowledge gap awareness, recall quality scoring, and git-commit down-weighting ([#30](https://github.com/Tencent/teamai-cli/pull/30)).

## [0.16.7](https://github.com/Tencent/teamai-cli/compare/v0.16.6...v0.16.7) (2026-06-12)

### ✨ Features

- Merge the TeamAI commands for one hook event into a single `hook-dispatch` process ([`be158d4`](https://github.com/Tencent/teamai-cli/commit/be158d4)).
- The first session after an upgrade migrates legacy standalone hooks to the dispatch format ([`b0edb75`](https://github.com/Tencent/teamai-cli/commit/b0edb75)).
- `teamai init` shows the actual user/project storage paths before asking for a scope ([`843ed79`](https://github.com/Tencent/teamai-cli/commit/843ed79)).

## [0.16.6](https://github.com/Tencent/teamai-cli/compare/v0.16.5...v0.16.6) (2026-05-27)

### 🐛 Bug Fixes

- The release pipeline moves to Node.js 22, and `NPM_TOKEN` auth is restored after the OIDC trusted publisher attempt so npm publishing works.

## [0.16.5](https://github.com/Tencent/teamai-cli/compare/v0.16.4...v0.16.5) (2026-05-27)

### ✨ Features

- An environment variable disables wiki pull, push, and built-in skill deployment, and `status` shows the disabled state ([#22](https://github.com/Tencent/teamai-cli/pull/22)).

### 🐛 Bug Fixes

- Unify wiki skill path resolution and `teamai push` scope logic, fixing wrong paths under project scope ([#15](https://github.com/Tencent/teamai-cli/pull/15)).

## [0.16.4](https://github.com/Tencent/teamai-cli/compare/v0.16.3...v0.16.4) (2026-05-19)

### 💥 Breaking Changes

- The wiki moves from per-agent directories to a shared location: `~/.teamai/wiki/` for user scope and `<projectRoot>/.teamai/wiki/` for project scope ([#9](https://github.com/Tencent/teamai-cli/pull/9), !186).

### 🐛 Bug Fixes

- Exclude a nested `.git` when copying skills so no gitlink/submodule is created ([#12](https://github.com/Tencent/teamai-cli/pull/12)).
- Disable file-level parallelism in the GitHub E2E run, fixing the missing `dist/index.js` caused by concurrent cleanup ([#5](https://github.com/Tencent/teamai-cli/pull/5)).

### 📝 Documentation

- English is the default README on GitHub, and the Chinese version moves to `README.zh-CN.md` ([#2](https://github.com/Tencent/teamai-cli/pull/2), [#3](https://github.com/Tencent/teamai-cli/pull/3), [#4](https://github.com/Tencent/teamai-cli/pull/4)).

## [0.16.3](https://github.com/Tencent/teamai-cli/compare/v0.16.2...v0.16.3) (2026-05-09)

### 🐛 Bug Fixes

- pull filters rules by the current role's knowledge namespaces; root-level rules are always kept, and everything syncs when no role is configured (!182).

### 🔧 Refactoring

- Normalize npm package metadata: drop the redundant `./` in the `bin` path and standardize the repository URL.

### 📝 Documentation

- Update the project tagline to "The team harness for AI agents" (!180, !181, !184).

## [0.16.2](https://github.com/Tencent/teamai-cli/compare/v0.16.1...v0.16.2) (2026-05-01)

### ⚡ Performance

- Optimize Stop hooks: shorten the update timeout, add a `contribute-check` fast path and score cache, and lower the Dashboard JSONL compaction threshold (!176).

## [0.16.1](https://github.com/Tencent/teamai-cli/compare/v0.16.0...v0.16.1) (2026-04-29)

### 🐛 Bug Fixes

- Ensure `SKILL.md` frontmatter during pull and built-in skill deployment so Codex does not refuse to load them (!177).

### 📝 Documentation

- Update to the Tencent MIT License, remove ROADMAP/TODOS, and add open-source badges plus a full English README (!170, !171, !172, !174, !175).

## [0.16.0](https://github.com/Tencent/teamai-cli/compare/v0.15.0...v0.16.0) (2026-04-27)

### 💥 Breaking Changes

- `teamai list` now shows both the team repository and installed agents; `--source repo` restores the old behavior (!162).

### ✨ Features

- The provider for a bare `owner/repo` is inferred from the installed package name, and `TEAMAI_DEFAULT_PROVIDER` overrides it (!161).
- Add the built-in `/wiki` skill with multi-source ingestion, incremental updates, query, check, and export (!117).
- `teamai list` adds `--source` and `--agent`, plus the `teamai skill list/show` commands (!162).
- `teamai.yaml` adds a team-level `autoUpdate` policy, and `teamai push --skill` supports force-push and recursive skill scanning (!164, !167).

### 🐛 Bug Fixes

- Complete wiki repository push, failure rollback, remove, and tombstone cleanup (!163).
- Fix built-in wiki skill detection, hidden/workspace directory scanning, and false "modified" reports (!168, !169).

## [0.15.0](https://github.com/Tencent/teamai-cli/compare/v0.14.4...v0.15.0) (2026-04-20)

### 💥 Breaking Changes

- The default provider for a bare `owner/repo` becomes GitHub; TGit users need a full URL or an explicit provider (!156).
- The public package is `teamai-cli`; internal tnpm releases restore the `@tencent/teamai-cli` name (!156).

### ✨ Features

- Add the GitHub provider with `gh` / `GITHUB_TOKEN` auth, clone, repository creation, and pull requests (!156).
- Add dual-channel npm/tnpm publishing, and let the update check pick the registry from the package name (!156).

### 🐛 Bug Fixes

- Detect `main`/`master` dynamically, fixing GitHub push, branch cleanup, and PR creation (!156).
- `doctor` reads project-scope config first, and `source add` clones through the matching provider (!156).

### 🔧 CI/CD

- GitHub Actions adds a Node 20/22 × Ubuntu/macOS matrix and E2E coverage for the main commands; Coding CI is hardened to match (!157, !158).

## [0.14.4](https://github.com/Tencent/teamai-cli/compare/v0.14.3...v0.14.4) (2026-04-17)

### ✨ Features

- Dashboard cards show the AI output, first prompt, and last prompt by default, with Markdown rendering (!153, !154).
- Session states become `AI Working`, `Your Turn`, and `Ended` (!153).

### 🐛 Bug Fixes

- push syncs teammates' updates before scanning while keeping real local edits, so resources are no longer reported as modified (!152).
- Dashboard cards sort stably by total runtime (!151).

## [0.14.3](https://github.com/Tencent/teamai-cli/compare/v0.14.2...v0.14.3) (2026-04-17)

### 🐛 Bug Fixes

- The Stop hook waits for user input and monitors the AI tool process, ending the session only after that process exits (!149).
- The CodeBuddy team instruction path is corrected from `.codebuddy/CLAUDE.md` to `.codebuddy/CODEBUDDY.md` (!150).

## [0.14.2] (2026-04-16)

### 🐛 修复

- **pull role filtering**: 修复当团队无 `tags.yaml` 或用户无 tag 订阅时，`teamai pull` 同步角色外命名空间 skills 的问题 (!148)

## [0.14.0] (2026-04-16)

### ✨ 新功能

- **跨团队 Skill 订阅（Cross-team Source）**：`teamai source add/remove/list/browse` 订阅其他团队的公共 skill 仓库，pull 时自动同步订阅源的 skills (!141)
  - `teamai source add <repo> [--name <alias>]` — 添加订阅源
  - `teamai source remove <name>` — 移除订阅源并清理其 skills
  - `teamai source list` — 列出已配置的订阅源
  - `teamai source browse <name>` — 浏览订阅源的公共 skills
- **团队文化注入（Culture Engine Phase 1）**：在团队仓库创建 `culture.md`，`teamai pull` 时自动编译并注入到各 AI 工具的 `CLAUDE.md` 中 (!84)
  - 支持 YAML frontmatter 定义公司/团队信息（name, mission, vision, values, goals）
  - Markdown body 部分作为团队文化指引正文注入
  - 通用 CLAUDE.md section 注入工具（`utils/claudemd.ts`），被 rules 和 culture 共用
- **Uninstall 命令**：`teamai uninstall [--force]` 智能清理所有 teamai 管理的资源（hooks、CLAUDE.md 块、skills、rules、env、docs、~/.teamai/），保留用户自建内容，支持 `--dry-run` 预览 (!137)
- **Dashboard 全生命周期会话展示**：dashboard 新增完整 session 生命周期追踪，支持展开查看会话详情（prompt 摘要、工具调用序列、时间线） (!140)
- **codex-internal 工具支持**：hooks 注入和资源同步新增对 codex-internal 的适配，与 claude-internal 同等待遇 (!143)
- **CLAUDE.md 团队知识库引用**：pull 时自动在 CLAUDE.md 中添加 `~/.teamai/learnings/` 目录引用，AI 工具可直接发现团队知识库 (!139)
- **Init 非交互模式**：新增 `--role <id>` 和 `--force` 参数，支持完全非交互式初始化，适合 CI/CD 和 AI agent 自动化 (!138)
  - `teamai init --repo owner/repo --scope user --role hai_dev --force`
  - 非 TTY 环境下自动使用默认值，不再 hang
- **共享 Prompt 工具**：统一 6 个模块（init/uninstall/update/remove/push/roles-cmd）的 readline 实现为单例模式，修复管道输入兼容性问题 (!138)
- **Push 交互式命名空间选择**：推送新 skill 时，CLI 自动检测团队仓库中的命名空间并提供交互式选择，无需手动指定 `--role` (!128)
  - 有 `primaryRole` 时，从 manifest 展开可用 namespace 列表
  - 无 `primaryRole` 时，自动扫描团队仓库目录结构
  - 单一命名空间时自动选中，`--silent` 模式下使用默认值
- **Push 自动注入 YAML Frontmatter**：推送 skill 时自动检查 `SKILL.md`，缺少 `name`/`description` frontmatter 则自动补全 (!130)
  - 从目录名推导 `name`，从第一个标题或有意义文本行推导 `description`
  - 已有完整 frontmatter 的文件不做任何修改

### 🐛 修复

- **Pull cache 失效修复**：切换 role 后自动清理过期 skills 缓存，确保新角色立即生效 (!142)
- **Learnings 改为扁平共享模型**：learnings 不再按角色 namespace 隔离，全团队共享 (!126)
- **Push role 模式过滤修正**：修复 role 模式下误显示非允许命名空间 skill 的问题 (!127)
- **Push 支持无 role 的 namespaced 仓库**：无 `primaryRole` 配置时也能正确推送到有命名空间结构的团队仓库 (!129)
- **Votes 不再阻塞 push**：votes 改为本地存储（`~/.teamai/votes/`），由 `teamai pull` 的 auto-report 统一同步到团队仓库，不再直接写入 repo 导致脏文件阻塞 git 操作 (!131)
- **Pull 跳过未安装的 AI 工具**：pull 时检测工具是否已安装，跳过未安装工具，不再创建多余的空目录 (!132)
- **Team repo 自动恢复**：push/pull 前自动检测并恢复 team repo 的脏状态（unmerged 文件、残留 push 分支），使用 `git reset --hard` + 切回 master (!133, !134)
- **Auto-recall 误判修复**：修复源代码中的错误关键词被 auto-recall 误判为运行时错误触发搜索的问题 (!135)

## [0.13.2](https://git.woa.com/teamai/teamai-cli/compare/v0.13.1...v0.13.2) (2026-04-10)

### 🐛 修复

- 修复 Cursor hooks.json 中残留已废弃的 `userPromptSubmit` 事件 key 导致 "Invalid hooks.json" 报错的问题 (!122)

## [0.13.3](https://git.woa.com/teamai/teamai-cli/compare/v0.13.2...v0.13.3) (2026-04-10)

### ✨ 新功能

- **Roles CRUD 命令**：新增 `teamai roles add/remove/update`，管理员无需手动编辑 YAML 即可管理团队角色 (!125)
  - `teamai roles add <id> --namespaces <ns> [-d <desc>]` — 添加角色
  - `teamai roles remove <id>` — 删除角色
  - `teamai roles update <id> --add-namespaces/--remove-namespaces` — 修改角色

### 🐛 修复

- **Pull 安全降级**：成员配置的角色被删除后，pull 不再崩溃，改为 warn + 回退全量同步 (!125)
- **Push namespace 解析**：从 manifest 读取实际 namespace 列表，不再错误地将 role id 当作 namespace (!125)

### 🔧 重构

- 抽出 `pushManifestChange()` 和 `pullLatest()` 共用函数，消除 `rolesInit` 中的重复代码 (!125)
- 新增 `saveRolesManifest()` 含写前校验，防止写入非法 manifest (!125)

---

## [0.13.1](https://git.woa.com/teamai/teamai-cli/compare/v0.11.2...v0.13.1) (2026-04-09)

### ✨ 新功能

- **Roles 管理**：新增 `teamai roles` 命令组（`init`/`list`/`set`），支持团队角色的创建、列举和切换 (!113)
- **Role-aware Skill 同步**：`teamai pull/push` 支持按角色过滤 skill，不同角色看到不同的技能集 (!100)
- **Local Pushignore**：skill 目录支持 `.pushignore` 文件，push 时自动排除不需要同步的本地文件 (!114)
- **Marketplace 自动刷新**：skill push/remove 后自动刷新 `.codebuddy-plugin/marketplace.json`，兼容 CodeBuddy 插件市场 (!119)

### 🐛 修复

- 修复 roles manifest 缺失时 `teamai init` role 选择报错的问题 (!112)
- 修复 auto-recall 对自身输出产生递归误报的问题 (!111)
- 修复 auto-recall 搜索精度不足，新增 title/tag 匹配要求，跳过只读命令 (!104)
- 修复 Stop hook 使用错误的 output schema（`hookSpecificOutput` → `stopReason`）(!107, !108)

### ⚡ 性能优化

- **Team Repo 同步加速**：当 team repo HEAD 未变化时跳过资源同步，避免无意义的文件扫描 (!110)
- **Auto-recall 精准匹配**：matcher 从通配符 `*` 收窄为 4 个精确工具，减少不必要的触发 (!106)

### ♻️ 重构

- 统一 recall 机制 — hook 搜索工具，删除 session-recall 和 recall rule (!102)
- `contribute-check` 从 PostToolUse hook 迁移到 Stop hook，减少每次工具调用的开销 (!103)
- `role bucket` 重命名为 `namespace`，语义更清晰 (!105)

### 📝 文档

- 添加 CLAUDE.md 项目说明和发布流程 (!97)
- 文档中 tnpm 替换为标准 npm + --registry (!118)

---

## [0.9.1](https://git.woa.com/teamai/teamai-cli/compare/v0.9.0...v0.9.1) (2026-03-30)

### 🔧 修复 debug.log 始终为空的问题

`~/.teamai/debug.log` 现在能正确记录所有 hook 运行时的调试和错误信息，方便排查 teamai 后台行为。

#### 问题根因

Hook 命令通过 `2>>~/.teamai/debug.log` 捕获 stderr，但代码中所有日志（包括错误）都写到 stdout（`console.log`），且 `--verbose` 默认关闭——三重静默导致 debug.log 永远为空。

#### 修复方案

- **File Transport**：所有 `log.debug()` 和 `log.error()` 调用现在同时写入 `~/.teamai/debug.log`，不再依赖 shell 的 stderr 重定向
- **ISO 时间戳**：每行日志带 `2026-03-30T06:32:14.123Z [DEBUG]` 格式前缀
- **错误级别拆分**：catch 块中的失败信息从 `log.debug` 改为 `log.error`，方便 `grep ERROR ~/.teamai/debug.log` 快速定位问题
- **自动 Rotation**：debug.log 超过 5MB 自动轮转为 `debug.log.1`，总占用不超过 10MB
- **同步写入**：使用 `appendFileSync` 确保短命 hook 进程不丢日志

#### 使用方式

```bash
# 查看最近的调试日志
tail -20 ~/.teamai/debug.log

# 快速找错误
grep ERROR ~/.teamai/debug.log
```

---

## [0.9.0](https://git.woa.com/teamai/teamai-cli/compare/v0.8.1...v0.9.0) (2026-03-29)

### 🔌 内置规则自动部署 — AI 工具零配置接入团队知识库

`teamai pull` 现在会自动将 CLI 内置的 AI 规则（rules）部署到所有已安装的 AI 工具目录中，**团队成员无需手动配置**，pull 一次即可让 Claude Code / Cursor 等工具自动搜索团队知识库。

#### 工作原理

1. `teamai pull` 执行时，自动检测已安装的 AI 工具（Claude Code、Cursor 等）
2. 将内置规则写入各工具的 `rules/` 目录：
   - `~/.claude/rules/teamai-recall.md`
   - `~/.claude-internal/rules/teamai-recall.md`
   - `~/.cursor/rules/teamai-recall.md`
3. 规则内容随 CLI 版本更新，每次 pull 自动同步最新版本

#### 首个内置规则：`teamai-recall`

该规则指导 AI 在遇到错误、部署问题或不熟悉的模式时，**先搜索团队知识库**再从零开始解决：

```bash
teamai recall "API timeout retry"
teamai recall "K8s OOM pod restart"
```

#### 设计要点

- **零配置** — pull 即生效，团队成员不需要手动复制规则文件
- **跳过未安装工具** — 自动检测，只部署到已安装的 AI 工具
- **与团队规则隔离** — `teamai push` 不会误将内置规则推送到团队仓库
- **可扩展** — 后续可轻松添加更多内置规则

#### 完善知识飞轮闭环

```
contribute(写入) → pull(同步+索引+部署规则) → AI 自动 recall(搜索) → upvote(投票)
                                    ↑ NEW
```

## [0.8.1](https://git.woa.com/teamai/teamai-cli/compare/v0.8.0...v0.8.1) (2026-03-28)

### Digest 隐私改进 + Skill 动态展示

#### 隐私改进

* **移除 digest 中的个人可推断信息** — `(142 uses by 3 member(s))` → `(142 uses)`，小团队中不再能反推谁用了什么
* **移除 skill 推荐中的百分比** — `used by 57% of team` → `popular with your team`，同理保护隐私

#### 新功能

* **Digest 新增 Skill 动态** — `teamai digest` 现在展示近 7 天新增和更新的 Skill
  - 🆕 New Skills This Week — 新创建的 skill，显示作者
  - 🔄 Recently Updated Skills — 有内容更新的 skill
  - 数据来源：team repo 的 git log，零额外配置

#### 示例

```
🆕 New Skills This Week:
  • hai-gpu-sold-report (by jeffyxu)
  • hai-prod-db (by keitewang)

🔄 Recently Updated Skills:
  • tke-deploy
  • hai-deploy-quick
  • tapd-tech-design
```

## [0.8.0](https://git.woa.com/teamai/teamai-cli/compare/v0.7.1...v0.8.0) (2026-03-28)

### 🧠 Git-Native Memory — 团队知识回忆系统

借鉴 [vectorize-io/hindsight](https://github.com/vectorize-io/hindsight) 的 retain/recall 记忆模型，为 teamai 补全知识飞轮的"读出路径"。之前通过 `/teamai-share-learnings` 贡献的经验文档写了没人看，现在 AI 可以通过 `teamai recall` 自动搜索和引用。

**知识飞轮闭环：** `contribute(写入) → pull(同步+索引) → recall(搜索) → upvote(投票) → 排序优化`

#### 新功能

* **`teamai recall <query>`** — 搜索团队知识库，返回按相关性排名的结果 ([!81](https://git.woa.com/teamai/teamai-cli/-/merge_requests/81))
* **Pull 自动同步 learnings** — `teamai pull` 现在会同步 `learnings/` 目录到本地，并自动重建搜索索引
* **Hybrid 中英文搜索** — Intl.Segmenter 拆分英文词 + CJK bigrams 捕捉中文复合词（如"超时""排查"），解决纯 Segmenter 把中文拆成单字的问题
* **搜索自动投票** — recall 返回结果时自动为文档投票（`votes/<user>.yaml`），好文档随时间自然浮到顶部
* **Frontmatter 标准化** — SKILL.md 模板要求 AI 生成的文档包含 `title/author/date/tags` YAML frontmatter，提升搜索精准度

#### 搜索评分规则

| 匹配类型 | 分值 | 说明 |
|----------|------|------|
| 标题命中 | ×3 | frontmatter title 中的词匹配 |
| 标签命中 | ×2 | frontmatter tags 中的词匹配 |
| 正文命中 | ×1 | 文档正文（前 2000 字）中的词匹配 |
| 投票加分 | +0.5/票 | 每票 +0.5，上限 5 分 |

#### 示例

```bash
$ teamai recall "fuse 端口"
--- [teamai:recall:start] --- (1 result)

[1/1] MR 审查发现 FUSE 端口冲突 Bug 及 UpdateInferService 接口测试验证 ★1
Author: jeffyxu | Date: 2026-03-28 | Score: 18.5
Tags: troubleshooting, code-review, tdd, hai_flow, fuse, k8s
File: ~/.teamai/learnings/mr审查发现fuse端口冲突bug及...md

--- [teamai:recall:end] ---
```

#### 技术细节

| 文件 | 说明 |
|------|------|
| `src/utils/search-index.ts` | 搜索引擎核心：hybrid tokenize, buildIndex, loadIndex, search |
| `src/recall.ts` | recall CLI 命令 + autoUpvote |
| `src/types.ts` | LearningDoc, SearchIndex, UserVotes 类型 |
| `src/pull.ts` | learnings 同步 + 索引重建（内联实现，不继承 ResourceHandler） |
| `src/team-push.ts` | auto-report 扩展：投票数据随 pull 捎带推送 |

**测试：** 29 个新测试，全量 444 通过。
**设计文档：** `docs/designs/git-native-memory.md`

## [0.7.1](https://git.woa.com/teamai/teamai-cli/compare/v0.7.0...v0.7.1) (2026-03-28)

### 改进 contribute 经验分享系统

**目录重命名：** `ai-docs/` → `learnings/`，语义更清晰。

**smartScore 评分修复：** 之前的评分逻辑导致提醒从未触发（13 个 session，0 个达标）。
- 新增 toolCount 梯度维度（30→10, 50→15, 80+→20，max 20 分）
- Skill/Error 权重从 25 分降至 15 分（大多数有价值 session 不一定用到）
- 阈值从 60 降至 35
- 真实数据验证：7 个历史 session 中 6 个可触发（之前 0 个）

**文件名格式：** `data-<slug>-<random>.md` → `<slug>-<date>-<random>.md`，加入日期便于辨识。

**中文文档模板：** SKILL.md 改为中文模板，AI 生成的经验文档默认中文撰写。

**测试：** 新增 2 个测试用例（toolCount gradient + 典型 session 集成），全量 12 个 contribute-check 测试通过。

## [0.7.0](https://git.woa.com/teamai/teamai-cli/compare/v0.6.2...v0.7.0) (2026-03-28)

### 🚀 `teamai hooks` 子命令 + update 钩子刷新修复

CLI 升级后新钩子永远无法自动注入的 bug 终于修复。根因：`update.ts` 在 `npm install -g` 后直接调用内存中的 `injectHooksToAllTools()`，但 Node.js 进程仍加载旧版代码，新版代码在磁盘上却不会被重新加载。

**新命令：**
- `teamai hooks inject` — 将 teamai 钩子注入所有 AI 工具的 settings 文件（支持 `--silent` 静默模式）
- `teamai hooks remove` — 从所有 AI 工具的 settings 文件中移除 teamai 钩子

**Bug Fix：**
- `teamai update` 安装新版后，改为 spawn `teamai hooks inject --silent` 子进程，确保加载磁盘上的新版代码，而非旧进程内存中的过时代码

**Doctor 增强：**
- `teamai doctor` 钩子检查从只检查 `pull` / description prefix 改为校验全部 6 个子命令（pull, update, track, track-slash, dashboard-report, contribute-check）
- 缺失子命令时建议运行 `teamai hooks inject`

**新 CLI 命令：**
| Command | Description |
|---------|-------------|
| `teamai hooks inject` | 注入 teamai 钩子到所有 AI 工具 settings |
| `teamai hooks remove` | 移除所有 AI 工具 settings 中的 teamai 钩子 |

**测试：**
- 新增 11 个测试用例（hooks-cmd 7 + doctor 4），全量 413 测试通过

**For Existing Users：**
无需手动操作。下次 `teamai update` 时新版代码会正确刷新钩子。如需手动修复，运行 `teamai hooks inject`。

### [0.6.2](https://git.woa.com/teamai/teamai-cli/compare/v0.6.1...v0.6.2) (2026-03-27)


### Improvements

* **contribute-check**: rename `hinted` → `evaluated`, add `smartScore` field ([!78](https://git.woa.com/teamai/teamai-cli/-/merge_requests/78))
  - `hinted` 语义不准确（实际含义是"已评估"而非"已提示用户"），重命名为 `evaluated`
  - 新增 `smartScore` 字段，持久化评估分数便于排查 session 为何未触发 hint
  - `readContributeState` 向后兼容旧格式，自动迁移 `hinted` → `evaluated`
  - Cursor 端补上遗漏的 `contribute-check` hook

### [0.6.1](https://git.woa.com/teamai/teamai-cli/compare/v0.6.0...v0.6.1) (2026-03-27)


### Bug Fixes

* **contribute-check**: per-session state files to prevent multi-window overwrite ([!77](https://git.woa.com/teamai/teamai-cli/-/merge_requests/77))
  - `contribute-state.json` 单文件被多窗口互相覆盖，toolCount 反复归零
  - 改为 `~/.teamai/sessions/{sessionId}.json`，每个 session 独立文件，零竞争
  - 写入时自动清理超过 24h 的旧 session 文件
  - `CONTRIBUTE_BASE_THRESHOLD` 从 100 降到 50，匹配实际 session 工具调用分布

## [0.6.0](https://git.woa.com/teamai/teamai-cli/compare/v0.5.2...v0.6.0) (2026-03-27)

### 🚀 Session 经验自动分享

AI coding session 中使用超过 100 次工具调用时，系统智能评估 session 价值并提示用户分享经验给团队。

**工作原理：**

```
AI coding session
    │
    ▼  PostToolUse hook 每次工具调用自动计数（~1ms）
    │
    ├─ < 100 次 → 静默计数
    │
    ▼  达到 100 次 → 智能评分
    │
    ├─ 分数不够（只是重复调用同一个工具）→ 不打扰
    │
    ▼  分数达标（工具多样、用了 skill、有错误重试、session 够长）
    │
    AI 提示："本次 session 内容丰富，建议运行 /teamai-share-learnings 分享经验"
    │
    ▼  用户同意 → AI sub-agent 生成摘要 → push 到团队仓库 ai-docs/
```

**新命令：**
- `teamai contribute --file <path> --title <title>` — 将经验文档推送到团队仓库 `ai-docs/` 目录
- `teamai contribute-check --stdin` — hook 内部使用，智能阈值检测

**内置 Skill：**
- `/teamai-share-learnings` — AI sub-agent 总结 session 经验并推送到团队仓库
- 随 `teamai pull/init` 自动部署到本地，CLI 升级时 skill 内容跟着更新
- `teamai push` 自动排除内置 skill，不会推到团队 repo

**智能评分机制：**
- 工具多样性（用了多少种不同工具）— 最高 30 分
- Skill 使用（触发了复杂工作流）— 25 分
- 错误和重试（踩坑经验更有价值）— 25 分
- Session 时长（> 30 分钟）— 20 分
- 总分 ≥ 60 才触发提示

**性能设计：**
- 两层检测：前 99 次只读写小 JSON state 文件（~1ms），不读 events.jsonl
- 达到 100 次时一次性读取 events.jsonl 做智能评估
- 每个 session 最多提示一次（去重），用户可忽略

**技术细节：**
- 新增 `contribute-check.ts`（阈值检测 + STDOUT hint）、`contribute.ts`（push 命令）、`builtin-skills.ts`（内置 skill 自动部署）
- 修改 `hooks.ts`（新增 PostToolUse contribute-check hook）、`pull.ts`/`init.ts`（内置 skill 部署）
- 15 个新单测 + 更新现有 hooks 测试

### [0.5.2](https://git.woa.com/teamai/teamai-cli/compare/v0.5.1...v0.5.2) (2026-03-26)

### Bug Fixes

* clean up stale local rule files during pull (merge request !71) ([30a4662](https://git.woa.com/teamai/teamai-cli/commit/30a466271394b2a7b2ca3d229aada3ea8cb57f17))
  - `teamai pull` 现在会自动清理本地已从 team repo 删除的 rule 文件
  - 之前从 team repo 删除 rule 后，本地 `~/.claude/rules/` 等目录会残留过期副本
  - 清理逻辑：对比本地 `.md` 文件与 team repo，删除上游已不存在的文件
  - 自动清理删除后留下的空子目录
  - 仅影响 `.md` 文件，其他文件类型不受影响
  - 新增 5 个测试用例覆盖各种清理场景

## [0.5.1](https://git.woa.com/teamai/teamai-cli/compare/v0.5.0...v0.5.1) (2026-03-25)

### Bug Fixes

* skip tracking slash commands for non-existent skills (merge request !70) ([8eb2778](https://git.woa.com/teamai/teamai-cli/commit/8eb2778))
  - 输入 `/data` 等不存在的 skill 不再被计入 `teamai stats` 统计
  - 新增 `skillExistsOnDisk()` 检查，验证 SKILL.md 存在后才记录
  - 仅影响 slash command 路径，Skill tool 调用不受影响

## [0.5.0](https://git.woa.com/teamai/teamai-cli/compare/v0.4.5...v0.5.0) (2026-03-25)

### 🚀 AI Coding Session Dashboard (Phase 1)

新增 `teamai dashboard` 命令，在浏览器中实时展示所有 AI coding session 的状态。解决多窗口 Alt+Tab 切换的痛点。

**新命令：**
- `teamai dashboard` — 启动本地 Web UI（默认 localhost:3721），展示 session 状态卡片
- `teamai dashboard -p <port>` — 自定义端口
- `teamai dashboard-report --stdin --tool <name>` — hook 内部使用，上报 session 事件

**Dashboard 功能：**
- 🟢🟡🔴⚪ 状态灯：running / waiting / error / idle
- Session 卡片展示：工作目录 (cwd)、首个 prompt 摘要、最后使用工具、活动时间
- SSE 实时推送，延迟 < 3 秒
- Session 识别：session_id 优先 + PID+cwd fallback
- 自动清理：Stop hook + 5 分钟 idle 超时 + 30 分钟移除
- JSONL 事件日志 + 超过 10,000 行自动 compact
- 暗色主题 Web UI，零新依赖（Node.js 内置 http 模块）

**Hook 变更：**
- 新增 4 个独立 dashboard hooks（SessionStart / PostToolUse / UserPromptSubmit / Stop）
- 与现有 usage tracking hooks 完全解耦，可独立开关

### Features

* add AI coding session dashboard (Phase 1) (merge request !69) ([25308dd](https://git.woa.com/teamai/teamai-cli/commit/25308dd08a32ed52a3a43aa661475c0e6893c0ea))


### Bug Fixes

* cleanup all teamai hooks (including outdated descriptions) before re-inject ([8352449](https://git.woa.com/teamai/teamai-cli/commit/8352449fed58398a008440cd80b9760602431bf7))
* usage tracking tool field + auto hook cleanup (merge request !68) ([3086278](https://git.woa.com/teamai/teamai-cli/commit/30862780f86e883de5bd74c710e94ab502b8cf16))
* usage tracking tool field correctly identifies each AI tool (merge request !67) ([dfd51ca](https://git.woa.com/teamai/teamai-cli/commit/dfd51ca197729b14eea5e9977f37114f02c04c42))

## [0.4.7] - 2026-03-24

### Fixed
- **彻底清理重复 hooks**：`cleanupLegacyHooks` 现在清理所有命令含 teamai 的条目（无论有无 description），修复了 description 关键词改名（如 "Check for updates" → "Auto-update"）导致的重复问题

### Tests
- 新增过时 description 清理测试，全量 340 测试通过

## [0.4.6] - 2026-03-24

### Fixed
- **Usage tracking `tool` 字段归因修复**：hook 命令从 `teamai track --stdin` 改为 `teamai track --stdin --tool <name>`，每个工具的 settings.json 注入各自标识（claude / claude-internal / codebuddy 等），usage 数据不再全部记为 `'claude'`
- **清理遗留重复 hooks**：早期版本注入的 hook 无 `description` 字段导致重复堆积，新增 `cleanupLegacyHooks()` 在注入前自动清理，非 teamai hook（如 continuous-learning）不受影响

### Added
- **Update 后自动刷新 hooks**：`teamai update` 成功安装新版后自动调用 `injectHooksToAllTools()`，老用户无需重新 `teamai init`，未初始化则静默跳过
- `track` / `track-slash` CLI 命令新增 `--tool <name>` option，缺省默认 `'claude'`（向后兼容）

### Tests
- 新增 17 个测试：--tool 参数传递、向后兼容、hook 命令字符串验证、遗留 hook 清理、非 teamai hook 保留、update 后 hooks 刷新
- 全量 317 测试通过，零回归

### For Existing Users
无需任何手动操作。下次 session 结束时 Stop hook 触发 `teamai update` → 自动安装新版 → 自动刷新 hooks + 清理重复条目。

## [0.4.5] - 2026-03-24

### Added
- **Slash Command 使用追踪**：新增 `UserPromptSubmit` hook 检测 `/slash-command` 调用（如 `/plan-eng-review`、`/tdd`），自动记录到 `usage.jsonl`
  - 新增 `teamai track-slash --stdin` CLI 命令，解析 Claude Code 的 `UserPromptSubmit` hook JSON
  - 支持冒号命名空间格式（如 `/gstack:tdd`）
  - `teamai init` 自动注入 `UserPromptSubmit` hook 到 Claude Code settings.json

### Fixed
- **Usage 上报竞态条件**：`reportUsageToTeam` 改为先 `git pull` 获取最新远端 stats 再合并本地数据，防止并发 push 时相互覆盖导致数据丢失

### Changed
- **Hooks 注入重构**：`hooks.ts` 从 200+ 行嵌套 if/else 重构为数据驱动的 `CLAUDE_HOOKS[]` 数组 + 通用 `ensureClaudeHook()` 函数，新增 hook 只需加一行定义
- `stats.ts` 和 `team-push.ts` 之间新增交叉引用注释，标注两处 merge 逻辑的关联

### Tests
- 新增 8 个 trackSlashCommand 测试：合法追踪、冒号命名空间、非 slash 忽略、空 prompt、空 STDIN、畸形 JSON、known-skills 更新
- 全量 302 测试通过，零回归

### For Existing Users
存量用户下次 `teamai pull` 或重新运行 `teamai init` 后，`UserPromptSubmit` hook 会自动注入，无需手动操作。

## [0.4.4] - 2026-03-22

### Added
- **Cursor Skill 使用追踪**：通过 postToolUse hook (matcher: `Read`) 检测 SKILL.md 文件读取，自动记录 Cursor 用户的 skill 使用到 `usage.jsonl`
  - `teamai init` 自动注入 postToolUse hook 到 Cursor 的 `hooks.json`
  - `UsageEvent.tool` 字段区分 `cursor` / `claude`，支持按工具来源分析使用数据
  - 适配 Cursor 原生 STDIN 格式（`file_path` 字段），经实际 hook 触发验证
- **Hook 自动更新**：stop hook 从 `teamai update --check` 改为 `teamai update`，支持根据 updatePolicy 自动安装更新（不再仅打印提示）
  - `doUpdate` 通过 TTY 检测区分 hook/手动模式，非 TTY 环境下 prompt 策略自动降级为提示

### Tests
- 新增 7 个测试：Cursor Read + SKILL.md 路径追踪、file_path 原生格式、非 SKILL.md 忽略、工具来源标记验证
- 全量 294 测试通过，零回归

### For Existing Users
存量 Cursor 用户需重新运行 `teamai init` 以注入 postToolUse hook。Claude Code 用户无需操作，hook 会在下次会话结束时自动更新。

## [0.4.3] - 2026-03-22

### Fixed
- **Stats 数据每次上报后丢失（Critical）**：`reportUsageToTeam` 每次 `teamai pull` 时直接覆写 `stats/<user>.yaml`，不与历史数据合并，导致之前累积的统计全部丢失。修复后先读取已有 stats 文件，count 累加、lastUsed 取更新值
- **`teamai stats` 在 pull 后显示空数据**：`showStats` 只读 `usage.jsonl`（每次成功上报后被 truncate 清空），导致用户看到 "No skill usage data yet"。修复后同时读取本地 `usage.jsonl`（未上报事件）+ 团队仓库 `stats/<user>.yaml`（已上报历史），合并展示完整统计
- **Skill 名提取字段兼容性不足**：`extractSkillName` 仅检查 `skill`/`name` 字段，遗漏部分 AI 工具的 hook 格式
  - 新增 `skill_name`、`command` 字段支持
  - 支持从 SKILL.md 文件路径（如 `/root/.cursor/skills/tdd/SKILL.md`）中自动提取 skill 目录名

### Tests
- 新增 17 个测试用例：mergeStats 合并逻辑（4）、extractSkillName 多格式提取（9）、边界条件（4）
- 全量 288 测试通过，零回归

## [0.4.2] - 2026-03-20

### Fixed
- **Skill 使用追踪完全失效**：PostToolUse hook 通过环境变量 (`$CLAUDE_TOOL_NAME`) 读取数据，但 Claude Code 实际通过 STDIN JSON 传递。hook 每次收到空参数，从未记录任何真实 skill 使用事件
  - 新增 `teamai track --stdin` 模式，从 STDIN 读取 Claude Code hook JSON 并解析 `tool_name`/`tool_input`
  - Hook 命令从 `'teamai track "$CLAUDE_TOOL_NAME" ...'` 改为 `'teamai track --stdin'`
  - 旧 CLI 参数方式仍兼容，支持手动测试
- **Skill 推荐始终显示 "you haven't tried it"**：`usage.jsonl` 上报到团队仓库后被 truncate 清空，但推荐引擎只读 `usage.jsonl`，丢失全部历史数据
  - 新增 `~/.teamai/known-skills.json` 持久化已用 skill 集合，不受 truncate 影响
  - 推荐引擎合并 `usage.jsonl`（未上报事件）+ `known-skills.json`（历史记录）两个数据源
- Hook 错误不再静默丢弃：stderr 从 `/dev/null` 改为追加到 `~/.teamai/debug.log`，方便排查

### For Existing Users
存量用户下次 `teamai pull` 时 hook 会自动升级为 `--stdin` 模式，无需手动操作。

## [0.4.1] - 2026-03-20

### Fixed
- `scanLocalForPush()` crash bug：遍历 `toolPaths` 时缺少 `toolPath.skills` null 检查，当工具配置没有 `skills` 字段时 `teamai push` 会崩溃 (TypeError)。该 bug 在 v0.3.13 重构时遗漏 (!61)
- `ToolPathsSchema.skills` 从 required 改为 optional，与运行时防御性检查一致

### Removed
- 清理 `syncTargets` 僵尸配置：v0.3.13 已改为自动检测工具，但 `syncTargets` 残留在 schema、init、28+ 处测试中。全部清除
- `init` 生成的 `teamai.yaml` 不再包含 `sharing.skills.syncTargets` 字段

## [0.4.0] - 2026-03-19

### Added
- **Skill Usage Tracking**: PostToolUse hook 自动追踪 Skill 工具调用，写入 `~/.teamai/usage.jsonl`
  - `teamai track <toolName> [toolInput]` — hook 调用的底层命令，自带 skill name 校验（防 path traversal）
  - `teamai stats` — 查看本地 skill 使用统计（次数 + 最近使用时间）
  - `teamai init` 自动注入 PostToolUse hook 到 Claude Code / Claude Internal / CodeBuddy 的 settings.json
- **团队 Usage 自动上报**: `teamai pull` 时自动聚合本地 usage 数据为 `stats/<user>.yaml` 并 git push 到团队仓库
  - Best-effort 策略，5s 超时，失败不阻塞 session 启动
  - 上报成功后自动截断本地 JSONL，文件永远很小
- **Skill Health Score**: 两维评分 = usage(0-60) + freshness(0-40)，0-100 分显示为 ★★★★★
- **Skill 推荐**: `teamai pull` 后自动推荐团队热门但用户未使用的 skill
- **Session 记录**: `teamai save-session [--summary "..."]` 收集会话工具使用记录并评估价值
  - 有价值（含错误/重试/踩坑）的 session 标记为可推送
  - 按月聚合存储到 `~/.teamai/sessions/<year-month>.md`
- **团队周报**: `teamai digest` 生成团队 AI 工具使用周报（最热 skill、活跃成员、session 摘要）
- 新增设计文档 `docs/designs/team-intelligence-platform.md`
- 新增 `TODOS.md` 记录延迟工作项

### New CLI Commands
| Command | Description |
|---------|-------------|
| `teamai track` | 追踪工具使用（PostToolUse hook 调用） |
| `teamai stats` | 查看本地 skill 使用统计 |
| `teamai save-session` | 保存会话工具使用摘要 |
| `teamai digest` | 生成团队周报 |

### For Existing Users
存量用户需重新运行 `teamai init` 以注入 PostToolUse hook。

## [0.3.14] - 2026-03-19

### Added
- 自动更新功能：新增 `teamai update [--check]` 命令，支持从 tnpm 检查并安装最新版本
  - 24 小时版本检查缓存，避免频繁请求 registry
  - 可配置更新策略：`auto`（自动安装）、`prompt`（提示确认）、`skip`（跳过）
  - PID 文件锁防止并发安装冲突
- Session 结束自动检查更新：`teamai init` 自动注入 Stop/SessionEnd hook，AI 工具会话结束时自动检测新版本

## [0.3.13] - 2026-03-17

### Added
- OpenClaw 支持：skills 和 rules 自动同步到 `~/.openclaw/skills/` 和 `~/.openclaw/rules/` (!57)

### Changed
- Skills sync 改为自动检测已安装工具，不再依赖 `syncTargets` 配置 (!58)
  - 遍历所有 `toolPaths` 并通过 `isToolInstalled` 检测 `~/` 下目录是否存在
  - 新增工具无需修改 `teamai.yaml` 即可自动同步
  - 与 rules sync 行为保持一致

### Fixed
- Cursor skills 路径修正：`.cursor/skills-cursor` → `.cursor/skills` (!56)

## [0.3.12] - 2026-03-12

### Fixed
- `teamai pull` docs 数量显示修复：之前始终显示 "Synced 1 docs"，现在正确显示实际文件数（如 "Synced 2 docs"）
- `teamai status` docs 计数修复：之前用 `listDirs` 统计目录数（结果为 0），改为用 `listFiles` 统计实际文档文件数

## [0.3.11] - 2026-03-12

### Fixed
- 文件系统操作（目录扫描、内容比较、复制、mtime 计算）全局过滤 `__pycache__/`、`.pyc`、`.DS_Store`、`node_modules` 等无关文件，避免 push/pull 时产生误判的"已修改"diff

## [0.3.10] - 2026-03-11

### Added
- Rules 子目录支持：`teamai push`/`pull` 递归扫描 rules 目录，支持按语言/类别组织规则文件（如 `common/`、`python/`、`golang/`）(!52)
- 新增 `listFilesRecursive()` 工具函数用于递归文件遍历
- `teamai push` 默认显示每个资源的源文件路径

### Changed
- CLAUDE.md 引用从逐文件列举改为目录级引用（`~/.claude/rules/`），减少上下文占用
- CLAUDE.md 新增 docs 目录引用（`~/.teamai/docs/`）
- `teamai pull` 日志从 "Merged N rule(s) into CLAUDE.md" 改为 "Synced N rule(s)"

## [0.3.9] - 2026-03-10

### Fixed
- `teamai init --repo group/subgroup/repo` 多级路径支持：`gf repo clone` 不支持三级及以上路径，改为回退到带 OAuth token 的 `git clone`
- `gfCreateRepo` 查找 namespace 时使用 `full_path` 匹配，修复多级 group 下创建仓库 namespace 匹配失败的问题

## [0.3.8] - 2026-03-10

### Added
- `teamai push` skill 推送时自动维护 CONTRIBUTORS 文件，记录每个 skill 的贡献者 (!46)

### Fixed
- `gfGetOAuthToken` 返回用户密码而非 OAuth token (!47)
- OAuth token 改为从 `~/.netrc` 读取，替代不可靠的 `git credential fill` (!48)
- 修正 OAuth token 相关的误导性注释 (!49)
- `gf mr create` MR title/description 使用 shell 单引号，修复换行符丢失问题 (!50)
- 支持多级 group 路径的仓库 URL 解析（如 `group/subgroup/repo`）(!42)

### Changed
- 简化 README，按角色（管理员/成员）分离快速上手指南 (!43, !45)

## [0.3.7] - 2026-03-09

### Fixed
- `gf mr create` 创建 MR 时 PushNotFastForward 错误：`pushRepoBranch` 在 push 后切回 master，导致 gf 内部 push HEAD 时分支不匹配。现在保持 HEAD 在 source branch 直到 MR 创建完成

## [0.3.6] - 2026-03-09

### Fixed
- `teamai remove` 创建 MR 失败（"remote not found"）：`gfMrCreate` 调用缺少 `cwd` 参数，导致 gf CLI 在错误目录下执行

## [0.3.5] - 2026-03-09

### Fixed
- `teamai members` 读取前先 `git pull`，确保能看到远程新注册的成员
- `teamai init` 已配置 reviewer 的团队仓库，新成员加入时不再重复提示配置 reviewer

## [0.3.3] - 2026-03-09

### Fixed
- `teamai init` 新成员注册 push 失败：当团队仓库中缺少某些 `.gitkeep` 文件时，`git add` 报错导致整个 push 失败，成员注册信息无法推送到远程 (!36)

## [0.3.2] - 2026-03-09

### Added
- `teamai push`/`teamai status` 检测本地已修改的 rules，在差异扫描中标记 modified 状态 (!31)
- 新增 `src/utils/fs.ts` 文件内容比对工具函数，支持跨工具目录的内容一致性检查
- 新增 `fs-compare.test.ts`、`rules.test.ts`、`skills.test.ts`、`skip-uninstalled-tools.test.ts` 测试文件

### Fixed
- `teamai pull` 跳过未安装的 AI 工具，不再向不存在的工具目录同步资源 (!34)
- `teamai push` 扫描改为跨所有工具目录比对内容，修复时间戳比较的 timing bug (!33)
- `teamai doctor` 不再误报 Cursor hook 缺失 (!32)

### Changed
- 项目名称由 "Team AI DevKit" 更名为 "团队 AI 经验共享框架 TeamAI" (!35)

## [0.3.1] - 2026-03-08

### Added
- `teamai pull` env 变量注入改为 source 文件引用方式，避免直接修改 shell profile (!30)
- env push 改为 deferred 模式，减少不必要的 MR 创建

## [0.3.0] - 2026-03-08

### Changed
- **重构资源类型**：移除 hooks 和 instincts 资源类型，简化架构 (!26)

### Fixed
- `teamai init` 处理不存在和空仓库的场景 (!27)
- `teamai init` clone path 修复及误判仓库不存在的问题 (!28)

### Removed
- 删除 `teamai sync` 命令（不安全的双向同步） (!29)
- 删除 `src/resources/hooks-config.ts` 和 `src/resources/instincts.ts`

## [0.2.4] - 2026-03-08

### Removed
- 删除 `teamai sync` 命令：该命令在 pull 阶段会无提示覆盖本地修改，存在数据丢失风险。请分别使用 `teamai push` 和 `teamai pull`

## [0.2.3] - 2026-03-08

### Fixed
- `teamai init` clone path 不再交互确认，直接使用默认路径 `~/.teamai/team-repo`
- 修复仓库存在却误判为"不存在"的问题：git 对象统计中的 `reused 404` 被误匹配为 HTTP 404

## [0.2.2] - 2026-03-07

### Fixed
- `teamai init` 不存在的远程仓库自动创建：检测到仓库不存在时询问用户确认，通过 TGit API 自动创建
- `teamai init` 空仓库克隆兜底：克隆空仓库后目录不存在时，自动 `git init` + 配置 remote
- `pushRepoDirectly` 首次 push 设置 upstream (`git push -u origin <branch>`)，兼容 main/master 等分支名

### Added
- `gfGetOAuthToken()` 从 git credential store 提取 OAuth token
- `gfCreateRepo()` 通过 TGit REST API (Bearer auth) 创建远程仓库
- `RepoNotFoundError` 错误类型，区分"仓库不存在"和其他克隆错误
- `initRepo()` 本地 git 初始化 + 添加 remote 的工具函数
- `init.test.ts` 覆盖空仓库兜底、自动创建、用户拒绝、创建失败等场景

## [0.2.1] - 2026-03-07

### Fixed
- 修复 gf CLI 下载地址错误：改为从 `mirrors.tencent.com` 官方源下载
- 修复平台架构名称：x64/arm64（之前误用 amd64）

## [0.2.0] - 2026-03-07

### Changed
- **认证方式改造**：使用工蜂 CLI (`gf`) 替代手动 Private Token 配置
  - `teamai init` 自动安装 gf CLI 到 `~/.teamai/gf/`（无需 sudo）
  - 通过 `gf auth login` 交互式 OAuth 登录（支持 iOA、浏览器设备码、手动 Token）
  - 不再需要手动获取和配置 `TGIT_TOKEN`
- **Clone 方式改造**：使用 `gf repo clone` 替代 simple-git clone
  - gf clone 自动将 OAuth token 嵌入 remote URL，后续 git pull/push 无需额外认证
- **MR 创建改造**：使用 `gf mr create` 替代 TGit v3 REST API
  - reviewer 直接传 username，不再需要查询 user ID
  - 影响 `teamai push`、`teamai remove`、`teamai env add/remove`

### Removed
- 删除 `src/utils/tgit-api.ts`（TGit v3 REST API 客户端）及其测试文件
- 不再需要 `TGIT_TOKEN` 环境变量
- 移除手动 token 配置流程（`askSecret`、`openBrowser`、`saveTokenToEnvFile`）
- 移除 `resolveRepo` 预检查（`getProject`、`isRepoEmpty`、`fileExistsInRepo`）

### Added
- 新增 `src/utils/gf-cli.ts`：gf CLI 安装、认证、clone、MR 创建的完整封装
- `teamai doctor` 新增 gf CLI 安装和认证状态检查

## [0.1.14] - 2026-03-06

### Added
- 团队环境变量同步：新增 `env` 资源类型，支持从团队仓库 `env/env.yaml` 同步环境变量到成员的 shell 配置文件 (!23)
- `teamai env list` — 列出团队环境变量
- `teamai env add <key> <value>` — 添加/更新环境变量（通过 branch + MR 流程）
- `teamai env remove <key>` — 删除环境变量（通过 branch + MR 流程）
- `teamai pull` 自动将 env 变量注入 ~/.bashrc 或 ~/.zshrc，使用标记注释 `[teamai:env:start/end]` 实现幂等更新
- `teamai pull` 同时写入 `~/.teamai/env` 作为 KEY=VALUE 格式备份
- `teamai status` 显示 env 变量计数，`teamai list env` 显示变量详情
- `teamai doctor` 新增 shell profile env 注入检查项
- `teamai init` 创建 `env/` 目录，默认配置含 `env: { injectShellProfile: true }`
- 支持 `sharing.env.shellProfilePath` 自定义注入路径，`sharing.env.injectShellProfile: false` 禁用注入

## [0.1.13] - 2026-03-06

### Added
- `teamai pull` 输出详情：显示 skills/instincts 的新增/更新数量（如 `3 new, 29 updated`），hooks 显示实际条目数 (!20)
- TGit API `fileExistsInRepo` 辅助函数：检查远程仓库文件是否存在 (!18)

### Fixed
- `teamai --version` 从 `package.json` 动态读取版本号，不再硬编码（修复 0.1.12 版本号不一致问题）
- 修复 MR 创建时 `web_url` 返回 undefined 及 reviewer 未设置的问题（TGit v3 API 兼容） (!17)
- `teamai init` 对已有 teamai 仓库/已注册成员跳过多余确认提示 (!18, !19)
- `teamai init` 使用 `default_branch` 替代硬编码 `master` 检查远程文件 (!19)
- Session start hook 去掉 `--silent`，新会话启动时可见 pull 输出；`teamai init` 自动更新旧版 hook command (!20)
- `teamai pull` docs 目录只有 `.gitkeep` 时跳过同步，复制时过滤 dot 文件 (!20)

## [0.1.11] - 2026-03-05

### Added
- CodeBuddy IDE 支持：hooks/skills/rules 同步覆盖 CodeBuddy 工具目录 (!15)
- 分支 + MR 工作流：`teamai push` 改为创建独立分支并自动创建 Merge Request，支持 reviewer 审批 (!14)
- Tombstone 机制：已删除的资源不会被 `teamai push` 重新推送 (!12)

### Changed
- 简化成员管理：移除 readonly/write 角色系统，所有成员统一权限 (!13)

## [0.1.9] - 2026-03-05

### Added
- `teamai remove <type> <name>` 命令：从团队仓库和本地删除 skills/rules 资源 (!10)
- Cursor hooks 支持：`teamai init` 自动注入 `.cursor/hooks.json` 格式的 SessionStart hook (!9)

### Fixed
- 文档与代码对齐 (!11)

## [0.1.7] - 2026-03-05

### Added
- `teamai push` 支持推送 rules 到团队仓库 (!6)
- 成员角色管理：支持 readonly/write 角色区分 (!5)
- `teamai init --repo` 支持短格式 `owner/repo` (!1)

### Changed
- Rules 分发改为独立文件同步到各工具 rules 目录，不再内联到 CLAUDE.md (!7)

### Fixed
- `teamai init` 自动配置 git user (!4)
- TGIT_TOKEN 获取链接更新为 `/profile/account` (!2)

## [0.1.0] - 2026-03-03

### Added
- 初始发布
- `teamai init` — 初始化团队仓库关联、注册成员、注入 SessionStart hooks
- `teamai push` — 推送本地 skills 到团队仓库
- `teamai pull` — 拉取团队资源（skills、rules、hooks、docs）到本地 AI 工具目录
- `teamai sync` — 双向同步（push + pull）
- `teamai status` — 查看本地与团队仓库的差异
- `teamai list` — 列出团队资源
- `teamai members` — 列出团队成员
- `teamai doctor` — 诊断配置问题
- 支持 Claude Code、Codex、Claude Code Internal、Cursor 四种 AI 工具
- SessionStart hook 自动拉取团队最新内容