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

package/skill-data/setup/references/join-member.md

@@ -0,0 +1,189 @@
+# Scenario: Member — join an existing team
+
+Goal: the user joins a team that already has a TeamAI repo. You need the team
+repo's **full URL** (the admin shares it). Do NOT create a new repo.
+
+Run the commands yourself. Only stop to ask when a step says "ASK".
+
+## Step 0 — Get the repo URL (REQUIRED — stop if missing)
+
+A member joins an **existing** repo. You need its full URL from the admin.
+
+If the user has not given a full URL, ask for it:
+*"Paste the full team repo URL your admin gave you (e.g.
+https://github.com/your-org/your-repo)."* Do not proceed with `owner/repo` short
+form.
+
+**If the user does not have the URL, STOP here.** Do not guess a URL, do not probe
+platforms, and — most importantly — **do not create a new repo.** Tell the user:
+*"Ask your team's TeamAI admin for the repository URL, then come back and paste it
+here."* A member without a repo URL cannot continue; creating one would fork the
+team into a second, empty repo. (Setting up a brand-new team repo is the admin
+flow — see `{SKILL_DIR}/references/setup-admin.md` — not this one.)
+
+## Step 1 — Install and verify
+
+```bash
+npm install -g teamai-cli
+teamai --version
+```
+
+If it fails, Node.js ≥ 20 is missing — have them install Node 20+ first.
+
+## Step 2 — Choose scope (ASK)
+
+- **This project only** (default): `cd` into the project directory first.
+- **Whole machine**: add `--scope user`.
+- **A folder holding several repos** (a workspace): set up each repo from
+  inside it, then run the same `init` in the folder. The folder also receives
+  what each repo inside selects; pass `--project` there only for a project the
+  folder itself belongs to.
+
+## Step 3 — Log in to the same platform as the URL
+
+Match the login to the URL's host (do NOT create a second repo):
+
+- **`git.woa.com/...`** (Tencent TGit) → after telling the user this installs the
+  `gf` binary and stores a credential, and getting their OK, **you may run the
+  `gf` install and `gf … auth login` for them** (or show the commands if they
+  prefer to run them). Follow `{SKILL_DIR}/references/provider-tgit.md` ("Log in");
+  the user's only action is approving the login URL in their browser / iOA. No
+  `GITLAB_URL` needed. (No headless shortcut: `TGIT_TOKEN` is REST-API-only and
+  cannot clone, so the login has to be run once on the machine.)
+- **`cnb.cool/...`** → install the CNB CLI, then authorize, in this order:
+  1. `npm install -g @cnbcool/cnb-cli`
+  2. `cnb login` — have the user approve it in the browser (OAuth2 device flow);
+     wait until they confirm before continuing.
+- **`github.com/...`** → **you run the login yourself; never hand the user a
+  command.** Log them in before `teamai init`:
+  `gh auth login --web --git-protocol https`. Relay the one-time code and the
+  `https://github.com/login/device` URL it prints, and ask the user to open that URL
+  and approve — that approval is their *only* action. Confirm with `gh auth status`
+  before continuing. (Headless/CI only: pre-set `GITHUB_TOKEN` — a token with `repo`
+  scope — instead.)
+- **`gitlab.com/...`** or self-hosted GitLab → set `GITLAB_TOKEN` (and `GITLAB_URL`
+  for self-hosted, with `api` scope). **Exception:** a member who only syncs and
+  never needs the CLI to open merge requests (typical for non-developers) can skip
+  the token: add `--provider git` to the `init` in Step 4. Git then uses their
+  existing SSH key or credential helper, and `push` leaves the MR for them to open
+  on the web.
+- **Other Git hosts, including Azure Repos** → use the existing Git credential
+  helper or SSH key. Keep the clone path as provided, including whether it ends
+  in `.git`; do not embed HTTPS credentials in the URL.
+
+If they have no account on that platform, they register there, then ask the admin
+to add them to the repo.
+
+## Step 4 — Initialize with the URL (you run it)
+
+Before running `init`, 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
+# this project only (run from inside the project)
+teamai init https://<platform>/<org>/<repo>
+
+# or whole machine
+teamai init https://<platform>/<org>/<repo> --scope user
+```
+
+**Set up all their AI tools by default (global rule 9).** Don't add `--agent` to
+restrict the install unless the user said to. Omitting it gives a picker — select
+**every AI tool already installed**. Afterwards, **tell the user (in their
+language) which agents will now auto-sync TeamAI**, and note any detected tool that
+was skipped and why.
+
+**Read-only / restricted environments (no Git access):** some sandboxed hosts
+cannot use Git. If the admin provides an HTTP endpoint + API key instead, use:
+
+```bash
+teamai init --http https://your-team-host/api --token <api-key>
+```
+
+This is a read-only consumer mode — `push` / `contribute` are not available, but
+skills and rules still sync.
+
+**Claude Code or Codex kept in a different directory (`CLAUDE_CONFIG_DIR`,
+`CODEX_HOME`):** `init` records that directory (as `toolRoots.claude` /
+`toolRoots.codex` in the local config) and syncs every path of that tool there,
+so run `init` from a shell that has the variable exported. Re-running `init` after
+changing it moves the install (the old root's hooks and managed MCP servers are
+removed, and for Claude Code its delivered model credentials; its skills and rules
+are left and named in the output). To end the relocation, run `init` once with the
+variable set but blank: `CLAUDE_CONFIG_DIR= teamai init …` or `CODEX_HOME= teamai init …`.
+
+## Step 5 — Verify with doctor
+
+```bash
+teamai doctor
+teamai hooks list      # per-tool: which AI tools actually got the hooks
+```
+
+Fix anything `doctor` reports. **Don't trust the "Hooks injected into all AI tool
+settings" message alone** — it prints even for tools where nothing was written;
+`teamai doctor` / `teamai hooks list` show the real per-tool status. If it flags
+hook problems, load the troubleshooting reference (`"$(teamai skill path core)/references/troubleshooting.md"`),
+section "Which tools actually get hooks".
+
+## Step 6 — Confirm the skills actually arrived
+
+`teamai init` does not copy team skills, rules or MCP. They arrive on the next
+session start, or when you run `teamai pull`. A workspace-scope init run without a
+terminal and without `--agent` creates no tool directory; that directory appears
+when the user first opens that tool in the project, and that session start pulls.
+To confirm after a session start or a pull:
+
+```bash
+teamai list        # see the team skills / rules / docs you now have
+```
+
+Then tell the user: from now on, **opening a new session in this AI tool
+auto-syncs** the latest team resources — no manual step needed. If their tool has
+no session-start hook (e.g. Gemini CLI, JoyCode), they run `teamai pull` by hand.
+
+**Reassure them about privacy** (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 joined — usage counts and knowledge you choose to contribute, never
+your raw conversation content."* (Team reporting is opt-in and carries counts +
+tool names only, on a separate branch of that same repo.)
+
+## Agent-specific note
+
+If this conversation is running in **ChatGPT App** or **WorkBuddy**, the hooks
+that drive auto-sync need an extra manual step — load the troubleshooting reference (`"$(teamai skill path core)/references/troubleshooting.md"`), section "Agent-specific caveats" and walk the user through it before finishing.
+
+## If something is denied
+
+Permission errors (can't clone, can't read) usually mean the admin has not added
+this user to the repo yet. Have them copy the exact error message to their admin.
+
+## Wrap up in the user's language, and how to leave
+
+Summarize the outcome **in the user's own language** (global rule 1). Cover:
+
+1. **They're done — sync is automatic.** From now on, opening a session in this AI
+   tool keeps their team skills up to date; no commands needed.
+2. **Sharing a session learning is automatic — no command to remember.** When a
+   session produced something worth sharing, TeamAI **prompts them on its own** (at
+   the end of the session) and the `share` workflow (`teamai skill get share`) takes over to
+   summarize and contribute it. They do **not** invoke `/teamai` for this. (This
+   prompt only appears when recall is on — it is off by default; the admin turns it
+   on in `teamai.yaml` (`sharing.recall.enabled`), a member with `teamai recall enable` — and the admin has not switched the
+   reminder off in `teamai.yaml`. It also stays silent while their teamai config
+   cannot be loaded; `teamai skill get share` then names the file and the error.)
+3. **They can also contribute a skill — just ask in plain language.** A member does
+   not need to be an admin to publish a skill. They tell TeamAI something like
+   *"share this xxx skill with my team"*, in their own language, and you
+   run the publish for them (see `"$(teamai skill path core)/references/contribute-member.md"`;
+   it needs no recall).
+4. **How to leave — via the skill, not raw commands.** They can remove TeamAI any
+   time by re-invoking the skill; you'll run it for them:
+   `/teamai Uninstall TeamAI` (in their language; the `/teamai` prefix stays as-is).
+   One line, in their language: *"This only removes things from your machine; the
+   team repo stays — rejoin any time with `/teamai` and the repo URL."*

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

@@ -0,0 +1,354 @@
+# Scenario: Admin — day-to-day management
+
+The user already ran `teamai init`. Do NOT re-init or re-register. Before changing
+anything, say what you are about to change. Pick the task below that matches.
+
+Day-to-day management is mostly **publishing and updating team resources — skills,
+rules, MCP servers, and env** — plus inviting members and checking the dashboard.
+
+## Publish or update a skill / rule / doc
+
+The user (or you) creates or edits a skill, rule, or doc locally, then publishes it
+to the team. The same `teamai push` handles both new resources and updates to
+existing ones:
+
+```bash
+teamai push            # review the diff, then confirm
+teamai push --all      # push everything without per-item confirmation
+teamai push --skill <path>   # push one specific skill
+teamai push --branch <name> # use an explicit branch for a new push
+```
+
+An existing open PR is updated on its recorded branch. TeamAI refuses to reset a
+team-repo clone with unrelated modified, staged, untracked, or conflicted files;
+commit or stash those changes before retrying.
+
+Members receive it automatically the next time they open a session (or when they
+run `teamai pull`).
+
+## Publish or update team MCP servers
+
+```bash
+teamai mcp list        # team MCP servers + per-tool install status
+teamai mcp inject      # push team MCP servers into every AI tool's config
+teamai mcp remove --dry-run # preview removal without changing tool configs or managed records
+teamai mcp remove      # remove teamai-managed MCP servers
+```
+
+MCP definitions travel with the team repo like skills/rules — edit, then the
+members pick them up on sync.
+
+A server with a `${VAR}` the tool cannot expand itself gets the resolved value
+written into its project config (`.mcp.json`, `.cursor/mcp.json`, ...). With
+`sharing.gitExclude` on, Claude's (not in a single-repo team, whose worktrees
+each read their own branch's servers) and CodeBuddy's servers go to their local
+scopes in `~/.claude.json` and `.codebuddy.json` instead, outside the project,
+and the next pull (on an HTTP-backed team, the local agent's next sync) moves
+teamai's servers out of `.mcp.json`. Before
+that write, teamai lists the file in the clone's `.git/info/exclude`, inside a
+`# [teamai:mcp-exclude:start]` block; the committed `.gitignore` is never touched.
+A file under a symlinked directory is listed and checked where the write lands
+(`.cursor/` linking to `config/`: `/config/mcp.json`); a config that is itself a
+symlink stays one, and its target is listed in, and checked by, its own repository.
+When it cannot (git already tracks the file, a rule in the member's git ignore
+files re-includes it, `.git/info` is not writable, the exclude file is held by
+another teamai command, or git errors), it leaves the file as it was, warns, and
+`teamai mcp list` shows `withheld: <tool> — <reason>. <fix>`. Apply the fix it
+names (a tracked file: `git rm --cached <file>` and rotate the token; a
+re-including rule such as `!/.mcp.json`: remove it), then run `teamai pull`. A pull or `teamai mcp remove` takes a line out
+once its file no longer holds a resolved value; `teamai uninstall` does so in
+every worktree. A file written under a `toolPaths.<tool>.mcpProject` the team
+later changes or removes stays listed until it is deleted or holds no server;
+for one an older teamai wrote, the first pull finds the path in the team repo's
+history of `teamai.yaml`, or among the built-in paths teamai has since changed
+(not one the same tool maps today), and lists it while it holds any server; one
+git tracks is recorded instead and listed once the member runs `git rm --cached`
+on it. `teamai doctor` checks those paths until that pull. A file written for a
+tool the team moved elsewhere (recorded, or found in that history), that another
+tool still maps, stays listed while it holds a server that tool did not write,
+one of the member's own included. The built-in location of a tool the team drops
+from `toolPaths` or moves elsewhere stays listed while it holds any server; one
+another tool maps today (CodeBuddy's `.mcp.json`, which Claude maps) while it
+holds a server that tool did not write. A file two tools map, with no pull on
+this version having recorded it, needs a `managed-mcp.json` record from each of
+them. While a worktree has no `managed-mcp.json` at all (lost, or before its
+first pull), an untracked config holding a server no record claims is listed,
+and that server noted: it keeps the line until it leaves the file. So is the
+file of a tool `managed-mcp.json` has no record for, when a pull writes that
+tool's first record (its record lost, or teamai's first delivery to it). While that
+note cannot be written (another teamai command holds the record), the line stays
+until a later pull writes it. A Copilot project config's bare top-level servers
+still count once another tool writes `mcpServers` into the file. On an HTTP-backed
+team the local agent's `install_mcp` lists a project config before writing a
+server with any header, env value, argument or URL (only a bare stdio command is not), fails the install when it cannot, and only
+`teamai uninstall` takes that line out. The next sync or `teamai pull` in the
+workspace also lists a file an older local agent wrote a credential into; `teamai doctor` checks those files too.
+
+### Pi MCP delivery
+
+Pi 0.99.0+ receives stdio and streamable HTTP servers through the existing MCP commands and `teamai pull`; SSE is skipped. User scope writes `~/.pi/agent/mcp.json`, workspace scope writes `.pi/mcp.json` (Pi requires project trust). TeamAI keeps Pi's default codemode exposure and converts timeout milliseconds to seconds. Relocated Pi agent directories (`PI_CODING_AGENT_DIR` / `PI_CONFIG_DIR`) are unsupported. Local exposure/enabled edits on managed servers survive until the team definition changes; doctor reports differences from the team entry. Extensions that replace `/mcp` must be removed to use Pi's built-in MCP.
+
+## Invite a member
+
+There is **no CLI invite flag.** Inviting is done on the Git platform's website:
+
+1. On the platform (GitHub / GitLab / CNB), add the person to the team repo
+   (Settings → Collaborators / Members).
+2. Send them the **full repo URL** and this line to paste into their AI tool:
+   `/teamai Help me join my team's TeamAI, repo URL is <URL>`
+
+(If you want to see who is already registered: `teamai members` /
+`teamai members list`.)
+
+## See members and resources
+
+```bash
+teamai members list          # registered team members
+teamai list                  # all resource types
+teamai list skills           # just skills
+teamai status                # local vs team differences
+```
+
+## Roles (skill namespaces per job function)
+
+```bash
+teamai roles list            # roles defined + your current role
+teamai roles init            # create the roles manifest (admin, interactive)
+teamai roles add <id>        # add a role
+teamai roles update <id>     # change a role's namespaces / description
+teamai roles remove <id>     # remove a role
+```
+
+After editing roles, `teamai push` to publish the manifest. Members re-sync on
+their next session.
+
+## Projects (manage several projects from one repo)
+
+`project` is a second dispatch dimension alongside `role` — one team repo can serve
+multiple projects, each with its own skills/rules/learnings, without a separate
+repo per project:
+
+```bash
+teamai projects list         # projects defined + the ones active in this directory
+teamai projects set [ids...]     # set the active project(s) for this directory
+teamai projects members <id> # who is registered on a project
+teamai projects add <id> --namespaces common,<id>   # add a project (creates projects.yaml if needed)
+teamai projects update <id> --add-namespaces <ns>   # or --remove-namespaces / --name / --description
+teamai projects remove <id>  # remove a project
+```
+
+A workspace (a folder set up with `init`) also delivers the projects of the
+repos set up inside it, up to three levels down, with no list to keep: `teamai
+projects list` there shows each one and what it selects. A repo that uses
+another team repo, or single-repo mode, is left out and named.
+
+A member gets the union of their role resources and their active project's
+resources. Admins declare projects in `manifest/projects.yaml` with the commands
+above, each of which opens a PR. `roles init/add/update/remove` and
+`projects add/update/remove` support `--dry-run` without pulling the team repo.
+Clone previews use the contents after a real pull on the checked-out branch: an
+ahead branch stays ahead, a behind branch advances, and a diverged branch uses
+origin/current-branch. `roles init` preview checks that manifest before asking
+for overwrite confirmation. After `projects remove`,
+keep the project's content in the team repo until members have pulled: that is
+what lets their next pull clean up the copies they deployed.
+
+`roles init/add/update/remove` and `projects add/update/remove` previews, and resource removal
+previews, refuse a team clone with uncommitted changes. Commit or stash them before retrying. Single-repo
+previews still work with dirty business files because they read origin. Clone
+previews refresh the configured upstream first, even when its branch or remote
+name differs. A failed fast-forward or missing upstream uses origin/current-branch
+for the real reset fallback. Removal refuses when that refresh also fails.
+
+Every namespace that names a directory — `knowledge`, `skills`, `agents`, `env`,
+`hooks`, `mcp`, `models`, `docs` and `wiki` in either manifest, and `learnings` in `projects.yaml` (a role's `learnings:` is
+ignored and unchecked) — must be a single path segment: no `/`, `\`, `:` or control character, no trailing
+`.` or space, and not a Windows device name (`CON`, `NUL`, `COM1`, …). `team-codebase`
+cannot be a `docs` namespace (`docs/team-codebase/` is the legacy codebase output). Two
+namespaces of one resource type may not differ only by case, across both
+manifests. A manifest that breaks this, does not parse, or is empty stops
+members' pull for that scope until it is fixed; the error names the entry. Fix
+it rather than deleting it — with no `roles.yaml`, delivery is unfiltered.
+
+An item in an active namespace replaces the root item of the same name, whole:
+a skill by directory name (including a root skill a member gets through a tag),
+an agent by file stem, a rule by first-level file name (`rules/<ns>/<name>.md`
+replaces `rules/<name>.md`), and a `claudemd/<ns>/<name>.md` file replaces
+`claudemd/<name>.md`. Use this to give a project its own version of a shared
+item under the same name, and keep that shared item at the root rather than in
+a namespace every role activates: `rules/code-style.md` is replaced by
+`rules/checkout/code-style.md` for checkout members, while a
+`rules/common/code-style.md` would reach them alongside it. The same skill or
+agent name in two namespaces one member has active is an error naming both
+files; two namespace rules or claudemd files of one name are both delivered.
+A replacement must be usable to replace anything: a skill directory needs its
+`SKILL.md` (pull names one without it), and while an agent file does not parse
+the root agent stays installed. `teamai doctor` lists each replacement as a note. Teams without roles or
+projects are unaffected.
+
+Docs have no override. A top-level `docs/<ns>/` that any role or project lists
+under `resources.docs` reaches only members with that namespace active; a
+`docs/<dir>/` nobody lists stays shared with everyone. When a member leaves the
+namespace, their next pull removes its docs that still match the team copy and
+keeps (and names) the ones they edited. Recall and `teamai doctor` follow the
+same filter.
+
+Wiki codebase slugs follow the same rule under `resources.wiki`: once any role
+or project lists a `teamwiki/evidence/code/<slug>/` slug there, `recall` only
+surfaces it for members with that namespace active; an undeclared slug stays
+shared. The slug is whatever `teamai codebase --project <slug>` wrote, not
+necessarily the project's manifest id.
+
+## Keep delivered files out of git
+
+With `sharing.gitExclude.enabled: true` in `teamai.yaml`, each member's pull lists
+the skills and rules (one file per line, never a skill's directory, so a file a
+member adds to a delivered skill stays visible), agents, `teamai-context` files, hook
+files and team docs (one file per line) it delivered into a project, and each shared
+config file (MCP, `.codex/hooks.json`, OpenCode's) while it holds only teamai's entries,
+in teamai's `delivered` block in the clone's
+`.git/info/exclude` (local to the clone, never committed), so `git add -A` does
+not commit them; a member's own files, and copies they edited, stay visible. `init` writes it for a
+new team; an existing team adds the line and commits it through the normal
+review flow. A member overrides it on their machine with `gitExcludeEnabled:
+true|false` in the project's `config.yaml` (`~/.teamai/projects/<slug>/config.yaml`).
+Either takes effect on the next pull, no `--force`; turned off, the next pull
+removes only that block. `teamai doctor` says where the setting comes from and
+what git still sees; `teamai pull --dry-run` previews the block.
+
+## Team dashboard (web UI)
+
+```bash
+teamai dashboard             # start the AI coding session dashboard (default port 3721)
+teamai dashboard --port 8080 # custom port
+```
+
+Opens a local web UI for team coding-session activity and knowledge-base health.
+
+## Team packages (npm + Claude plugins)
+
+Declare packages once; members get a prompt to install them (TeamAI never runs
+third-party package code automatically):
+
+```bash
+teamai packages install typescript          # npm dependency
+teamai packages install eslint@latest --global   # global CLI tool
+teamai packages install code-review@claude-plugins-official   # Claude plugin
+teamai push                                 # share the updated teamai.yaml
+```
+
+## Shared environment variables, hooks and MCP servers
+
+```bash
+teamai env list              # what reaches this directory, each with its namespace (values masked)
+teamai env list --reveal     # show variable values in plaintext (never a secret's)
+teamai env add <KEY> <VALUE> # add or update in env/env.yaml
+teamai env add <KEY> <VALUE> --project <id>   # or --role <ns>: in that namespace's env/<ns>/env.yaml (warns if nothing declares <ns>)
+teamai env remove <KEY>      # remove (same --role / --project)
+teamai env add <KEY> --secret -d "<what it is for>" --url <where to get one>   # declare a secret in env/secrets.yaml, no value (same --role / --project)
+teamai env remove <KEY> --secret   # remove a declared secret (plain `env remove` does too when env.yaml does not set <KEY>)
+teamai remove mcp <name>     # root mcp/mcp.yaml if it has the name, else the one namespace file; --role / --project pick a namespace
+```
+
+Env variables, team hooks and MCP servers are scoped like skills: the root file
+(`env/env.yaml`, `hooks/hooks.yaml`, `mcp/mcp.yaml`) reaches everyone, and
+`env/<ns>/env.yaml`, `hooks/<ns>/hooks.yaml`, `mcp/<ns>/mcp.yaml` reach only
+members whose role or project lists `<ns>` under `resources.env`, `resources.hooks`
+or `resources.mcp`. A namespace entry replaces the root entry of the same key, hook
+id or server name. Hooks and MCP servers have no add command, and `teamai push`
+does not pick up `hooks/` or `mcp/`: edit the file in the team repo, then commit
+and push it with git. `teamai doctor` lists each override.
+
+- A name twice in one file, in two active namespaces, or an active file that does
+  not parse: that type is not applied for affected members and their installed
+  state is kept. Fix the file the warning names. A hooks or MCP file with none of
+  its top-level keys (`server:` for `servers:`) counts as one that does not parse.
+- Per-entry `projects:` (and `roles:` on env) no longer works: such an entry reaches
+  nobody. `roles:` on hooks and MCP still filters for one more minor release. Pull,
+  the list commands (`teamai env list`, `teamai mcp list`, `teamai hooks list`,
+  `teamai list <env|hooks|mcp> --source repo`), `teamai status` and
+  `teamai doctor` name the namespace file each entry belongs in; move it there.
+  When `teamai env add` updates a variable carrying either removed key, it keeps
+  the key and warns that pull will not deliver the variable, naming that file.
+- An env, hook or MCP entry with a key its schema does not know (a mistyped `role:`)
+  also reaches nobody. Pull, the list commands, `teamai status` and
+  `teamai doctor` name the file, entry and key; correct the key or remove it.
+  A key a later teamai version adds is unknown to an older one, so upgrade every
+  member before the team uses a new entry key.
+- Team model profiles work the same way: `models/<ns>/models.yaml`, declared under
+  `resources.models`, replaces the root profile with the same `id` for members who
+  have `<ns>` active. A member's API key is bound to the profile's gateway origin:
+  when an override points at another host, their pull leaves the agent alone and
+  asks them to run `teamai models switch team:<id>` to set the key for it.
+- Secrets are declared with no value in `env/secrets.yaml` or `env/<ns>/secrets.yaml`
+  (active through `resources.env`; a namespace entry replaces the root entry with the
+  same key): a `secrets:` list of `key`, optional `description` and optional `url`
+  (where a member gets one). Never put a value there: `teamai env add <KEY> --secret`
+  takes none and rejects one. Declare with it or edit the file in the team repo;
+  `teamai push` picks it up. Each member sets their own value with `teamai env set KEY`
+  in their terminal (`--global` for every team on their machine; a team value still
+  wins). That updates MCP servers for the current scope. Run `teamai pull` afterwards
+  only to update `env.sh`, and only when the key is an env variable. `teamai env list` shows each secret as `team`, `global`, `environment`,
+  `missing` or `unreadable` and never shows a value, `--reveal` included. The `description` is what
+  agents see: the session-start hook lists each declared key with it and tells the
+  agent to run the CLIs that need them through `teamai env exec --`, so say which
+  tool or server uses the key. As the agent, run `teamai env add <KEY> --secret`
+  yourself and leave the value to each member's own terminal. A key declared as a secret
+  and also set in `env.yaml` is a secret: its `env.yaml` value is not delivered. A
+  secrets file that does not parse keeps `env.sh` and MCP servers as they were, and
+  `teamai doctor` fails a check naming the file.
+- Have every member upgrade before declaring `env`, `hooks`, `mcp`, `models`, `docs` or `wiki` in a
+  manifest: teamai 0.25.0 and the 0.26.0 betas reject those keys and their pull stops.
+
+## When sync fails
+
+Run `teamai doctor` first. If it reports hook or path problems, load
+the troubleshooting reference (`"$(teamai skill path core)/references/troubleshooting.md"`). Have the affected member reopen their session; if their tool
+has no session-start hook, they run `teamai pull` manually.
+
+## Capture a lesson learned
+
+Turning a tricky fix into team knowledge is **automatic** once recall is on for
+the team (`sharing.recall.enabled: true` in `teamai.yaml`, then `teamai push`; it is
+off by default, and `teamai recall enable` turns it on for one machine only): at the end of a session
+worth sharing, TeamAI prompts the member and the dedicated
+`share` workflow (`teamai skill get share`) summarizes the session and runs
+`teamai contribute`. Nobody has to invoke it by hand. (A member whose teamai config
+cannot be loaded gets no prompt; `teamai skill get share` names the file and the error.)
+
+Teams that work in English set `language: en` in `teamai.yaml` and `teamai push`.
+That makes the built-in teamai-recall rule, the TodoWrite hint, and the merged-MR
+hint English only. Omit `language`, or set `zh`, to keep the historical bilingual
+text. Each scope reads its own team repo, so a project install and a user install
+can differ. Members receive the recall rule in that language on the next
+`teamai pull`.
+
+(Publishing a **reusable skill** someone authored is a different task — any member
+can do it, see `"$(teamai skill path core)/references/contribute-member.md"`.)
+
+### Turn the sharing prompt on or off (admin)
+
+The auto-share prompt is **on by default once recall is on**, and only shows in directories set up
+with teamai (never on a read-only HTTP source, or while a member's teamai config cannot be loaded).
+To disable it team-wide, set this in
+`teamai.yaml` and `teamai push`:
+
+```yaml
+sharing:
+  contributeHint:
+    enabled: false      # team-wide default; members can still override locally
+```
+
+Resolution order: `TEAMAI_CONTRIBUTE_HINT_DISABLED=1` env kill switch > a member's
+local override > this team setting > default (on). Turning it off here only removes
+the nudge; members can still contribute on request.
+
+## Don't
+
+- Don't hand-run raw `git` commands.
+- Don't create a second team repo.
+- Don't use `owner/repo` short form — always the full URL.
+
+### Superproject worktrees
+
+Initialize each original submodule once. After the parent initializes submodules in a new worktree, run `teamai pull --silent` in each initialized child before starting an AI session; the children inherit the original config and install their own Git hooks. Independent child clones need separate init. On Git < 2.54, if the children use the parent's versioned `core.hooksPath`, put the dispatch line once in each applicable parent hook. Follow the admin guide for the full sequence.

package/skill-data/setup/references/provider-tgit.md

@@ -0,0 +1,101 @@
+# Provider: Tencent TGit
+
+git.woa.com is **Tencent-internal only**. TeamAI supports it natively as the `tgit`
+provider — it recognizes the host on its own, so you **never** set `GITLAB_URL`.
+Both `{SKILL_DIR}/references/setup-admin.md` and
+`{SKILL_DIR}/references/join-member.md` point here for the reachability probe and
+the `gf` login; follow the relevant section for whichever flow you are in.
+
+## Probe reachability (setup flow only)
+
+When an admin is choosing a platform and hasn't named one, check whether this
+machine can reach TGit. A request to git.woa.com that returns the header
+`x-env: tgit` means TGit is reachable — plain reachability is not enough,
+the header is what confirms it:
+
+```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`, **prefer TGit** and list it first among the choices — it
+is the Tencent-internal default. Choose by account + reachability only, never by
+region. (A member joining an existing `git.woa.com` URL skips the probe — the URL
+already fixes the platform.)
+
+## Log in: install `gf`, then `gf auth login`
+
+TeamAI can drive the TGit CLI (`gf`) on the user's behalf. Before the first
+command, **tell the user what this does** — it downloads and installs the `gf`
+binary and, after login, stores an auth credential on their machine — and **get
+their OK to proceed**. Once they agree, you may run the install and login steps
+for them so they don't have to type `gf` commands; their remaining action is
+approving the login in their browser / iOA when it opens. If the user prefers to
+run the commands themselves, show them the exact commands instead.
+
+### 1. Install `gf` (you run this)
+
+Use the **same source, path, and check teamai uses** — do not invent your own URL.
+`${TEAMAI_HOME}` is `~/.teamai` unless overridden:
+
+```bash
+set -eu   # abort on any failure — never fall through to `gf auth login` on a bad install
+
+# 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"
+url="https://mirrors.tencent.com/repository/generic/gongfeng-cli/files/channels/stable/gf-${os}-${arch}.tar.gz"
+
+# unique temp files per attempt so concurrent/interrupted runs never collide,
+# cleaned up on any exit
+mkdir -p "$dir"
+tmp="$dir/gf-download.$$-$RANDOM"
+trap 'rm -f "$tmp.tar.gz" "$tmp.headers"' EXIT
+
+# download over HTTPS, verify sha256, THEN extract (the same safe path teamai
+# uses). Fail closed: no advertised digest, or a mismatch, aborts the install.
+curl -fsSL -D "$tmp.headers" -o "$tmp.tar.gz" "$url"
+# The mirror 302-redirects to a content-addressed backend whose URL path is the
+# artifact's sha256; fall back to the x-checksum-sha256 header for direct serves.
+expected=$(grep -i '^location:' "$tmp.headers" | grep -oiE '[0-9a-f]{64}' | tail -1 || true)
+[ -n "$expected" ] || expected=$(grep -i '^x-checksum-sha256:' "$tmp.headers" | tr -d '\r' | awk '{print $2}' || true)
+actual=$( (command -v sha256sum >/dev/null && sha256sum "$tmp.tar.gz" || shasum -a 256 "$tmp.tar.gz") | awk '{print $1}')
+if [ -z "$expected" ] || [ "$expected" != "$actual" ]; then
+  echo "gf download integrity check FAILED (expected=$expected actual=$actual)" >&2
+  exit 1
+fi
+
+tar xz -f "$tmp.tar.gz" -C "$dir"
+# verify exactly as teamai does: the binary exists and is executable
+test -x "$dir/gf/bin/gf"
+echo "gf installed OK"
+```
+
+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.
+
+There is no headless substitute for this step: a `TGIT_TOKEN` Personal Access
+Token reaches the git.woa.com REST API only, and the git endpoint rejects it, so
+`init` cannot clone with it. Run the login once on the machine (interactively);
+later unattended runs reuse the credential it stores.
+
+## When you `teamai init` on TGit
+
+Because `gf` and login are already done, `init` goes straight to creating/cloning —
+no browser step. When the repo doesn't exist, **accept the create prompt and init
+creates it via the API.** Prefer this over sending the user to the browser first.
+
+It only falls back to https://git.woa.com/projects/new if the group/namespace
+doesn't exist or you lack create permission there. No `GITLAB_URL` is ever needed.