teamai-cli 0.24.0-beta.1 → 0.24.0-beta.11

package/CHANGELOG.md

@@ -11,12 +11,16 @@ All notable changes to this project will be documented in this file. See [standa
 
 ### 🐛 Bug Fixes
 
+- 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)).
 
 ### 📝 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)
 

package/README.md

@@ -13,6 +13,16 @@
 
 TeamAI manages your team's skills, rules, MCP, and knowledge across Claude Code, Codex, CodeBuddy, WorkBuddy, OpenCode, Cursor, and other AI agents.
 
+## Contributors
+
+Thanks to everyone who has contributed to TeamAI!
+
+<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).
+
 ## Quick Start
 
 ### Install
@@ -46,13 +56,13 @@ Once initialized, every AI session automatically pulls the latest skills / rules
 
 ## Product architecture
 
-**Team Execution × Team Context × Team Improvement**:
+**Team Execution × Team Context (beta) × Team Improvement (beta)**:
 
 | Layer | Job | In this CLI today |
 |-------|-----|-------------------|
 | **Team Execution** | Make every agent work the team's way | `init` / `pull` / `push`, skills, rules, agents, hooks, MCP, env |
-| **Team Context** | Make every agent understand the team | recall, learnings, codebase graph, teamwiki... |
-| **Team Improvement** | Make every execution improve the team | friction-based share-learnings, sessions, digest, dashboard... |
+| **Team Context** (beta) | Make every agent understand the team | recall, learnings, codebase graph, teamwiki... |
+| **Team Improvement** (beta) | Make every execution improve the team | friction-based share-learnings, sessions, digest, dashboard... |
 
 ## Overview
 
@@ -61,8 +71,8 @@ Once initialized, every AI session automatically pulls the latest skills / rules
     <tr>
       <th rowspan="2">Agent</th>
       <th colspan="7">Team Execution</th>
-      <th colspan="3">Team Context</th>
-      <th colspan="3">Team Improvement</th>
+      <th colspan="3">Team Context (beta)</th>
+      <th colspan="3">Team Improvement (beta)</th>
     </tr>
     <tr>
       <th>skills</th><th>rules</th><th>docs</th><th>env</th><th>agents</th><th>hooks</th><th>mcp</th>
@@ -81,6 +91,7 @@ Once initialized, every AI session automatically pulls the latest skills / rules
     <tr><td>Hermes</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td></tr>
     <tr><td>DeepSeek Harness</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td></tr>
     <tr><td>Qoder</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td></tr>
+    <tr><td>ZCode</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td></tr>
   </tbody>
 </table>
 
@@ -92,10 +103,13 @@ Team-wide settings an admin configures once and delivers to every member on `tea
 
 | Capability | Command | What it does |
 |------------|---------|--------------|
+| **Projects** | `teamai projects` | Bind a working directory to one or more logical projects so it syncs that project's skills, knowledge, and isolated learnings. Orthogonal to roles. |
 | **Roles** | `teamai roles` | Define role → namespace mappings so each member syncs only the skills for their role. |
 | **Tags** | `teamai tags` | Tag skills / rules so members subscribe to just the tags they need. |
 | **Sources** | `teamai source` | Subscribe to additional skill repos — other teams' public repos, or shared/public repos within your own org; subscribed skills sync automatically on pull. |
 
+Learnings isolation: `learnings/` at the repo root is shared with everyone; `learnings/<project-id>/` is project-private. See the [usage guide](docs/usage-guide.md#multi-project-project-as-a-dimension-orthogonal-to-role).
+
 ## Team Execution
 
 > One Team. One Harness. Every Agent.
@@ -110,74 +124,27 @@ teamai push → create branch + MR → reviewer approves + merges
               SessionStart hook → teamai pull → synced to local AI tools
 ```
 
