docs: slim README to a landing page and move product details out (#722)

Keep README as title, Why TeamAI, quick start, docs links, contributors, and contributing. Move architecture and capability details into product-overview, and the command table into the usage guide.
2026-10-02 03:14:40 +08:00 · 2026-09-22 16:37:56 +08:00
parent 3735a4672d
commit ff0d30c19c
11 changed files with 580 additions and 1135 deletions
@@ -23,15 +23,11 @@

 TeamAI は個人の AI 能力をチーム共有の能力へと変え、Agent・マシン・メンバーをまたいで活用できるようにします。

-## コントリビューター
+## なぜ TeamAI なのか

-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) で生成しています。
+<p align="center">
+  <img src="assets/use-cases.png" alt="8 つの日常シーン：TeamAI 導入前と導入後" width="100%">
+</p>

 ## クイックスタート

@@ -52,10 +48,12 @@ TeamAI をセットアップしたら、AI ツールで `/teamai` skill に話
 **チームに参加**

 ```text
-/teamai チームの TeamAI に参加したい、リポジトリ URL は https://github.com/yourorg/yourrepo
+/teamai チームの TeamAI に参加したい、リポジトリ URL は https://github.com/your-org/your-repo
 ```

-**skill をチームに共有**
+**チームに共有する**
+
+Skills、Rules、MCP など、Agent が使えるリソースはすべて共有できます:

 ```text
 /teamai xxx skill をチームに共有して
@@ -68,7 +66,7 @@ TeamAI をセットアップしたら、AI ツールで `/teamai` skill に話
 ```

 <details>
-<summary>コマンドラインの方が好みですか？（手動セットアップ）</summary>
+<summary>コマンドラインでインストール</summary>

 ### インストール

@@ -78,7 +76,7 @@ npm install -g teamai-cli

 ### チーム管理者 / 個人利用

