teamai-cli 0.25.0-beta.6 → 0.25.0

package/README.md

@@ -23,15 +23,11 @@
 
 TeamAI turns individual AI capabilities into shared team capabilities — across agents, machines, and team members.
 
-## Contributors
-
-Thanks to everyone who has contributed to TeamAI!
-
-<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
-</a>
+## Why TeamAI
 
-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.
-
-## 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](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
+## Learn More
 
-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:
+- [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
 
-```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)
+## Contributors
 
-> Every execution makes the entire team smarter.
+Thanks to everyone who has contributed to TeamAI!
 
-### Maintenance
+<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
+</a>
 
-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:
+Made with [contrib.rocks](https://contrib.rocks).
 
-```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
-```
+## Contributing
 
-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.