-Members push changes via `teamai push`, which opens a Merge Request for review. Re-running `teamai push` on a resource that is still waiting in an unmerged PR updates that PR in place instead of opening a duplicate. Once merged, `teamai pull` (triggered automatically on session start via the SessionStart hook) syncs the latest resources locally. Skills sync to `~/.claude/skills/`, `~/.codex/skills/`, `~/.cursor/skills/`, `~/.codebuddy/skills/`, etc. For Codex, an existing skill under `~/.agents/skills/` is updated there instead of duplicated under `~/.codex/skills/`. In a **project-scope** install, SessionStart first creates that tool's project root (e.g. `<project>/.claude`) if it is missing, then pulls into it — a bare `teamai pull` still will not invent agent directories.
-
-### Team Hooks
-
-Declare custom hooks in `hooks/hooks.yaml` and `teamai pull` delivers them to every AI tool:
-
-```yaml
-hooks:
-  - id: block-secret
-    description: Scan for secrets before commit
-    event: PreToolUse
-    matcher: Bash
-    command: 'bash -lc "~/.teamai/team-scripts/scan-secret.sh" || true'
-    tools: [claude, cursor]
-```
-
-```bash
-teamai hooks list      # list effective hooks
-teamai hooks inject    # re-reconcile into every installed tool
-teamai hooks remove    # remove all teamai-managed hooks
-```
-
-### Team MCP Servers
-
-Declare once in `mcp/mcp.yaml`; `teamai pull` writes each tool's native config. Use `${VAR}` for secrets.
-
-```yaml
-servers:
-  - name: gpu-analysis
-    transport: http            # stdio | http | sse
-    url: https://example.com/api/mcp
-    headers:
-      Authorization: Bearer ${GPU_ANALYSIS_TOKEN}
-```
-
-```bash
-teamai mcp list | inject | remove
-```
-
-### Skill Subscription Sources
-
-Subscribe to additional skill repos — other teams' public repos, or shared/public repos within your own org:
+### What Gets Shared
 
-```bash
-teamai source add https://github.com/other-team/teamai-public.git --name other-team
-teamai source list
-teamai source browse other-team    # browse available skills
-teamai source remove other-team
-```
+Each resource is delivered to every agent:
 
-The add/remove change takes effect locally right away, and subscribed skills sync on the next
-`teamai pull`. Run `teamai push` when you want to share the `teamai.yaml` change with teammates.
+| Resource | In the team repo | Notes |
+|----------|------------------|-------|
+| **Skills** | `skills/<name>/SKILL.md` | |
+| **Rules** | `rules/*.md` | |
+| **Docs** | `docs/` | Foundational project docs; not all loaded by default (progressive disclosure) |
+| **Agents** | `agents/<name>.yaml` | |
+| **Culture** | `culture.md` | Team mission, values, and working principles — injected into each agent's CLAUDE.md / AGENTS.md so every session inherits them |
+| **CLAUDE.md** | `claudemd/*.md` | |
+| **Env** | `env/` | Shared team-level environment variables and switches; do not put secrets here |
+| **Hooks** | `hooks/hooks.yaml` | |
+| **MCP** | `mcp/mcp.yaml` | |
+| **Packages** | `teamai.yaml` | Currently npm packages and Claude Code plugins only |
+| **Models** | — | Not implemented for every provider yet |
 
-### Team Packages
+For file formats and full workflows, see the [Usage Guide](docs/usage-guide.md).
 
