teamai-cli 0.26.0-beta.1 → 0.26.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamai-cli",
-  "version": "0.26.0-beta.1",
+  "version": "0.26.0-beta.3",
   "description": "TeamAI — Make Every Team AI Native (skill sync + shared knowledge base, powered by Git)",
   "type": "module",
   "bin": {

package/skill-data/core/SKILL.md

@@ -15,7 +15,11 @@ do not skip, reorder, or invent commands.
 
 Look at what the user typed after `/teamai`.
 
-**If they gave NO scenario** (bare `/teamai`, or only greetings/no task):
+**If they gave NO scenario right after a TeamAI friction reminder** (the
+`[teamai]` line that suggests `/teamai share what this session taught me`),
+that reminder is the scenario: load `teamai skill get share` and follow it.
+
+**If they gave NO scenario otherwise** (bare `/teamai`, or only greetings/no task):
 print the menu below **exactly**, then **STOP and wait**. Take no other action —
 do not run any command, do not load another skill yet.
 
@@ -62,7 +66,8 @@ Sharing a session's learnings needs no menu choice: TeamAI prompts on its own at
 the end of a session that produced something worth sharing, and that prompt means
 `teamai skill get share`. (Only when recall is on; it is off by default. The team turns it on with
 `sharing.recall.enabled: true` in `teamai.yaml`, a member with `teamai recall enable`;
-while it is off, `teamai skill get share` says so.)
+while it is off, or while the teamai config cannot be loaded, `teamai skill get share`
+says so and why.)
 
 ## Global rules
 

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

@@ -37,6 +37,7 @@ Generated: do not edit by hand. Regenerate with
   - `--skill <path>` — Push a specific skill by path (e.g., ~/.claude/skills/hai/my-skill or skills/hai_dev/my-skill)
   - `--role <id>` — Namespace for new skills, rules and agents (skills/<id>/, rules/<id>/, agents/<id>/)
   - `--project <id>` — Target a project: each new resource goes to that project's namespace for its own type — skills, knowledge for rules, agents (from manifest/projects.yaml)
+  - `--branch <name>` — Push to this destination branch instead of a generated teamai/push branch
 
 ## pull
 
@@ -120,6 +121,16 @@ Generated: do not edit by hand. Regenerate with
 - `teamai projects` — Manage multi-project resource distribution (orthogonal to roles)
   - `teamai projects list` — List defined projects and the ones active in this directory
   - `teamai projects set [ids...]` — Set the projects active in this directory (comma-separated or repeated; empty to clear)
+  - `teamai projects add <id>` — Add a project to manifest/projects.yaml, creating the file if needed (admin)
+    - `--namespaces <ns>` — Comma-separated namespaces for every project resource type (e.g. common,checkout)
+    - `--name <name>` — Display name for the project
+    - `-d, --description <desc>` — Description for the project
+  - `teamai projects update <id>` — Update a project in manifest/projects.yaml (admin)
+    - `--add-namespaces <ns>` — Comma-separated namespaces to add to every resource type
+    - `--remove-namespaces <ns>` — Comma-separated namespaces to remove from every resource type
+    - `--name <name>` — New display name for the project
+    - `-d, --description <desc>` — New description for the project
+  - `teamai projects remove <id>` — Remove a project from manifest/projects.yaml (admin)
   - `teamai projects members <id>` — List members registered for a project
 
 ## tags
@@ -207,11 +218,38 @@ Generated: do not edit by hand. Regenerate with
   - `teamai webhook test` — Send test event to webhook endpoints
     - `--url <url>` — Test specific endpoint URL
 
