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

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

@@ -0,0 +1,471 @@
+# 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; a command with no preview exits 1 without running
+- `-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)
+  - `--provider <name>` — Git provider for the team repo on this machine: tgit, github, cnb, gitlab, gitcode, or git. Skips auto-detection. `git` uses your existing Git auth and needs no platform token, but opens no PR/MR.
+  - `--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: workspace (default, <cwd>/.teamai + <cwd>/.claude) or user (~/.teamai + ~/.claude); project is the older name for workspace
+  - `--inherit-user-scope` — In workspace scope, also sync safe user-scope resources, load its env variables (not its secrets) in the workspace, and search its knowledge
+  - `--no-inherit-user-scope` — Disable user-scope inheritance for this workspace
+  - `--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; a custom agent defined only in teamai.yaml's toolPaths also gets its root created here (git-backed init only — an HTTP init has no local teamai.yaml to read custom paths from). 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>/). Without --role or --project, the namespaces of your role and active projects decide
+  - `--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
+
+- `teamai pull` — Pull team resources and inject into local AI tools. Team docs land in sharing.docs.localDir: .teamai/docs/ in a workspace by default, a hidden directory, so search that path directly
+  - `--silent` — Silent mode (for hooks)
+  - `--force` — Force full sync even if repo is unchanged
+  - `--team-ref <ref>` — Pin this workspace to a branch, tag or commit of the team repo; the default branch unpins it
+
+## 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
+  - `--role <ns>` — mcp: remove the server from mcp/<ns>/mcp.yaml instead of the root mcp/mcp.yaml
+  - `--project <id>` — mcp: remove the server from the project's mcp namespace instead of the root mcp/mcp.yaml
+
+## 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)
+  - `--fix` — Remove lock files left behind by dead processes
+
+## 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 add <id>` — Add a project to manifest/projects.yaml, creating the file if needed (admin)
+    - `--namespaces <ns>` — Comma-separated namespaces for knowledge, skills, learnings and agents (e.g. common,checkout); env, hooks, mcp, models, docs and wiki are declared by hand
+    - `--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 knowledge, skills, learnings and agents
+    - `--remove-namespaces <ns>` — Comma-separated namespaces to remove from knowledge, skills, learnings and agents
+    - `--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
+
+- `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 in this checkout; shared resources, and the project's other checkouts, go only if it is the last tool
+
+## script
+
+- `teamai script` — Run a Node script the team declared in teamai.yaml
+  - `teamai script run <event>` — Run preInit, postInit, prePull, postPull, or postDeploy for this checkout. preInit and postInit need a terminal. postInit then syncs MCP servers.
+
+## 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, or declare a secret with --secret
+    - `-d, --description <desc>` — Description for the variable or secret
+    - `--secret` — Declare a secret in env/secrets.yaml: no value, each member sets their own
+    - `--url <url>` — Where a member gets a value for the secret (with --secret)
+    - `--role <ns>` — Write to env/<ns>/ instead of env/ (env.yaml, or secrets.yaml with --secret)
+    - `--project <id>` — Write to the project's env namespace (resources.env in manifest/projects.yaml)
+  - `teamai env remove <key>` — Remove a team environment variable or declared secret
+    - `--secret` — Remove the declared secret only (env/secrets.yaml), for a key env.yaml also sets
+    - `--role <ns>` — Remove from env/<ns>/ instead of env/
+    - `--project <id>` — Remove from the project's env namespace (resources.env in manifest/projects.yaml)
+  - `teamai env set <key>` — Set your value for a secret the team declares, or an env variable it sets, for this directory's team, on this machine (prompts without echo)
+    - `--stdin` — Read the value from piped stdin
+    - `--from-env <var>` — Read the value from this environment variable each time it is used; no copy is stored
+    - `--global` — Set a secret for every team on this machine; a value set for a team still wins
+  - `teamai env unset <key>` — Remove your value for a secret or env variable, for this directory's team, from this machine
+    - `--global` — Remove the value set for every team on this machine instead
+  - `teamai env exec <command...>` — Run a command with this directory's team env variables and secrets (put -- before the command)
+
+## workflow
+
+- `teamai workflow` — Run a validated workflow from workflows/<name>.yaml
+  - `teamai workflow start <name>` — Create a run. With --driver local, execute command and prompt steps in this process.
+    - `--driver <kind>` — Run the workflow in this process. Only local is available.
+    - `--tools <list>` — Override local prompt tools for this run, as comma-separated name=tool pairs
+    - `--auto-approve` — With --driver local, automatically answer optional approve HITL requests and choose defaults in this process
+    - `--inputs <json>` — Values for the inputs the workflow declares, as a JSON object, for example {"issue":42}. Every declared input is required.
+  - `teamai workflow next <run>` — Get a lease, hitl, wait, or done JSON envelope. Show hitl.message and hitl.respond to a person, who replaces <option> with a choice.
+    - `--json <payload>` — Driver identity, for example {"driver":{"kind":"local","machine":"host","workspace":"/work"}}. Optional: running, the attempt ids of its open leases the driver still runs (an open lease left out is handed back), canTakeLease, false to poll while a tool runs without taking a new lease, and driver.can.hitl, true when a person can answer HITL requests and work interactively. Send driver.can.hitl on every next request, including busy polls. Every answer lists in cancelled the running attempts whose tools the driver must stop.
+  - `teamai workflow report <run>` — Report the outcome of a leased step. Prints a JSON envelope.
+    - `--json <payload>` — attempt, revision, outcome (success, failed, or released), and driver
+  - `teamai workflow respond <run> <step> <choice>` — Answer a waiting approve (yes/no) or choose HITL request. Required HITL requests accept terminal answers or declared person answers from a driver UI. Prints one JSON envelope.
+    - `--json <payload>` — Driver identity {"driver":{"kind":"ide","machine":"host","workspace":"/work"}} declares an answer a person gave in the driver UI, never one its agent chose. Records channel driver with agent false; accepts required HITL requests.
+    - `--note <text>` — Keep a note with the answer, readable as steps.<id>.note
+    - `--pass <n>` — Answer only this positive pass number; rejects an answered or replaced HITL request
+  - `teamai workflow retry <run> <step>` — Retry a leased or stopped step, or a HITL request to answer it again, with a new pass and revision. Reopen its dependent steps and a settled run; keep earlier passes. After reopening, run resume or let your driver poll next. Prints one JSON envelope.
+  - `teamai workflow resume <run>` — Continue a run with the local driver after retry, respond, or a stopped driver (Ctrl-C or closed terminal). Uses this machine's open local lease workspace, then the latest local driver's workspace on this machine, then cwd. Another live local driver returns driver_running. A settled run returns done.
+    - `--tools <list>` — Override local prompt tools for this run, as comma-separated name=tool pairs
+    - `--auto-approve` — Automatically answer optional approve HITL requests and choose defaults in this process
+  - `teamai workflow cancel <run> [step]` — Cancel a whole run, or a pending, waiting, leased, or running step and its open descendants. Invalidates leases; drivers stop tools listed in next.cancelled. Prints one JSON envelope.
+
+## 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
+
+## 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); omit the profile to pick one
+    - `--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 the local event log down per repository
+  - `--by-time` — Show local event log activity by hour of day
+
+## session
+
+- `teamai session` — Session recording, cross-platform migration, and team sync
+  - `teamai session save` — Record a privacy-scrubbed summary of a coding session to a local monthly log
+    - `--session-id <id>` — Session to record (default: the agent's session, e.g. $CLAUDE_CODE_SESSION_ID, or the most recent)
+    - `--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 | workspace (default: auto-detect)
+  - `teamai session platforms` — List supported and installed AI agent platforms
+  - `teamai session migrate [sessionId]` — Migrate a session from one platform to another (or archive to same platform)
+    - `-s, --source <platform>` — Source platform (e.g. claude-code, codebuddy)
+    - `-t, --target <platform>` — Target platform
+    - `--cwd <path>` — Working directory (defaults to current directory)
+    - `--target-cwd <path>` — Override cwd for the target session
+    - `--push` — Also push the migrated session to the team repo
+    - `--repo-root <path>` — Team repo root (for --push)
+    - `--scrub` — Redact secrets (tokens/keys/passwords) from the session before writing it
+    - `--all` — Migrate every session from source (not just the 5 most recent)
+    - `--limit <n>` — Max sessions to migrate (only caps --all; ignored otherwise)
+    - `-y, --yes` — Skip confirmation prompts, including archiving unredacted transcripts
+    - `--json` — Print one {data}|{error} JSON envelope on stdout; never prompts (needs a session id, -s and -t)
+  - `teamai session push` — Push local sessions to the team repo
+    - `--source <platform>` — Source platform to read sessions from
+    - `--repo-root <path>` — Team repo root (defaults to cwd)
+    - `--cwd <path>` — Working directory (defaults to current directory)
+    - `--limit <n>` — Max sessions to push (default: 5; ignored with --all)
+    - `--all` — Push every session of the platform across all workspace directories (ignores --limit)
+    - `-y, --yes` — Skip confirmation prompts, including archiving unredacted transcripts (--all)
+    - `--scrub` — Redact secrets before archiving (archived sessions are team-readable)
+  - `teamai session pull` — Pull team sessions for the current project
+    - `--repo-root <path>` — Team repo root (defaults to cwd)
+    - `--cwd <path>` — Working directory (defaults to current directory)
+    - `--all` — Rebuild indexes for every repo in the team repo (not just the current project)
+  - `teamai session list` — List team sessions for the current project
+    - `--repo-root <path>` — Team repo root (defaults to cwd)
+    - `--cwd <path>` — Working directory (defaults to current directory)
+    - `--author <name>` — Filter by author
+    - `--all` — List sessions across all projects in the team repo (not just the current one)
+  - `teamai session resume <sessionName>` — Restore a team session to a local platform
+    - `--platform <platform>` — Target platform to restore into
+    - `--repo-root <path>` — Team repo root (defaults to cwd)
+    - `--cwd <path>` — Working directory for the restored session (defaults to current directory)
+    - `--author <name>` — Author of the session (if ambiguous)
+  - `teamai session search <query>` — Search team session content
+    - `--repo-root <path>` — Team repo root (defaults to cwd)
+    - `--cwd <path>` — Working directory (defaults to current directory)
+    - `--limit <n>` — Max results (default: 10)
+    - `--all` — Search across all projects (not just current)
+  - `teamai session rollback <sessionId>` — Rollback a migration (delete the target session)
+    - `--platform <platform>` — Platform where the session was written
+    - `--cwd <cwd>` — Only roll back the copy under this project path (default: all)
+
+## 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)
+  - `--prompt-mode <mode>` — Project association reminder: auto (ask in each new workspace) or manual (no automatic reminder)
+  - `--settings` — Show the project association reminder mode and how to change it
+
+## contribute
+
+- `teamai contribute` — Contribute session knowledge to team repo; projects list shows the default destination and allowed namespaces
+  - `--file <path>` — Path to the contribution document
+  - `--title <title>` — Title for the contribution document
+  - `--namespace <ns>` — Write to an active learnings namespace (default: the only active namespace, or the shared root when none or several are active)
+  - `--session-id <id>` — Session ID for dedup tracking
+  - `--scope <scope>` — Target scope: user or workspace
+
+## 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
+  - `--caller <name>` (hidden) — Internal, set by the teamai-recall subagent to mark its own runs; do not pass it yourself
+  - `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 (the Claude root's rules/ — ~/.claude or the recorded toolRoots.claude — and ~/.cursor/rules)
+  - `--from-mr <url...>` — Extract learning from one or more merged MRs/PRs and trigger incremental teamwiki update
+  - `--no-discussions` — Leave the MR's review threads out of the extraction (with --from-mr)
+  - `--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; code knowledge goes to <path>/teamwiki
+  - `--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` — Re-extract only files changed since the last import (with --dir, --from-repo or --from-repo-list; remote repos also reuse the cached clone)
+  - `--skip-enrich` — Skip AI enrichment (only clone + extract + graph, no LLM calls)
+  - `--max-files <n>` — Max source files collected per repository (default 200)
+  - `--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 the teamwiki that `teamai import` writes
+  - `--project <name>` (hidden) — Codebase slug under teamwiki/evidence/code/, required for --deep-enrich
+  - `--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) — Use <path>/teamwiki, as written by `teamai import --output <path>`, instead of the team repo's
+
+## review
+
+- `teamai review [id]` — Inspect and process .teamai/pending-review.jsonl items; --dry-run validates apply decisions and previews rejections without writing documents or removing pending items. With --branch <name>, run read-only health checks on a team repo branch instead
+  - `--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)
+  - `--branch <name>` — Run read-only health checks on this team repo branch (e.g. teamai/push/<user>/<timestamp>) and report fail/warn/info findings
+  - `--json` — Machine-readable output (dry-run decisions include dryRun: true; ok reports validation only; --branch prints the findings object)
+
+## 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
+    - `--no-discussions` — Leave the MR's review threads out of the extraction

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

@@ -0,0 +1,161 @@
+# Scenario: Member — publish a reusable skill
+
+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.
+
+**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) 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.)
+- **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 `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
+   indexing:
+
+   ```markdown
+   ---
+   title: "<short title of the problem or finding>"
+   author: <username>
+   date: <YYYY-MM-DD>
+   tags: [tag1, tag2, tag3]
+   ---
+
+   ## Background
+   What were you doing? What went wrong?
+
+   ## Solution
+   How did you fix it? Key steps.
+
+   ## Takeaways
+   - Lesson 1
+   - Lesson 2
+   ```
+
+2. Save it to a temp file, then push it to the team:
+
+   ```bash
+   teamai contribute --file /tmp/my-learning.md --title "K8s pod startup timeout"
+   ```
+
+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: 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
+
+1. Create the skill directory with a `SKILL.md`:
+
+   ```
+   skills/my-skill/SKILL.md
+   ```
+
+   Minimal frontmatter:
+
+   ```markdown
+   ---
+   name: my-skill
+   description: "One line — what it does and when to use it"
+   ---
+
+   # My Skill
+
+   Step-by-step instructions the AI should follow.
+   ```
+
+2. Publish it:
+
+   ```bash
+   teamai push --skill skills/my-skill        # one skill
+   # or
+   teamai push                                # review and push everything
+   ```
+
+   To publish into a specific role namespace: `teamai push --skill <path> --role <id>`.
+   `--skill <path>` selects that exact local copy after resolving `~` and
+   symlinks; a same-named copy in another tool is never a substitute.
+   `--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,
+   the role and the active projects decide; with neither, a new rule or agent
+   stays at the shared root and reaches the whole team. When an active project
+   cannot be resolved (not in `manifest/projects.yaml`, or that file is
+   missing), push stops with exit 2 until you fix it or pass `--role` /
+   `--project`. An edit of a skill, rule or agent you received from a namespace
+   goes back to that namespace, even when it replaces a shared item of the same
+   name; the shared one is left as it is. A delivered skill copy is pushed only
+   when its recorded version matches exactly one current team skill, using that
+   path's history since its latest creation after deletion. `--role`, `--project`
+   and `--skill` do not establish an origin. If no unique origin is proven, push
+   skips the edit with a warning; copy it under a new name to send it as a new
+   skill. 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.
+
+   In single-repo mode, a skill or rule under `.teamai/` that matches an older
+   version of the team's file, as it does when the branch is behind the default
+   branch, is skipped with a warning that it "is an older version of" that file:
+   pushing it would revert a teammate's update. To publish an edit of it, bring
+   the current version in first (`git fetch origin && git merge origin/<default>`,
+   or copy the team's current file over it), redo the edit on top, and push again.
+
+## After contributing
+
+- Confirm it landed: `teamai list skills` (or `teamai status`).
+- Teammates receive it automatically on their next session, or via `teamai pull`.
+
+Before listing rules, `push` refreshes copies whose bodies still match a recorded
+sync revision. The header teamai generates for a tool's own rules format
+(Cursor `.mdc`, JoyCode's own `.mdc`, Copilot `applyTo`, Kiro `inclusion`, Qoder
+`trigger`, Trae `globs`/`alwaysApply`, CodeBuddy and WorkBuddy `alwaysApply`, Oh My Pi `alwaysApply`/`globs`) does not count as a local edit: unedited old copies update in that
+format, including under `COPILOT_HOME` in user scope. Genuine local body edits remain push candidates.
+Rule pre-sync leaves tools excluded by `enabledAgents` or `disabledAgents` untouched.
+When only team `paths` change, `applyTo` refreshes if the local file still matches
+a recorded version's generated copy; locally edited headers are kept.
+The copies push refreshes are recorded, so a later `teamai pull` still updates them.
+Oh My Pi and Kiro read only the top of their rules directories, so a namespaced
+rule is written flat there (`rules/fe/style.md` as `fe.style.md`); an edit of that file
+pushes back to `rules/fe/style.md`. Push requires a delivery record for the flat copy.
+A personal file with that name is neither refreshed before push nor offered as
+an edit of the team rule.
+If two namespaced rules flatten to the same name, neither is written; `teamai doctor`
+reports the collision even when no other rule reaches that tool. Rename one in the
+team repo, then run `teamai pull`. Doctor also reports team-owned OpenCode globs
+or inline blocks left after the last rule is removed.
+
+A new file in the rules directory of a tool with a rules format of its own
+(Cursor, JoyCode, Copilot, Kiro, Qoder, Trae, CodeBuddy, WorkBuddy, Oh My Pi) is the
+member's own rule in that tool's format: push never offers it, and pull leaves
+it. To author a new team rule, write it as a plain `.md` in `.claude/rules/`
+(scope it with `paths:` frontmatter, which teamai renders into each tool's
+format), then run `teamai push`. A YAML comment after an unquoted glob stays
+outside its scope: `paths: **/*.ts # TypeScript files` matches `**/*.ts`, including
+when written as a block-list entry under `paths:`.
+
+## If push is denied
+
+A permission error usually means you don't have write access to the team repo.
+Copy the exact error to your admin and ask them to grant access. (In read-only
+HTTP mode, `contribute` / `push` are not available — you can only consume.)