teamai-cli 0.25.0 → 0.26.0-beta.1

package/{skills/teamai → skill-data/setup}/references/join-member.md

@@ -19,7 +19,7 @@ platforms, and — most importantly — **do not create a new repo.** Tell the u
 *"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 `setup-admin.md` — not this one.)
+flow — see `{SKILL_DIR}/references/setup-admin.md` — not this one.)
 
 ## Step 1 — Install and verify
 
@@ -39,11 +39,12 @@ 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
+- **`git.woa.com/...`** (Tencent TGit) → **you run both the `gf` install and
   the `gf … auth login`** (never tell the user to run them). Follow
-  `provider-tgit.md` ("Log in"); the user's only action is approving the login URL
-  in their browser / iOA. No `GITLAB_URL` needed. (Headless only: pre-set
-  `TGIT_TOKEN`.)
+  `{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);
@@ -97,7 +98,8 @@ 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 `troubleshooting.md` ("Which tools actually get hooks").
+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
 
@@ -122,8 +124,7 @@ 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 `troubleshooting.md`
-("Agent-specific caveats") and walk the user through it before finishing.
+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
 
@@ -138,16 +139,18 @@ Summarize the outcome **in the user's own language** (global rule 1). Cover:
    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 `teamai-share-learnings` skill takes over to
+   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 if the admin left team sharing enabled — it is on by
-   default; the admin can turn it off in `teamai.yaml`.)
+   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`.)
 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"* / *"把这个 xxx skill 分享给团队"*, and you
-   run the publish for them (see `contribute-member.md`).
+   *"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 卸载` / `/teamai Uninstall TeamAI`.
+   `/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/{skills/teamai → skill-data/setup}/references/manage-admin.md

@@ -74,13 +74,22 @@ repo per project:
 
 ```bash
 teamai projects list         # projects defined + the ones active in this directory
-teamai projects set <id>     # set the active project(s) for this directory
+teamai projects set [ids...]     # set the active project(s) for this directory
 teamai projects members <id> # who is registered on 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`.
 
+Every namespace that names a directory — `knowledge`, `skills` and `agents` 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`, …). 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.
+
 ## Team dashboard (web UI)
 
 ```bash
@@ -114,21 +123,24 @@ teamai env remove <KEY>      # remove
 ## When sync fails
 
 Run `teamai doctor` first. If it reports hook or path problems, load
-`troubleshooting.md`. Have the affected member reopen their session; if their tool
+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**: at the end of a session
+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
-**`teamai-share-learnings`** skill summarizes the session and runs
+`share` workflow (`teamai skill get share`) summarizes the session and runs
 `teamai contribute`. Nobody has to invoke it by hand.
 (Publishing a **reusable skill** someone authored is a different task — any member
-can do it, see `contribute-member.md`.)
+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**. To disable it team-wide, set this in
+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
 `teamai.yaml` and `teamai push`:
 
 ```yaml

package/{skills/teamai → skill-data/setup}/references/provider-tgit.md

@@ -1,15 +1,16 @@
-# Provider: Tencent TGit (工蜂)
+# 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 `setup-admin.md` and `join-member.md` point here for the reachability probe
-and the `gf` login; follow the relevant section for whichever flow you are in.
+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,
+`x-env: tgit` means TGit is reachable — plain reachability is not enough,
 the header is what confirms it:
 
 ```bash
@@ -62,8 +63,10 @@ their browser — that approval is the *only* thing they do; the command finishe
 its own once they do. Confirm with
 `"${TEAMAI_HOME:-$HOME/.teamai}/gf/gf/bin/gf" auth whoami` before continuing.
 
-(Headless/CI only: skip the interactive login and pre-set `TGIT_TOKEN` — a
-git.woa.com Personal Access Token — instead.)
+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
 

package/{skills/teamai → skill-data/setup}/references/setup-admin.md

@@ -24,13 +24,13 @@ through these sub-steps **in order**:
 
 ### 2a — Ask which platform they know
 
-**Tencent-internal first:** before asking, probe whether TGit (工蜂) is reachable
-on this machine — see `provider-tgit.md` ("Probe reachability") for the one-line
-`x-env: tgit` check. If it says `tgit: OK`, **list Tencent TGit (工蜂) first** and
+**Tencent-internal first:** before asking, probe whether TGit is reachable
+on this machine — see `{SKILL_DIR}/references/provider-tgit.md` ("Probe
+reachability") for the one-line `x-env: tgit` check. If it says `tgit: OK`, **list Tencent TGit first** and
 prefer it. Then ask: *"Have you heard of / do you have an account on any of these —
-Tencent TGit (工蜂), GitHub, GitLab, or CNB (cnb.cool)?"*
+Tencent TGit, GitHub, GitLab, or CNB (cnb.cool)?"*
 
-- **Tencent TGit (工蜂)** — https://git.woa.com (Tencent-internal only; shown
+- **Tencent TGit** — https://git.woa.com (Tencent-internal only; shown
   first when the probe above says `tgit: OK`)
 - **GitHub** — https://github.com
 - **GitLab** — https://gitlab.com (or a self-hosted company GitLab)
