@team-ai/teamai-cli 0.0.0-stage → 0.22.2

package/skill-data/setup/references/setup-admin.md

@@ -0,0 +1,312 @@
+# 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 TGit is reachable
+on this machine — see `{SKILL_DIR}/references/provider-tgit.md` ("Probe
+reachability") for the one-line `x-env: tgit` check. If it says `tgit: OK`, **list Tencent TGit first** and
+prefer it. 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 (see
+`{SKILL_DIR}/references/provider-tgit.md`); the others just check 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 `{SKILL_DIR}/references/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:** don't send the user to the browser to create the repo —
+> prefer letting `teamai init` create it via the API in Step 5. See
+> `{SKILL_DIR}/references/provider-tgit.md` ("When you `teamai init` on TGit").
+
+Tell the user to sign in, create an **empty** repo (suggested name
+`<team-name>-teamai`), 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
+
+See `{SKILL_DIR}/references/provider-tgit.md` ("Log in") — you install `gf` and
+run `gf auth login` yourself; the user only approves in the browser / iOA. No `GITLAB_URL` needed.
+Then return here for Step 4.
+
+### 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 — YOU run the login; user only clicks approve
+
+**Don't hand the user a `gh` command to run** — you run the login, they only approve
+it in the browser. Log them in before `teamai init`:
+
+```bash
+gh auth login --web --git-protocol https
+```
+
+The flow prints a one-time code and a `https://github.com/login/device` URL.
+**Relay both to the user and ask them to open that URL and approve** — that approval
+is the *only* thing they do; the command finishes on its own once they do. Confirm
+with `gh auth status` before continuing.
+
+(Headless/CI only: skip the interactive login and pre-set `GITHUB_TOKEN` — a token
+with `repo` scope — instead.)
+
+### GitLab (gitlab.com)
+
+Set a Personal Access Token with `api` scope. Prefer a **short-lived** token and
+pull it from a secret manager or a no-echo prompt rather than typing the literal
+value (a pasted `export` lands in shell history and process listings):
+```bash
+read -rs GITLAB_TOKEN && export GITLAB_TOKEN   # paste when prompted; not echoed
+```
+Self-hosted GitLab: also set the instance URL first —
+`export GITLAB_URL=https://git.example.com`. Run `unset GITLAB_TOKEN` when
+`teamai init` is done.
+
+For GitHub/GitLab, `teamai init` installs any helper CLI it needs automatically.
+
+## Step 4 — Decide the scope (ASK)
+
+One choice — this workspace or the whole machine?
+
+- Default (workspace): resources land in the current workspace's `.claude/` etc.
+  `cd` into the workspace first.
+- Whole machine: add `--scope user` so every project gets the team resources.
+- A folder holding several repos (a workspace): set up each repo, then run the
+  same `init` in the folder. It also receives what each repo inside selects.
+
+(The repo name was already chosen when the user created the repo in Step 2c —
+suggested form `<team-name>-teamai`.)
+
+## Step 5 — Initialize (you run it)
+
+Use the **full URL**, never `owner/repo`:
+
+Ask whether the user wants to activate any logical projects this team repo
+declares. If `init` lists **Available projects**, show the names/IDs and ask
+which belong to this setup; enter the corresponding comma-separated numbers.
+Press Enter for none only when the user explicitly chooses no project. If the
+IDs are already known, pass `--project id1,id2` to skip the picker. For a
+non-interactive run, ask first and pass `--project`: without it, init keeps
+`projects: []` and prints a `teamai projects set <id>` follow-up instead of
+waiting for a choice.
+
+```bash
+# workspace 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, so init creates the
+  repo via the API when it's missing — see
+  `{SKILL_DIR}/references/provider-tgit.md` ("When you `teamai init` on TGit").
+- **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` asks for one or more comma-separated role
+numbers when running interactively. The first number is the primary role and the
+remaining numbers become additional roles; pass `--role <id>` for a
+non-interactive run when only a primary role is needed. Without a terminal (or
+with `CI` / `TEAMAI_NONINTERACTIVE` set) `init` never waits: a provider that
+would need a browser login fails at once and names the credential to prepare —
+a token for GitHub / CNB / GitLab / GitCode, and for TGit a prior `gf auth
+login` run in an interactive shell (see Step 3).
+
+**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. CodeBuddy/WorkBuddy by design),
+and any installed hooks that still need trust (e.g. Codex with automatic trust
+disabled or unavailable). See the troubleshooting reference, `"$(teamai skill path core)/references/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.
+
+**Don't trust the "Hooks injected into all AI tool settings" message on its own** —
+it prints even for tools where nothing was written. `teamai doctor` / `teamai hooks
+list` show the real per-tool status. Only the tool you set up (e.g. `claude`) is
+expected to show hooks installed; others are skipped by design or not yet supported,
+which is normal. Full table in the troubleshooting reference
+(`"$(teamai skill path core)/references/troubleshooting.md"`), section "Which tools actually get hooks".
+
+## Step 7 — Grant members branch access (required before they can join)
+
+TeamAI uses the Git host's access control. After the repo exists, each member
+needs permission to clone it and to push branches. Leave the default branch
+protected. They open pull requests against it.
+
+`teamai push` pushes a feature branch and opens a pull request. Reports and
+learnings use the branches `teamai-reports` and `teamai-learnings`.
+
+Do this before handing off the invite line below. Without branch access,
+`teamai init` or `teamai push` fails with a permission error.
+
+## 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:
+   `/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): a member's `teamai init` does not copy team
+   resources. They arrive on the next session start, or when the member runs
+   `teamai pull`. In workspace scope, init creates a tool directory only for a tool
+   named with `--agent` or picked in init's tool picker; otherwise that directory
+   appears when the member first opens that tool in the project. Resources the
+   team adds later arrive at the next session start.
+
+## 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 (in their language):
+  `/teamai I already have TeamAI set up, help me manage it` — this loads
+  the daily-management flow (`{SKILL_DIR}/references/manage-admin.md`): publishing skills, inviting
+  members, roles / packages / env.
+- To share a reusable skill with the team, they run (in their language):
+  `/teamai Share this <skill-name> skill with my team` — see
+  `"$(teamai skill path core)/references/contribute-member.md"`.
+- Sharing a **session's learnings** needs no command from them: TeamAI prompts on
+  its own at the end of a session worth sharing, and the `share` workflow
+  (`teamai skill get share`) takes over. (Only once recall is on — off by default;
+  turn it on team-wide with `sharing.recall.enabled: true` in `teamai.yaml`, then
+  `teamai push`. Never on a read-only HTTP source, or while a member's teamai
+  config cannot be loaded. A team that works in English also sets `language: en`
+  in that file so the recall rule and the TodoWrite and merged-MR hints are
+  English only; omit it, or set `zh`, to keep the historical bilingual text.)
+
+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 Uninstall TeamAI` (in their language; the `/teamai` prefix stays as-is)
+
+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 `{SKILL_DIR}/references/uninstall.md` and run it for them.)

package/skill-data/setup/references/uninstall.md

@@ -0,0 +1,180 @@
+# 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. An instructions file several tools read (CodeBuddy and WorkBuddy share
+  `.codebuddy/rules/teamai-context.md`) is cleaned block by block: a teamai
+  block stays while a remaining tool on that file still writes it, so
+  `--agent workbuddy` keeps that file while CodeBuddy is installed. The team
+  rules in a project's `.codebuddy/rules` are shared the same way. A file an
+  earlier release wrote the blocks to, such as the project `AGENTS.md`, loses
+  its teamai blocks, since no tool reads them there now. A file teamai created
+  goes with its last block; one the user had before stays, even if empty.
+- **Whole machine** → no `--agent` flag. Run outside a project, it removes the
+  user scope but keeps the data of each project still set up, and names them
+  (`Kept the data of N project(s) still set up on this machine: ...`). Each of
+  those needs `teamai uninstall` run in it; after the last one, one more
+  `teamai uninstall` outside any project removes what is left in `~/.teamai`.
+
+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)
+
+A targeted project exclusion needs the same confirmation even when there are no local files to remove. `--dry-run` and declining confirmation leave the project config unchanged.
+
+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
+
+- If no valid configuration is found and TeamAI reports "home directory only," uninstall removes `~/.teamai` but keeps each project still set up (or registered in `~/.teamai/env-scopes`) and the shared files it reads, as a user-scope uninstall does.
+- Project uninstall keeps the shared Claude/Codex team hooks in the main checkout
+  while another checkout uses them. A targeted uninstall releases only the selected
+  tool. Checkouts that exclude a tool do not retain its shared hook. Bare-repository
+  worktrees remove their own hook files independently. When the main checkout has
+  no install, the shared manifest and its empty `.teamai` directory are removed
+  after the last team hook is removed.
+- A migrated data partition is one installation shared by its checkouts. Full
+  uninstall removes every checkout's shared hooks and registrations, then the
+  partition. Targeted uninstall (`--agent`) removes only that tool's hooks and
+  registration the current checkout uses, and keeps the other tools; when it is
+  the last tool it removes the partition, so every checkout's hooks go too.
+  Inherited submodule clones keep separate checkout ownership within that partition;
+  full uninstall removes their recorded hooks too, preserving versioned parent hooks.
+- For OpenCode, uninstall also removes the rules globs teamai added to
+  `instructions` in `opencode.json`, including the relative `rules/*.md` an
+  earlier release wrote in user scope. In a project it removes
+  `.opencode/rules/**/*.md` from `.opencode/opencode.json` and the
+  `.opencode/rules/*.md` an earlier release wrote to the root `opencode.json`,
+  and deletes `.opencode/opencode.json` when nothing else is left in it.
+  The user's own entries stay.
+- Uninstall removes the team-rules block from the file a tool with no rules
+  format reads in user scope (`~/.codex/AGENTS.md`, `~/.zcode/AGENTS.md`,
+  `$DSH_HOME/AGENTS.md`, the OpenClaw workspace `AGENTS.md`,
+  `~/.pi/agent/AGENTS.md`, `~/.joycode/rules.txt`, `~/.config/muse/AGENTS.md`), and the file when teamai
+  created it for the block alone.
+- Uninstall cleans legacy Codex rule copies at the recorded `toolRoots`
+  location, including publishers' bare local filenames, and the copies earlier
+  releases left in a project's `.workbuddy/rules` and `.pi/rules`, in
+  `.openclaw/rules`, `~/.pi/agent/rules` and `~/.joycode/rules`. It keeps
+  edited copies and names them.
+  For a rule the team has
+  removed, it deletes the copy only if its hash matches the recorded delivery.
+  Without that record, it keeps the copy and names it in a warning. Save any
+  changes you need, then delete the copy manually.
+- A skill directory, rule or agent at a team resource's name goes only when it
+  is teamai's (on the delivery record, or a team version by the history). The
+  user's own file or skill of that name stays, and uninstall names it in a
+  warning.
+- A copy git tracks is never deleted: uninstall names it and lists it in its
+  summary under `Kept (tracked)`. If the repository no longer needs it, have
+  the user run `git rm -r <path>` and commit.
+- If the output kept the data of projects still set up, list them and say that
+  TeamAI stays in those projects until `teamai uninstall` is run in each.
+- If an OpenCode config entry cannot be removed, repair its config or permissions
+  and retry the same uninstall command. Uninstall reports failure and keeps
+  its ownership record and shared data directory, even for the last tool.
+- Project uninstall keeps the global Pi and Oh My Pi extensions, Hermes
+  plugin and config, OpenCode's user plugin, and the Codex family's
+  user-level hooks, which the user
+  scope, the HTTP agent or another project may use, and names them. If none
+  does, run `teamai hooks remove` in the project first: it removes them.
+  Targeted project Codex uninstall keeps project config and records its
+  exclusion, even without local resources. Legacy project hook copies go.
+  User-scope uninstall removes these global channels.
+  The retained adapters respect project exclusions, including cached HTTP
+  prompt injection and HTTP sync. An excluded tool does not download its
+  resources again on the next session start.
+- An enabled, installed Pi, Oh My Pi, Hermes or project Codex also keeps the
+  project's shared state in use without a local tool directory. Uninstalling
+  another tool preserves that state and the remaining tool's instructions.
+- 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.
+- In a project, uninstall also removes teamai's git hook: the
+  `hook.teamai-post-checkout`, `hook.teamai-post-merge` and `hook.teamai-post-rewrite` entries in the repo's git
+  config and the `# >>> teamai git hook` block in `.git/hooks/post-checkout`,
+  `post-merge` and `post-rewrite`. Other hooks stay; a script left with only its shebang is deleted.
+- In a project, uninstall also takes teamai's blocks out of `.git/info/exclude`
+  once it has deleted the files they hid: the `delivered` block, the
+  `delivered/<id>` block it keeps in another repository (a tool folder that is
+  a nested clone or submodule, a tool home kept in git), the HTTP local
+  agent's lines for this project (it keeps serving the other workspaces; a
+  user-scope uninstall removes its `local-agent` block in every exclude file it
+  recorded), and every other `# [teamai:…]` block in those files. A file the user creates later at one of
+  those paths is visible to git. Their own lines stay, and so does another
+  project's block in a shared repository. A read-only exclude file is left as
+  it is, and the warning lists the lines to delete by hand; the uninstall is
+  then incomplete (exit 1) and keeps its records, so rerunning it once the
+  file is writable removes the block. Copies in other
+  worktrees stay on disk and become visible there. `--agent <tool>` drops only
+  that tool's lines (`.agents/skills` too for Codex) from every worktree,
+  keeping a path another tool in use reads. `--dry-run` lists the blocks under
+  `Git exclude blocks (teamai's):`. An incomplete uninstall keeps the line of
+  every file still on disk until the retry. With no configuration found (a
+  machine set up only with `init --http`, uninstall run outside its projects),
+  uninstall removes `~/.teamai/` and the HTTP source, and first teamai's lines
+  from every exclude file its records name, but the line of a file it leaves on
+  disk (named), and the local agent's MCP servers in Claude's and CodeBuddy's
+  local scopes that are still as it wrote them (a changed copy stays, named).
+  If such a file does not parse, `~/.teamai/` and the records stay and it exits
+  1, naming the file: fix it and rerun. `teamai source remove-http` leaves
+  those servers but keeps their records, for this uninstall to remove. In a workspace with no project config, run uninstall there: it also reads that workspace's `.teamai/managed-local-mcp.json`, with or without user config. A failed removal keeps those records and exits 1; repair the named file and retry in the same workspace. It does not scan other unconfigured workspaces. The local agent's skills and rules go only as far as they are
+  still what it installed: a file the user added inside a skill, an edited
+  copy, and a tracked file stay, named. If another pull or push holds the
+  project's sync lock, uninstall changes nothing and exits 1: run it again.
+- A `credentials` line stays, with a warning, while the models file it names
+  still holds an API key in any checkout of that repository. MCP lines
+  (the `# [teamai:mcp-exclude:start]` block) go only for MCP configs it proves
+  hold no resolved `${VAR}` value, judged in every checkout of the repository
+  (the main checkout of a `--separate-git-dir` repo or a submodule too), after
+  removing teamai's servers from each. A line names the path a write lands in: for a config
+  under a symlinked directory, the link's target (`/config/mcp.json` for
+  `.cursor/` linking to `config/`); for a config that is itself a symlink, its
+  target, in that target's repository. For one it cannot prove clean (including one written
+  under a `toolPaths` mapping since changed, at the built-in location of a tool
+  the team dropped or moved that no other tool maps, or in a nested repository's
+  linked worktree, that still holds servers, and one written for a tool since moved
+  (or at its built-in location) that another tool maps, holding a server that tool
+  did not write) it keeps the line
+  and warns, naming the file and why: have the user remove teamai's servers from
+  that file, then delete the line (with the last one, the block's markers). Do not
+  delete a kept line while its file still holds a token.

package/skill-data/share/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: share
+description: >-
+  Turn a session into a team learning: summarize what was solved, discovered or worked around,
+  and publish it to the team knowledge base with `teamai contribute`. Loaded on demand by the
+  teamai discovery stub, and by the friction reminder that ends a session worth sharing.
+---
+
+# Contribute — share what a session taught you with the team
+
+Summarize what this AI coding session taught you and push it to the team knowledge base.
+
+**Write the document in Simplified Chinese**, as earlier releases required. Commands, flags,
+URLs, paths and code identifiers stay as they are.
+
+## When to Use
+
+- When teamai suggests this session has valuable content worth sharing
+- When you've solved a tricky problem and want to document the solution
+- When you've discovered a useful workflow or pattern
+- After a long session with diverse tool usage
+
+## How It Works
+
+1. **Summarize**: review the tools used, the problems solved and the patterns found in this session
+2. **Write the document**: a Markdown document (language as above) covering:
+   - What the task or problem was
+   - The key decisions and why they were made
+   - The solution, workaround or pattern discovered
+   - Which tools or skills proved especially useful
+   - Pitfalls and things to watch out for
+3. **Save it**: write the document to a temporary file
+4. **Push it to the team**: run `teamai contribute --file <path> --title "<title>"`
+
+## Document Template
+
+Copy the template, the frontmatter field table and the tag taxonomy from
+`{SKILL_DIR}/references/doc-template.md`. The frontmatter is required: it is what
+makes the document searchable.
+
+## Example
+
+```bash
+# After writing the summary to /tmp/session-summary.md
+teamai contribute --file /tmp/session-summary.md --title "Debugging K8s pod startup timeouts"
+```
+
+## Important
+
+- Run this as a **sub-agent** (Agent tool) to avoid polluting the main session's context
+- 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
+
+## Publishing a reusable skill instead
+
+A member asking to publish a skill ("share this xxx skill with my team") is a
+different flow, and it does not need recall: it lives in the `core` skill, at
+`"$(teamai skill path core)/references/contribute-member.md"`. This file
+is for turning a *session* into a learning.
+
+## References
+
+In the files below, `{SKILL_DIR}` is the directory `teamai skill path share` prints; a reference file you open on its own writes that directory as `SKILL_DIR` in braces.
+
+| File | When to load it |
+|---|---|
+| `{SKILL_DIR}/references/doc-template.md` | Writing the learning document: template, frontmatter fields, tag taxonomy. |
+
+`teamai skill get share --full` prints this skill with its reference appended.

package/skill-data/share/references/doc-template.md

@@ -0,0 +1,44 @@
+# Learning document template
+
+**Required: the document must start with YAML frontmatter.** It feeds the search index
+and is how other members discover the learning.
+
+```markdown
+---
+title: "<short title naming the core problem or finding>"
+author: <username>
+date: <YYYY-MM-DD>
+tags: [tag1, tag2, tag3]
+---
+
+## Context
+What were you doing? What problem did you hit?
+
+## Solution
+How did you solve it? What were the key steps?
+
+## Lessons
+- Lesson 1
+- Lesson 2
+
+## Related Skills
+- skill-name-1
+- skill-name-2
+```
+
+### Frontmatter fields
+
+| Field | Required | Meaning | Example |
+|------|------|------|------|
+| title | yes | Short title (under 60 characters) | "Diagnosing K8s Pod OOM kills" |
+| author | yes | Contributor's username | jeffyxu |
+| date | yes | Date as YYYY-MM-DD | 2026-03-28 |
+| tags | yes | 2-5 key tags | [k8s, oom, troubleshooting] |
+
+### Choosing tags
+
+Pick 2-5 from these categories:
+- **Stack**: python, typescript, go, k8s, docker, sglang, cuda
+- **Problem type**: troubleshooting, performance, deployment, config, api
+- **Pattern**: workflow, pattern, tool-usage, best-practice
+- **Scenario**: debugging, testing, monitoring, security