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

package/skill-data/core/references/troubleshooting.md

@@ -0,0 +1,419 @@
+# 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.
+
+## "Cannot acquire lock <path>: <reason>"
+
+The lock could not be inspected, created or reclaimed, including during a
+dry-run preview. Fix the filesystem error named in
+the message (permissions, a full disk, or a parent path that is a file), then
+retry; waiting for another process does not fix it. Ordinary contention still
+uses the command's busy/skip message. An existing permission-denied or ownerless lock
+is treated as held: remove it only after confirming no teamai process uses it.
+
+A lock whose owning process is dead blocks nothing: the next command that takes
+the same lock reclaims it, and a process exiting normally removes the locks it
+still holds. `teamai doctor` reports leftover lock files, and
+`teamai doctor --fix` removes the ones whose owner is provably dead.
+
+## "My skills / rules aren't showing up"
+
+This is the #1 onboarding issue. In order:
+
+1. **Did init pick this tool?** `teamai init` does not copy team resources. A
+   workspace-scope init creates only the directories of tools named with `--agent`
+   or picked in its interactive tool picker. Run without a terminal and without
+   `--agent`, it creates none, and a tool's project directory appears when that
+   tool opens a session there. The resources arrive on that session start, or
+   when you run `teamai pull`. Re-run `teamai init <repo> --agent <tool>` to add
+   the tool's directory now, then pull or open the tool to fill it.
+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?** Workspace-scope built-in hooks are written to your HOME tool
+   settings (e.g. `~/.claude/settings.json`), not the project folder; the team's own
+   hooks for Claude Code and Codex go to the main checkout
+   (`.claude/settings.local.json`, `.codex/hooks.json`). That is intentional.
+   With `sharing.gitExclude` on, Codex's team hooks run from `~/.codex/hooks.json`
+   instead (one `hook-dispatch <Event> --tool codex --team-hooks` entry per event)
+   while the project's `.codex/hooks.json` is tracked or holds entries of its own,
+   and always in single-repo mode.
+   Existing Claude/Codex main-checkout hook files count as installed targets
+   even when HOME and current worktree tool roots are missing. Injection and
+   pull update team hooks and restore HOME built-ins; removal clears managed
+   main-checkout hooks without recreating HOME roots.
+   If Git-hook installation fails after writing agent hooks, `hooks inject`,
+   `init` and self-repo bootstrap still attempt Codex trust. Injection preserves
+   the installation error without reporting overall success. Init reports the
+   error and retains exit code 1 while completing local setup, including HTTP
+   initialization. Bootstrap records the error in the debug log and continues
+   local setup.
+   In workspace scope, `teamai hooks remove` preserves other projects' gated team
+   hooks in HOME, while removing the shared built-in hooks.
+   If `source remove-http` reports incomplete hook removal, the HTTP source is
+   disabled and the failed hooks stay on record. Fix the settings file it names,
+   then repeat `source remove-http` to finish removing them.
+   If removal cannot acquire the HTTP source lock, it leaves the source intact.
+   Wait for sync or plugin reconciliation to finish, check directory permissions,
+   then retry removal.
+   If you initialized workspace 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.
+6. **Claude Code or Codex reads a different directory** (`CLAUDE_CONFIG_DIR` or
+   `CODEX_HOME` is set). `teamai doctor` reports `Claude Code root matches
+   CLAUDE_CONFIG_DIR` / `Codex root matches CODEX_HOME` when the directory the
+   variable names is not the one this config syncs to. Re-run
+   `teamai init` from a shell that has the variable exported; it records the root
+   and moves the install. If the check says the value cannot be synced to (outside
+   your home, or neither a plain directory in it nor one under `.config/`), fix the
+   variable first.
+6. **A command reports a broken manifest** (`Invalid roles manifest…`,
+   `Invalid projects manifest…`, `Invalid manifests…`, or `…manifest … could not
+   be read`). `pull` skips that scope on purpose, since syncing without the
+   manifest would deliver every namespace it gates; `push` stops before pushing
+   anything, even with `--role`; `status` lists the other resource types. The fix
+   belongs in the team repo's `manifest/roles.yaml` or `manifest/projects.yaml`,
+   which the error names by entry — tell the user to ask a team admin. Do not
+   delete the manifest or edit the local clone to get past it.
+   `recall` still searches learnings and warns once (`Recall indexed learnings
+   only…` or `Recall indexed the shared learnings only…`): what it names is
+   missing from results until the manifest is fixed and `teamai pull` rebuilds
+   the index, so do not report that the team has none of it. If recall also says
+   `Recall skips the older index at <path>…`, the smaller index could not be
+   written and that scope was not searched at all: resolve the error it names
+   (for example a read-only file or a full disk), then fix the manifest and pull.
+7. **`pull` says `Nothing was synced: <file>: <reason>`.** The project's teamai
+   config exists but cannot be read, so no scope syncs there, not even the user
+   scope, and the session-start hook syncs nothing either. Show the user the
+   file and the reason; `teamai doctor` checks another config and can pass
+   here. Moving it aside and re-running `teamai init` replaces their settings
+   for that project: do it only with their consent.
+   `recall` refuses the same way with `Nothing was searched: <file>: <reason>`:
+   no team knowledge was searched, so do not report that the team has none.
+
+## Path names appear in skill usage statistics
+
+Slash-command tracking accepts a complete `/skill-name` token at the start of the prompt, followed by whitespace or the end of the prompt, and only for a skill installed for the tool. Absolute paths such as `/Volumes/External/project` and URL components are not skill invocations. Updating prevents new false counts; already recorded usage remains.
+
+## Submodule checkouts and linked skill directories
+
+A submodule's Git directory is an identity, not a delivery directory. Team hooks and Codex project trust use its real main checkout. An initialized submodule in a superproject worktree inherits the original submodule's configuration when it exists; run `teamai pull` there without repeating init. The first pull installs Git hooks in that clone. If the parent's hook initializes submodules, follow the admin guide's initialization-and-pull sequence before starting an AI session. With Git < 2.54 and a shared versioned `core.hooksPath`, one dispatch line in each parent hook covers its submodules.
+
+Both team skills and the built-in stub accept root-directory links within the same checkout and repository. Links outside it or into child repositories are rejected. Individual skill links, tracked skills, edited stubs and unrelated files stay. Remove a kept stub to receive the packaged one.
+
+Pull removes proven TeamAI hook entries left in a Git directory. Older releases did not record file creation or project trust ownership: empty legacy files and unrecorded Codex grants stay. Remove a grant manually only after checking that it is not the member's choice.
+
+## "Last git hook run failed: ..." / a new worktree lacks team resources
+
+In workspace scope, teamai's git hook syncs on `git worktree add` and `git pull`
+through merge or a completed rebase (`post-rewrite`, including `pull.rebase=true`; on Git 2.32
+and older, a fast-forward rebase with autostash syncs on `post-checkout`).
+A conflicting rebase syncs only on completion; `git commit --amend` does not sync. It runs
+silently and always exits 0, so its failures surface only here: `teamai doctor`
+names the last one with its fix, and the next interactive `teamai pull` says it
+once. The causes are a team repo fetch that failed or hit the 5 s git-pull hook
+cap without the background pull finishing it, and another teamai process
+holding the project's sync lock longer than the hook waits, or incomplete resource,
+hook or MCP delivery. Only a complete startup sync clears the recorded failure.
+Run `teamai pull`
+in the checkout (after a stuck pull ends, or once the team repo is reachable);
+`~/.teamai/debug.log` has the details. If doctor reports `Git hook syncs new
+worktrees and git pull` as failing, follow its fix: `teamai pull` installs it.
+Git older than 2.54 has no config hooks: teamai then adds a marked block to
+`.git/hooks/post-checkout`, `post-merge` and `post-rewrite`, unless `core.hooksPath` is set (or a
+hook there is a symlink or not an executable shell script), in which case doctor's fix says to upgrade Git
+or, if the team agrees, to commit its guarded `command -v teamai ... || true`
+line into the manager's post-checkout, post-merge and post-rewrite hooks.
+Doctor also detects hooks disabled by name (Git 2.54+) or event (Git 2.55+)
+in effective global, local or worktree config. Follow its command (`git config --local <key> true`,
+or `git config --worktree --unset <key>` for a worktree setting) to enable the named hook or event, then run `teamai pull` to sync. Pull preserves
+explicit disable settings, so reinstalling alone does not enable a disabled hook.
+Existing hook contents and permissions stay unchanged; read/write errors propagate
+from `init` and `hooks inject`, and Git-started pulls record them. An unreadable
+project config prevents sync and keeps its reason in `~/.teamai/debug.log`.
+
+Hosts that skip checkout hooks need `teamai pull` in the new checkout before the AI
+tool starts. For Codex CLI 0.160.0, use `git worktree add`, run `teamai pull` there, then
+launch `codex exec -C <worktree>`. Its native `codex exec --worktree` path creates
+the checkout without `post-checkout`, so SessionStart sync arrives after startup
+discovery.
+
+## "KEY is not set. Run `teamai env set KEY`"
+
+`pull`, `teamai mcp list`, `teamai env list`, `teamai doctor` and
+`teamai env exec` (on stderr) print this for a secret the team declares in
+`env/secrets.yaml` that has no value on this machine, naming the MCP servers
+that need it and where to get one. It is a note, not a failure: `doctor` exits
+as it would without it. The value is the user's: ask them to run
+`teamai env set KEY` in their own terminal (it prompts without echo). 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. A CLI run through
+`teamai env exec` gets the value on its next run. Never ask for the value in
+chat or pipe one to `teamai env set --stdin`. A note that an entry "may hold an
+old" value means an earlier write left it, and it stays until `teamai env set`
+or `teamai pull` finds the value.
+
+`KEY reads VAR, which is not set` means the user's value for KEY is a
+reference to VAR (`--from-env`) and VAR is unset in this environment. Ask the
+user whether to set VAR in their shell or replace the reference with the
+command in the line; do not choose for them.
+
+## "Did not write <tool>'s MCP servers to <file>" / `withheld:`
+
+`pull` prints this, and `teamai mcp list` (`withheld:`) and `teamai doctor`
+report it, when a project MCP config would get a resolved `${VAR}` value that
+git would commit: the file could not be kept out of git first. It is left as
+it was, and an entry an earlier pull wrote stays. The line names the reason and the
+fix. For `git already tracks <file>`, tell the user: `git rm --cached <file>`
+(the file stays on disk), commit that, and rotate the token if the file was
+ever committed with it; then `teamai pull`. Do not run `git rm` or commit for
+them. For an exclude file that is not writable, one another teamai command
+held, or a git error, relay the fix the line gives.
+
+For new HTTP local-agent MCP installs, a failed initial ownership-manifest write leaves the MCP config and Git exclusions unchanged. Retry the install after fixing the manifest write error. A bare Copilot entry beside `mcpServers` is removed only with a matching ownership record proving a completed bare write. Older records without that evidence preserve the bare entry. A bare ownership record cannot claim a same-named member entry under `mcpServers`: updates skip the collision, and removal leaves that keyed entry alone. An unmarked Copilot record needs a matching keyed hash that does not also match the bare entry. Completed writes record `bare: true` or `bare: false`; missing placement remains unproven, including after a failed placement-record write. Existing JSON MCP updates keep the old ownership until the config write completes; a later manifest failure restores the config. `uninstall_mcp` keeps ownership if reading or writing the config fails, and restores the entry if removing its manifest record fails. MCP reconcile also restores all configs written before an ownership-save failure. If restoration fails too, repair the named configs and ownership records before retrying; the error reports both failures, and configs still carrying credentials stay excluded from Git.
+
+## "Workspace child <path> is left out" / "<item> differs between ..."
+
+`pull` in a workspace prints these; `teamai doctor` repeats the first.
+
+- **Left out**: that repo uses another team repo, is in single-repo mode, or
+  its config cannot be read. The line gives the reason. To include it, run
+  `teamai init <this workspace's team repo>` in it; otherwise it keeps working
+  on its own and nothing needs doing.
+- **Differs between**: two repos inside the workspace receive an item of that
+  name with different content, so the workspace holds it: what teamai
+  installed for it before stays, in the place the workspace's rules give it. Tell the user to make the two copies equal in the team repo or
+  rename one. Each repo still receives its own copy.
+
+## 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. Use a
+short-lived `api`-scope token via a no-echo prompt (not a literal `export`, which
+lands in shell history), and `unset GITLAB_TOKEN` afterward:
+
+```bash
+export GITLAB_URL=https://git.example.com
+read -rs GITLAB_TOKEN && export GITLAB_TOKEN   # paste when prompted; api scope
+teamai init https://git.example.com/yourgroup/yourrepo
+```
+
+A member who only syncs and never needs the CLI to open merge requests can skip
+both: `teamai init <url> --provider git` uses their existing Git authentication.
+
+For a GitLab deployed at a sub-path, include that path in `GITLAB_URL`, for
+example `https://git.example.com/gitlab`. MR import keeps it in the API base
+and removes it from the project id. An MR outside that instance path is refused.
+
+## Which tools actually get hooks
+
+`teamai hooks inject` prints **"Hooks injected into all AI tool settings"** even
+for tools where it wrote nothing. **Do not take that line as proof.** (When the
+team hooks cannot be resolved it exits 1 with the reason instead: the built-in
+hooks are installed, the team hooks are left as they were.) 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                 | Installed and trusted     | Codex runs only trusted hooks; teamai trusts the ones it writes through `codex app-server`, and `teamai doctor` names any Codex will not run |
+| Cursor                | Installed                 | Also runs `~/.claude/settings.json`. That copy exits only when `~/.cursor/hooks.json` or the project `.cursor/hooks.json` contains `--tool cursor` |
+| Copilot CLI           | Installed                 | Built-ins use `$COPILOT_HOME/hooks/teamai.json` (default `~/.copilot/hooks/teamai.json`); self mode keeps them in the project. Claude built-ins exit for a valid, enabled version-1 file, global or project, with a `--tool copilot` command; self mode checks only the project directory. A Claude team hook exits only when a valid, enabled project version-1 file delivers the same command to Copilot for the same event and matcher. `COPILOT_CLI` alone does not skip |
+| CodeBuddy / WorkBuddy | Installed                 | Claude-format hooks in their own `settings.json`                    |
+
+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 runs a non-managed hook only once it is **trusted**. `teamai init`, `pull`
+and `teamai hooks inject` trust the hooks they write (and, in a project, the main
+checkout, or the current worktree when Git cannot locate a main checkout) through `codex app-server`.
+Trust written by a session-start pull applies from the next Codex session. `teamai doctor` names any teamai hook Codex will not
+run. Then: run `teamai pull`; if `codex` is not on PATH or `codexTrustEnabled: false`
+is set in `config.yaml`, guide the user to trust the teamai hooks in Codex `/hooks`,
+then reopen a session. A new linked worktree gets the team hooks from its second
+Codex session (the first creates its `.codex/`). Member hooks with the same command
+are preserved and remain untouched by automatic trust. Codex ownership uses the
+recorded event, position and complete entry. A moved entry is recovered only by a
+unique full-definition match. Legacy records recover only a unique event, matcher
+and command match; `timeout` and `additionalContextLimit` were not recorded.
+Pre-#370 project Codex ownership is imported from the main checkout's
+`.teamai/managed-hooks.json` before reconciliation or direct removal.
+An unrecorded entry equal to teamai's entry for exactly one team hook (current or
+any earlier team-repo revision) is adopted, so a lost manifest adds no second copy.
+Other unrecorded copies are preserved; pull and doctor name the ambiguous ones.
+Project hook paths follow `toolPaths`;
+Claude uses `settings.local.json` beside its configured settings file. A custom
+Codex path that Codex does not load is reported as `not loaded` by doctor.
+
+### Cursor
+
+Cursor writes hooks to `~/.cursor/hooks.json` and also runs `~/.claude/settings.json`. `hook-dispatch --tool claude` and team hook commands written for `claude` exit only when `CURSOR_VERSION` is set and `~/.cursor/hooks.json` or `$CURSOR_PROJECT_DIR/.cursor/hooks.json` contains `--tool cursor`. A setup with only Claude has no second copy, so those hooks still run inside Cursor. Claude Code does not set `CURSOR_VERSION`. An already installed team hook picks up the guard on the next `teamai pull` or `teamai hooks inject`. If `teamai hooks list` shows Cursor without hooks, run `teamai pull` at the start of the session.
+
+### Copilot CLI
+
+Built-in hooks use `$COPILOT_HOME/hooks/teamai.json` (default `~/.copilot/hooks/teamai.json`) for normal project installs. Custom team hooks stay in `.github/hooks/teamai.json`; self mode keeps built-ins there too. The next `init`, `pull`, or `hooks inject` migrates each project’s generated built-ins, preserving unrelated hooks. Self sessions skip the global copy. Otherwise each event runs once among the copies a session loaded (global files under any name, or a legacy project command a running host still holds): the first copy claims the event under `~/.teamai/copilot-hook-claims/` and the others exit. A payload without a `timestamp`, or a claim that cannot be written, runs every loaded copy. A cached copy stops once no enabled JSON file Copilot loads holds its built-in: a global copy checks `$COPILOT_HOME/hooks/`, and a legacy project copy checks that directory and its project’s `.github/hooks/`. Hook dispatch uses the working directory’s project config, including its `builtin.disabled`; `builtin.overrides` timeouts do not apply to the shared file. A custom hooks filename keeps its name in `$COPILOT_HOME/hooks/`. Project uninstall preserves the shared global hooks; `hooks remove` removes the built-ins from every JSON file in `$COPILOT_HOME/hooks/`, including filenames other projects configured.
+
+Copilot CLI runs a trusted project's `.claude/settings.json` as well as its own `.github/hooks/teamai.json`. `hook-dispatch --tool claude` exits only when `COPILOT_PROJECT_DIR` is set and a valid version-1 hook file without `disableAllHooks`, in the project or global hook directory, has a command containing `--tool copilot`; self mode checks only the project directory. A team hook command written for `claude` exits only when an active version-1 JSON file in `$COPILOT_PROJECT_DIR/.github/hooks/` holds the same command for the same event and matcher, so a hook the project sends only to Claude, or to Copilot for another event or matcher, keeps running. `COPILOT_CLI` is not a signal: Copilot sets it on every subprocess, including a Claude session started from its shell. Copilot does not run `~/.claude/settings.json`. Re-run `teamai pull` or `teamai hooks inject` so an already installed team hook picks up the guard.
+
+### 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 list`
+to see what should be present, then have them replicate it. Until then, they can
+sync with a manual `teamai pull`.
+
+### Muse Code
+
+Hooks go in the `hooks` block of `~/.config/muse/settings.json`, which Muse runs in every workspace; a project's `.muse/hooks.json` runs only once the workspace is trusted. Muse starts each hook with an emptied environment, so a variable set only on the command that launched `muse` (such as `TEAMAI_HOOKS_DISABLED=1 muse`) does not reach the hook. The hook command runs `bash -lc`, so export it in `~/.bash_profile` or `~/.profile` instead.
+
+### 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.
+
+## "A recalled doc got no upvote"
+
+A recalled doc is upvoted once per session when the session that ran the recall
+opens it within 24 hours: a file read, a reader command (`cat`, `sed -n`, …), or
+a search whose output shows its lines. Listing the doc does not count, and
+neither does working from the recall subagent's summary alone; only the opt-in
+judge (`TEAMAI_UPVOTE_JUDGE=1`) credits that. `teamai stats` shows each recent
+session's runs, recalled docs and adopted docs. Per agent:
+
+- **Claude Code, Codex (0.134+), CodeBuddy (2.103.1+), WorkBuddy, Qoder,
+  OpenCode, OMP**: both a recall the main agent runs and one the
+  `teamai-recall` subagent runs are credited when the main agent opens the doc.
+  On OMP the subagent's recall needs the main session's file on disk, so a
+  `--no-session` run credits only the main agent's own recalls.
+- **Cursor, Copilot CLI, ZCode, Pi**: only a recall the main agent runs
+  itself. A subagent's recall is not linked to the main session, and Pi has no
+  TeamAI subagent.
+- **OpenClaw, Hermes, Kiro, JoyCode, Trae**: no PostToolUse hook, so recalls never
+  vote.
+
+A read after the session's last Stop is credited at SubagentStop, at Copilot CLI's
+SessionEnd, or at the next `teamai pull`.
+
+Pending votes reach the team repo's `teamai-reports` branch on the next Stop or
+`teamai pull`. A push that fails — offline, no write access, a crashed run —
+keeps the deltas pending; the next session re-sends them, and each delta is
+added to the team totals exactly once.
+
+Index rebuilds (including `teamai pull`) use confirmed team votes plus pending
+local votes, even when reporting is disabled or a push fails. A busy votes lock
+makes that rebuild use confirmed counts only; it does not wait for the lock.
+
+Manual `teamai recall feedback --positive <docId>` adds an upvote without adding
+a recall. Confidence caps the upvote-to-recall ratio at 1: more feedback cannot
+exceed that factor's 30% weight or replace recency. This is an activity score,
+not proof of knowledge correctness or task success.
+
+## OpenCode V2 rejects the hooks plugin
+
+If OpenCode reports “Plugin must export a default definition”, upgrade TeamAI,
+run `teamai hooks inject` or `teamai pull`, and restart OpenCode. The generated
+built-in and enterprise plugins support both OpenCode 1.18.23 (`server`) and V2
+(`setup`). V1 shell recall uses `TEAMAI_AGENT_SESSION_ID`; V2 supplies its native
+`OPENCODE_SESSION_ID`.
+
+## 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.
+
+## "Pull left an instruction file unchanged"
+
+If pull reports incomplete TeamAI markers, it keeps the entire file unchanged.
+Fix the named block so it has exactly one start marker followed by one end
+marker, then run `teamai pull` again. Other files can still sync successfully.
+
+Pull keeps retired instruction blocks until every installed tool that wrote the
+file has a working replacement. Repair the named target, extension or plugin
+and run `teamai pull` again. Excluded tools' current and retired files stay
+unchanged and are excluded from doctor's stale-instruction check.
+When a native project file retains a TeamAI block, the session hook skips that
+block, including cached HTTP prompts, until cleanup succeeds. Other blocks
+still reach the hook. Doctor reports malformed markers in retired files;
+repair them before retrying pull.
+If a block's source cannot be resolved, its old block stays even when other
+blocks sync. Repair the source and pull again to complete its migration.
+HTTP prompt commands verify earlier deliveries against the current prompt
+before cleaning shared instructions. Older destination contents do not count;
+culture and recall stay because HTTP prompt commands do not replace them.
+An HTTP prompt sync that cannot clean retired blocks reports a failed ACK and
+keeps its previous cache and manifest for the server's retry.
+OpenClaw HTTP prompts require an existing resolved user workspace, but not an
+existing `AGENTS.md`: the prompt sync creates that file and preserves personal
+text already in it.
+
+OpenCode registration saves ownership before activating a new config entry.
+If the state write fails, repair the state directory's permissions and retry
+`teamai pull`; the entry is not activated without its removal ownership.
+If the config write fails, ownership stays available for retry. Entries the
+member already listed are never claimed.
+
+## GitHub MR/PR import API error
+
+When import falls back from `gh` to the REST API, a failed metadata, commits,
+or diff request stops before AI extraction and names the HTTP status and
+response body. Check PR visibility and authentication for 404/403, the rate
+limit for 429, or retry a temporary server failure. The error page is not a diff.

