teamai-cli 0.25.0 → 0.26.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamai-cli",
-  "version": "0.25.0",
+  "version": "0.26.0-beta.1",
   "description": "TeamAI — Make Every Team AI Native (skill sync + shared knowledge base, powered by Git)",
   "type": "module",
   "bin": {
@@ -9,6 +9,9 @@
   "files": [
     "dist/**/*.js",
     "skills",
+    "skill-data",
+    "!**/__pycache__",
+    "!**/*.pyc",
     "agents",
     "README.md",
     "CHANGELOG.md",

package/skill-data/core/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: core
+description: >-
+  TeamAI daily workflow: route a /teamai request, sync with pull and push, inspect status,
+  diagnose with doctor, and reach the specialized workflows. Loaded by the teamai discovery stub.
+---
+
+# teamai — daily workflow
+
+You are guiding a user through TeamAI. **They may not know Git.** You run the
+commands; they only make choices when you ask. Follow the steps literally —
+do not skip, reorder, or invent commands.
+
+## Start here
+
+Look at what the user typed after `/teamai`.
+
+**If they gave NO scenario** (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.
+
+```
+teamai — Team AI Skills & Rules Sync
+
+Usage examples (copy one to get started):
+
+  🏗️  Admin — set up a new team repo:
+      /teamai Help me set up TeamAI for my team from scratch
+
+  🤝  Member — join an existing team:
+      /teamai Help me join my team's TeamAI, repo URL is https://...
+
+  🔧  Admin — daily management (publish & update skills, rules, MCP, env):
+      /teamai I already have TeamAI set up, help me manage it
+
+  📊  Anyone — open the team dashboard:
+      /teamai Open the TeamAI dashboard
+
+  💡  Member — share a skill with the team (just ask in plain language):
+      /teamai Share this <skill-name> skill with my team
+
+  🗑️  Anyone — remove TeamAI from this machine:
+      /teamai Uninstall TeamAI
+```
+
+**If they DID describe a scenario**, match it to one row and follow what it loads.
+
+| The user wants to…                                                    | Load this                                      |
+|-----------------------------------------------------------------------|------------------------------------------------|
+| Set up a team from scratch, join a team, manage one, or uninstall      | `teamai skill get setup`                       |
+| Publish a skill, rule or doc they already have                         | `{SKILL_DIR}/references/contribute-member.md`  |
+| Share what this session taught them                                    | `teamai skill get share`                       |
+| Understand a large multi-repo codebase, build an architecture wiki     | `teamai skill get wiki`                        |
+| Sync now, see differences, diagnose                                    | `teamai pull` · `teamai status` · `teamai doctor` |
+| Open the team dashboard                                                | `teamai dashboard` — it starts a local server (default port 3721); give the user the URL |
+| Something broke                                                        | `{SKILL_DIR}/references/troubleshooting.md`    |
+
+If the request is ambiguous (e.g. "help me with teamai" with no direction),
+ask ONE short question to pick a row, then proceed.
+
+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.)
+
+## Global rules
+
+1. **Reply in the user's language — including every example and hand-off blurb.**
+   Answer in whatever language the user used, for the whole conversation. This
+   applies to **everything you write**: the invite line you give an admin to
+   forward, the one-line explanations, the "what's next" summary — all of it is
+   translated before you show it. *Only* commands, flags, URLs, file paths and
+   code identifiers stay verbatim (never translate `teamai pull`, `--scope user`,
+   `/teamai`, a repo URL).
+2. **Never teach Git.** Do not mention branches, commits, clone, or push/pull of
+   Git itself. TeamAI hides all of that. The user thinks in terms of "my team's
+   skills", not repositories.
+3. **You run the commands.** Only pause to ask the user when you need a web login,
+   a value only they know, or a genuine either/or choice. Show each command before
+   you run it, in one short line.
+4. **Detect the current AI tool first.** TeamAI behaves differently per host. Note
+   which tool this conversation is running in (Claude Code, Cursor, CodeBuddy,
+   WorkBuddy, ChatGPT App, Codex, OpenCode, Kiro, Gemini CLI, …). When you reopen a
+   session, use the name of **this** tool — do not assume Claude Code or Cursor.
+   Some hosts need extra manual steps for hooks — see the troubleshooting
+   reference ("Agent-specific caveats").
+
+## Daily commands
+
+```bash
+teamai pull        # Sync team resources into local AI tools now
+teamai push        # Publish your local skills/rules/docs to the team
+teamai status      # Show local vs team differences
+teamai doctor      # Diagnose configuration and hook problems
+teamai list        # List resources (skills|rules|docs|env|agents|hooks|mcp)
+teamai recall <q>  # Search what the team has already learned
+```
+
+Every other command, every flag, and the flags `--help` hides live in the
+generated reference below. Read it instead of guessing a flag.
+
+## References
+
+In the files below, `{SKILL_DIR}` is the directory `teamai skill path core` 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/commands.md` | Before using any command not in the daily list, or any flag. Generated from the CLI's own command table, so it cannot drift. |
+| `{SKILL_DIR}/references/troubleshooting.md` | A command fails, a hook does not fire, or a host needs manual steps. |
+| `{SKILL_DIR}/references/contribute-member.md` | A member wants to publish a skill, rule or doc they already have. Any member can, not just admins. |
+
+`teamai skill get core --full` prints this skill with all three references
+appended. Load a single file above when you only need one.

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

@@ -0,0 +1,339 @@
+# teamai command reference
+
+Every public command the installed CLI accepts, rendered from its own command
+table. Hidden commands are left out: they are hook plumbing the CLI runs itself,
+never something to type. Flags marked `(hidden)` work but are absent from
+`--help`, so treat this file — not `--help` — as the complete list of flags.
+
+Generated: do not edit by hand. Regenerate with
+`npx vitest run commands-reference -u` after changing a command or a flag.
+
+
+## Global options
+
+- `-V, --version` — output the version number
+- `--dry-run` — Preview mode, no changes made
+- `-v, --verbose` — Verbose output
+
+## init
+
+- `teamai init [repo]` — Initialize teamai (configure Git provider, clone repo, register member)
+  - `--repo <repo>` — Team repo (alias of the positional argument)
+  - `--http <url>` — Git-free HTTP team repo (read-only consumer; only needs an API key)
+  - `--self` — Single-repo mode: the current git repo is the team repo (equivalent to `teamai init .`). Knowledge lives on main under .teamai/; reports go to the teamai-reports orphan branch.
+  - `--token <key>` — API key for HTTP team repo / status reporting (stored 0600, never committed). Also reads TEAMAI_API_TOKEN.
+  - `--scope <scope>` — Install scope: project (default, <cwd>/.teamai + <cwd>/.claude) or user (~/.teamai + ~/.claude)
+  - `--inherit-user-scope` — In project scope, also sync safe user-scope resources and search its knowledge
+  - `--no-inherit-user-scope` — Disable user-scope inheritance for this project
+  - `--role <id>` — Primary role ID (e.g. hai_dev) for non-interactive setup
+  - `--project <ids>` — Active logical project(s) from manifest/projects.yaml (comma-separated); scopes which project resources and learnings this directory syncs. Pass "all" to activate every project the manifest declares (a snapshot taken now)
+  - `--agent <name>` — AI tools to set up (e.g. claude, codex, cursor, codebuddy, workbuddy, dsh). Repeatable or comma-separated. In single-repo mode, selects which tool dirs to create; omit for an interactive picker. Additive on repeated runs.
+  - `--force` — Overwrite existing config without confirmation
+
+## push
+
+- `teamai push` — Push local resources to team repo
+  - `--all` — Push all without confirmation
+  - `--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)
+
+## pull
+
+- `teamai pull` — Pull team resources and inject into local AI tools
+  - `--silent` — Silent mode (for hooks)
+  - `--force` — Force full sync even if repo is unchanged
+
+## status
+
+- `teamai status` — Show local vs team repo diff
+  - `--all` — List every project data partition under ~/.teamai/projects (flags stale/orphan ones)
+
+## list
+
+- `teamai list [type]` — List resources (skills|rules|docs|env|agents|hooks|mcp). For skills, --source local/all also scans installed AI agent skill directories.
+  - `--source <src>` — Where to look for skills: repo | local | all
+  - `--agent <name>` — Filter local agents by id (only applies to skills)
+  - `--reveal` — Show env values in plaintext (default: masked)
+
+## skill
+
+- `teamai skill` — List and inspect skills (default: repo + installed agents, then the CLI-served catalog)
+  - `teamai skill list` — List team and installed skills, then the built-in catalog the CLI serves
+    - `--json` — Output the CLI-served built-in skill catalog as JSON
+  - `teamai skill get [names...]` — Print built-in skill content served by the installed CLI
+    - `--full` — Append the skill's references/ and templates/ files
+    - `--all` — Print every skill the CLI serves
+  - `teamai skill path <name>` — Print the packaged directory of a built-in skill (for scripts and templates)
+  - `teamai skill show <name>` — Show skill metadata: source / contributors / installed agents / description
+  - `teamai skill exclude` — Manage per-user skill exclusion (skip sync without affecting team repo)
+    - `teamai skill exclude list` — List excluded skills
+    - `teamai skill exclude add <skills...>` — Add skill(s) to the exclude list
+    - `teamai skill exclude remove <skills...>` — Remove skill(s) from the exclude list
+
+## members
+
+- `teamai members` — Manage team members
+  - `teamai members list` — List team members
+
+## remove
+
+- `teamai remove <type> <names...>` — Remove resource(s) from team repo and all local AI tools (type: skills|rules|agents|mcp)
+  - `--force` — Skip confirmation prompt
+
+## packages
+
+- `teamai packages [target]` — Install team npm packages and Claude plugins declared in teamai.yaml
+  - `-g, --global` — Install an npm target globally (for CLI tools)
+  - `--registry <url>` — Use a specific npm registry for this target
+  - `--npm` — Treat an ambiguous target as an npm package
+  - `--claude` — Treat the target as a Claude plugin
+  - `teamai packages install [target]` — Install team npm packages and Claude plugins declared in teamai.yaml
+    - `-g, --global` — Install an npm target globally (for CLI tools)
+    - `--registry <url>` — Use a specific npm registry for this target
+    - `--npm` — Treat an ambiguous target as an npm package
+    - `--claude` — Treat the target as a Claude plugin
+
+## doctor
+
+- `teamai doctor` — Diagnose configuration issues
+  - `--json` — Output the report as JSON (suitable for CI)
+
+## roles
+
+- `teamai roles` — Manage team roles and resource namespaces
+  - `teamai roles init` — Create a roles manifest for the team repo (admin)
+  - `teamai roles list` — List all defined roles and your current role
+  - `teamai roles set <primary>` — Set your primary role (updates local config)
+    - `--add <roles...>` — Additional roles to include
+  - `teamai roles add <id>` — Add a new role to the manifest (admin)
+    - `--namespaces <ns>` — Comma-separated resource namespaces (e.g. common,hai)
+    - `-d, --description <desc>` — Description for the role
+  - `teamai roles remove <id>` — Remove a role from the manifest (admin)
+  - `teamai roles update <id>` — Update a role in the manifest (admin)
+    - `--add-namespaces <ns>` — Comma-separated namespaces to add
+    - `--remove-namespaces <ns>` — Comma-separated namespaces to remove
+    - `-d, --description <desc>` — New description for the role
+
+## projects
+
+- `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 members <id>` — List members registered for a project
+
+## tags
+
+- `teamai tags` — Manage tag-based skill/rule filtering
+  - `teamai tags list` — List all available tags and subscription status
+  - `teamai tags subscribe <tags...>` — Subscribe to tags (only matching skills/rules will be synced)
+  - `teamai tags unsubscribe <tags...>` — Unsubscribe from tags
+  - `teamai tags add <type> <name> <tags...>` — Add tags to a skill or rule in tags.yaml (admin)
+
+  <type>  Resource type: "skills" or "rules"
+  <name>  Name of the skill or rule (directory name)
+  <tags>  One or more tags to add
+
+  Examples:
+    $ teamai tags add skills hai-deploy hai infra
+    $ teamai tags add rules common-coding-style coding best-practices
+
+  - `teamai tags remove <type> <name> <tags...>` — Remove tags from a skill or rule in tags.yaml (admin)
+
+  <type>  Resource type: "skills" or "rules"
+  <name>  Name of the skill or rule (directory name)
+  <tags>  One or more tags to remove
+
+  Examples:
+    $ teamai tags remove skills hai-deploy infra
+    $ teamai tags remove rules common-coding-style best-practices
+
+
+## source
+
+- `teamai source` — Manage cross-team skill sources
+  - `teamai source add <repo>` — Add a cross-team source repo
+    - `--name <name>` — Alias for this source
+  - `teamai source remove <name>` — Remove a source and clean up its skills
+  - `teamai source add-http <endpoint>` — Add an HTTP source (report/sync/ack) alongside a git main repo
+    - `--token <key>` — API token for the HTTP endpoint (stored 0600, never committed)
+    - `--force` — Overwrite an existing HTTP source config
+  - `teamai source remove-http` — Remove the HTTP source and clean up its resources
+  - `teamai source list` — List all configured sources
+  - `teamai source browse <name>` — Browse public skills from a source
+
+## update
+
+- `teamai update` — Check for updates and upgrade teamai CLI
+  - `--check` — Only check if an update is available, do not install
+
+## uninstall
+
+- `teamai uninstall` — Remove all teamai-managed resources and hooks from this machine
+  - `--force` — Skip confirmation prompt
+  - `--agent <name>` — Only uninstall this agent's resources; shared resources go only if it is the last tool
+
+## env
+
+- `teamai env` — Manage team environment variables
+  - `--reveal` — Show env variable values in plaintext (default: masked)
+  - `teamai env list` — List team environment variables
+    - `--reveal` — Show env variable values in plaintext (default: masked)
+  - `teamai env add <key> <value>` — Add or update a team environment variable
+    - `-d, --description <desc>` — Description for the variable
+  - `teamai env remove <key>` — Remove a team environment variable
+
+## hooks
+
+- `teamai hooks` — Manage teamai hooks in AI tool settings
+  - `teamai hooks list` — List hook install status + effective built-in (A) and team (B) hooks
+  - `teamai hooks inject` — Inject teamai hooks into all AI tool settings
+    - `--silent` — Silent mode (suppress success message)
+  - `teamai hooks remove` — Remove teamai hooks from all AI tool settings
+
+## mcp
+
+- `teamai mcp` — Manage team MCP servers across AI tools
+  - `teamai mcp list` — List team MCP servers and their per-tool install status
+  - `teamai mcp inject` — Inject team MCP servers into all AI tool configs
+    - `--dry-run` — Show what would change without writing
+    - `--force` — Overwrite servers that collide with user-owned entries
+  - `teamai mcp remove` — Remove all teamai-managed MCP servers from AI tool configs
+
+## webhook
+
+- `teamai webhook` — Manage webhook integrations for team notifications
+  - `teamai webhook list` — List configured webhook endpoints
+  - `teamai webhook test` — Send test event to webhook endpoints
+    - `--url <url>` — Test specific endpoint URL
+
+## stats
+
+- `teamai stats` — Show local skill usage statistics
+  - `--by-repo` — Break usage down per repository
+  - `--by-time` — Show activity by hour of day
+
+## session
+
+- `teamai session` — Record and inspect coding-session summaries
+  - `teamai session save` — Record a privacy-scrubbed summary of a coding session to a local monthly log
+    - `--session-id <id>` — Session to record (default: most recent, or $CLAUDE_SESSION_ID)
+    - `--push` — Also push the summary to the team repo (feeds `teamai digest`)
+    - `--force` — Push even if the session is not flagged as valuable
+    - `--include-prompt` — Include the redacted first-prompt line in the pushed summary (default: off)
+    - `--scope <scope>` — Config scope for --push: user | project (default: auto-detect)
+
+## digest
+
+- `teamai digest` — Generate weekly team activity digest
+
+## dashboard
+
+- `teamai dashboard` — Start the AI coding session dashboard (Web UI)
+  - `-p, --port <port>` — Port number
+
+## bind-project
+
+- `teamai bind-project` — Bind the current workspace to a ClawPro project for HTTP local-agent sync
+  - `--project-id <id>` — Project ID from /projects/mine
+  - `--skip` — Mark current workspace as skipped (never prompt again)
+
+## contribute
+
+- `teamai contribute` — Contribute session knowledge to team repo
+  - `--file <path>` — Path to the contribution document
+  - `--title <title>` — Title for the contribution document
+  - `--session-id <id>` — Session ID for dedup tracking
+  - `--scope <scope>` — Target scope: user or project
+
+## recall
+
+- `teamai recall [query...]` — Search team learnings knowledge base
+  - `--depth <level>` — Recall depth: route (entry-points only) | context (module-level, default) | lookup (full graph traversal)
+  - `--check` — Relevance precheck only: print RELEVANT/NOT_RELEVANT + top score; no file reads, no upvote
+  - `teamai recall disable` — Disable automatic knowledge-base recall
+  - `teamai recall enable` — Enable automatic knowledge-base recall
+  - `teamai recall status` — Show recall feature status
+  - `teamai recall feedback` — Record manual feedback for a recalled document
+    - `--positive <docId>` — Upvote a document (marks as actually useful)
+    - `--negative <docId>` — Record negative signal for a document
+  - `teamai recall maintenance` — Automatic maintenance of team knowledge base
+    - `--prune` — Remove low-confidence learnings
+    - `--threshold <n>` — Confidence threshold for pruning (default 0.15)
+    - `--archive` — Move to archive/ instead of deleting
+    - `--confidence-writeback` — Update frontmatter confidence scores
+    - `--update-quality` — Find stale docs/rules/skills and suggest updates
+    - `--dry-run` — Show what would be done without making changes
+  - `teamai recall promote [learningId]` — Promote a high-confidence learning to formal knowledge (docs/skills/rules)
+    - `--category <cat>` — Target category: skills | rules | docs
+    - `--dry-run` — Show what would be done without making changes
+
+## import
+
+- `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-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
+  - `--all` — Accept all suggestions without interactive confirmation
+  - `--output <path>` (hidden) — Write drafts to this directory instead of pushing to team repo
+  - `--from-repo <url>` — Clone a remote repo and generate per-repo codebase summary
+  - `--ssh` (hidden) — Force SSH clone even if HTTPS token is available
+  - `--domain <name>` (hidden) — Skip AI recommendation and assign repo to this domain explicitly
+  - `--from-repo-list <path>` — Batch import repos from a YAML whitelist
+  - `--concurrency <n>` (hidden) — Concurrent repos for --from-repo-list (default 3)
+  - `--incremental` — Use cached clone with fetch+reset (with --from-repo or --from-repo-list)
+  - `--skip-enrich` — Skip AI enrichment (only clone + extract + graph, no LLM calls)
+  - `--from-org <org>` — List repos under an org and generate a repo whitelist
+  - `--max-repos <n>` (hidden) — Cap on repos pulled from --from-org (default 200)
+  - `--exclude-archived` (hidden) — Exclude archived repos from --from-org (default true)
+  - `--include-pattern <re>` (hidden) — Regex to include repos by full name (used with --from-org)
+  - `--exclude-pattern <re>` (hidden) — Regex to exclude repos by full name (used with --from-org)
+  - `--skip-import` (hidden) — Only write drafts; skip the actual --from-repo-list run
+  - `--iwiki-dual` (hidden) — Enable dual-output mode for --from-iwiki (write codebase sections in addition to learning)
+  - `--require-review` (hidden) — Defer codebase section writes to .teamai/pending-review.jsonl for human review
+  - `--cache-status` — Show import cache status (repos cached, disk usage)
+  - `--cache-gc` — Garbage-collect stale import cache entries
+  - `--json` — Output cache status or GC result as JSON
+  - `--max-bytes <n>` (hidden) — Override capacity cap for --cache-gc
+  - `--stale-days <n>` (hidden) — Threshold for stale-eviction in days (default 30)
+
+## codebase
+
+- `teamai codebase` — Inspect and maintain team-codebase outputs
+  - `--extract [path]` — Extract code knowledge and build graph from source
+  - `--incremental` (hidden) — Only re-extract changed files (requires prior manifest)
+  - `--project <name>` (hidden) — Project slug for --extract (defaults to directory name) and required for --deep-enrich
+  - `--max-files <n>` (hidden) — Max source files to scan (default: 200)
+  - `--upgrade-wiki` (hidden) — Migrate docs/team-codebase/ to teamwiki/ graph format
+  - `--lint` — Run global consistency lint over the teamwiki knowledge graph
+  - `--reconcile` — Reconcile product and code knowledge in teamwiki
+  - `--deep-enrich` — Generate deep knowledge docs from extracted evidence
+  - `--fix` (hidden) — Deprecated: teamwiki lint has no autofix; runs lint in report-only mode
+  - `--status` — Show knowledge-base git baseline (headSha / repoUrl / branch)
+  - `--severity <level>` (hidden) — Minimum severity to report: high|medium|low|info
+  - `--json` — Output report as JSON (suitable for CI)
+  - `--output <path>` (hidden) — Custom teamwiki output root directory
+
+## review
+
+- `teamai review [id]` — Inspect and process .teamai/pending-review.jsonl items
+  - `--apply` — Apply the change for the given id (only for codebase-section)
+  - `--reject` — Reject the given id without applying
+  - `--reason <msg>` — Reason for reject
+  - `--all-apply` — Apply all items at or below --max-risk
+  - `--max-risk <level>` — Risk ceiling for --all-apply: high|medium|low (default medium)
+  - `--json` — Machine-readable output
+
+## ci
+
+- `teamai ci` — CI pipeline integration commands
+  - `teamai ci extract-mr` — Extract knowledge from MR/PR and post as comment or write to team repo
+    - `--url <url>` — MR/PR web URL
+    - `--mode <mode>` — Operation mode: comment | write | both
+    - `--team-repo <path>` — Team knowledge repo path (required for write mode)
+    - `--comment-marker <marker>` — HTML comment anchor for idempotent updates
+    - `--write-mode <mode>` — Write strategy: direct | pending-review
+    - `--output <dir>` — Write artifacts to directory
+    - `--individual-comments` — Post each suggestion as separate comment with reaction/resolve support

package/{skills/teamai → skill-data/core}/references/contribute-member.md

@@ -3,23 +3,22 @@
 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"* / *"把这个 xxx skill 分享给团队"* — then you run the publish for them.
+team"*, in whatever language they work in — then you run the publish for them.
 
 ## Which kind of contribution?
 
 - **A learning** (a lesson, a gotcha, how you solved something) → this is
-  **automatic**: TeamAI prompts at the end of a session worth sharing and the
-  dedicated **`teamai-share-learnings`** skill takes over (it summarizes the
+  **automatic** once recall is on (off by default): 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 when that skill isn't
-  available.)
+  for it. (Step A below is only a manual fallback for while recall is off.)
 - **A reusable skill** (a `SKILL.md` others invoke) → author the skill, then
   `teamai push` (Step B — the main purpose of this reference).
 
 ## Step A — Contribute a learning by hand (fallback only)
 
-> Prefer the **`teamai-share-learnings`** skill. Use these manual steps only if it
-> is unavailable in the current tool.
+> Prefer the `share` workflow (`teamai skill get share`). Use these manual steps only while
+> it refuses because recall is off.
 
 1. Write a short Markdown doc that captures the lesson. Keep it concrete and
    actionable — a knowledge base, not a diary. Include YAML frontmatter for search
@@ -53,9 +52,8 @@ team"* / *"把这个 xxx skill 分享给团队"* — then you run the publish fo
 The doc lands in the team's `learnings/` and appears for teammates on their next
 `teamai pull`. It is also searchable via `teamai recall`.
 
-> Tip: if there is a dedicated learnings skill available in this tool
-> (`teamai-share-learnings`), you can use it to auto-summarize the current session
-> instead of writing the doc by hand.
+> Tip: while recall is on, `teamai skill get share` auto-summarizes the current
+> session instead of you writing the doc by hand.
 
 ## Step B — Contribute a reusable skill
 
@@ -87,6 +85,11 @@ The doc lands in the team's `learnings/` and appears for teammates on their next
    ```
 
    To publish into a specific role namespace: `teamai push --skill <path> --role <id>`.
+   `--role <ns>` / `--project <id>` place every new resource, not only skills: a
+   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.
 
 ## After contributing
 

package/{skills/teamai → skill-data/core}/references/troubleshooting.md

@@ -34,6 +34,14 @@ 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. **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.
 
 ## Permission / access denied
 
@@ -115,7 +123,7 @@ session and verify with `teamai pull` + `teamai list`.
 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`
+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`.
 

package/skill-data/setup/SKILL.md

@@ -0,0 +1,76 @@
+---
+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/yourorg/yourrepo`). 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, and which detected tools were skipped and why (e.g. Codex
+   trust-gate, CodeBuddy design). Verify the real per-tool result with
+   `teamai doctor` and `teamai hooks list`.
+3. **After init, resources appear on the NEXT session.** `teamai init` injects a
+   session-start hook that auto-runs `teamai pull`. Empty skills/rules directories
+   right after init are normal; they fill in when the user opens a fresh session in
+   this tool. To sync immediately, run `teamai pull`.
+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.