-Share and restore the team's npm packages and Claude Code plugins:
-
-```bash
-teamai packages install typescript
-teamai packages install typescript@5.9.2 --npm
-teamai packages install code-review@claude-plugins-official
-teamai push       # Share the declarations
-teamai packages    # Install everything declared by the team
-```
-
-See the [Usage Guide](docs/usage-guide.md#team-packages) for the complete workflow and configuration.
-
-## Team Context
+## Team Context (beta)
 
 > Every agent understands how the team works.
 
@@ -227,9 +194,13 @@ Matched: conflict | Missing: port
 teamai import --from-repo https://github.com/org/repo
 teamai import --from-org myorg              # batch import all repos
 teamai codebase --extract /path/to/repo     # local extract into teamwiki/
-teamai codebase --lint                      # health check
+teamai codebase --deep-enrich --project my-service --output /path/to/repo # generate deep knowledge docs
+teamai codebase --reconcile --output /path/to/repo # map product docs to code pages
+teamai codebase --lint --output /path/to/repo # check the locally extracted graph
 ```
 
+Extract writes `teamwiki/evidence/code/<project>/_manifest.json` even when AI enrichment is skipped or produces nothing, so `--deep-enrich` can start.
+
 The graph stores components, interfaces, configs, and cross-repo import edges. `teamai recall` uses it for graph-boosted re-ranking.
 When a recall hit comes from a codebase page, the result includes a `Sources:` line listing the relevant source file paths — giving agents a direct starting point for code changes instead of re-exploring the repo.
 
@@ -240,17 +211,27 @@ Edges come from two tracks that run together, with AST results taking precedence
 
 The WASM parser is a pure-JavaScript dependency — no native toolchain is required. If it fails to load for any reason, extraction falls back to the heuristic track and records an `AST_UNAVAILABLE` gap. Set `TEAMAI_SKIP_AST=1` to force heuristic-only extraction.
 
-## Team Improvement
+## Team Improvement (beta)
 
 > Every execution makes the entire team smarter.
 
+### Maintenance
+
+As skills and knowledge accumulate, prune what the team no longer uses. `teamai recall maintenance` archives low-confidence learnings and flags stale skills, rules, and docs for cleanup or updates:
+
+```bash
+teamai recall maintenance --prune --dry-run      # preview
+teamai recall maintenance --prune --archive      # archive unused learnings
+teamai recall maintenance --update-quality       # draft updates for stale skills / docs
+```
+
 Insight into how the team actually uses its AI tools, and a starting point for turning session friction into shared skills, rules, and knowledge:
 
 | Capability | Command | What it shows |
 |------------|---------|---------------|
-| **Usage** | `teamai digest` | Weekly team digest — token usage, conversation volume, and intervention rate. |
+| **Usage** | `teamai digest` | Weekly team digest — 7-day success, prompt, active-time, estimated cost, cache, and correction trends, plus lifetime totals. |
 | **Sessions** | `teamai session save` | Privacy-scrubbed per-session summaries (tool sequence, prompt turns, interventions) that feed the digest's Session Highlights. |
-| **Dashboard** | `teamai dashboard` | Web dashboard showing team members' live coding-session status, intervention count, and token usage. |
+| **Dashboard** | `teamai dashboard` | Web dashboard showing live sessions and local 7-day trends compared with the prior 7 days. |
 | **KB Health** | `teamai dashboard` → KB Health | Built-in dashboard page reporting knowledge-base usage & health — coverage by type, top recalled entries, silent entries, recall trend, author contributions, and a maintenance console. |
 
 ## Commands
@@ -261,7 +242,7 @@ Insight into how the team actually uses its AI tools, and a starting point for t
 | `teamai pull` | Pull team resources and inject into local AI tools |
 | `teamai push` | Push local resources to a branch and open a Merge Request |
 | `teamai packages [install] [target]` | Install declared npm packages and Claude plugins; with a target, also update `teamai.yaml`. Bare `teamai packages` installs everything; `teamai packages install <target>` adds one |
-| `teamai status` | Show local vs team repo diff |
+| `teamai status` | Show local vs team repo diff and resource counts, including namespaced skills and nested docs |
 | `teamai contribute` | Share session experience to team repo |
 | `teamai recall <query>` | Search the team knowledge base (BM25 + graph-boost) |
 | `teamai recall enable/disable/status` | Toggle or check recall state |
@@ -269,9 +250,12 @@ Insight into how the team actually uses its AI tools, and a starting point for t
 | `teamai recall maintenance` | Maintain knowledge base health: prune low-confidence learnings, writeback confidence scores, flag stale entries |
 | `teamai import` | Import knowledge (`--dir`, `--from-repo`, `--from-org`, `--from-repo-list`, `--from-mr`) |
 | `teamai codebase --extract [path]` | Extract code facts and build the local graph under `teamwiki/` |
+| `teamai codebase --deep-enrich` | Generate deep knowledge docs from extracted evidence |
+| `teamai codebase --reconcile` | Reconcile product documentation with extracted code knowledge |
 | `teamai codebase --lint` | Knowledge graph health check |
 | `teamai ci extract-mr --url <url>` | CI: extract knowledge from MR, post comments, write after merge |
 | `teamai members` | List team members |
+| `teamai projects` | Bind a working directory to one or more logical projects |
 | `teamai roles` | Manage team roles and namespaces |
 | `teamai tags` | Manage tag-based skill/rule filtering |
 | `teamai skill exclude add/remove/list` | Manage skills excluded from local sync ([usage guide](docs/usage-guide.md#excluding-skills-you-dont-need)) |
@@ -289,13 +273,3 @@ Insight into how the team actually uses its AI tools, and a starting point for t
 ## Contributing
 
 PRs are welcome! Please read [CONTRIBUTING.md](.github/CONTRIBUTING.md) first.
-
-## Contributors
-
-Thanks to everyone who has contributed to TeamAI!
-
-<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
-</a>
-
-Made with [contrib.rocks](https://contrib.rocks).

package/README.zh-CN.md

@@ -13,6 +13,16 @@
 
 TeamAI 统一管理团队的 Skills、Rules、MCP 和知识，驾驭 Claude Code、Codex、CodeBuddy、WorkBuddy、OpenCode、Cursor 等 AI Agents。
 
+## 贡献者
+
+感谢每一位为 TeamAI 贡献代码的伙伴！
+
+<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
+</a>
+
+由 [contrib.rocks](https://contrib.rocks) 生成。
+
 ## 快速开始
 
 ### 安装
@@ -46,13 +56,13 @@ teamai init https://github.com/yourorg/yourrepo --scope user
 
 ## 产品架构
 
-**Team Execution × Team Context × Team Improvement**：
+**Team Execution × Team Context (beta) × Team Improvement (beta)**：
 
 | 层 | 要解决的问题 | 当前 CLI 中的体现 |
 |----|--------------|-------------------|
 | **Team Execution** | 让每个 Agent 按团队的方式工作 | `init` / `pull` / `push`，skills、rules、agents、hooks、MCP、env |
-| **Team Context** | 让每个 Agent 理解整个团队 | recall、learnings、代码知识图谱、teamwiki... |
-| **Team Improvement** | 让每一次执行都成为团队能力的积累 | 基于摩擦信号的经验分享、sessions、digest、dashboard... |
+| **Team Context** (beta) | 让每个 Agent 理解整个团队 | recall、learnings、代码知识图谱、teamwiki... |
+| **Team Improvement** (beta) | 让每一次执行都成为团队能力的积累 | 基于摩擦信号的经验分享、sessions、digest、dashboard... |
 
 ## 功能概览
 
@@ -61,8 +71,8 @@ teamai init https://github.com/yourorg/yourrepo --scope user
     <tr>
       <th rowspan="2">Agent</th>
       <th colspan="7">Team Execution</th>
-      <th colspan="3">Team Context</th>
-      <th colspan="3">Team Improvement</th>
+      <th colspan="3">Team Context (beta)</th>
+      <th colspan="3">Team Improvement (beta)</th>
     </tr>
     <tr>
       <th>skills</th><th>rules</th><th>docs</th><th>env</th><th>agents</th><th>hooks</th><th>mcp</th>
@@ -81,6 +91,7 @@ teamai init https://github.com/yourorg/yourrepo --scope user
     <tr><td>Hermes</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td></tr>
     <tr><td>DeepSeek Harness</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td></tr>
     <tr><td>Qoder</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td></tr>
+    <tr><td>ZCode</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td></tr>
   </tbody>
 </table>
 
@@ -92,10 +103,13 @@ teamai init https://github.com/yourorg/yourrepo --scope user
 
 | 能力 | 命令 | 作用 |
 |------|------|------|
+| **项目（Projects）** | `teamai projects` | 将工作目录绑定到一个或多个逻辑项目，使其同步该项目的 skills、knowledge 以及隔离的 learnings。与角色正交。 |
 | **角色（Roles）** | `teamai roles` | 定义「角色 → 命名空间」映射，让每位成员只同步与自身角色匹配的 skills。 |
 | **标签（Tags）** | `teamai tags` | 给 skills / rules 打标签，成员只订阅自己需要的标签。 |
 | **订阅源（Sources）** | `teamai source` | 订阅额外的 skill 仓库——其他团队的公开仓库，或本团队内的公共/共享仓库；已订阅的 skills 会在 pull 时自动同步。 |
 
+learnings 隔离：仓库 `learnings/` 根目录对所有人共享；`learnings/<project-id>/` 为项目私有。详见[使用指南](docs/usage-guide.zh-CN.md#多项目project-作为与-role-正交的维度)。
+
 ## Team Execution
 
 > One Team. One Harness. Every Agent.
@@ -110,74 +124,27 @@ teamai push → 创建分支 + MR → reviewer 审批合并
            SessionStart hook → teamai pull → 同步到本地 AI 工具
 ```
 
-成员通过 `teamai push` 提交变更并创建合并请求供审核。若某个资源已在未合并的 PR 中等待评审，再次对它执行 `teamai push` 会就地更新该 PR，而非新开一个重复的 PR。合并后，`teamai pull`（由 SessionStart hook 在会话启动时自动触发）将最新资源同步到本地。Skills 会同步到 `~/.claude/skills/`、`~/.codex/skills/`、`~/.cursor/skills/`、`~/.codebuddy/skills/` 等目录。对于 Codex，若 skill 已存在于 `~/.agents/skills/`，则会在原位置更新，不会在 `~/.codex/skills/` 创建重复副本。在 **project scope** 安装下，SessionStart 会先为当前工具创建项目根目录（例如 `<project>/.claude`），再 pull 写入；单独执行 `teamai pull` 仍不会凭空创建 Agent 目录。
-
-### 团队 Hooks
-
-在 `hooks/hooks.yaml` 中声明自定义 hooks，`teamai pull` 自动分发到所有 AI 工具：
-
-```yaml
-hooks:
-  - id: block-secret
-    description: 提交前扫描密钥
-    event: PreToolUse
-    matcher: Bash
-    command: 'bash -lc "~/.teamai/team-scripts/scan-secret.sh" || true'
-    tools: [claude, cursor]
-```
-
-```bash
-teamai hooks list      # 查看生效的 hooks
-teamai hooks inject    # 重新注入到每个已安装的工具
-teamai hooks remove    # 移除所有 teamai 管理的 hooks
-```
-
-### 团队 MCP Server
-
-在 `mcp/mcp.yaml` 中声明一次，`teamai pull` 按各工具原生格式写入。密钥用 `${VAR}`。
-
-```yaml
-servers:
-  - name: gpu-analysis
-    transport: http            # stdio | http | sse
-    url: https://example.com/api/mcp
-    headers:
-      Authorization: Bearer ${GPU_ANALYSIS_TOKEN}
-```
-
-```bash
-teamai mcp list | inject | remove
-```
-
-### Skill 订阅源
-
-订阅额外的 skill 仓库——其他团队的公开仓库，或本团队内的公共/共享仓库：
+### 分发内容
 
-```bash
-teamai source add https://github.com/other-team/teamai-public.git --name other-team
-teamai source list
-teamai source browse other-team    # 浏览可用 skills
-teamai source remove other-team
-```
+每类资源分发到每个 Agent：
 
-添加/移除会立即在本机生效，订阅的 skills 会在下一次 `teamai pull` 时同步。需要将
-`teamai.yaml` 的改动分享给团队成员时，再运行 `teamai push`。
+| 资源 | 团队仓库中的位置 | 备注 |
+|------|------------------|------|
+| **Skills** | `skills/<name>/SKILL.md` | |
+| **Rules** | `rules/*.md` | |
+| **Docs** | `docs/` | 项目基础文档，默认不全量加载（渐进式披露） |
+| **Agents** | `agents/<name>.yaml` | |
+| **Culture** | `culture.md` | 团队使命、价值观与协作准则——注入各 Agent 的 CLAUDE.md / AGENTS.md，成为每次会话的行事底色 |
+| **CLAUDE.md** | `claudemd/*.md` | |
+| **Env** | `env/` | 通用环境变量、团队级开关；不建议直接放密钥 |
+| **Hooks** | `hooks/hooks.yaml` | |
+| **MCP** | `mcp/mcp.yaml` | |
+| **Packages** | `teamai.yaml` | 目前只支持 npm 包和 Claude 插件 |
+| **Models** | — | 暂时没有对全部 provider 实现 |
 
-### 团队包
+文件格式与完整工作流见[使用指南](docs/usage-guide.zh-CN.md)。
 
-共享并一键恢复团队的 npm 包和 Claude Code 插件：
-
-```bash
-teamai packages install typescript
-teamai packages install typescript@5.9.2 --npm
-teamai packages install code-review@claude-plugins-official
-teamai push       # 分享团队声明
-teamai packages    # 安装团队声明的全部包
-```
-
-完整工作流和配置见[使用指南](docs/usage-guide.zh-CN.md#团队包)。
-
-## Team Context
+## Team Context (beta)
 
 > Every agent understands how the team works.
 
@@ -227,9 +194,13 @@ Matched: conflict | Missing: port
 teamai import --from-repo https://github.com/org/repo
 teamai import --from-org myorg              # 批量导入所有仓库
 teamai codebase --extract /path/to/repo     # 本地提取到 teamwiki/
-teamai codebase --lint                      # 健康检查
+teamai codebase --deep-enrich --project my-service --output /path/to/repo # 从提取结果生成深度知识文档
+teamai codebase --reconcile --output /path/to/repo # 将产品文档映射到代码页面
+teamai codebase --lint --output /path/to/repo # 检查本地提取的图谱
 ```
 
+只要 extract 发现了组件，就会写入 `teamwiki/evidence/code/<project>/_manifest.json`（包括跳过 AI 增强或增强没有产出的情况），因此 `--deep-enrich` 可以接着跑。
+
 图谱存储组件、接口、配置和跨仓库依赖边。`teamai recall` 利用图谱进行增强排名。
 当召回命中 codebase 页面时，结果会附带一行 `Sources:`，列出相关源文件路径，供 agent 直接作为代码改动的入口，无需重新探索代码库。
 
@@ -240,17 +211,27 @@ teamai codebase --lint                      # 健康检查
 
 WASM 解析器是纯 JavaScript 依赖，无需任何原生编译工具链。若因任何原因加载失败，提取会降级到启发式轨并记录一条 `AST_UNAVAILABLE` gap。设置 `TEAMAI_SKIP_AST=1` 可强制仅使用启发式提取。
 
-## Team Improvement
+## Team Improvement (beta)
 
 > Every execution makes the entire team smarter.
 
+### Maintenance
+
+随着 skills 和知识积累，可以把团队不再使用的内容清掉。`teamai recall maintenance` 会归档低置信度 learnings，并标出过时的 skills、rules 和 docs，供清理或更新：
+
+```bash
+teamai recall maintenance --prune --dry-run      # 预览
+teamai recall maintenance --prune --archive      # 归档无用 learnings
+teamai recall maintenance --update-quality       # 为过时 skills / docs 生成更新草稿
+```
+
 洞察团队实际如何使用 AI 工具，也是把 session 中的摩擦转化为共享 Skill、Rule 和知识的起点：
 
 | 能力 | 命令 | 呈现内容 |
 |------|------|----------|
-| **用量（Usage）** | `teamai digest` | 团队周报——token 用量、会话量、干预率。 |
+| **用量（Usage）** | `teamai digest` | 团队周报——近 7 天成功率、对话、活跃时长、估算成本、缓存与纠偏趋势，以及历史累计数据。 |
 | **会话（Sessions）** | `teamai session save` | 脱敏的单会话摘要（工具序列、对话轮次、干预次数），喂给周报的 Session Highlights。 |
-| **看板（Dashboard）** | `teamai dashboard` | Web 看板，实时展示成员的编码会话状态、干预次数和 token 用量。 |
+| **看板（Dashboard）** | `teamai dashboard` | Web 看板，展示实时会话，以及本机近 7 天相对前 7 天的趋势。 |
 | **知识库健康（KB Health）** | `teamai dashboard` → KB Health | 内置于看板的报告页面，展示知识库使用情况与健康状态——各类型覆盖率、高频召回条目、沉默条目、召回趋势、作者贡献及维护控制台。 |
 
 ## 命令一览
@@ -261,7 +242,7 @@ WASM 解析器是纯 JavaScript 依赖，无需任何原生编译工具链。若
 | `teamai pull` | 拉取团队资源并注入到本地 AI 工具 |
 | `teamai push` | 推送本地资源到分支并创建合并请求 |
 | `teamai packages [install] [target]` | 安装团队 npm 包和 Claude 插件。裸 `teamai packages` 安装全部；`teamai packages install <target>` 添加单个并更新声明 |
-| `teamai status` | 显示本地与团队仓库的差异 |
+| `teamai status` | 显示本地与团队仓库的差异及资源数量，包含 namespace 下的技能和子目录中的文档 |
 | `teamai contribute` | 将 session 经验分享到团队仓库 |
 | `teamai recall <query>` | 搜索团队知识库（BM25 + 图谱增强） |
 | `teamai recall enable/disable/status` | 开关或查看 recall 状态 |
@@ -269,9 +250,12 @@ WASM 解析器是纯 JavaScript 依赖，无需任何原生编译工具链。若
 | `teamai recall maintenance` | 维护知识库健康：清理低置信度 learnings、回写置信度、标记过时条目 |
 | `teamai import` | 导入知识（`--dir`、`--from-repo`、`--from-org`、`--from-repo-list`、`--from-mr`） |
 | `teamai codebase --extract [path]` | 提取代码事实并在 `teamwiki/` 下构建本地图谱 |
+| `teamai codebase --deep-enrich` | 从已提取的 evidence 生成深度知识文档 |
+| `teamai codebase --reconcile` | 将产品文档与提取的代码知识进行对账 |
 | `teamai codebase --lint` | 知识图谱健康检查 |
 | `teamai ci extract-mr --url <url>` | CI：从 MR 提取知识、发评论、合并后写入 |
 | `teamai members` | 查看团队成员 |
+| `teamai projects` | 将工作目录绑定到一个或多个逻辑项目 |
 | `teamai roles` | 管理团队角色和命名空间 |
 | `teamai tags` | 管理基于标签的 skill/rule 过滤 |
 | `teamai skill exclude add/remove/list` | 管理不参与本地同步的 skills（[使用指南](docs/usage-guide.zh-CN.md#排除个人不需要的-skill)） |
@@ -289,13 +273,3 @@ WASM 解析器是纯 JavaScript 依赖，无需任何原生编译工具链。若
 ## 贡献
 
 欢迎提交 PR！请先阅读 [CONTRIBUTING.md](.github/CONTRIBUTING.md)。
-
-## 贡献者
-
-感谢每一位为 TeamAI 贡献代码的伙伴！
-
-<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
-</a>
-
-由 [contrib.rocks](https://contrib.rocks) 生成。