+## models
+
+- `teamai models` — Share gateway model profiles and switch agents to them
+  - `teamai models list [profile]` — Show team and personal model profiles, or one profile, and the agents using them
+  - `teamai models add <id>` — Add a personal model profile stored only on this machine
+    - `--name <name>` — Display name
+    - `--protocol <protocols>` — Comma-separated: anthropic, openai-chat-completions, openai-responses
+    - `--base-url <url>` — Gateway root URL (without /v1)
+    - `--model <ids>` — Comma-separated model IDs; the first is the default
+    - `--from-env <name>` — Read the API key from this environment variable
+    - `--api-key-stdin` — Read the API key from stdin without placing it in shell history
+  - `teamai models configure <profile>` — Set the API key of a profile, or edit a personal profile
+    - `--from-env <name>` — Read the API key from this environment variable
+    - `--api-key-stdin` — Read the API key from stdin without placing it in shell history
+    - `--name <name>` — Personal profiles: new display name
+    - `--base-url <url>` — Personal profiles: new gateway root URL
+    - `--protocol <protocols>` — Personal profiles: serve models over these protocols too
+    - `--model <ids>` — Personal profiles: add model IDs
+  - `teamai models switch <profile>` — Point agents at a model profile (every compatible agent by default)
+    - `--agent <name>` — Only switch this agent. Repeatable or comma-separated.
+    - `--model <id>` — Default model to select (defaults to the first in the profile)
+    - `--dry-run` — Show what would change without writing
+  - `teamai models restore` — Restore agent model settings captured before the first TeamAI switch
+    - `--agent <name>` — Only restore this agent. Repeatable or comma-separated.
+    - `--dry-run` — Show what would change without writing
+  - `teamai models remove <profile>` — Remove a personal model profile without changing agent settings
+
 ## stats
 
 - `teamai stats` — Show local skill usage statistics
-  - `--by-repo` — Break usage down per repository
-  - `--by-time` — Show activity by hour of day
+  - `--by-repo` — Break the local event log down per repository
+  - `--by-time` — Show local event log activity by hour of day
 
 ## session
 
@@ -272,7 +310,7 @@ Generated: do not edit by hand. Regenerate with
 
 - `teamai import` — Import knowledge from local directories, remote repos, organizations, MRs, or iWiki
   - `--dir <path>` — Extract code knowledge from a local directory (same as --from-repo but no clone)
-  - `--from-claude` (hidden) — Scan Claude/Cursor rule directories (~/.claude/rules, ~/.cursor/rules)
+  - `--from-claude` (hidden) — Scan Claude/Cursor rule directories (the Claude root's rules/ — ~/.claude or the recorded toolRoots.claude — and ~/.cursor/rules)
   - `--from-mr <url>` — Extract learning from merged MR/PR and trigger incremental teamwiki update
   - `--from-iwiki <space-id-or-url>` — Import documents from iWiki Space ID or page URL (requires TAI_PAT_TOKEN)
   - `--resume` (hidden) — Resume an interrupted import session

package/skill-data/core/references/contribute-member.md

@@ -3,12 +3,20 @@
 Goal: the user turns something they built into team knowledge everyone can pull.
 **Any member can do this — you do not need to be an admin.** The usual entry point
 is the user just asking in plain language, e.g. *"share this xxx skill with my
-team"*, in whatever language they work in — then you run the publish for them.
+team"*, in whatever language they work in.
+
+**Publishing is a team-visible action — confirm before you run it.** A plain
+worded request tells you *what* the user wants, not that they are ready to push
+it to everyone. Before `teamai push` / `teamai contribute`, show exactly what
+will be shared (which skill or file, and that it goes to the whole team) and get
+an explicit go-ahead. Do not publish from an offhand mention of "sharing" in
+ordinary conversation — only when the user has clearly asked to publish *this*
+thing now.
 
 ## Which kind of contribution?
 
 - **A learning** (a lesson, a gotcha, how you solved something) → this is
-  **automatic** once recall is on (off by default): TeamAI prompts at the end of a session worth sharing and the
+  **automatic** once recall is on (off by default) and the teamai config loads: TeamAI prompts at the end of a session worth sharing and the
   dedicated `share` workflow (`teamai skill get share`) takes over (it summarizes the
   session and runs `teamai contribute`). The user does not come through this flow
   for it. (Step A below is only a manual fallback for while recall is off.)
@@ -89,7 +97,10 @@ The doc lands in the team's `learnings/` and appears for teammates on their next
    new rule and a new agent land in that namespace too (a project resolves each
    from its own axis — `knowledge` for rules, `agents` for agents). Without one,
    a new resource whose namespace cannot be resolved stays at the shared root and
-   reaches the whole team.
+   reaches the whole team. Use `--branch <name>` when a new push must target a
+   specific branch; an existing open PR keeps its recorded branch. TeamAI refuses
+   to reset a team-repo clone with user changes, so commit or stash unrelated
+   modified, staged, untracked, or conflicted files before retrying.
 
 ## After contributing
 

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

@@ -34,6 +34,12 @@ This is the #1 onboarding issue. In order:
    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 reads a different directory** (`CLAUDE_CONFIG_DIR` is set).
+   `teamai doctor` reports `Claude Code root matches CLAUDE_CONFIG_DIR` 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 nested deeper than `~/.config/<name>`), 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
@@ -56,11 +62,13 @@ default is a common cause.
 
 ## GitLab host not detected
 