@@ -42,7 +42,7 @@ If they name one, use that platform and go to sub-step 2c.
 
 Test which sites this network can actually reach (probe each, ~3s timeout each).
 The TGit probe checks the `x-env: tgit` header, not just reachability (see
-`provider-tgit.md`); the others just check reachability:
+`{SKILL_DIR}/references/provider-tgit.md`); the others just check reachability:
 
 ```bash
 curl -sS -m 3 -D - -o /dev/null https://git.woa.com 2>/dev/null | grep -qi '^x-env:[[:space:]]*tgit' && echo "tgit: OK" || echo "tgit: unreachable"
@@ -51,12 +51,12 @@ curl -sSf -m 3 -o /dev/null https://gitlab.com  && echo "gitlab: OK"  || echo "g
 curl -sSf -m 3 -o /dev/null https://cnb.cool     && echo "cnb: OK"     || echo "cnb: unreachable"
 ```
 
-- **TGit reachable (`tgit: OK`)** → prefer Tencent TGit (工蜂); it is the
+- **TGit reachable (`tgit: OK`)** → prefer Tencent TGit; it is the
   Tencent-internal default.
 - **Exactly one reachable** → use that one.
 - **Several reachable** → list them (TGit first when present) and let the user pick.
 - **None reachable** → stop. Tell the user to ask their own admin for a ready-made
-  repo URL, then switch to `join-member.md`.
+  repo URL, then switch to `{SKILL_DIR}/references/join-member.md`.
 
 Choose by **account + reachability only — never by region**.
 
@@ -67,14 +67,14 @@ the repository, then continue to the next step:
 
 | Platform | Sign in / sign up            | Create a new repo (do this)        |
 |----------|------------------------------|------------------------------------|
-| Tencent TGit (工蜂) | https://git.woa.com | https://git.woa.com/projects/new |
+| Tencent TGit | https://git.woa.com | https://git.woa.com/projects/new |
 | GitHub   | https://github.com/login     | https://github.com/new             |
 | GitLab   | https://gitlab.com/users/sign_in | https://gitlab.com/projects/new |
 | CNB      | https://cnb.cool             | https://cnb.cool/new/repos (org first: https://cnb.cool/new/groups) |
 
-> **Tencent TGit (工蜂):** don't send the user to the browser to create the repo —
+> **Tencent TGit:** don't send the user to the browser to create the repo —
 > prefer letting `teamai init` create it via the API in Step 5. See
-> `provider-tgit.md` ("When you `teamai init` on TGit").
+> `{SKILL_DIR}/references/provider-tgit.md` ("When you `teamai init` on TGit").
 
 Tell the user to sign in, create an **empty** repo (suggested name
 `TeamAi-<team-name>`), and give you the resulting repo URL. Explain in one
@@ -91,10 +91,10 @@ computer only holds a synced copy — you never put business code in it."*
 Signing in on the website (Step 2c) is not enough — `teamai init` also needs the
 platform's CLI credentials. Have the user complete the matching CLI login:
 
-### Tencent TGit (工蜂)
+### Tencent TGit
 
-See `provider-tgit.md` ("Log in") — you install `gf` and run `gf auth login`
-yourself; the user only approves in the browser / iOA. No `GITLAB_URL` needed.
+See `{SKILL_DIR}/references/provider-tgit.md` ("Log in") — you install `gf` and
+run `gf auth login` yourself; the user only approves in the browser / iOA. No `GITLAB_URL` needed.
 Then return here for Step 4.
 
 ### CNB — install the CLI, authorize, then read the repo (in this order)
@@ -172,9 +172,9 @@ teamai init https://<platform>/<org>/<repo-name> --scope user
 
 If the repo does not exist yet, `init` offers to create it — accept the prompt.
 
-- **Tencent TGit (工蜂):** `gf` and login are already done, so init creates the
-  repo via the API when it's missing — see `provider-tgit.md` ("When you
-  `teamai init` on TGit").
+- **Tencent TGit:** `gf` and login are already done, so init creates the
+  repo via the API when it's missing — see
+  `{SKILL_DIR}/references/provider-tgit.md` ("When you `teamai init` on TGit").
 - **CNB caveat:** a `cnb login` token **cannot create** an org or repo — that is
   exactly why the CNB flow has the user create the repo on the website first
   (Step 2c). If the org/repo is still missing here, `init` prints web links