package/skill-data/setup/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: setup
+description: >-
+  TeamAI day 0 and repo lifecycle: create a team repo as admin, join an existing team as a member,
+  manage members, roles, MCP and env, and uninstall. Loaded on demand by the teamai discovery stub.
+---
+
+# teamai — setup and lifecycle
+
+You run the commands; the user only makes choices when you ask. **They may not
+know Git** — never explain branches, commits or clones.
+
+## Before anything
+
+```bash
+node --version      # must be >= 20
+teamai --version    # install once with: npm install -g teamai-cli
+```
+
+Then pick the flow. A user **setting up a new team** becomes its admin and creates
+the repo; a user **joining an existing team** needs a repo URL from their admin. A
+would-be member without a URL is still the **join** flow — `join-member.md` tells
+them how to ask for it. Do not send them to the create-repo flow because the URL
+is missing.
+
+| The user wants to…                                                          | Load this                                   |
+|-----------------------------------------------------------------------------|---------------------------------------------|
+| Set up TeamAI for a team from scratch (create the repo)                      | `{SKILL_DIR}/references/setup-admin.md`     |
+| Join their team, with or without a repo URL                                  | `{SKILL_DIR}/references/join-member.md`     |
+| Publish or update skills, rules, MCP, env; invite members; manage roles      | `{SKILL_DIR}/references/manage-admin.md`    |
+| Remove TeamAI from this machine                                              | `{SKILL_DIR}/references/uninstall.md`       |
+| Publish one skill or contribute a doc                                        | `"$(teamai skill path core)/references/contribute-member.md"` |
+| Anything that breaks along the way                                           | `"$(teamai skill path core)/references/troubleshooting.md"` |
+
+Supported Git providers are Tencent TGit, GitHub, GitLab and CNB;
+`{SKILL_DIR}/references/setup-admin.md` carries the detection probe, the sign-in
+and create-repo URLs, and the per-provider caveats, and points at
+`{SKILL_DIR}/references/provider-tgit.md` for everything TGit-specific.
+
+## Rules for these flows
+
+1. **Always use a full URL** for the team repo (e.g.
+   `https://github.com/your-org/your-repo`). Never the `owner/repo` short form.
+2. **Don't limit which AI tools get set up — cover all of them by default.**
+   Unless the user names specific tools, do **not** pass `--agent` to restrict the
+   install. Let `teamai init` set up every AI tool already installed (omitting
+   `--agent` gives an interactive picker; select all detected tools). **After init,
+   report which agents were set up** — in the user's language, which tools now
+   auto-start TeamAI, which detected tools were skipped and why (e.g. CodeBuddy
+   design), and any installed hooks that still need trust (e.g. Codex with
+   automatic trust disabled or unavailable). Verify the real per-tool result with
+   `teamai doctor` and `teamai hooks list`.
+3. **`teamai init` does not pull.** It saves the config and installs hooks. It does
+   not copy team skills, rules or MCP. In workspace scope it creates a tool directory
+   only for a tool named with `--agent`, or picked when a person runs it in a
+   terminal. Those resources arrive on that tool's next session start, or when you
+   run `teamai pull`. Run from an agent shell (no terminal), a workspace-scope init
+   without `--agent` creates no tool directory: the directory appears when the user
+   opens that tool in the project, and that session start pulls.
+4. **Finish with `teamai doctor`.** Every setup or onboarding flow ends by running
+   it and resolving what it reports before you call the job done.
+
+Every public command and every flag, including the flags `--help` hides, is listed in
+`teamai skill get core --full` under `references/commands.md`. Do not guess a flag:
+there is no member-invite flag, for instance — inviting happens on the Git
+platform's website, as `manage-admin.md` describes.
+
+## References
+
+In the files below, `{SKILL_DIR}` is the directory `teamai skill path setup` 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/setup-admin.md` | Creating a team repo: provider detection, auth, repo creation, first push. |
+| `{SKILL_DIR}/references/join-member.md` | Joining an existing team from a repo URL. |
+| `{SKILL_DIR}/references/manage-admin.md` | Day-to-day admin: publishing resources, roles, projects, MCP, env, members. |
+| `{SKILL_DIR}/references/uninstall.md` | Removing TeamAI from a machine or from one agent. |
+| `{SKILL_DIR}/references/provider-tgit.md` | Tencent TGit: reachability probe, `gf` install and login, repo creation on init. |
+
+`teamai skill get setup --full` prints this skill with all five appended.