-If `init` can't confirm a self-hosted GitLab instance, set both and retry:
+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
-export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxx   # api scope
+read -rs GITLAB_TOKEN && export GITLAB_TOKEN   # paste when prompted; api scope
 teamai init https://git.example.com/yourgroup/yourrepo
 ```
 

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

@@ -39,12 +39,13 @@ If it fails, Node.js ≥ 20 is missing — have them install Node 20+ first.
 
 Match the login to the URL's host (do NOT create a second repo):
 
-- **`git.woa.com/...`** (Tencent TGit) → **you run both the `gf` install and
-  the `gf … auth login`** (never tell the user 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.)
+- **`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);
@@ -88,6 +89,14 @@ 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 kept in a different directory (`CLAUDE_CONFIG_DIR`):** `init` records
+that directory (as `toolRoots.claude` in the local config) and syncs every Claude
+path 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, managed MCP
+servers and delivered model credentials are removed; 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 …`.
+
 ## Step 5 — Verify with doctor
 
 ```bash
@@ -143,7 +152,8 @@ Summarize the outcome **in the user's own language** (global rule 1). Cover:
    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`.)
+   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

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

@@ -16,8 +16,13 @@ existing ones:
 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`).
 
@@ -76,10 +81,16 @@ repo per project:
 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 member gets the union of their role resources and their active project's
-resources. Admins declare projects in `manifest/projects.yaml`, then `teamai push`.
+resources. Admins declare projects in `manifest/projects.yaml` with the commands
+above, each of which opens a PR (`--dry-run` previews). 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.
 
 Every namespace that names a directory — `knowledge`, `skills` and `agents` in
 either manifest, and `learnings` in `projects.yaml` (a role's `learnings:` is
@@ -133,14 +144,16 @@ the team (`sharing.recall.enabled: true` in `teamai.yaml`, then `teamai push`; i
 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.
+`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.)
 (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. To disable it team-wide, set this in
+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

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

@@ -22,12 +22,15 @@ 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` — YOU run both
+## Log in: install `gf`, then `gf auth login`
 
-TeamAI drives the TGit CLI (`gf`) on the user's behalf. **Run every command in this
-section yourself — both the install and the login. Never tell the user to run a
-`gf` command.** The user's only action is approving the login in their browser /
-iOA when it opens.
+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)
 
@@ -35,17 +38,37 @@ Use the **same source, path, and check teamai uses** — do not invent your own
 `${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"
 
-# download + extract from the Tencent-internal mirror (same URL teamai uses)
+# unique temp files per attempt so concurrent/interrupted runs never collide,
+# cleaned up on any exit
 mkdir -p "$dir"
-curl -fsSL "http://mirrors.tencent.com/repository/generic/gongfeng-cli/files/channels/stable/gf-${os}-${arch}.tar.gz" | tar xz -C "$dir"
-
+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" || echo "gf install FAILED"
+test -x "$dir/gf/bin/gf"
+echo "gf installed OK"
 ```
 
 Only macOS and Linux, on x64 or arm64, are supported.

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

@@ -138,12 +138,15 @@ with `repo` scope — instead.)
 
 ### GitLab (gitlab.com)
 
-Set a Personal Access Token with `api` scope:
+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
-export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxx
+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`.
+`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.
 
@@ -187,9 +190,11 @@ If the repo does not exist yet, `init` offers to create it — accept the prompt
 - If `init` detects an unknown GitLab host, it stops and asks you to set
   `GITLAB_URL` + `GITLAB_TOKEN`, then retry.
 
-If the repo has roles enabled, `init` may ask for a primary role — pick one with
-the user, or pass `--role <id>` for a non-interactive run. Without a terminal
-(or with `CI` / `TEAMAI_NONINTERACTIVE` set) `init` never waits: a provider that
+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).
@@ -275,7 +280,8 @@ day-to-day work — they can keep letting the AI run things for them:
   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`.)
+  `teamai push`. Never on a read-only HTTP source, or while a member's teamai
+  config cannot be loaded.)
 
 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`.