-Git ホスト（GitHub、GitLab、GitCode、CNB、TGit、またはプライベート Git サービス）に共有リポジトリを作成し、**チームメンバーに書き込み権限を付与**してから、`teamai init https://github.com/yourorg/yourrepo` を実行します。
+Git ホスト（GitHub、GitLab、GitCode、CNB、TGit、またはプライベート Git サービス）に共有リポジトリを作成し、**チームメンバーに書き込み権限を付与**してから、`teamai init https://github.com/your-org/your-repo` を実行します。

 > **まだチームリポジトリがない場合は？** 本番向けの skills、rules、review agents が入ったテンプレートから始められます。[teamai-hub](https://github.com/teamai-hub) org を開き、**Fork** してから、新しいリポジトリに対して `teamai init` を実行してください。

@@ -89,237 +87,38 @@ Git ホスト（GitHub、GitLab、GitCode、CNB、TGit、またはプライベ

 # Project-scope init (default, resources installed under the project directory)
 cd /path/to/my-project
-teamai init https://github.com/yourorg/yourrepo
+teamai init https://github.com/your-org/your-repo

 # Or, user-scope init (resources installed under ~/)
-teamai init https://github.com/yourorg/yourrepo --scope user
+teamai init https://github.com/your-org/your-repo --scope user
 ```

 初期化後は、管理者が公開した最新の skills / rules などの Harness 更新が、AI セッション開始時に自動で取り込まれます。手動同期は不要です。

 </details>

-> **完全な利用ガイド:** [docs/usage-guide.md](docs/usage-guide.md)（[中文版](docs/usage-guide.zh-CN.md)）— チーム作成から日常利用までをカバーします。
+## 詳細情報

-## プロダクトアーキテクチャ
+- [Usage Guide](docs/usage-guide.md) — setup, onboarding, daily workflows, and commands
+- [Product Overview](docs/product-overview.md) — architecture, capabilities, and agent support
+- [Git Providers](docs/providers.md) — supported repository providers
+- [Windows Setup](docs/windows-hooks.md) — hooks and shell configuration
+- [Technical Designs](docs/designs/) — design documents and proposals

-**Team Execution × Team Context (beta) × Team Improvement (beta)**:
+## コントリビューター

-| レイヤー | 役割 | 本 CLI での現状 |
-|----------|------|-----------------|
-| **Team Execution** | どの Agent もチームのやり方で動かす | `init` / `pull` / `push`、skills、rules、agents、hooks、MCP、env |
-| **Team Context** (beta) | どの Agent もチームを理解する | recall、learnings、codebase graph、teamwiki... |
-| **Team Improvement** (beta) | 毎回の実行がチームを強くする | 摩擦ベースの share-learnings、sessions、digest、dashboard... |
+TeamAI に貢献してくださったみなさんに感謝します。

-## 概要
+<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
+</a>

-<table>
-  <thead>
-    <tr>
-      <th rowspan="2">Agent</th>
-      <th colspan="7">Team Execution</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>
-      <th>learnings</th><th>codebase</th><th>teamwiki</th>
-      <th>usage</th><th>sessions</th><th>dashboard</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr><td>Claude Code</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>Codex</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>Cursor</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>GitHub Copilot CLI</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>CodeBuddy</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>WorkBuddy</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>OpenCode</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>OpenClaw</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>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>Kiro</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>
-    <tr><td>Oh My Pi</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>
+[contrib.rocks](https://contrib.rocks) で生成しています。

-**Git プロバイダー** — GitHub · GitLab · GitCode · CNB · TGit · プライベート Git サービス。
+## コントリビュート

-### 配布コントロール
-
-管理者が一度設定すれば、`teamai pull` 時に全メンバーへ届くチーム共通の設定です。
-
-| 機能 | コマンド | 内容 |
-|------|----------|------|
-| **Projects** | `teamai projects` | 作業ディレクトリを 1 つ以上の論理プロジェクトに紐づけ、そのプロジェクトの skills、ナレッジ、隔離された learnings を同期します。Roles とは直交します。 |
-| **Roles** | `teamai roles` | ロール → 名前空間の対応を定義し、各メンバーが自分のロール向け skills だけを同期するようにします。 |
-| **Tags** | `teamai tags` | skills / rules にタグを付け、メンバーは必要なタグだけを購読します。 |
-| **Sources** | `teamai source` | 追加の skill リポジトリを購読します。他チームの公開リポジトリや、自組織内の共有/公開リポジトリが対象です。購読した skills は pull 時に自動同期されます。 |
-
-learnings の隔離: リポジトリ直下の `learnings/` は全員で共有、`learnings/<project-id>/` はプロジェクト専用です。詳細は [usage guide](docs/usage-guide.md#multi-project-project-as-a-dimension-orthogonal-to-role) を参照してください。
-
-## Team Execution
-
-> One Team. One Harness. Every Agent.
-
-TeamAI は skills、rules、docs、hooks を共有 Git リポジトリに置き、「push → レビューしてマージ → pull」の流れで各メンバーのローカル AI ツールへ配布します。他チームや共有リポジトリの Harness 購読にも対応します。
-
-### 仕組み
-
-```
-teamai push → create branch + MR → reviewer approves + merges
-                                         ↓
-              SessionStart hook → teamai pull → synced to local AI tools
-```
-
-### 共有されるもの
-
-各リソースはすべての Agent に届けられます。
-
-| リソース | チームリポジトリ内 | 備考 |
-|----------|-------------------|------|
-| **Skills** | `skills/<name>/SKILL.md` | |
-| **Rules** | `rules/*.md` | |
-| **Docs** | `docs/` | プロジェクトの基礎ドキュメント。デフォルトでは全件読み込みません（progressive disclosure） |
-| **Agents** | `agents/<name>.yaml` | |
-| **Culture** | `culture.md` | チームのミッション、価値観、働き方の原則。各 Agent の CLAUDE.md / AGENTS.md に注入され、すべてのセッションに引き継がれます |
-| **CLAUDE.md** | `claudemd/*.md` | |
-| **Env** | `env/` | チーム共通の環境変数とスイッチ。secrets は置かないでください |
-| **Hooks** | `hooks/hooks.yaml` | 各 hook に `roles:` を付け、該当ロールを持つメンバーにだけ届けることができます |
-| **MCP** | `mcp/mcp.yaml` | 各 server に `roles:` を付け、該当ロールを持つメンバーにだけ届けることができます |
-| **Packages** | `teamai.yaml` | 現時点では npm パッケージと Claude Code plugins のみ |
-| **Models** | — | まだすべての provider には未対応です |
-
-ファイル形式と一連のワークフローは [Usage Guide](docs/usage-guide.md) を参照してください。
-
-## Team Context (beta)
-
-> Every agent understands how the team works.
-
-Harness の配布に加え、TeamAI は蓄積したチーム経験とコード構造を検索可能なナレッジベースに整理し、必要に応じて AI が自動で recall します。
-
-### 経験の自動共有
-
-セッション終了時、Stop hook は **friction**（摩擦）でスコアします。これは「覚えておく価値がある」兆候です。AI を中断・訂正した、ツール呼び出しを拒否した、失敗したツールを AI が何度も再試行した、などです。長くても順調なセッション（ツール呼び出しは多いが摩擦がない）では発火しません。本当に問題と向き合ったセッションだけが対象です。スコアが十分高いと、AI は次のように提案します。
-
-```
-[teamai] This session may contain a problem worth documenting: you interrupted the AI twice, the AI retried failing tools 8 times.
-
-Task: Fix duplicate project-level Hook injection
-
-Consider running /teamai-share-learnings to summarize what you learned and share it with your team.
-```
-
-ヒントには、発火のきっかけになった非ゼロの friction シグナルが入ります。取得できる場合は、最初のタスクをマスクした 1 行要約も付きます。`/teamai-share-learnings` skill はセッションを要約し、learning ドキュメントをチームリポジトリへ直接 push します。各セッションへの提示は最大 1 回です。チームは `teamai.yaml` の `sharing.contributeHint.enabled: false` でヒントだけをオフにできます（メンバー側はローカル設定の `contributeHintEnabled`）。Stop hook のほかの処理はそのまま残ります。
-
-### Team Knowledge Recall
-
-タスクの前に、蓄積したチームナレッジを AI が自動検索できるようにします。この機能は **デフォルトオフ** で、明示的に有効化する必要があります。チームは `teamai.yaml` で `sharing.recall.enabled: true` をデフォルトにでき、メンバーはローカルで上書きできます。
-
-```bash
-teamai recall enable     # on: deploy the teamai-recall subagent + inject guidance rules
-teamai recall disable    # off: remove the subagent and rules
-teamai recall status     # show effective state (team default + user override)
-```
-
-**検索は subagent 経由**です。有効化後、`teamai pull` は組み込みの `teamai-recall` subagent を各 AI ツールの `agents/` に配備します。AI はタスク前にこれを呼び出します。subagent がキーワードを抽出し、検索を実行し、ヒットしたソースファイルを読んで、チームナレッジの構造化サマリーを返します。先に関連性の事前チェック（`teamai recall --check`）を行い、タスクがチームナレッジと無関係なら検索自体をスキップします。内部では `teamai recall` コマンドをシェル実行しており、手動でも同じコマンドを使えます。
-
-```bash
-$ teamai recall "port conflict"
-[1/2] MR review caught a port-conflict bug ★1 [user]
-Author: member-a | Score: 18.5 | Tags: troubleshooting, networking
-
-[2/2] Deployment configuration best practices [project]
-Author: member-b | Score: 12.0 | Tags: deploy, config
-Matched: conflict | Missing: port
-```
-
-### Codebase Knowledge Graph
-
-`teamai import` はソースリポジトリを解析し、`teamwiki/` 配下の構造化グラフにします。構造を意識した検索が可能になります。
-
-```bash
-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 --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 は、AI enrichment をスキップした場合や成果が空でも、`teamwiki/evidence/code/<project>/_manifest.json` を書き出すので、`--deep-enrich` から始められます。
-
-グラフにはコンポーネント、インターフェース、設定、リポジトリ間の import エッジが入ります。`teamai recall` はこれを graph-boost の再ランキングに使います。
-recall のヒットが codebase ページ由来のときは、結果に関連ソースパスを列挙する `Sources:` 行が付きます。Agent はリポジトリを最初から探索し直さず、コード変更の起点にできます。
-
-エッジは 2 本のトラックが同時に走り、重複時は AST 側が優先されます。
-
- **AST track**（TypeScript/JavaScript、Python、Go）: WASM の [tree-sitter](https://tree-sitter.github.io/) パーサーが `import`/`require`、呼び出し箇所、TS の `implements` 句を、ファイル間の正確な `DEPENDS_ON` / `REFERENCES` / `IMPLEMENTS` エッジに解決します（タグは `code-ast`、信頼度の重み付き）。
- **Heuristic track**（Java/Rust を含む全言語）: 正規表現ベースの抽出（タグは `code-heuristic`）。AST track が対象にしない言語もカバーします。
-
-WASM パーサーは純粋な JavaScript 依存で、ネイティブのツールチェーンは不要です。何らかの理由で読み込めない場合、抽出は heuristic track にフォールバックし、`AST_UNAVAILABLE` の gap を記録します。`TEAMAI_SKIP_AST=1` を設定すると、heuristic のみの抽出を強制できます。
-
-## 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      # preview
-teamai recall maintenance --prune --archive      # archive unused learnings
-teamai recall maintenance --update-quality       # draft updates for stale skills / docs
-```
-
-チームが AI ツールを実際にどう使っているかの洞察と、セッションの摩擦を共有の skills、rules、ナレッジへ変える出発点です。
-
-| 機能 | コマンド | 表示内容 |
-|------|----------|----------|
-| **Usage** | `teamai digest` | チームの週次 digest — 直近 7 日の成功率、prompt、アクティブ時間、推定コスト、cache、訂正の傾向と、累計値。 |
-| **Sessions** | `teamai session save` | プライバシーを除去したセッション要約（ツール列、prompt ターン、介入）。digest の Session Highlights の入力になります。 |
-| **Dashboard** | `teamai dashboard` | Overview / Team Execution / Team Context / Team Improvement を統合。本機のライブセッション、7 日間の傾向、セッション当たり推定コスト、英語/簡体字中国語、ライト/ダーク/システムテーマに対応。 |
-| **KB Health** | `teamai dashboard` → Team Context / Team Improvement | 組み込みの dashboard ページ。ナレッジベースの利用と健全性（タイプ別カバレッジ、よく recall されるエントリ、沈黙エントリ、recall トレンド、作者の貢献、メンテナンスコンソール）を報告します。 |
-
-## コマンド
-
-| コマンド | 説明 |
-|----------|------|
-| `teamai init` | 初期化: OAuth ログイン、リポジトリ連携、メンバー登録、hooks 注入 |
-| `teamai pull` | チームリソースを取得し、ローカル AI ツールへ注入 |
-| `teamai push` | ローカルリソースをブランチへ push し、Merge Request を開く |
-| `teamai packages [install] [target]` | 宣言済みの npm パッケージと Claude plugins をインストール。target 指定時は `teamai.yaml` も更新。引数なしの `teamai packages` はすべてインストール、`teamai packages install <target>` は 1 件追加 |
-| `teamai status` | ローカルとチームリポジトリの差分とリソース件数を表示。名前空間付き skills と入れ子の docs も含む |
-| `teamai contribute` | セッション経験をチームリポジトリの `teamai-learnings` ブランチへ共有 |
-| `teamai recall <query>` | チームナレッジベースを検索（BM25 + graph-boost） |
-| `teamai recall enable/disable/status` | recall のオン/オフ、または状態確認 |
-| `teamai recall promote [learningId]` | 信頼度の高い learning を正式ナレッジ（skills/rules/docs）へ昇格 |
-| `teamai recall maintenance` | ナレッジベースの健全性を維持: 低信頼度 learnings の整理、信頼度スコアの書き戻し、古いエントリの印付け |
-| `teamai import` | ナレッジを 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` | Knowledge graph の健全性チェック |
-| `teamai ci extract-mr --url <url>` | CI: MR からナレッジを抽出、コメント投稿、マージ後に書き込み |
-| `teamai members` | チームメンバー一覧 |
-| `teamai projects` | 作業ディレクトリを 1 つ以上の論理プロジェクトに紐づけ |
-| `teamai roles` | チームの roles と名前空間を管理 |
-| `teamai tags` | タグベースの skill/rule フィルタを管理 |
-| `teamai skill exclude add/remove/list` | ローカル同期から除外する skills を管理（[usage guide](docs/usage-guide.md#excluding-skills-you-dont-need)） |
-| `teamai source` | skill 購読ソースを管理（他チーム、または自組織の共有リポジトリ） |
-| `teamai remove <type> <name>` | リソースを削除し、MR を開く |
-| `teamai session save` | プライバシー除去済みのセッション要約を月次ログへ記録（`--push` は `digest` へ供給） |
-| `teamai digest` | チーム利用の週次 digest を生成 |
-| `teamai doctor` | 設定の問題を診断（`--json` で JSON 出力、CI・hook・agent 向け）|
-| `teamai uninstall` | すべての teamai リソースと hooks を削除 |
+コミュニティでの交流、Issue、PR を歓迎します。開発の進め方は [CONTRIBUTING.md](.github/CONTRIBUTING.md) を参照してください。

 ## ライセンス

 [MIT](LICENSE)
-
-## コントリビュート
-
-PR を歓迎します。先に [CONTRIBUTING.md](.github/CONTRIBUTING.md) を読んでください。
@@ -23,15 +23,11 @@

 TeamAI는 개인의 AI 역량을 팀 공동의 역량으로 바꾸고, 여러 Agent와 기기, 팀원 전반에서 활용할 수 있게 합니다.

-## 기여자
+## 왜 TeamAI인가

-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)로 생성했습니다.
+<p align="center">
+  <img src="assets/use-cases.png" alt="일상적인 8가지 상황: TeamAI 도입 전과 후" width="100%">
+</p>

 ## 빠른 시작

@@ -52,10 +48,12 @@ TeamAI를 설정한 뒤에는 AI 도구에서 `/teamai` skill에게 말만 걸
 **팀 참여**

 ```text
-/teamai 우리 팀의 TeamAI에 참여하고 싶어, 저장소 URL은 https://github.com/yourorg/yourrepo
+/teamai 우리 팀의 TeamAI에 참여하고 싶어, 저장소 URL은 https://github.com/your-org/your-repo
 ```

-**skill을 팀에 공유**
+**팀에 공유하기**
+
+Skills, Rules, MCP 등 Agent가 사용할 수 있는 리소스는 모두 공유할 수 있습니다:

 ```text
 /teamai xxx skill을 팀에 공유해줘
@@ -68,7 +66,7 @@ TeamAI를 설정한 뒤에는 AI 도구에서 `/teamai` skill에게 말만 걸
 ```

 <details>
-<summary>명령줄이 더 편한가요? (수동 설치)</summary>
+<summary>명령줄 설치</summary>

 ### 설치

@@ -78,7 +76,7 @@ npm install -g teamai-cli

 ### 팀 관리자 / 개인 사용자

-Git 호스트(GitHub, GitLab, GitCode, CNB, TGit 또는 비공개 Git 서비스)에 공유 경험 저장소를 만들고, **팀원에게 쓰기 권한을 부여한 뒤** `teamai init https://github.com/yourorg/yourrepo`를 실행하세요.
+Git 호스트(GitHub, GitLab, GitCode, CNB, TGit 또는 비공개 Git 서비스)에 공유 경험 저장소를 만들고, **팀원에게 쓰기 권한을 부여한 뒤** `teamai init https://github.com/your-org/your-repo`를 실행하세요.

 > **아직 팀 저장소가 없나요?** 프로덕션에 바로 쓸 수 있는 Skills, Rules, review agents가 미리 들어 있는 템플릿으로 시작하세요. [teamai-hub](https://github.com/teamai-hub) org를 둘러본 뒤 **Fork**하고, 새로 만든 저장소에 `teamai init`을 실행하면 됩니다.

@@ -89,237 +87,38 @@ Git 호스트(GitHub, GitLab, GitCode, CNB, TGit 또는 비공개 Git 서비스)

 # Project-scope init (default, resources installed under the project directory)
 cd /path/to/my-project
-teamai init https://github.com/yourorg/yourrepo
+teamai init https://github.com/your-org/your-repo

 # Or, user-scope init (resources installed under ~/)
-teamai init https://github.com/yourorg/yourrepo --scope user
+teamai init https://github.com/your-org/your-repo --scope user
 ```

 초기화가 끝나면 관리자가 배포한 최신 Skills / Rules 및 기타 Harness 업데이트가 매 AI 세션에서 자동으로 반영됩니다. 수동 동기화는 필요 없습니다.

 </details>

-> **전체 사용 가이드:** [docs/usage-guide.md](docs/usage-guide.md) ([中文版](docs/usage-guide.zh-CN.md)) — 팀 생성부터 일상 사용까지 모두 다룹니다.
+## 자세히 알아보기

-## 제품 아키텍처
+- [Usage Guide](docs/usage-guide.md) — setup, onboarding, daily workflows, and commands
+- [Product Overview](docs/product-overview.md) — architecture, capabilities, and agent support
+- [Git Providers](docs/providers.md) — supported repository providers
+- [Windows Setup](docs/windows-hooks.md) — hooks and shell configuration
+- [Technical Designs](docs/designs/) — design documents and proposals

-**Team Execution × Team Context (beta) × Team Improvement (beta)**:
+## 기여자

-| 계층 | 역할 | 현재 CLI에서 |
-|-------|-----|-------------------|
-| **Team Execution** | 모든 Agent가 팀의 방식대로 일하게 합니다 | `init` / `pull` / `push`, skills, rules, agents, hooks, MCP, env |
-| **Team Context** (beta) | 모든 Agent가 팀을 이해하게 합니다 | recall, learnings, codebase graph, teamwiki... |
-| **Team Improvement** (beta) | 모든 실행이 팀을 더 강하게 만듭니다 | 마찰 기반 share-learnings, sessions, digest, dashboard... |
+TeamAI에 기여해 주신 모든 분께 감사합니다!

-## 개요
+<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
+</a>

-<table>
-  <thead>
-    <tr>
-      <th rowspan="2">Agent</th>
-      <th colspan="7">Team Execution</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>
-      <th>learnings</th><th>codebase</th><th>teamwiki</th>
-      <th>usage</th><th>sessions</th><th>dashboard</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr><td>Claude Code</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>Codex</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>Cursor</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>GitHub Copilot CLI</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>CodeBuddy</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>WorkBuddy</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>OpenCode</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>OpenClaw</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>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>Kiro</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>
-    <tr><td>Oh My Pi</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>
+[contrib.rocks](https://contrib.rocks)로 생성했습니다.

-**Git providers** — GitHub · GitLab · GitCode · CNB · TGit · 비공개 Git 서비스.
+## 기여하기

-### 배포 제어
-
-관리자가 한 번 설정하면 `teamai pull` 때 모든 멤버에게 전달되는 팀 전역 설정입니다.
-
-| 기능 | 명령 | 하는 일 |
-|------------|---------|--------------|
-| **Projects** | `teamai projects` | 작업 디렉터리를 하나 이상의 논리 프로젝트에 묶어, 해당 프로젝트의 Skills, 지식, 격리된 learnings를 동기화합니다. Roles와는 별개의 차원입니다. |
-| **Roles** | `teamai roles` | role → namespace 매핑을 정의해, 각 멤버가 자신의 role에 해당하는 Skills만 동기화하게 합니다. |
-| **Tags** | `teamai tags` | Skills / Rules에 태그를 달아, 멤버가 필요한 태그만 구독하게 합니다. |
-| **Sources** | `teamai source` | 추가 skill 저장소를 구독합니다 — 다른 팀의 공개 저장소, 또는 우리 org 안의 공유/공개 저장소. 구독한 Skills는 pull 때 자동 동기화됩니다. |
-
-Learnings 격리: 저장소 루트의 `learnings/`는 전원과 공유되고, `learnings/<project-id>/`는 프로젝트 전용입니다. [usage guide](docs/usage-guide.md#multi-project-project-as-a-dimension-orthogonal-to-role)를 참고하세요.
-
-## Team Execution
-
-> One Team. One Harness. Every Agent.
-
-TeamAI는 Skills, Rules, docs, hooks를 공유 Git 저장소에 두고, "push → review & merge → pull" 흐름으로 각 멤버의 로컬 AI 도구에 배포합니다. 다른 팀이나 공유 저장소의 Harness 구독도 지원합니다.
-
-### 작동 방식
-
-```
-teamai push → create branch + MR → reviewer approves + merges
-                                         ↓
-              SessionStart hook → teamai pull → synced to local AI tools
-```
-
-### 공유되는 항목
-
-각 리소스는 모든 Agent에 전달됩니다.
-
-| 리소스 | 팀 저장소 위치 | 참고 |
-|----------|------------------|-------|
-| **Skills** | `skills/<name>/SKILL.md` | |
-| **Rules** | `rules/*.md` | |
-| **Docs** | `docs/` | 프로젝트 기반 문서. 기본값으로 전부 로드되지는 않습니다(progressive disclosure) |
-| **Agents** | `agents/<name>.yaml` | |
-| **Culture** | `culture.md` | 팀의 미션, 가치, 일하는 원칙 — 각 Agent의 CLAUDE.md / AGENTS.md에 주입되어 모든 세션이 이를 이어받습니다 |
-| **CLAUDE.md** | `claudemd/*.md` | |
-| **Env** | `env/` | 팀 단위 공유 환경 변수와 스위치. 시크릿은 넣지 마세요 |
-| **Hooks** | `hooks/hooks.yaml` | 각 hook에 `roles:`를 달면 해당 role을 가진 멤버에게만 전달됩니다 |
-| **MCP** | `mcp/mcp.yaml` | 각 server에 `roles:`를 달면 해당 role을 가진 멤버에게만 전달됩니다 |
-| **Packages** | `teamai.yaml` | 현재는 npm 패키지와 Claude Code 플러그인만 지원 |
-| **Models** | — | 아직 모든 provider에 구현되지 않았습니다 |
-
-파일 형식과 전체 워크플로는 [Usage Guide](docs/usage-guide.md)를 참고하세요.
-
-## Team Context (beta)
-
-> Every agent understands how the team works.
-
-Harness를 배포하는 것을 넘어, TeamAI는 쌓인 팀 경험과 코드 구조를 검색 가능한 지식 베이스로 정리하고, AI가 필요할 때 자동으로 불러오게 합니다.
-
-### 경험 자동 공유
-
-세션이 끝나면 Stop hook이 **friction**(마찰)으로 점수를 매깁니다. 세션에서 기억할 만한 일이 있었음을 나타내는 신호입니다. 예를 들어 AI를 중단하거나 고쳤거나, 도구 호출을 거절했거나, AI가 실패한 도구를 여러 번 재시도한 경우입니다. 도구 호출은 많지만 마찰이 없는 길고 평범한 세션은 트리거되지 않고, 실제로 문제를 붙잡고 씨름한 세션만 해당합니다. 점수가 충분하면 AI가 이렇게 제안합니다.
-
-```
-[teamai] This session may contain a problem worth documenting: you interrupted the AI twice, the AI retried failing tools 8 times.
-
-Task: Fix duplicate project-level Hook injection
-
-Consider running /teamai-share-learnings to summarize what you learned and share it with your team.
-```
-
-힌트에는 트리거가 된 0이 아닌 friction 신호가 나오고, 가능하면 첫 번째 작업을 마스킹한 한 줄 요약도 붙습니다. `/teamai-share-learnings` skill은 세션을 요약해 learning 문서를 팀 저장소에 바로 push합니다. 세션당 힌트는 최대 한 번입니다. 팀은 `teamai.yaml`에서 `sharing.contributeHint.enabled: false`로 힌트만 끌 수 있고(멤버는 로컬 설정의 `contributeHintEnabled`), Stop hook의 나머지 기능은 그대로 둡니다.
-
-### 팀 지식 Recall
-
-작업 전에 AI가 쌓인 팀 지식을 자동으로 검색하게 합니다. 이 기능은 **기본값이 꺼짐**이며, 명시적으로 켜야 합니다. 팀은 `teamai.yaml`에서 `sharing.recall.enabled: true`를 기본값으로 둘 수 있고, 멤버는 로컬에서 덮어쓸 수 있습니다.
-
-```bash
-teamai recall enable     # on: deploy the teamai-recall subagent + inject guidance rules
-teamai recall disable    # off: remove the subagent and rules
-teamai recall status     # show effective state (team default + user override)
-```
-
-**검색은 subagent로 실행됩니다**: 켜면 `teamai pull`이 내장 `teamai-recall` subagent를 각 AI 도구의 `agents/` 디렉터리에 배포합니다. AI는 작업 전에 이를 호출하고, subagent가 키워드를 뽑고, 검색을 돌리고, 맞은 원본 파일을 읽은 뒤 팀 지식의 구조화된 요약을 돌려줍니다. subagent는 먼저 관련성 사전 검사(`teamai recall --check`)를 하고, 작업이 팀 지식과 무관하면 검색을 아예 건너뜁니다. 내부적으로는 `teamai recall` 명령을 호출하며, 직접 실행할 수도 있습니다.
-
-```bash
-$ teamai recall "port conflict"
-[1/2] MR review caught a port-conflict bug ★1 [user]
-Author: member-a | Score: 18.5 | Tags: troubleshooting, networking
-
-[2/2] Deployment configuration best practices [project]
-Author: member-b | Score: 12.0 | Tags: deploy, config
-Matched: conflict | Missing: port
-```
-
-### 코드베이스 지식 그래프
-
-`teamai import`는 소스 저장소를 `teamwiki/` 아래의 구조화된 그래프로 파싱해, 구조를 아는 검색을 가능하게 합니다.
-
-```bash
-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 --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는 AI enrichment를 건너뛰거나 결과가 없어도 `teamwiki/evidence/code/<project>/_manifest.json`을 쓰므로 `--deep-enrich`를 이어서 시작할 수 있습니다.
-
-그래프는 컴포넌트, 인터페이스, 설정, 저장소 간 import 엣지를 저장합니다. `teamai recall`은 이를 그래프 부스팅 재랭킹에 사용합니다.
-recall 결과가 codebase 페이지에서 온 경우, 결과에는 관련 소스 파일 경로를 나열하는 `Sources:` 줄이 포함됩니다. Agent가 저장소를 다시 탐색하지 않고 코드 변경의 출발점을 바로 잡을 수 있습니다.
-
-엣지는 함께 도는 두 트랙에서 나오며, 겹치면 AST 결과가 우선합니다.
-
- **AST track** (TypeScript/JavaScript, Python, Go): WASM [tree-sitter](https://tree-sitter.github.io/) 파서가 `import`/`require`, 호출 지점, TS `implements` 절을 파일 간 정확한 `DEPENDS_ON` / `REFERENCES` / `IMPLEMENTS` 엣지로 해석합니다(`code-ast` 태그, confidence 가중치).
- **Heuristic track** (Java/Rust를 포함한 모든 언어): 정규식 기반 추출(`code-heuristic` 태그). AST track이 다루지 않는 언어도 커버합니다.
-
-WASM 파서는 순수 JavaScript 의존성이라 네이티브 툴체인이 필요 없습니다. 어떤 이유로든 로드에 실패하면 추출은 heuristic track으로 떨어지고 `AST_UNAVAILABLE` gap을 기록합니다. `TEAMAI_SKIP_AST=1`을 설정하면 heuristic 전용 추출을 강제합니다.
-
-## 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      # preview
-teamai recall maintenance --prune --archive      # archive unused learnings
-teamai recall maintenance --update-quality       # draft updates for stale skills / docs
-```
-
-팀이 AI 도구를 실제로 어떻게 쓰는지 보고, 세션 friction을 공유 Skills, Rules, 지식으로 바꾸는 출발점입니다.
-
-| 기능 | 명령 | 보여주는 것 |
-|------------|---------|---------------|
-| **Usage** | `teamai digest` | 주간 팀 digest — 7일간의 성공률, prompt, 활성 시간, 추정 비용, cache, 수정 추세와 누적 합계. |
-| **Sessions** | `teamai session save` | 개인정보를 제거한 세션별 요약(도구 순서, prompt 턴, 개입)으로 digest의 Session Highlights에 들어갑니다. |
-| **Dashboard** | `teamai dashboard` | Overview / Team Execution / Team Context / Team Improvement 통합 화면. 로컬 실시간 세션, 7일 추세, 세션당 예상 비용, 영어/중국어 간체 및 밝게/어둡게/시스템 테마를 지원합니다. |
-| **KB Health** | `teamai dashboard` → Team Context / Team Improvement | 지식 베이스 사용량과 건강 상태를 보여주는 내장 dashboard 페이지 — 유형별 커버리지, 상위 recall 항목, 침묵 항목, recall 추세, 작성자 기여, maintenance 콘솔. |
-
-## 명령어
-
-| 명령 | 설명 |
-|---------|-------------|
-| `teamai init` | 초기화: OAuth 로그인, 저장소 연결, 멤버 등록, hooks 주입 |
-| `teamai pull` | 팀 리소스를 가져와 로컬 AI 도구에 주입 |
-| `teamai push` | 로컬 리소스를 브랜치에 push하고 Merge Request를 엽니다 |
-| `teamai packages [install] [target]` | 선언된 npm 패키지와 Claude 플러그인을 설치합니다. target이 있으면 `teamai.yaml`도 갱신합니다. 인자 없는 `teamai packages`는 전부를 설치하고, `teamai packages install <target>`은 하나를 추가합니다 |
-| `teamai status` | 로컬과 팀 저장소의 diff 및 리소스 개수(네임스페이스 Skills, 중첩 docs 포함)를 표시 |
-| `teamai contribute` | 세션 경험을 팀 저장소의 `teamai-learnings` 브랜치에 공유 |
-| `teamai recall <query>` | 팀 지식 베이스 검색 (BM25 + graph-boost) |
-| `teamai recall enable/disable/status` | recall 상태를 켜거나 끄거나 확인 |
-| `teamai recall promote [learningId]` | 신뢰도가 높은 learning을 정식 지식(skills/rules/docs)으로 승격 |
-| `teamai recall maintenance` | 지식 베이스 건강 유지: 신뢰도가 낮은 learnings 정리, confidence 점수 되쓰기, 낡은 항목 표시 |
-| `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` | 팀 roles와 namespaces 관리 |
-| `teamai tags` | 태그 기반 skill/rule 필터 관리 |
-| `teamai skill exclude add/remove/list` | 로컬 동기화에서 제외할 Skills 관리 ([usage guide](docs/usage-guide.md#excluding-skills-you-dont-need)) |
-| `teamai source` | skill 구독 소스 관리(다른 팀 또는 org의 공유 저장소) |
-| `teamai remove <type> <name>` | 리소스를 제거하고 MR을 엽니다 |
-| `teamai session save` | 개인정보를 제거한 세션 요약을 월별 로그에 기록 (`--push`는 `digest`에 공급) |
-| `teamai digest` | 주간 팀 사용 digest 생성 |
-| `teamai doctor` | 구성 문제 진단 (`--json`으로 JSON 출력, CI·hook·agent용) |
-| `teamai uninstall` | 모든 teamai 리소스와 hooks 제거 |
+커뮤니티 참여, Issue, PR을 환영합니다. 기여 방법은 [CONTRIBUTING.md](.github/CONTRIBUTING.md)를 참고하세요.

 ## 라이선스

 [MIT](LICENSE)
-
-## 기여하기
-
-PR을 환영합니다! 먼저 [CONTRIBUTING.md](.github/CONTRIBUTING.md)를 읽어 주세요.
@@ -23,15 +23,11 @@

 TeamAI turns individual AI capabilities into shared team capabilities — across agents, machines, and team members.

-## Contributors
+## Why TeamAI

-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).
+<p align="center">
+  <img src="assets/use-cases.png" alt="Eight everyday scenarios, before and after TeamAI" width="100%">
+</p>

 ## Quick Start

@@ -52,10 +48,12 @@ Once TeamAI is set up, just talk to the `/teamai` skill in your AI tool:
 **Join a team**

 ```text
-/teamai Help me join my team's TeamAI, repo URL is https://github.com/yourorg/yourrepo
+/teamai Help me join my team's TeamAI, repo URL is https://github.com/your-org/your-repo
 ```

-**Share a skill with the team**
+**Share with the team**
+
+Skills, rules, MCP servers, and other agent resources can all be shared:

 ```text
 /teamai Share my xxx skill with the team
@@ -68,7 +66,7 @@ Once TeamAI is set up, just talk to the `/teamai` skill in your AI tool:
 ```

 <details>
-<summary>Prefer the command line? (manual setup)</summary>
+<summary>Command-line install</summary>

 ### Install

@@ -78,7 +76,7 @@ npm install -g teamai-cli

 ### Team admin / solo user

-Create a shared-experience repo on your git host (GitHub, GitLab, GitCode, CNB, TGit, or a private Git service), **grant write access to team members**, then run `teamai init https://github.com/yourorg/yourrepo`.
+Create a shared-experience repo on your git host (GitHub, GitLab, GitCode, CNB, TGit, or a private Git service), **grant write access to team members**, then run `teamai init https://github.com/your-org/your-repo`.

 > **No team repo yet?** Start from a template pre-loaded with production-ready skills, rules, and review agents. Browse the [teamai-hub](https://github.com/teamai-hub) org, click **Fork**, then `teamai init` against your new repo.

@@ -89,237 +87,38 @@ Create a shared-experience repo on your git host (GitHub, GitLab, GitCode, CNB,

 # Project-scope init (default, resources installed under the project directory)
 cd /path/to/my-project
-teamai init https://github.com/yourorg/yourrepo
+teamai init https://github.com/your-org/your-repo

 # Or, user-scope init (resources installed under ~/)
-teamai init https://github.com/yourorg/yourrepo --scope user
+teamai init https://github.com/your-org/your-repo --scope user
 ```

 Once initialized, every AI session automatically pulls the latest skills / rules and other Harness updates published by admins — no manual sync needed.

 </details>

-> **Full usage guide:** [docs/usage-guide.md](docs/usage-guide.md) ([中文版](docs/usage-guide.zh-CN.md)) — covers everything from team creation to day-to-day use.
+## Learn More

-## Product architecture
+- [Usage Guide](docs/usage-guide.md) ([中文版](docs/usage-guide.zh-CN.md)) — setup, onboarding, daily workflows, and commands
+- [Product Overview](docs/product-overview.md) ([中文版](docs/product-overview.zh-CN.md)) — architecture, capabilities, and agent support
+- [Git Providers](docs/providers.md) — supported repository providers
+- [Windows Setup](docs/windows-hooks.md) ([中文版](docs/windows-hooks.zh-CN.md)) — hooks and shell configuration
+- [Technical Designs](docs/designs/) — design documents and proposals

-**Team Execution × Team Context (beta) × Team Improvement (beta)**:
+## Contributors

-| 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** (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... |
+Thanks to everyone who has contributed to TeamAI!

-## Overview
+<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
+</a>

-<table>
-  <thead>
-    <tr>
-      <th rowspan="2">Agent</th>
-      <th colspan="7">Team Execution</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>
-      <th>learnings</th><th>codebase</th><th>teamwiki</th>
-      <th>usage</th><th>sessions</th><th>dashboard</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr><td>Claude Code</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>Codex</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>Cursor</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>GitHub Copilot CLI</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>CodeBuddy</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>WorkBuddy</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>OpenCode</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>OpenClaw</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>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>Kiro</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>
-    <tr><td>Oh My Pi</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>
+Made with [contrib.rocks](https://contrib.rocks).

-**Git providers** — GitHub · GitLab · GitCode · CNB · TGit · private Git service.
+## Contributing

-### Distribution Controls
-
-Team-wide settings an admin configures once and delivers to every member on `teamai pull`:
-
-| 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.
-
-TeamAI keeps skills, rules, docs, and hooks in a shared git repo and distributes them to every member's local AI tools through a "push → review & merge → pull" flow — with support for subscribing to other teams' or shared repos' Harness.
-
-### How It Works
-
-```
-teamai push → create branch + MR → reviewer approves + merges
-                                         ↓
-              SessionStart hook → teamai pull → synced to local AI tools
-```
-
-### What Gets Shared
-
-Each resource is delivered to every agent:
-
-| 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`, `agents/<namespace>/<name>.yaml` | Root agents reach everyone; a namespace directory ships only to roles/projects that list it under `agents:` |
-| **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` | Each hook may carry `roles:` to reach only members holding one of those roles |
-| **MCP** | `mcp/mcp.yaml` | Each server may carry `roles:` to reach only members holding one of those roles |
-| **Packages** | `teamai.yaml` | Currently npm packages and Claude Code plugins only |
-| **Models** | — | Not implemented for every provider yet |
-
-For file formats and full workflows, see the [Usage Guide](docs/usage-guide.md).
-
-## Team Context (beta)
-
-> Every agent understands how the team works.
-
-Beyond distributing the Harness, TeamAI organizes accumulated team experience and code structure into a searchable knowledge base that the AI recalls automatically when needed.
-
-### Automatic Experience Sharing
-
-When a session ends, the Stop hook scores it by **friction** — signals that the session hit something worth remembering: you interrupted or corrected the AI, denied a tool call, or the AI had to retry failing tools. A long-but-routine session (lots of tool calls, no friction) does not trigger; a session where you actually fought a problem does. If the score is high enough, the AI suggests:
-
-```
-[teamai] This session may contain a problem worth documenting: you interrupted the AI twice, the AI retried failing tools 8 times.
-
-Task: Fix duplicate project-level Hook injection
-
-Consider running /teamai-share-learnings to summarize what you learned and share it with your team.
-```
-
-The hint names the non-zero friction signals that triggered it and, when available, includes a redacted, single-line summary of the first task. The `/teamai-share-learnings` skill summarizes the session and pushes a learning document directly to the team repo. Each session is prompted at most once. Teams can switch the hint off with `sharing.contributeHint.enabled: false` in `teamai.yaml` (members: `contributeHintEnabled` in local config) while keeping the rest of the Stop hook.
-
-### Team Knowledge Recall
-
-Let the AI automatically search accumulated team knowledge before a task. This feature is **off by default** and must be enabled explicitly — teams can set `sharing.recall.enabled: true` in `teamai.yaml` as the default, and members can override locally:
-
-```bash
-teamai recall enable     # on: deploy the teamai-recall subagent + inject guidance rules
-teamai recall disable    # off: remove the subagent and rules
-teamai recall status     # show effective state (team default + user override)
-```
-
-**Search runs via a subagent**: once enabled, `teamai pull` deploys the built-in `teamai-recall` subagent into each AI tool's `agents/` directory. The AI invokes it before a task — the subagent extracts keywords, runs the search, reads the matched source files, and returns a structured summary of team knowledge. The subagent first runs a relevance precheck (`teamai recall --check`) and skips retrieval entirely when the task is unrelated to team knowledge. Under the hood it shells out to the `teamai recall` command, which you can also run manually:
-
-```bash
-$ teamai recall "port conflict"
-[1/2] MR review caught a port-conflict bug ★1 [user]
-Author: member-a | Score: 18.5 | Tags: troubleshooting, networking
-
-[2/2] Deployment configuration best practices [project]
-Author: member-b | Score: 12.0 | Tags: deploy, config
-Matched: conflict | Missing: port
-```
-
-### Codebase Knowledge Graph
-
-`teamai import` parses source repos into a structured graph under `teamwiki/`, enabling structurally-aware retrieval:
-
-```bash
-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 --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.
-
-Edges come from two tracks that run together, with AST results taking precedence on overlap:
-
- **AST track** (TypeScript/JavaScript, Python, Go): a WASM [tree-sitter](https://tree-sitter.github.io/) parser resolves `import`/`require`, call sites, and TS `implements` clauses to precise file-to-file `DEPENDS_ON` / `REFERENCES` / `IMPLEMENTS` edges (tagged `code-ast`, with confidence weights).
- **Heuristic track** (all languages, including Java/Rust): regex-based extraction (tagged `code-heuristic`), which also covers languages the AST track does not.
-
-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 (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 — 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` | Unified Overview / Team Execution / Team Context / Team Improvement views with local live sessions, 7-day trends, estimated cost per session, English/Chinese, and light/dark/system themes. |
-| **KB Health** | `teamai dashboard` → Team Context / Team Improvement | Coverage by type, top-recalled and silent entries, last-recall month distribution, author contributions, and maintenance; the full `/kb-report` remains available. |
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `teamai init` | Initialize: OAuth login, link repo, register member, inject hooks |
-| `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 and resource counts, including namespaced skills and nested docs |
-| `teamai contribute` | Share session experience to the team repo's `teamai-learnings` branch |
-| `teamai recall <query>` | Search the team knowledge base (BM25 + graph-boost) |
-| `teamai recall enable/disable/status` | Toggle or check recall state |
-| `teamai recall promote [learningId]` | Promote a high-confidence learning to formal knowledge (skills/rules/docs) |
-| `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)) |
-| `teamai source` | Manage skill subscription sources (other teams or your org's shared repos) |
-| `teamai remove <type> <name>` | Remove a resource and open MR |
-| `teamai session save` | Record a privacy-scrubbed session summary to a monthly log (`--push` feeds `digest`) |
-| `teamai digest` | Generate weekly team usage digest |
-| `teamai doctor` | Diagnose configuration issues (`--json` for CI, hooks and agents) |
-| `teamai uninstall` | Remove all teamai resources and hooks |
+Join the conversation, or open an issue or PR. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for how to contribute.

 ## License

 [MIT](LICENSE)
-
-## Contributing
-
-PRs are welcome! Please read [CONTRIBUTING.md](.github/CONTRIBUTING.md) first.
@@ -23,15 +23,11 @@

 TeamAI เปลี่ยนความสามารถด้าน AI ของแต่ละคนให้เป็นความสามารถร่วมของทีม ใช้ได้ข้าม Agent อุปกรณ์ และสมาชิกในทีม

-## ผู้ร่วมพัฒนา
+## ทำไมต้อง TeamAI

-ขอขอบคุณทุกคนที่ได้ร่วมพัฒนา 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)
+<p align="center">
+  <img src="assets/use-cases.png" alt="แปดสถานการณ์ในการทำงานจริง ก่อนและหลังใช้ TeamAI" width="100%">
+</p>

 ## เริ่มต้นอย่างรวดเร็ว

@@ -52,10 +48,12 @@ TeamAI เปลี่ยนความสามารถด้าน AI ขอ
 **เข้าร่วมทีม**

 ```text
-/teamai ช่วยพาฉันเข้าร่วม TeamAI ของทีม, URL รีโปคือ https://github.com/yourorg/yourrepo
+/teamai ช่วยพาฉันเข้าร่วม TeamAI ของทีม, URL รีโปคือ https://github.com/your-org/your-repo
 ```

-**แชร์ skill ให้ทีม**
+**แชร์ให้ทีม**
+
+Skills, Rules, MCP และทรัพยากรอื่นที่ Agent ใช้ได้ แชร์ได้ทั้งหมด:

 ```text
 /teamai ช่วยแชร์ xxx skill ให้ทีม
@@ -68,7 +66,7 @@ TeamAI เปลี่ยนความสามารถด้าน AI ขอ
 ```

 <details>
-<summary>ถนัดใช้คอมมานด์ไลน์มากกว่า? (ติดตั้งเอง)</summary>
+<summary>ติดตั้งด้วยคอมมานด์ไลน์</summary>

 ### ติดตั้ง

@@ -78,7 +76,7 @@ npm install -g teamai-cli

 ### ผู้ดูแลทีม / ผู้ใช้คนเดียว

-สร้างรีโปสำหรับแบ่งปันประสบการณ์บน Git host ของคุณ (GitHub, GitLab, GitCode, CNB, TGit หรือบริการ Git ส่วนตัว) **ให้สิทธิ์เขียนแก่สมาชิกทีม** จากนั้นรัน `teamai init https://github.com/yourorg/yourrepo`
+สร้างรีโปสำหรับแบ่งปันประสบการณ์บน Git host ของคุณ (GitHub, GitLab, GitCode, CNB, TGit หรือบริการ Git ส่วนตัว) **ให้สิทธิ์เขียนแก่สมาชิกทีม** จากนั้นรัน `teamai init https://github.com/your-org/your-repo`

 > **ยังไม่มีรีโปของทีม?** เริ่มจากเทมเพลตที่มี Skills, Rules และ review agents พร้อมใช้จริงอยู่แล้ว เปิดดู org [teamai-hub](https://github.com/teamai-hub) กด **Fork** แล้วรัน `teamai init` กับรีโปใหม่ของคุณ

@@ -89,237 +87,38 @@ npm install -g teamai-cli

 # Project-scope init (default, resources installed under the project directory)
 cd /path/to/my-project
-teamai init https://github.com/yourorg/yourrepo
+teamai init https://github.com/your-org/your-repo

 # Or, user-scope init (resources installed under ~/)
-teamai init https://github.com/yourorg/yourrepo --scope user
+teamai init https://github.com/your-org/your-repo --scope user
 ```

 เมื่อเริ่มต้นแล้ว ทุกเซสชัน AI จะดึง Skills / Rules และการอัปเดต Harness อื่นๆ ล่าสุดที่ผู้ดูแลเผยแพร่โดยอัตโนมัติ — ไม่ต้องซิงก์ด้วยตนเอง

 </details>

-> **คู่มือการใช้งานฉบับเต็ม:** [docs/usage-guide.md](docs/usage-guide.md) ([中文版](docs/usage-guide.zh-CN.md)) — ครอบคลุมตั้งแต่การสร้างทีมไปจนถึงการใช้งานประจำวัน
+## เรียนรู้เพิ่มเติม

-## สถาปัตยกรรมผลิตภัณฑ์
+- [Usage Guide](docs/usage-guide.md) — setup, onboarding, daily workflows, and commands
+- [Product Overview](docs/product-overview.md) — architecture, capabilities, and agent support
+- [Git Providers](docs/providers.md) — supported repository providers
+- [Windows Setup](docs/windows-hooks.md) — hooks and shell configuration
+- [Technical Designs](docs/designs/) — design documents and proposals

-**Team Execution × Team Context (beta) × Team Improvement (beta)**:
+## ผู้ร่วมพัฒนา

-| เลเยอร์ | หน้าที่ | ปัจจุบันใน CLI นี้ |
-|-------|-----|-------------------|
-| **Team Execution** | ให้ทุก Agent ทำงานตามแบบของทีม | `init` / `pull` / `push`, skills, rules, agents, hooks, MCP, env |
-| **Team Context** (beta) | ให้ทุก Agent เข้าใจทีม | recall, learnings, codebase graph, teamwiki... |
-| **Team Improvement** (beta) | ให้ทุกครั้งที่ทำงานช่วยพัฒนาทีม | friction-based share-learnings, sessions, digest, dashboard... |
+ขอขอบคุณทุกคนที่ได้ร่วมพัฒนา TeamAI!

-## ภาพรวม
+<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
+</a>

-<table>
-  <thead>
-    <tr>
-      <th rowspan="2">Agent</th>
-      <th colspan="7">Team Execution</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>
-      <th>learnings</th><th>codebase</th><th>teamwiki</th>
-      <th>usage</th><th>sessions</th><th>dashboard</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr><td>Claude Code</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>Codex</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>Cursor</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>GitHub Copilot CLI</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>CodeBuddy</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>WorkBuddy</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>OpenCode</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>OpenClaw</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>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>Kiro</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>
-    <tr><td>Oh My Pi</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>
+สร้างด้วย [contrib.rocks](https://contrib.rocks)

-**Git providers** — GitHub · GitLab · GitCode · CNB · TGit · บริการ Git ส่วนตัว
+## การร่วมพัฒนา

-### การควบคุมการกระจาย
-
-การตั้งค่าทั้งทีมที่ผู้ดูแลกำหนดครั้งเดียว แล้วส่งถึงสมาชิกทุกคนเมื่อ `teamai pull`:
-
-| ความสามารถ | คำสั่ง | ทำอะไร |
-|------------|---------|--------------|
-| **Projects** | `teamai projects` | ผูกไดเรกทอรีทำงานกับหนึ่งหรือหลาย logical projects เพื่อซิงก์ Skills ความรู้ และ learnings ที่แยกของโปรเจกต์นั้น ไม่ขึ้นกับ roles |
-| **Roles** | `teamai roles` | กำหนดการแมป role → namespace เพื่อให้สมาชิกแต่ละคนซิงก์เฉพาะ Skills ของ role ตนเอง |
-| **Tags** | `teamai tags` | ติดแท็ก Skills / Rules เพื่อให้สมาชิกสมัครรับเฉพาะแท็กที่ต้องการ |
-| **Sources** | `teamai source` | สมัครรับรีโป Skills เพิ่มเติม — รีโปสาธารณะของทีมอื่น หรือรีโปที่แชร์/สาธารณะใน org ของคุณ Skills ที่สมัครจะซิงก์อัตโนมัติเมื่อ pull |
-
-การแยก learnings: `learnings/` ที่รากรีโปแชร์กับทุกคน; `learnings/<project-id>/` เป็นของโปรเจกต์นั้นโดยเฉพาะ ดู [usage guide](docs/usage-guide.md#multi-project-project-as-a-dimension-orthogonal-to-role)
-
-## Team Execution
-
-> One Team. One Harness. Every Agent.
-
-TeamAI เก็บ Skills, Rules, docs และ hooks ไว้ในรีโป Git ที่ใช้ร่วมกัน แล้วกระจายไปยังเครื่องมือ AI ในเครื่องของสมาชิกทุกคนผ่านโฟลว์ "push → review & merge → pull" — พร้อมรองรับการสมัครรับ Harness จากทีมอื่นหรือรีโปที่แชร์
-
-### วิธีการทำงาน
-
-```
-teamai push → create branch + MR → reviewer approves + merges
-                                         ↓
-              SessionStart hook → teamai pull → synced to local AI tools
-```
-
-### สิ่งที่ถูกแชร์
-
-แต่ละทรัพยากรถูกส่งไปยังทุก Agent:
-
-| ทรัพยากร | ในรีโปทีม | หมายเหตุ |
-|----------|------------------|-------|
-| **Skills** | `skills/<name>/SKILL.md` | |
-| **Rules** | `rules/*.md` | |
-| **Docs** | `docs/` | เอกสารพื้นฐานของโปรเจกต์; ไม่ได้โหลดทั้งหมดโดยค่าเริ่มต้น (progressive disclosure) |
-| **Agents** | `agents/<name>.yaml` | |
-| **Culture** | `culture.md` | พันธกิจ ค่านิยม และหลักการทำงานของทีม — ถูกฉีดเข้า CLAUDE.md / AGENTS.md ของแต่ละ Agent เพื่อให้ทุกเซสชันสืบทอดสิ่งเหล่านี้ |
-| **CLAUDE.md** | `claudemd/*.md` | |
-| **Env** | `env/` | ตัวแปรสภาพแวดล้อมและสวิตช์ระดับทีมที่ใช้ร่วมกัน; อย่าใส่ secrets ที่นี่ |
-| **Hooks** | `hooks/hooks.yaml` | แต่ละ hook อาจมี `roles:` เพื่อส่งถึงเฉพาะสมาชิกที่มี role เหล่านั้น |
-| **MCP** | `mcp/mcp.yaml` | แต่ละ server อาจมี `roles:` เพื่อส่งถึงเฉพาะสมาชิกที่มี role เหล่านั้น |
-| **Packages** | `teamai.yaml` | ขณะนี้รองรับเฉพาะแพ็กเกจ npm และปลั๊กอิน Claude Code |
-| **Models** | — | ยังไม่ได้ implement สำหรับทุก provider |
-
-รูปแบบไฟล์และเวิร์กโฟลว์ทั้งหมด ดูที่ [Usage Guide](docs/usage-guide.md)
-
-## Team Context (beta)
-
-> Every agent understands how the team works.
-
-นอกจากการกระจาย Harness แล้ว TeamAI ยังจัดระเบียบประสบการณ์ที่ทีมสะสมและโครงสร้างโค้ดเป็นคลังความรู้ที่ค้นหาได้ ให้ AI เรียกคืนอัตโนมัติเมื่อจำเป็น
-
-### การแชร์ประสบการณ์อัตโนมัติ
-
-เมื่อเซสชันจบ Stop hook จะให้คะแนนตาม **friction** — สัญญาณว่าเซสชันเจอสิ่งที่ควรจดจำ: คุณขัดจังหวะหรือแก้ AI ปฏิเสธการเรียกเครื่องมือ หรือ AI ต้อง retry เครื่องมือที่ล้มเหลว เซสชันที่ยาวแต่เป็นงานประจำ (เรียกเครื่องมือเยอะแต่ไม่มี friction) จะไม่ถูกกระตุ้น ส่วนเซสชันที่คุณสู้กับปัญหาจริงจะถูกกระตุ้น หากคะแนนสูงพอ AI จะแนะนำ:
-
-```
-[teamai] This session may contain a problem worth documenting: you interrupted the AI twice, the AI retried failing tools 8 times.
-
-Task: Fix duplicate project-level Hook injection
-
-Consider running /teamai-share-learnings to summarize what you learned and share it with your team.
-```
-
-ข้อความแนะนำจะระบุสัญญาณ friction ที่ไม่เป็นศูนย์ซึ่งเป็นตัวกระตุ้น และเมื่อมีข้อมูล จะแนบสรุปบรรทัดเดียวที่ปกปิดข้อมูลอ่อนไหวของงานแรก Skill `/teamai-share-learnings` จะสรุปเซสชันแล้ว push เอกสาร learning ไปยังรีโปทีมโดยตรง แต่ละเซสชันถูกถามอย่างมากหนึ่งครั้ง ทีมสามารถปิดคำแนะนำได้ด้วย `sharing.contributeHint.enabled: false` ใน `teamai.yaml` (สมาชิก: `contributeHintEnabled` ในคอนฟิกท้องถิ่น) โดยยังคงส่วนที่เหลือของ Stop hook
-
-### การเรียกคืนความรู้ทีม
-
-ให้ AI ค้นหาความรู้ที่ทีมสะสมโดยอัตโนมัติก่อนเริ่มงาน ฟีเจอร์นี้ **ปิดโดยค่าเริ่มต้น** และต้องเปิดอย่างชัดเจน — ทีมตั้ง `sharing.recall.enabled: true` ใน `teamai.yaml` เป็นค่าเริ่มต้นได้ และสมาชิกสามารถ override ในเครื่องได้:
-
-```bash
-teamai recall enable     # on: deploy the teamai-recall subagent + inject guidance rules
-teamai recall disable    # off: remove the subagent and rules
-teamai recall status     # show effective state (team default + user override)
-```
-
-**การค้นหาทำงานผ่าน subagent**: เมื่อเปิดแล้ว `teamai pull` จะติดตั้ง `teamai-recall` subagent ในตัวไปยังไดเรกทอรี `agents/` ของแต่ละเครื่องมือ AI AI จะเรียกใช้ก่อนเริ่มงาน — subagent สกัดคำสำคัญ รันการค้นหา อ่านไฟล์ต้นทางที่ตรงกัน แล้วคืนสรุปความรู้ทีมแบบมีโครงสร้าง Subagent จะรันการตรวจความเกี่ยวข้องล่วงหน้าก่อน (`teamai recall --check`) และข้ามการดึงข้อมูลทั้งหมดเมื่องานไม่เกี่ยวกับความรู้ทีม เบื้องหลังจะเรียกคำสั่ง `teamai recall` ซึ่งคุณรันเองด้วยมือก็ได้:
-
-```bash
-$ teamai recall "port conflict"
-[1/2] MR review caught a port-conflict bug ★1 [user]
-Author: member-a | Score: 18.5 | Tags: troubleshooting, networking
-
-[2/2] Deployment configuration best practices [project]
-Author: member-b | Score: 12.0 | Tags: deploy, config
-Matched: conflict | Missing: port
-```
-
-### กราฟความรู้ Codebase
-
-`teamai import` แปลงรีโปซอร์สเป็นกราฟมีโครงสร้างภายใต้ `teamwiki/` เพื่อให้ค้นหาโดยคำนึงถึงโครงสร้าง:
-
-```bash
-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 --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 จะเขียน `teamwiki/evidence/code/<project>/_manifest.json` แม้จะข้าม AI enrichment หรือไม่ได้ผลลัพธ์ เพื่อให้ `--deep-enrich` เริ่มได้
-
-กราฟเก็บ components, interfaces, configs และขอบ import ข้ามรีโป `teamai recall` ใช้กราฟนี้เพื่อจัดอันดับใหม่แบบ graph-boosted
-เมื่อผลการ recall มาจากหน้า codebase ผลลัพธ์จะมีบรรทัด `Sources:` ระบุพาธไฟล์ต้นทางที่เกี่ยวข้อง — ให้ Agents มีจุดเริ่มต้นตรงสำหรับแก้โค้ดโดยไม่ต้องสำรวจรีโปใหม่
-
-ขอบมาจากสองแทร็กที่ทำงานคู่กัน โดยผล AST มีลำดับความสำคัญเมื่อซ้อนทับ:
-
- **AST track** (TypeScript/JavaScript, Python, Go): พาร์เซอร์ WASM [tree-sitter](https://tree-sitter.github.io/) จะ resolve `import`/`require` จุดเรียกใช้ และประโยค `implements` ของ TS เป็นขอบไฟล์ต่อไฟล์แบบ `DEPENDS_ON` / `REFERENCES` / `IMPLEMENTS` ที่แม่นยำ (แท็ก `code-ast` พร้อมน้ำหนักความเชื่อมั่น)
- **Heuristic track** (ทุกภาษา รวม Java/Rust): การ extract ด้วย regex (แท็ก `code-heuristic`) ซึ่งครอบคลุมภาษาที่ AST track ยังไม่รองรับด้วย
-
-พาร์เซอร์ WASM เป็น dependency แบบ pure-JavaScript — ไม่ต้องใช้ native toolchain หากโหลดไม่สำเร็จด้วยเหตุใดก็ตาม การ extract จะถอยไปใช้ heuristic track และบันทึกช่องว่าง `AST_UNAVAILABLE` ตั้ง `TEAMAI_SKIP_AST=1` เพื่อบังคับให้ extract แบบ heuristic อย่างเดียว
-
-## Team Improvement (beta)
-
-> Every execution makes the entire team smarter.
-
-### การบำรุงรักษา
-
-เมื่อ Skills และความรู้สะสมมากขึ้น ให้ตัดสิ่งที่ทีมไม่ใช้แล้ว `teamai recall maintenance` จะ archive learnings ที่ความเชื่อมั่นต่ำ และทำเครื่องหมาย Skills, Rules และ docs ที่ล้าสมัยเพื่อทำความสะอาดหรืออัปเดต:
-
-```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
-```
-
-ช่วยให้เห็นว่าทีมใช้เครื่องมือ AI จริงอย่างไร และเป็นจุดตั้งต้นในการแปลง friction ของเซสชันเป็น Skills, Rules และความรู้ที่แชร์กัน:
-
-| ความสามารถ | คำสั่ง | สิ่งที่แสดง |
-|------------|---------|---------------|
-| **Usage** | `teamai digest` | สรุปทีมรายสัปดาห์ — ความสำเร็จใน 7 วัน, prompt, เวลาที่ใช้งาน, ต้นทุนโดยประมาณ, cache และแนวโน้มการแก้ไข รวมถึงยอดสะสมตลอดอายุการใช้งาน |
-| **Sessions** | `teamai session save` | สรุปรายเซสชันที่ล้างข้อมูลส่วนตัวแล้ว (ลำดับเครื่องมือ, รอบ prompt, การแทรกแซง) ซึ่งป้อน Session Highlights ของ digest |
-| **Dashboard** | `teamai dashboard` | รวม Overview / Team Execution / Team Context / Team Improvement พร้อมเซสชันสดในเครื่อง แนวโน้ม 7 วัน ค่าใช้จ่ายโดยประมาณต่อเซสชัน ภาษาอังกฤษ/จีนตัวย่อ และธีมสว่าง/มืด/ตามระบบ |
-| **KB Health** | `teamai dashboard` → Team Context / Team Improvement | หน้าในแดชบอร์ดที่รายงานการใช้งานและสุขภาพของคลังความรู้ — ความครอบคลุมตามประเภท, รายการที่ถูก recall บ่อย, รายการที่เงียบ, แนวโน้ม recall, ผลงานของผู้เขียน และคอนโซลบำรุงรักษา |
-
-## คำสั่ง
-
-| คำสั่ง | คำอธิบาย |
-|---------|-------------|
-| `teamai init` | เริ่มต้น: ล็อกอิน OAuth, เชื่อมรีโป, ลงทะเบียนสมาชิก, ฉีด hooks |
-| `teamai pull` | ดึงทรัพยากรทีมแล้วฉีดเข้าเครื่องมือ AI ในเครื่อง |
-| `teamai push` | ผลักทรัพยากรในเครื่องไปยังสาขาแล้วเปิด Merge Request |
-| `teamai packages [install] [target]` | ติดตั้งแพ็กเกจ npm และปลั๊กอิน Claude ที่ประกาศไว้; ถ้ามี target จะอัปเดต `teamai.yaml` ด้วย `teamai packages` เปล่าติดตั้งทั้งหมด; `teamai packages install <target>` เพิ่มทีละรายการ |
-| `teamai status` | แสดงความต่างระหว่างเครื่องกับรีโปทีม และจำนวนทรัพยากร รวมถึง Skills ที่มี namespace และ docs ที่ซ้อนกัน |
-| `teamai contribute` | แชร์ประสบการณ์จากเซสชันไปยังแบรนช์ `teamai-learnings` ของรีโปทีม |
-| `teamai recall <query>` | ค้นหาคลังความรู้ทีม (BM25 + graph-boost) |
-| `teamai recall enable/disable/status` | เปิด/ปิด หรือตรวจสถานะ recall |
-| `teamai recall promote [learningId]` | เลื่อน learning ที่ความเชื่อมั่นสูงให้เป็นความรู้ทางการ (skills/rules/docs) |
-| `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, โพสต์คอมเมนต์, เขียนหลัง merge |
-| `teamai members` | แสดงรายชื่อสมาชิกทีม |
-| `teamai projects` | ผูกไดเรกทอรีทำงานกับหนึ่งหรือหลาย logical projects |
-| `teamai roles` | จัดการ roles และ namespaces ของทีม |
-| `teamai tags` | จัดการการกรอง skill/rule ตามแท็ก |
-| `teamai skill exclude add/remove/list` | จัดการ Skills ที่ไม่ซิงก์ในเครื่อง ([usage guide](docs/usage-guide.md#excluding-skills-you-dont-need)) |
-| `teamai source` | จัดการแหล่งสมัคร Skills (ทีมอื่น หรือรีโปที่แชร์ใน org ของคุณ) |
-| `teamai remove <type> <name>` | ลบทรัพยากรแล้วเปิด MR |
-| `teamai session save` | บันทึกสรุปเซสชันที่ล้างข้อมูลส่วนตัวแล้วลงล็อกรายเดือน (`--push` จะป้อน `digest`) |
-| `teamai digest` | สร้างสรุปการใช้งานทีมรายสัปดาห์ |
-| `teamai doctor` | วินิจฉัยปัญหาคอนฟิก (`--json` แสดงผลเป็น JSON สำหรับ CI, hook และ agent) |
-| `teamai uninstall` | ลบทรัพยากรและ hooks ของ teamai ทั้งหมด |
+ยินดีให้เข้าร่วมพูดคุยในชุมชน หรือเปิด Issue และ PR ดูวิธีมีส่วนร่วมได้ที่ [CONTRIBUTING.md](.github/CONTRIBUTING.md)

 ## ใบอนุญาต

 [MIT](LICENSE)
-
-## การร่วมพัฒนา
-
-ยินดีรับ PR! โปรดอ่าน [CONTRIBUTING.md](.github/CONTRIBUTING.md) ก่อน
@@ -23,15 +23,11 @@

 TeamAI 将个人的 AI 能力转化为团队共享能力，并在不同 Agent、设备和团队成员之间复用。

-## 贡献者
+## 为什么选择 TeamAI

-感谢每一位为 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) 生成。
+<p align="center">
+  <img src="assets/use-cases.zh-CN.png" alt="八个日常场景：使用 TeamAI 前后对比" width="100%">
+</p>

 ## 快速开始

@@ -52,10 +48,12 @@ TeamAI 将个人的 AI 能力转化为团队共享能力，并在不同 Agent、
 **加入团队**

 ```text
-/teamai 帮我加入团队的 TeamAI,仓库地址是 https://github.com/yourorg/yourrepo
+/teamai 帮我加入团队的 TeamAI,仓库地址是 https://github.com/your-org/your-repo
 ```

-**把 skill 分享给团队**
+**把资源分享给团队**
+
+Skills、Rules、MCP 等 Agent 能用的资源都可以分享：

 ```text
 /teamai 帮我把 xxx skill 分享给团队
@@ -68,7 +66,7 @@ TeamAI 将个人的 AI 能力转化为团队共享能力，并在不同 Agent、
 ```

 <details>
-<summary>更习惯用命令行？（手动安装）</summary>
+<summary>命令行安装</summary>

 ### 安装

@@ -78,7 +76,7 @@ npm install -g teamai-cli

 ### 团队管理员 / 个人使用者

-在 Git 托管平台（GitHub、GitLab、GitCode、CNB、TGit，或私有 Git 服务）创建共享经验仓库，**授予团队成员写权限**，然后运行 `teamai init https://github.com/yourorg/yourrepo`。
+在 Git 托管平台（GitHub、GitLab、GitCode、CNB、TGit，或私有 Git 服务）创建共享经验仓库，**授予团队成员写权限**，然后运行 `teamai init https://github.com/your-org/your-repo`。

 > **还没有团队仓库？** 可以从内置了成套 skills、rules、review agents 的模板起步。浏览 [teamai-hub](https://github.com/teamai-hub) org，点 **Fork** 生成自己的仓库，再对它执行 `teamai init`。

@@ -89,237 +87,38 @@ npm install -g teamai-cli

 # 项目级初始化（默认，资源安装到项目目录下）
 cd /path/to/my-project
-teamai init https://github.com/yourorg/yourrepo
+teamai init https://github.com/your-org/your-repo

 # 或者，用户级初始化（资源安装到 ~/ 下）
-teamai init https://github.com/yourorg/yourrepo --scope user
+teamai init https://github.com/your-org/your-repo --scope user
 ```

 初始化完成后，每次开启 AI 会话时都会自动拉取管理员发布的 skills / rules 等 Harness 更新，无需手动同步。

 </details>

-> **完整使用指南**：[docs/usage-guide.zh-CN.md](docs/usage-guide.zh-CN.md)（[English](docs/usage-guide.md)）— 涵盖从团队创建到日常使用的全流程。
+## 了解更多

-## 产品架构
+- [使用指南](docs/usage-guide.zh-CN.md)（[English](docs/usage-guide.md)）— 安装、成员接入、日常流程与命令参考
+- [产品概览](docs/product-overview.zh-CN.md)（[English](docs/product-overview.md)）— 架构、能力与 Agent 支持范围
+- [Git Provider](docs/providers.md) — 支持的代码托管平台
+- [Windows 配置](docs/windows-hooks.zh-CN.md)（[English](docs/windows-hooks.md)）— Hook 与 Shell 配置
+- [技术设计](docs/designs/) — 设计文档与提案

-**Team Execution × Team Context (beta) × Team Improvement (beta)**：
+## 贡献者

-| 层 | 要解决的问题 | 当前 CLI 中的体现 |
-|----|--------------|-------------------|
-| **Team Execution** | 让每个 Agent 按团队的方式工作 | `init` / `pull` / `push`，skills、rules、agents、hooks、MCP、env |
-| **Team Context** (beta) | 让每个 Agent 理解整个团队 | recall、learnings、代码知识图谱、teamwiki... |
-| **Team Improvement** (beta) | 让每一次执行都成为团队能力的积累 | 基于摩擦信号的经验分享、sessions、digest、dashboard... |
+感谢每一位为 TeamAI 贡献代码的伙伴！

-## 功能概览
+<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
+</a>

-<table>
-  <thead>
-    <tr>
-      <th rowspan="2">Agent</th>
-      <th colspan="7">Team Execution</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>
-      <th>learnings</th><th>codebase</th><th>teamwiki</th>
-      <th>usage</th><th>sessions</th><th>dashboard</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr><td>Claude Code</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>Codex</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>Cursor</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>GitHub Copilot CLI</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>CodeBuddy</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>WorkBuddy</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>OpenCode</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>OpenClaw</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>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>Kiro</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>
-    <tr><td>Oh My Pi</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>
+由 [contrib.rocks](https://contrib.rocks) 生成。

-**Git 托管平台** —— GitHub · GitLab · GitCode · CNB · TGit · 私有 Git 服务。
+## 贡献

-### 分发策略
-
-管理员一次配置、随 `teamai pull` 分发给每位成员的团队级设置：
-
-| 能力 | 命令 | 作用 |
-|------|------|------|
-| **项目（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.
-
-TeamAI 把 skills、rules、docs、hooks 统一存放在共享 Git 仓库，通过「push → 评审合并 → pull」的流程分发到每位成员的本地 AI 工具，并支持订阅其他团队或公共仓库的 Harness。
-
-### 工作原理
-
-```
-teamai push → 创建分支 + MR → reviewer 审批合并
-                                    ↓
-           SessionStart hook → teamai pull → 同步到本地 AI 工具
-```
-
-### 分发内容
-
-每类资源分发到每个 Agent：
-
-| 资源 | 团队仓库中的位置 | 备注 |
-|------|------------------|------|
-| **Skills** | `skills/<name>/SKILL.md` | |
-| **Rules** | `rules/*.md` | |
-| **Docs** | `docs/` | 项目基础文档，默认不全量加载（渐进式披露） |
-| **Agents** | `agents/<name>.yaml`、`agents/<namespace>/<name>.yaml` | 根目录 agents 对所有人生效；namespace 子目录只同步给在 `agents:` 中列出它的角色/项目 |
-| **Culture** | `culture.md` | 团队使命、价值观与协作准则——注入各 Agent 的 CLAUDE.md / AGENTS.md，成为每次会话的行事底色 |
-| **CLAUDE.md** | `claudemd/*.md` | |
-| **Env** | `env/` | 通用环境变量、团队级开关；不建议直接放密钥 |
-| **Hooks** | `hooks/hooks.yaml` | 每条 hook 可加 `roles:`，只分发给持有这些角色的成员 |
-| **MCP** | `mcp/mcp.yaml` | 每个 server 可加 `roles:`，只分发给持有这些角色的成员 |
-| **Packages** | `teamai.yaml` | 目前只支持 npm 包和 Claude 插件 |
-| **Models** | — | 暂时没有对全部 provider 实现 |
-
-文件格式与完整工作流见[使用指南](docs/usage-guide.zh-CN.md)。
-
-## Team Context (beta)
-
-> Every agent understands how the team works.
-
-除了分发 Harness，TeamAI 还把团队沉淀的经验和代码结构组织成可检索的知识库，让 AI 在需要时自动召回。
-
-### 自动经验沉淀
-
-Session 结束时，Stop hook 按**摩擦信号**对 session 评分——这些信号表明本次 session 踩到了值得记录的东西：你打断或纠正了 AI、拒绝了某次工具调用，或 AI 反复重试出错的工具。又长又顺（工具调用很多但没有摩擦）的 session 不会触发；真正较劲过的 session 才会。达标后 AI 会显示如下英文提示：
-
-```
-[teamai] This session may contain a problem worth documenting: you interrupted the AI twice, the AI retried failing tools 8 times.
-
-Task: Fix duplicate project-level Hook injection
-
-Consider running /teamai-share-learnings to summarize what you learned and share it with your team.
-```
-
-提示会列出实际触发它的非零摩擦信号；如果能取得首个任务摘要，还会在脱敏、单行化后附上任务上下文。`/teamai-share-learnings` skill 自动总结 session 经验并推送到团队仓库。每个 session 最多提示一次。团队可在 `teamai.yaml` 设置 `sharing.contributeHint.enabled: false` 关闭该提示（成员可用本地配置 `contributeHintEnabled` 覆盖），Stop hook 的其余功能不受影响。
-
-### 团队知识检索
-
-让 AI 在执行任务前自动检索团队积累的知识。该功能**默认关闭**，需显式开启——团队可在 `teamai.yaml` 设 `sharing.recall.enabled: true` 作为默认值，成员也可本地覆盖：
-
-```bash
-teamai recall enable     # 开启：部署 teamai-recall 子 agent + 注入引导规则
-teamai recall disable    # 关闭：移除子 agent 和规则
-teamai recall status     # 查看生效状态（团队默认 + 用户覆盖）
-```
-
-**通过子 agent 检索**：开启后 `teamai pull` 会把内置的 `teamai-recall` 子 agent 部署到各 AI 工具的 `agents/` 目录。AI 在任务开始前调用它——由子 agent 提取关键词、执行检索、读取命中的源文件，最后返回结构化的团队知识摘要。subagent 会先做相关性预检（`teamai recall --check`），当任务与团队知识无关时直接跳过检索。子 agent 底层调用的仍是 `teamai recall` 命令，也可手动直接运行：
-
-```bash
-$ teamai recall "port conflict"
-[1/2] MR review caught a port-conflict bug ★1 [user]
-Author: member-a | Score: 18.5 | Tags: troubleshooting, networking
-
-[2/2] Deployment configuration best practices [project]
-Author: member-b | Score: 12.0 | Tags: deploy, config
-Matched: conflict | Missing: port
-```
-
-### 代码知识图谱
-
-`teamai import` 将源码仓库解析为 `teamwiki/` 下的结构化图谱，实现结构感知的检索：
-
-```bash
-teamai import --from-repo https://github.com/org/repo
-teamai import --from-org myorg              # 批量导入所有仓库
-teamai codebase --extract /path/to/repo     # 本地提取到 teamwiki/
-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 直接作为代码改动的入口，无需重新探索代码库。
-
-依赖边来自两条并行的提取轨道，重叠时以 AST 结果优先：
-
- **AST 轨**（TypeScript/JavaScript、Python、Go）：使用 WASM 版 [tree-sitter](https://tree-sitter.github.io/) 解析器，将 `import`/`require`、调用点、以及 TS `implements` 子句解析为精确的文件到文件 `DEPENDS_ON` / `REFERENCES` / `IMPLEMENTS` 边（标记为 `code-ast`，带置信度权重）。
- **启发式轨**（所有语言，含 Java/Rust）：基于正则的提取（标记为 `code-heuristic`），同时覆盖 AST 轨未支持的语言。
-
-WASM 解析器是纯 JavaScript 依赖，无需任何原生编译工具链。若因任何原因加载失败，提取会降级到启发式轨并记录一条 `AST_UNAVAILABLE` gap。设置 `TEAMAI_SKIP_AST=1` 可强制仅使用启发式提取。
-
-## 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` | 团队周报——近 7 天成功率、对话、活跃时长、估算成本、缓存与纠偏趋势，以及历史累计数据。 |
-| **会话（Sessions）** | `teamai session save` | 脱敏的单会话摘要（工具序列、对话轮次、干预次数），喂给周报的 Session Highlights。 |
-| **看板（Dashboard）** | `teamai dashboard` | 统一的 Overview / Team Execution / Team Context / Team Improvement 界面，保留本机实时会话、近 7 天趋势、每会话估算费用，支持中英文及日间/夜间/跟随系统主题。 |
-| **知识库健康（KB Health）** | `teamai dashboard` → Team Context / Team Improvement | 保留各类型覆盖率、高频召回与沉默条目、最近召回月份统计、作者贡献及维护控制台；完整 `/kb-report` 报告仍可访问。 |
-
-## 命令一览
-
-| 命令 | 说明 |
-|------|------|
-| `teamai init` | 初始化：OAuth 登录、关联仓库、注册成员、注入 hooks |
-| `teamai pull` | 拉取团队资源并注入到本地 AI 工具 |
-| `teamai push` | 推送本地资源到分支并创建合并请求 |
-| `teamai packages [install] [target]` | 安装团队 npm 包和 Claude 插件。裸 `teamai packages` 安装全部；`teamai packages install <target>` 添加单个并更新声明 |
-| `teamai status` | 显示本地与团队仓库的差异及资源数量，包含 namespace 下的技能和子目录中的文档 |
-| `teamai contribute` | 将 session 经验分享到团队仓库的 `teamai-learnings` 分支 |
-| `teamai recall <query>` | 搜索团队知识库（BM25 + 图谱增强） |
-| `teamai recall enable/disable/status` | 开关或查看 recall 状态 |
-| `teamai recall promote [learningId]` | 将高置信度 learning 晋升为正式知识（skills/rules/docs） |
-| `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)） |
-| `teamai source` | 管理 skill 订阅源（其他团队或本团队公共仓库） |
-| `teamai remove <type> <name>` | 删除资源并创建 MR |
-| `teamai session save` | 将脱敏后的 session 摘要记录到月度日志（`--push` 可喂给 `digest`） |
-| `teamai digest` | 生成团队周报 |
-| `teamai doctor` | 诊断配置问题（`--json` 输出 JSON，供 CI、hook 与 agent 消费）|
-| `teamai uninstall` | 移除所有 teamai 资源和 hooks |
+欢迎加入社区交流，也可以提 Issue 或 PR。开发流程见 [CONTRIBUTING.md](.github/CONTRIBUTING.md)。

 ## 许可证

 [MIT](LICENSE)
-
-## 贡献
-
-欢迎提交 PR！请先阅读 [CONTRIBUTING.md](.github/CONTRIBUTING.md)。
@@ -0,0 +1,190 @@
+# TeamAI Product Overview
+
+> [English](product-overview.md) | [简体中文](product-overview.zh-CN.md)
+
+This document explains TeamAI's product architecture, supported agents, and core capabilities. For setup and day-to-day workflows, see the [Usage Guide](usage-guide.md).
+
+---
+
+## Product architecture
+
+**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** (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
+
+<table>
+  <thead>
+    <tr>
+      <th rowspan="2">Agent</th>
+      <th colspan="7">Team Execution</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>
+      <th>learnings</th><th>codebase</th><th>teamwiki</th>
+      <th>usage</th><th>sessions</th><th>dashboard</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr><td>Claude Code</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>Codex</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>Cursor</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>GitHub Copilot CLI</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>CodeBuddy</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>WorkBuddy</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>OpenCode</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>OpenClaw</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>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>Kiro</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>
+    <tr><td>Oh My Pi</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>
+
+**Git providers** — GitHub · GitLab · GitCode · CNB · TGit · private Git service.
+
+### Distribution Controls
+
+Team-wide settings an admin configures once and delivers to every member on `teamai pull`:
+
+| 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](usage-guide.md#multi-project-project-as-a-dimension-orthogonal-to-role).
+
+## Team Execution
+
+> One Team. One Harness. Every Agent.
+
+TeamAI keeps skills, rules, docs, and hooks in a shared git repo and distributes them to every member's local AI tools through a "push → review & merge → pull" flow — with support for subscribing to other teams' or shared repos' Harness.
+
+### How It Works
+
+```
+teamai push → create branch + MR → reviewer approves + merges
+                                         ↓
+              SessionStart hook → teamai pull → synced to local AI tools
+```
+
+### What Gets Shared
+
+Each resource is delivered to every agent:
+
+| 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`, `agents/<namespace>/<name>.yaml` | Root agents reach everyone; a namespace directory ships only to roles/projects that list it under `agents:` |
+| **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` | Each hook may carry `roles:` to reach only members holding one of those roles |
+| **MCP** | `mcp/mcp.yaml` | Each server may carry `roles:` to reach only members holding one of those roles |
+| **Packages** | `teamai.yaml` | Currently npm packages and Claude Code plugins only |
+| **Models** | — | Not implemented for every provider yet |
+
+For file formats and full workflows, see the [Usage Guide](usage-guide.md).
+
+## Team Context (beta)
+
+> Every agent understands how the team works.
+
+Beyond distributing the Harness, TeamAI organizes accumulated team experience and code structure into a searchable knowledge base that the AI recalls automatically when needed.
+
+### Automatic Experience Sharing
+
+When a session ends, the Stop hook scores it by **friction** — signals that the session hit something worth remembering: you interrupted or corrected the AI, denied a tool call, or the AI had to retry failing tools. A long-but-routine session (lots of tool calls, no friction) does not trigger; a session where you actually fought a problem does. If the score is high enough, the AI suggests:
+
+```
+[teamai] This session may contain a problem worth documenting: you interrupted the AI twice, the AI retried failing tools 8 times.
+
+Task: Fix duplicate project-level Hook injection
+
+Consider running /teamai-share-learnings to summarize what you learned and share it with your team.
+```
+
+The hint names the non-zero friction signals that triggered it and, when available, includes a redacted, single-line summary of the first task. The `/teamai-share-learnings` skill summarizes the session and pushes a learning document directly to the team repo. Each session is prompted at most once. Teams can switch the hint off with `sharing.contributeHint.enabled: false` in `teamai.yaml` (members: `contributeHintEnabled` in local config) while keeping the rest of the Stop hook.
+
+### Team Knowledge Recall
+
+Let the AI automatically search accumulated team knowledge before a task. This feature is **off by default** and must be enabled explicitly — teams can set `sharing.recall.enabled: true` in `teamai.yaml` as the default, and members can override locally:
+
+```bash
+teamai recall enable     # on: deploy the teamai-recall subagent + inject guidance rules
+teamai recall disable    # off: remove the subagent and rules
+teamai recall status     # show effective state (team default + user override)
+```
+
+**Search runs via a subagent**: once enabled, `teamai pull` deploys the built-in `teamai-recall` subagent into each AI tool's `agents/` directory. The AI invokes it before a task — the subagent extracts keywords, runs the search, reads the matched source files, and returns a structured summary of team knowledge. The subagent first runs a relevance precheck (`teamai recall --check`) and skips retrieval entirely when the task is unrelated to team knowledge. Under the hood it shells out to the `teamai recall` command, which you can also run manually:
+
+```bash
+$ teamai recall "port conflict"
+[1/2] MR review caught a port-conflict bug ★1 [user]
+Author: member-a | Score: 18.5 | Tags: troubleshooting, networking
+
+[2/2] Deployment configuration best practices [project]
+Author: member-b | Score: 12.0 | Tags: deploy, config
+Matched: conflict | Missing: port
+```
+
+### Codebase Knowledge Graph
+
+`teamai import` parses source repos into a structured graph under `teamwiki/`, enabling structurally-aware retrieval:
+
+```bash
+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 --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.
+
+Edges come from two tracks that run together, with AST results taking precedence on overlap:
+
+- **AST track** (TypeScript/JavaScript, Python, Go): a WASM [tree-sitter](https://tree-sitter.github.io/) parser resolves `import`/`require`, call sites, and TS `implements` clauses to precise file-to-file `DEPENDS_ON` / `REFERENCES` / `IMPLEMENTS` edges (tagged `code-ast`, with confidence weights).
+- **Heuristic track** (all languages, including Java/Rust): regex-based extraction (tagged `code-heuristic`), which also covers languages the AST track does not.
+
+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 (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 — 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` | Unified Overview / Team Execution / Team Context / Team Improvement views with local live sessions, 7-day trends, estimated cost per session, English/Chinese, and light/dark/system themes. |
+| **KB Health** | `teamai dashboard` → Team Context / Team Improvement | Coverage by type, top-recalled and silent entries, last-recall month distribution, author contributions, and maintenance; the full `/kb-report` remains available. |
@@ -0,0 +1,190 @@
+# TeamAI 产品概览
+
+> [English](product-overview.md) | [简体中文](product-overview.zh-CN.md)
+
+本文介绍 TeamAI 的产品架构、Agent 支持范围和核心能力。安装与日常使用流程请参阅[使用指南](usage-guide.zh-CN.md)。
+
+---
+
+## 产品架构
+
+**Team Execution × Team Context (beta) × Team Improvement (beta)**：
+
+| 层 | 要解决的问题 | 当前 CLI 中的体现 |
+|----|--------------|-------------------|
+| **Team Execution** | 让每个 Agent 按团队的方式工作 | `init` / `pull` / `push`，skills、rules、agents、hooks、MCP、env |
+| **Team Context** (beta) | 让每个 Agent 理解整个团队 | recall、learnings、代码知识图谱、teamwiki... |
+| **Team Improvement** (beta) | 让每一次执行都成为团队能力的积累 | 基于摩擦信号的经验分享、sessions、digest、dashboard... |
+
+## 功能概览
+
+<table>
+  <thead>
+    <tr>
+      <th rowspan="2">Agent</th>
+      <th colspan="7">Team Execution</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>
+      <th>learnings</th><th>codebase</th><th>teamwiki</th>
+      <th>usage</th><th>sessions</th><th>dashboard</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr><td>Claude Code</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>Codex</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>Cursor</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>GitHub Copilot CLI</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>CodeBuddy</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>WorkBuddy</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>OpenCode</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>OpenClaw</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>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>Kiro</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>
+    <tr><td>Oh My Pi</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>
+
+**Git 托管平台** —— GitHub · GitLab · GitCode · CNB · TGit · 私有 Git 服务。
+
+### 分发策略
+
+管理员一次配置、随 `teamai pull` 分发给每位成员的团队级设置：
+
+| 能力 | 命令 | 作用 |
+|------|------|------|
+| **项目（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>/` 为项目私有。详见[使用指南](usage-guide.zh-CN.md#多项目project-作为与-role-正交的维度)。
+
+## Team Execution
+
+> One Team. One Harness. Every Agent.
+
+TeamAI 把 skills、rules、docs、hooks 统一存放在共享 Git 仓库，通过「push → 评审合并 → pull」的流程分发到每位成员的本地 AI 工具，并支持订阅其他团队或公共仓库的 Harness。
+
+### 工作原理
+
+```
+teamai push → 创建分支 + MR → reviewer 审批合并
+                                    ↓
+           SessionStart hook → teamai pull → 同步到本地 AI 工具
+```
+
+### 分发内容
+
+每类资源分发到每个 Agent：
+
+| 资源 | 团队仓库中的位置 | 备注 |
+|------|------------------|------|
+| **Skills** | `skills/<name>/SKILL.md` | |
+| **Rules** | `rules/*.md` | |
+| **Docs** | `docs/` | 项目基础文档，默认不全量加载（渐进式披露） |
+| **Agents** | `agents/<name>.yaml`、`agents/<namespace>/<name>.yaml` | 根目录 agents 对所有人生效；namespace 子目录只同步给在 `agents:` 中列出它的角色/项目 |
+| **Culture** | `culture.md` | 团队使命、价值观与协作准则——注入各 Agent 的 CLAUDE.md / AGENTS.md，成为每次会话的行事底色 |
+| **CLAUDE.md** | `claudemd/*.md` | |
+| **Env** | `env/` | 通用环境变量、团队级开关；不建议直接放密钥 |
+| **Hooks** | `hooks/hooks.yaml` | 每条 hook 可加 `roles:`，只分发给持有这些角色的成员 |
+| **MCP** | `mcp/mcp.yaml` | 每个 server 可加 `roles:`，只分发给持有这些角色的成员 |
+| **Packages** | `teamai.yaml` | 目前只支持 npm 包和 Claude 插件 |
+| **Models** | — | 暂时没有对全部 provider 实现 |
+
+文件格式与完整工作流见[使用指南](usage-guide.zh-CN.md)。
+
+## Team Context (beta)
+
+> Every agent understands how the team works.
+
+除了分发 Harness，TeamAI 还把团队沉淀的经验和代码结构组织成可检索的知识库，让 AI 在需要时自动召回。
+
+### 自动经验沉淀
+
+Session 结束时，Stop hook 按**摩擦信号**对 session 评分——这些信号表明本次 session 踩到了值得记录的东西：你打断或纠正了 AI、拒绝了某次工具调用，或 AI 反复重试出错的工具。又长又顺（工具调用很多但没有摩擦）的 session 不会触发；真正较劲过的 session 才会。达标后 AI 会显示如下英文提示：
+
+```
+[teamai] This session may contain a problem worth documenting: you interrupted the AI twice, the AI retried failing tools 8 times.
+
+Task: Fix duplicate project-level Hook injection
+
+Consider running /teamai-share-learnings to summarize what you learned and share it with your team.
+```
+
+提示会列出实际触发它的非零摩擦信号；如果能取得首个任务摘要，还会在脱敏、单行化后附上任务上下文。`/teamai-share-learnings` skill 自动总结 session 经验并推送到团队仓库。每个 session 最多提示一次。团队可在 `teamai.yaml` 设置 `sharing.contributeHint.enabled: false` 关闭该提示（成员可用本地配置 `contributeHintEnabled` 覆盖），Stop hook 的其余功能不受影响。
+
+### 团队知识检索
+
+让 AI 在执行任务前自动检索团队积累的知识。该功能**默认关闭**，需显式开启——团队可在 `teamai.yaml` 设 `sharing.recall.enabled: true` 作为默认值，成员也可本地覆盖：
+
+```bash
+teamai recall enable     # 开启：部署 teamai-recall 子 agent + 注入引导规则
+teamai recall disable    # 关闭：移除子 agent 和规则
+teamai recall status     # 查看生效状态（团队默认 + 用户覆盖）
+```
+
+**通过子 agent 检索**：开启后 `teamai pull` 会把内置的 `teamai-recall` 子 agent 部署到各 AI 工具的 `agents/` 目录。AI 在任务开始前调用它——由子 agent 提取关键词、执行检索、读取命中的源文件，最后返回结构化的团队知识摘要。subagent 会先做相关性预检（`teamai recall --check`），当任务与团队知识无关时直接跳过检索。子 agent 底层调用的仍是 `teamai recall` 命令，也可手动直接运行：
+
+```bash
+$ teamai recall "port conflict"
+[1/2] MR review caught a port-conflict bug ★1 [user]
+Author: member-a | Score: 18.5 | Tags: troubleshooting, networking
+
+[2/2] Deployment configuration best practices [project]
+Author: member-b | Score: 12.0 | Tags: deploy, config
+Matched: conflict | Missing: port
+```
+
+### 代码知识图谱
+
+`teamai import` 将源码仓库解析为 `teamwiki/` 下的结构化图谱，实现结构感知的检索：
+
+```bash
+teamai import --from-repo https://github.com/org/repo
+teamai import --from-org myorg              # 批量导入所有仓库
+teamai codebase --extract /path/to/repo     # 本地提取到 teamwiki/
+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 直接作为代码改动的入口，无需重新探索代码库。
+
+依赖边来自两条并行的提取轨道，重叠时以 AST 结果优先：
+
+- **AST 轨**（TypeScript/JavaScript、Python、Go）：使用 WASM 版 [tree-sitter](https://tree-sitter.github.io/) 解析器，将 `import`/`require`、调用点、以及 TS `implements` 子句解析为精确的文件到文件 `DEPENDS_ON` / `REFERENCES` / `IMPLEMENTS` 边（标记为 `code-ast`，带置信度权重）。
+- **启发式轨**（所有语言，含 Java/Rust）：基于正则的提取（标记为 `code-heuristic`），同时覆盖 AST 轨未支持的语言。
+
+WASM 解析器是纯 JavaScript 依赖，无需任何原生编译工具链。若因任何原因加载失败，提取会降级到启发式轨并记录一条 `AST_UNAVAILABLE` gap。设置 `TEAMAI_SKIP_AST=1` 可强制仅使用启发式提取。
+
+## 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` | 团队周报——近 7 天成功率、对话、活跃时长、估算成本、缓存与纠偏趋势，以及历史累计数据。 |
+| **会话（Sessions）** | `teamai session save` | 脱敏的单会话摘要（工具序列、对话轮次、干预次数），喂给周报的 Session Highlights。 |
+| **看板（Dashboard）** | `teamai dashboard` | 统一的 Overview / Team Execution / Team Context / Team Improvement 界面，保留本机实时会话、近 7 天趋势、每会话估算费用，支持中英文及日间/夜间/跟随系统主题。 |
+| **知识库健康（KB Health）** | `teamai dashboard` → Team Context / Team Improvement | 保留各类型覆盖率、高频召回与沉默条目、最近召回月份统计、作者贡献及维护控制台；完整 `/kb-report` 报告仍可访问。 |
@@ -27,6 +27,7 @@
 - [Commit Co-Author Attribution](#commit-co-author-attribution)
 - [Team Culture](#team-culture)
 - [Advanced Features](#advanced-features)
+- [Command Reference](#command-reference)
 - [Configuration Reference](#configuration-reference)
 - [Uninstall](#uninstall)
 - [FAQ](#faq)
@@ -1704,6 +1705,40 @@ An HTTP source reports status and pulls skill commands via hook dispatch on ever

 ---

+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `teamai init` | Initialize: OAuth login, link repo, register member, inject hooks |
+| `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 and resource counts, including namespaced skills and nested docs |
+| `teamai contribute` | Share session experience to the team repo's `teamai-learnings` branch |
+| `teamai recall <query>` | Search the team knowledge base (BM25 + graph-boost) |
+| `teamai recall enable/disable/status` | Toggle or check recall state |
+| `teamai recall promote [learningId]` | Promote a high-confidence learning to formal knowledge (skills/rules/docs) |
+| `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](#excluding-skills-you-dont-need)) |
+| `teamai source` | Manage skill subscription sources (other teams or your org's shared repos) |
+| `teamai remove <type> <name>` | Remove a resource and open MR |
+| `teamai session save` | Record a privacy-scrubbed session summary to a monthly log (`--push` feeds `digest`) |
+| `teamai digest` | Generate weekly team usage digest |
+| `teamai doctor` | Diagnose configuration issues (`--json` for CI, hooks and agents) |
+| `teamai uninstall` | Remove all teamai resources and hooks |
+
+---
+
 ## Configuration Reference

 ### teamai.yaml (remote team config)
@@ -27,6 +27,7 @@
 - [提交 Co-Author 署名](#提交-co-author-署名)
 - [团队文化](#团队文化)
 - [进阶功能](#进阶功能)
+- [命令参考](#命令参考)
 - [配置文件参考](#配置文件参考)
 - [卸载](#卸载)
 - [常见问题 FAQ](#常见问题-faq)
@@ -1652,6 +1653,40 @@ HTTP 源通过 hook dispatch 在每次 session 中上报状态并拉取 skill

 ---

+## 命令参考
+
+| 命令 | 说明 |
+|------|------|
+| `teamai init` | 初始化：OAuth 登录、关联仓库、注册成员、注入 hooks |
+| `teamai pull` | 拉取团队资源并注入到本地 AI 工具 |
+| `teamai push` | 推送本地资源到分支并创建合并请求 |
+| `teamai packages [install] [target]` | 安装团队 npm 包和 Claude 插件。裸 `teamai packages` 安装全部；`teamai packages install <target>` 添加单个并更新声明 |
+| `teamai status` | 显示本地与团队仓库的差异及资源数量，包含 namespace 下的技能和子目录中的文档 |
+| `teamai contribute` | 将 session 经验分享到团队仓库的 `teamai-learnings` 分支 |
+| `teamai recall <query>` | 搜索团队知识库（BM25 + 图谱增强） |
+| `teamai recall enable/disable/status` | 开关或查看 recall 状态 |
+| `teamai recall promote [learningId]` | 将高置信度 learning 晋升为正式知识（skills/rules/docs） |
+| `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（[使用指南](#排除个人不需要的-skill)） |
+| `teamai source` | 管理 skill 订阅源（其他团队或本团队公共仓库） |
+| `teamai remove <type> <name>` | 删除资源并创建 MR |
+| `teamai session save` | 将脱敏后的 session 摘要记录到月度日志（`--push` 可喂给 `digest`） |
+| `teamai digest` | 生成团队周报 |
+| `teamai doctor` | 诊断配置问题（`--json` 输出 JSON，供 CI、hook 与 agent 消费）|
+| `teamai uninstall` | 移除所有 teamai 资源和 hooks |
+
+---
+
 ## 配置文件参考

 ### teamai.yaml（远端团队配置）