teamai-cli 0.25.0-beta.2 → 0.25.0-beta.3

package/skills/teamai/references/setup-admin.md

@@ -0,0 +1,328 @@
+# Scenario: Admin — set up a new team repo from scratch
+
+Goal: the user becomes the first admin of a brand-new TeamAI team. At the end they
+have a working team repo URL to share with members.
+
+Run the commands yourself. Only stop to ask when a step says "ASK".
+
+## Step 1 — Install and verify
+
+```bash
+npm install -g teamai-cli
+teamai --version
+```
+
+If `teamai --version` fails, Node.js ≥ 20 is missing. Tell the user to install
+Node 20+ (from https://nodejs.org), then retry. Do not continue until the version
+prints.
+
+## Step 2 — Pick a Git platform (only when the user gave NO repo URL)
+
+If the user already gave a full repo URL, skip to Step 4. Otherwise, TeamAI needs a
+place to store the team's skills/rules. The user does not need to know Git. Work
+through these sub-steps **in order**:
+
+### 2a — Ask which platform they know
+
+**Tencent-internal first:** before asking, probe whether this machine is on the
+Tencent corporate network — a request to `git.woa.com` that returns the header
+`x-env: tgit` means Tencent TGit (工蜂) is reachable:
+
+```bash
+curl -sS -m 3 -D - -o /dev/null https://git.woa.com 2>/dev/null | grep -qi '^x-env:[[:space:]]*tgit' && echo "tgit: OK" || echo "tgit: unreachable"
+```
+
+If it prints `tgit: OK`, **list Tencent TGit (工蜂) first** and prefer it —
+TeamAI supports it natively as the `tgit` provider (it detects `git.woa.com` on
+its own; you install `gf` and log in in Step 3). Then ask:
+*"Have you heard of / do you have an account on any of these — Tencent TGit
+(工蜂), GitHub, GitLab, or CNB (cnb.cool)?"*
+
+- **Tencent TGit (工蜂)** — https://git.woa.com (Tencent-internal only; shown
+  first when the probe above says `tgit: OK`)
+- **GitHub** — https://github.com
+- **GitLab** — https://gitlab.com (or a self-hosted company GitLab)
+- **CNB** — https://cnb.cool
+
+If they name one, use that platform and go to sub-step 2c.
+
+### 2b — If they've heard of NONE, auto-probe reachability
+
+Test which sites this network can actually reach (probe each, ~3s timeout each).
+The TGit probe checks the `x-env: tgit` header, not just reachability:
+
+```bash
+curl -sS -m 3 -D - -o /dev/null https://git.woa.com 2>/dev/null | grep -qi '^x-env:[[:space:]]*tgit' && echo "tgit: OK" || echo "tgit: unreachable"
+curl -sSf -m 3 -o /dev/null https://github.com  && echo "github: OK"  || echo "github: unreachable"
+curl -sSf -m 3 -o /dev/null https://gitlab.com  && echo "gitlab: OK"  || echo "gitlab: unreachable"
+curl -sSf -m 3 -o /dev/null https://cnb.cool     && echo "cnb: OK"     || echo "cnb: unreachable"
+```
+
+- **TGit reachable (`tgit: OK`)** → prefer Tencent TGit (工蜂); it is the
+  Tencent-internal default.
+- **Exactly one reachable** → use that one.
+- **Several reachable** → list them (TGit first when present) and let the user pick.
+- **None reachable** → stop. Tell the user to ask their own admin for a ready-made
+  repo URL, then switch to `join-member.md`.
+
+Choose by **account + reachability only — never by region**.
+
+### 2c — Give the sign-up / create link and let them create the project
+
+Once the platform is decided, hand the user the direct link to sign in and create
+the repository, then continue to the next step:
+
+| Platform | Sign in / sign up            | Create a new repo (do this)        |
+|----------|------------------------------|------------------------------------|
+| Tencent TGit (工蜂) | https://git.woa.com | https://git.woa.com/projects/new |
+| GitHub   | https://github.com/login     | https://github.com/new             |
+| GitLab   | https://gitlab.com/users/sign_in | https://gitlab.com/projects/new |
+| CNB      | https://cnb.cool             | https://cnb.cool/new/repos (org first: https://cnb.cool/new/groups) |
+
+> **Tencent TGit (工蜂):** **prefer letting `teamai init` create the repo for you**
+> in Step 5 — don't send the user to the browser first. Once you are logged in
+> (Step 3), init creates the repo under the chosen owner via the API. Only fall
+> back to https://git.woa.com/projects/new if init reports it can't (e.g. the
+> group/namespace doesn't exist, or you lack create permission). git.woa.com is
+> Tencent-internal only.
+
+Tell the user to sign in, create an **empty** repo (suggested name
+`TeamAi-<team-name>`), and give you the resulting repo URL. Explain in one
+sentence: *"The repo on the website is where the team's skills and rules live; your
+computer only holds a synced copy — you never put business code in it."*
+
+> You may instead let `teamai init` create the repo from the CLI in Step 5 (it
+> offers to create a missing repo on GitHub/GitLab). Creating it in the browser
+> first is the simplest path for a user who does not know Git, and is required on
+> CNB (see the CNB caveat in Step 5).
+
+## Step 3 — Log in from the CLI
+
+Signing in on the website (Step 2c) is not enough — `teamai init` also needs the
+platform's CLI credentials. Have the user complete the matching CLI login:
+
+### Tencent TGit (工蜂) — YOU run gf install and login; user only clicks approve
+
+TeamAI supports git.woa.com natively as the `tgit` provider (it recognizes the
+host on its own — no `GITLAB_URL` needed). **Run every command below yourself** —
+both the install and the login. **Never tell the user to run a `gf` command.** The
+user's only action is approving the login in their browser / iOA when it opens.
+
+**1. Install `gf` (you run this)** using the **same source, path, and check teamai
+uses** — do not invent your own URL. `${TEAMAI_HOME}` is `~/.teamai` unless
+overridden:
+
+```bash
+# pick the tarball for this machine's OS/arch (darwin|linux × x64|arm64)
+os=$(uname -s | tr '[:upper:]' '[:lower:]')          # darwin | linux
+arch=$(uname -m); [ "$arch" = "x86_64" ] && arch=x64; [ "$arch" = "aarch64" ] && arch=arm64
+dir="${TEAMAI_HOME:-$HOME/.teamai}/gf"
+
+# download + extract from the Tencent-internal mirror (same URL teamai uses)
+mkdir -p "$dir"
+curl -fsSL "http://mirrors.tencent.com/repository/generic/gongfeng-cli/files/channels/stable/gf-${os}-${arch}.tar.gz" | tar xz -C "$dir"
+
+# verify exactly as teamai does: the binary exists and is executable
+test -x "$dir/gf/bin/gf" && echo "gf installed OK" || echo "gf install FAILED"
+```
+
+Only macOS and Linux, on x64 or arm64, are supported.
+
+**2. Log in (you run this too — don't hand it to the user):**
+
+```bash
+"${TEAMAI_HOME:-$HOME/.teamai}/gf/gf/bin/gf" auth login
+```
+
+`gf auth login` starts an interactive flow offering three ways to sign in — iOA, a
+browser device code, or pasting a token. Pick the browser/iOA option, relay
+whatever URL / device code it prints to the user, and ask them to approve it in
+their browser — that approval is the *only* thing they do; the command finishes on
+its own once they do. Confirm with
+`"${TEAMAI_HOME:-$HOME/.teamai}/gf/gf/bin/gf" auth whoami` before continuing.
+
+(Headless/CI only: skip the interactive login and pre-set `TGIT_TOKEN` — a
+git.woa.com Personal Access Token — instead.)
+
+### CNB — install the CLI, authorize, then read the repo (in this order)
+
+Once the user has created their repo on cnb.cool and given you the URL, do these
+three steps **in order**:
+
+1. **Install the CNB CLI** (needed to talk to cnb.cool):
+   ```bash
+   npm install -g @cnbcool/cnb-cli
+   ```
+   (`teamai init` also installs it automatically if it is missing, but running it
+   here first makes the next step predictable.)
+2. **Ask the user to authorize.** Start the login and have them approve it in the
+   browser (OAuth2 device flow):
+   ```bash
+   cnb login
+   ```
+   Wait for them to confirm they finished authorizing before continuing.
+3. **Then read their repo** — proceed to Step 4/5 (`teamai init <their CNB URL>`),
+   which can now clone and read the repo with the authorized CLI.
+
+(Headless/CI alternative: set `CNB_TOKEN` instead of `cnb login`.)
+
+### GitHub
+
+```bash
+gh auth login
+```
+
+### GitLab (gitlab.com)
+
+Set a Personal Access Token with `api` scope:
+```bash
+export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxx
+```
+Self-hosted GitLab: also set the instance URL first —
+`export GITLAB_URL=https://git.example.com`.
+
+For GitHub/GitLab, `teamai init` installs any helper CLI it needs automatically.
+
+## Step 4 — Decide the scope (ASK)
+
+One choice — project-only or whole machine?
+
+- Default (project): resources land in the current project's `.claude/` etc.
+  `cd` into the project first.
+- Whole machine: add `--scope user` so every project gets the team resources.
+
+(The repo name was already chosen when the user created the repo in Step 2c —
+suggested form `TeamAi-<team-name>`.)
+
+## Step 5 — Initialize (you run it)
+
+Use the **full URL**, never `owner/repo`:
+
+```bash
+# project scope (default) — run from inside the project directory
+teamai init https://<platform>/<org>/<repo-name>
+
+# or whole machine
+teamai init https://<platform>/<org>/<repo-name> --scope user
+```
+
+If the repo does not exist yet, `init` offers to create it — accept the prompt.
+
+- **Tencent TGit (工蜂):** `gf` and login are already done (Step 3), so init goes
+  straight to creating/cloning. When the repo doesn't exist, **accept the create
+  prompt and init creates it via the API** — no browser needed. It only sends you
+  to https://git.woa.com/projects/new if the group/namespace is missing or you
+  lack create permission. No `GITLAB_URL`.
+- **CNB caveat:** a `cnb login` token **cannot create** an org or repo — that is
+  exactly why the CNB flow has the user create the repo on the website first
+  (Step 2c). If the org/repo is still missing here, `init` prints web links
+  (`https://cnb.cool/new/groups`, `https://cnb.cool/new/repos`) — have the user
+  create them in the browser, then re-run `teamai init`. By this step the CNB CLI
+  should already be installed and authorized (Step 3). (A `CNB_TOKEN` with
+  `group-manage:rw` + `group-resource:rw` lets the CLI create them directly.)
+- **GitHub caveat:** if a push later fails, check the repo's default branch is
+  `main` (not `master`).
+- If `init` detects an unknown GitLab host, it stops and asks you to set
+  `GITLAB_URL` + `GITLAB_TOKEN`, then retry.
+
+If the repo has roles enabled, `init` may ask for a primary role — pick one with
+the user, or pass `--role <id>` for a non-interactive run.
+
+**Which AI tools to set up — all of them by default (global rule 9).** Do not add
+`--agent` to restrict the install unless the user explicitly said to (e.g. "only
+Claude Code"). Omitting `--agent` gives an interactive picker — select **every AI
+tool already installed** on the machine. Then **report back which agents were set
+up**, in the user's language: name the tools that will now auto-start TeamAI, and
+any detected tool that was skipped and why (e.g. Codex trust-gate,
+CodeBuddy/WorkBuddy by design — see `troubleshooting.md`).
+
+## Step 6 — Verify with doctor
+
+```bash
+teamai doctor
+teamai hooks list      # per-tool: which AI tools actually got the hooks
+```
+
+Resolve everything `doctor` flags before continuing.
+
+**Do not trust the "Hooks injected into all AI tool settings" message on its own.**
+That line prints even for tools where nothing was written. Use `teamai doctor` /
+`teamai hooks list` to see the real per-tool status. It is expected that only the
+tool you set up with `--agent` (e.g. `claude`) shows the hooks installed; several
+other tools are skipped by design or not yet supported — this is CLI behaviour, not
+a broken setup. See `troubleshooting.md` ("Which tools actually get hooks") before
+worrying about a tool that shows as missing.
+
+## Step 7 — Grant members repo access (required before they can join)
+
+TeamAI has **no permission model of its own** — it rides the Git platform's
+access control. After you initialize the repo, **each member must be granted
+read/write access to it on the platform website**, or their `teamai init` / `pull`
+/ `push` will fail with a permission error.
+
+Tell the admin (in their language) to add every member on the repo's website:
+
+- **Tencent TGit (工蜂):** repo → 成员管理 / Members → add each member with at
+  least **Developer** (read/write) access.
+- **GitHub:** repo → Settings → Collaborators → add with **Write**.
+- **GitLab:** repo → Settings → Members → add with **Developer** or above.
+- **CNB:** repo → members → grant read/write.
+
+Do this **before** handing off the invite line below — otherwise the member hits a
+"permission denied / can't clone" error on their very first step.
+
+## Step 8 — Hand off to members
+
+Everything you show here goes **in the user's language** (global rule 1). Only the
+`/teamai …` line, URLs, and commands stay verbatim.
+
+**First, reassure them about privacy** (say this in their language): *"TeamAI does
+not send any of your session data to third parties. The only place anything is
+reported is the team repo you just set up — usage counts and knowledge go there,
+and raw conversation content is never uploaded."* (Team reporting is opt-in and
+carries counts + tool names only, on a separate branch of that same repo.)
+
+1. Give the user their **repo web URL** to share.
+2. Give them a ready-to-forward invite line **written in their language**, with the
+   URL filled in. The `/teamai` prefix stays as-is; translate the rest. For a
+   Chinese-speaking user, that is:
+   `/teamai 帮我加入团队的 TeamAI，仓库地址是 <URL>`
+   (English user: `/teamai Help me join my team's TeamAI, repo URL is <URL>`.)
+   Tell them to send the URL + this line to each member.
+3. Remind them (in their language): **new resources appear only after opening a
+   fresh session** in the AI tool. Right after init the skills folder may look
+   empty — that is expected. To sync now, run `teamai pull`.
+
+## Step 9 — What's next (guide them, don't just list commands)
+
+Wrap up **in the user's own language** (global rule 1).
+
+The user may not be comfortable with the command line, so **don't just hand them a
+list of `teamai …` commands.** Instead, point them back to *this skill* for
+day-to-day work — they can keep letting the AI run things for them:
+
+- To manage the team later, they run:
+  `/teamai 我已经装好了，帮我管理` (Chinese) /
+  `/teamai I already have TeamAI set up, help me manage it` (English) — this loads
+  the daily-management flow (`manage-admin.md`): publishing skills, inviting
+  members, roles / packages / env.
+- To share something they learned:
+  `/teamai 我想把学到的经验分享给团队` /
+  `/teamai I want to contribute what I learned to my team`.
+
+Mention the underlying commands (`teamai push`, `teamai roles`, …) only as a note
+for users who *do* want them — the primary path is re-invoking `/teamai`.
+
+## Step 10 — Tell them how to leave (via the skill, not raw commands)
+
+Finish by telling the user, **in their language**, that they can remove TeamAI any
+time — and that they don't need the command line to do it. They just re-invoke the
+skill and you'll handle it:
+
+`/teamai 卸载` (Chinese) / `/teamai Uninstall TeamAI` (English)
+
+One line, in their language: *"That removes the hooks and synced resources from
+your machine; your team repo on the website is untouched — you can rejoin any time
+with `/teamai` and the repo URL."*
+
+(If they ask right now, load `uninstall.md` and run it for them.)

package/skills/teamai/references/troubleshooting.md

@@ -0,0 +1,133 @@
+# Troubleshooting & Agent-specific caveats
+
+Load this whenever a step fails, `teamai doctor` flags something, or team
+resources don't show up. It is shared by all four scenarios.
+
+## First move: run doctor
+
+```bash
+teamai doctor
+```
+
+It checks provider config, hooks, paths, and package/plugin status. Fix what it
+reports before anything else.
+
+## "My skills / rules aren't showing up"
+
+This is the #1 onboarding issue. In order:
+
+1. **Open a fresh session.** Resources sync on **session start** via a hook, not
+   at init time. An empty skills folder right after `teamai init` is normal.
+2. **Sync manually to confirm:**
+   ```bash
+   teamai pull
+   teamai list        # do the team skills appear now?
+   ```
+3. **Check the hook is installed** (`teamai doctor` reports this). If missing,
+   re-inject and reopen the tool:
+   ```bash
+   teamai hooks inject
+   ```
+4. **Wrong scope?** Project-scope hooks are written to your HOME tool settings
+   (e.g. `~/.claude/settings.json`), not the project folder — that is intentional.
+   If you initialized project scope but expected machine-wide resources, re-run
+   with `--scope user`.
+5. **Tool has no hook surface** (e.g. Gemini CLI, JoyCode): there is no auto-sync;
+   run `teamai pull` manually each time.
+
+## Permission / access denied
+
+`init`, `pull`, or `push` failing with a permission error usually means the user
+has not been granted access to the team repo on the Git platform. Have them copy
+the **exact** error text to their admin, who adds them on the platform website.
+
+## GitHub push fails
+
+Check the team repo's default branch is `main` (not `master`). A stale `master`
+default is a common cause.
+
+## GitLab host not detected
+
+If `init` can't confirm a self-hosted GitLab instance, set both and retry:
+
+```bash
+export GITLAB_URL=https://git.example.com
+export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxx   # api scope
+teamai init https://git.example.com/yourgroup/yourrepo
+```
+
+## Which tools actually get hooks
+
+`teamai hooks inject` always prints **"Hooks injected into all AI tool settings"**,
+even for tools where it wrote nothing. **Do not take that line as proof.** Verify
+per-tool instead:
+
+```bash
+teamai doctor          # flags tools whose hooks are missing
+teamai hooks list      # per-tool status + the settings file it checked
+```
+
+What you will typically see, and why (this is expected CLI behaviour, **not** a
+broken machine):
+
+| Tool                  | Hooks status              | Why                                                                 |
+|-----------------------|---------------------------|---------------------------------------------------------------------|
+| Claude Code (`claude`)| Installed                 | Fully supported — this is the main, working path                    |
+| Codex                 | Written but **trust-gated** or skipped | Codex gates non-managed hooks behind an explicit trust step; `teamai doctor` prints a reminder to trust them |
+| Cursor                | Often not written         | Uses its own hook mechanism; broader CLI support is still pending   |
+| CodeBuddy / WorkBuddy | Skipped **by design**     | They only accept versioned plugins (`plugin@version`); teamai writes raw entries into a `hooks` field, which they don't take |
+
+Practical rule: if you set up with `--agent claude`, expect **only** Claude to show
+hooks installed. A tool you are not using, or one that is not a supported hook
+target, showing "missing" is normal — the Claude path is intact. For a tool where
+hooks did not land but you do use it, run `teamai pull` manually each session, and
+see the caveats below.
+
+## Agent-specific caveats
+
+Different AI hosts handle the hooks that TeamAI injects differently. When this
+conversation runs in one of these, proactively walk the user through the extra
+step — do not assume auto-sync just works.
+
+### Codex
+
+Codex gates non-managed hooks behind an explicit **trust** step. `teamai init` /
+`teamai hooks inject` may write the hooks, but Codex won't run them until the user
+trusts them (`teamai doctor` prints a reminder when it detects this). Guide the
+user to trust the teamai hooks in Codex, then reopen a session. Until then, run
+`teamai pull` manually.
+
+### Cursor
+
+Cursor uses its own hook mechanism and may not receive teamai's hooks yet. If
+`teamai hooks list` shows Cursor without hooks, treat it as a manual-sync tool: run
+`teamai pull` at the start of each session.
+
+### ChatGPT App
+
+Hooks injected by `teamai init` are **untrusted by default** in the sandbox. The
+user must **manually trust the hooks in ChatGPT's settings** before they run.
+Guide them to the settings, have them trust/enable the TeamAI hooks, then reopen a
+session and verify with `teamai pull` + `teamai list`.
+
+### WorkBuddy
+
+The sandbox **does not add hooks automatically** after `teamai init`. The user
+must **manually edit the config file to register the hook** so auto-sync works.
+Walk them through opening the tool's config and adding the TeamAI session-start
+hook entry; if unsure of the exact config, run `teamai doctor` and `teamai hooks`
+to see what should be present, then have them replicate it. Until then, they can
+sync with a manual `teamai pull`.
+
+### Tools without a writable hook surface
+
+Gemini CLI, JoyCode, and similar tools have no TeamAI-writable hook surface —
+there is no auto-sync. Tell the user to run `teamai pull` manually at the start of
+each session.
+
+## Still stuck
+
+- Re-run the failing command with `-v` / `--verbose` for detail.
+- `teamai status` shows exactly how local differs from the team repo.
+- Report unexpected behavior at https://github.com/Tencent/teamai-cli/issues
+  with the agent name, platform, and the step that failed.

package/skills/teamai/references/uninstall.md

@@ -0,0 +1,57 @@
+# Scenario: Uninstall — remove TeamAI from this machine
+
+The user wants to remove TeamAI. **You run the command for them** — they should not
+have to type `teamai uninstall` themselves. Everything you say goes in the user's
+language (global rule 1); only the commands stay verbatim.
+
+## Step 1 — Confirm scope first (ASK — this is destructive)
+
+Uninstalling removes hooks and synced resources from the machine and cannot be
+undone with a single button, so confirm before running anything. Ask ONE question:
+
+*"Do you want to remove TeamAI from **just this AI tool**, or from the **whole
+machine** (all tools)?"*
+
+- **Just this tool** → `--agent <tool>` (use the tool this conversation runs in,
+  e.g. `claude`). Shared resources are removed only if it is the last tool using
+  them.
+- **Whole machine** → no `--agent` flag.
+
+Reassure them (in their language): *"This only removes things from your computer.
+Your team's repo on the website is untouched — you can rejoin any time with
+`/teamai` and the repo URL."*
+
+## Step 2 — Run it (you run it)
+
+Whole machine:
+
+```bash
+teamai uninstall
+```
+
+Just the current tool (example for Claude Code):
+
+```bash
+teamai uninstall --agent claude
+```
+
+`teamai uninstall` asks for a confirmation of its own. Let the user answer that
+prompt. Only add `--force` (skips the prompt) if the user has already clearly told
+you to go ahead without further confirmation:
+
+```bash
+teamai uninstall --force
+```
+
+## Step 3 — Report the result in the user's language
+
+Tell them what was removed and remind them, in one line, how to come back:
+*"Done — TeamAI has been removed from this machine. To rejoin later, run `/teamai`
+and give it your team repo URL."*
+
+## Notes
+
+- Do **not** delete the team repo on the Git platform — uninstall never touches it,
+  and neither should you.
+- If the user only wants to stop auto-sync for one tool but keep TeamAI otherwise,
+  that is the `--agent <tool>` form, not a full uninstall.

package/skills/teamai-share-learnings/SKILL.md

@@ -82,6 +82,6 @@ teamai contribute --file /tmp/session-summary.md --title "K8s pod 启动超时
 ## Important
 
 - Run this as a **sub-agent** (Agent tool) to avoid polluting the main session's context
-- The document is pushed directly to master in the team repo's `learnings/` directory
+- The document is pushed to the team repo's `teamai-learnings` branch, under `learnings/`, with no pull request
 - Team members will see it on their next `teamai pull`
 - Keep summaries concise and actionable — this is a knowledge base, not a diary