@@ -188,7 +188,11 @@ If the repo does not exist yet, `init` offers to create it — accept the prompt
   `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.
+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
+would need a browser login fails at once and names the credential to prepare —
+a token for GitHub / CNB / GitLab / GitCode, and for TGit a prior `gf auth
+login` run in an interactive shell (see Step 3).
 
 **Which AI tools to set up — all of them by default (global rule 9).** Do not add
 `--agent` to restrict the install unless the user explicitly said to (e.g. "only
@@ -196,7 +200,7 @@ Claude Code"). Omitting `--agent` gives an interactive picker — select **every
 tool already installed** on the machine. Then **report back which agents were set
 up**, in the user's language: name the tools that will now auto-start TeamAI, and
 any detected tool that was skipped and why (e.g. Codex trust-gate,
-CodeBuddy/WorkBuddy by design — see `troubleshooting.md`).
+CodeBuddy/WorkBuddy by design — see the troubleshooting reference, `"$(teamai skill path core)/references/troubleshooting.md"`).
 
 ## Step 6 — Verify with doctor
 
@@ -211,8 +215,8 @@ Resolve everything `doctor` flags before continuing.
 it prints even for tools where nothing was written. `teamai doctor` / `teamai hooks
 list` show the real per-tool status. Only the tool you set up (e.g. `claude`) is
 expected to show hooks installed; others are skipped by design or not yet supported,
-which is normal. Full table in `troubleshooting.md` ("Which tools actually get
-hooks").
+which is normal. Full table in the troubleshooting reference
+(`"$(teamai skill path core)/references/troubleshooting.md"`), section "Which tools actually get hooks".
 
 ## Step 7 — Grant members repo access (required before they can join)
 
@@ -223,7 +227,7 @@ read/write access to it on the platform website**, or their `teamai init` / `pul
 
 Tell the admin (in their language) to add every member on the repo's website:
 
-- **Tencent TGit (工蜂):** repo → 成员管理 / Members → add each member with at
+- **Tencent TGit:** repo → Members → add each member with at
   least **Developer** (read/write) access.
 - **GitHub:** repo → Settings → Collaborators → add with **Write**.
 - **GitLab:** repo → Settings → Members → add with **Developer** or above.
@@ -245,10 +249,8 @@ carries counts + tool names only, on a separate branch of that same repo.)
 
 1. Give the user their **repo web URL** to share.
 2. Give them a ready-to-forward invite line **written in their language**, with the
-   URL filled in. The `/teamai` prefix stays as-is; translate the rest. For a
-   Chinese-speaking user, that is:
-   `/teamai 帮我加入团队的 TeamAI，仓库地址是 <URL>`
-   (English user: `/teamai Help me join my team's TeamAI, repo URL is <URL>`.)
+   URL filled in. The `/teamai` prefix stays as-is; translate the rest:
+   `/teamai Help me join my team's TeamAI, repo URL is <URL>`
    Tell them to send the URL + this line to each member.
 3. Remind them (in their language): **new resources appear only after opening a
    fresh session** in the AI tool. Right after init the skills folder may look
@@ -262,14 +264,18 @@ The user may not be comfortable with the command line, so **don't just hand them
 list of `teamai …` commands.** Instead, point them back to *this skill* for
 day-to-day work — they can keep letting the AI run things for them:
 
-- To manage the team later, they run:
-  `/teamai 我已经装好了，帮我管理` (Chinese) /
-  `/teamai I already have TeamAI set up, help me manage it` (English) — this loads
-  the daily-management flow (`manage-admin.md`): publishing skills, inviting
+- To manage the team later, they run (in their language):
+  `/teamai I already have TeamAI set up, help me manage it` — this loads
+  the daily-management flow (`{SKILL_DIR}/references/manage-admin.md`): publishing skills, inviting
   members, roles / packages / env.
-- To share something they learned:
-  `/teamai 我想把学到的经验分享给团队` /
-  `/teamai I want to contribute what I learned to my team`.
+- To share a reusable skill with the team, they run (in their language):
+  `/teamai Share this <skill-name> skill with my team` — see
+  `"$(teamai skill path core)/references/contribute-member.md"`.
+- Sharing a **session's learnings** needs no command from them: TeamAI prompts on
+  its own at the end of a session worth sharing, and the `share` workflow
+  (`teamai skill get share`) takes over. (Only once recall is on — off by default;
+  turn it on team-wide with `sharing.recall.enabled: true` in `teamai.yaml`, then
+  `teamai push`.)
 
 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`.
@@ -280,10 +286,10 @@ Finish by telling the user, **in their language**, that they can remove TeamAI a
 time — and that they don't need the command line to do it. They just re-invoke the
 skill and you'll handle it:
 
-`/teamai 卸载` (Chinese) / `/teamai Uninstall TeamAI` (English)
+`/teamai Uninstall TeamAI` (in their language; the `/teamai` prefix stays as-is)
 
 One line, in their language: *"That removes the hooks and synced resources from
 your machine; your team repo on the website is untouched — you can rejoin any time
 with `/teamai` and the repo URL."*
 
-(If they ask right now, load `uninstall.md` and run it for them.)
+(If they ask right now, load `{SKILL_DIR}/references/uninstall.md` and run it for them.)

package/skill-data/share/SKILL.md

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

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

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