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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamai-cli",
-  "version": "0.26.0-beta.3",
+  "version": "0.26.0-beta.4",
   "description": "TeamAI — Make Every Team AI Native (skill sync + shared knowledge base, powered by Git)",
   "type": "module",
   "bin": {
@@ -80,6 +80,7 @@
     "@types/node": "^20.17.0",
     "@types/semver": "^7.8.0",
     "@vitest/coverage-v8": "^3.2.7",
+    "fast-check": "^4.10.2",
     "opencode-ai": "1.18.23",
     "standard-version": "^9.5.0",
     "tsup": "^8.3.0",

package/skill-data/core/SKILL.md

@@ -105,6 +105,10 @@ 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.
 
+`teamai pull` mirrors the non-hidden docs you receive into `sharing.docs.localDir`,
+removing stale and local-only documents; an edited doc of a docs namespace you left
+is kept and named. Use a dedicated directory; preview with `--dry-run`.
+
 ## 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.

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

@@ -81,6 +81,8 @@ Generated: do not edit by hand. Regenerate with
 
 - `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
 
@@ -122,12 +124,12 @@ Generated: do not edit by hand. Regenerate with
   - `teamai projects list` — List defined projects and the ones active in this directory
   - `teamai projects set [ids...]` — Set the projects active in this directory (comma-separated or repeated; empty to clear)
   - `teamai projects add <id>` — Add a project to manifest/projects.yaml, creating the file if needed (admin)
-    - `--namespaces <ns>` — Comma-separated namespaces for every project resource type (e.g. common,checkout)
+    - `--namespaces <ns>` — Comma-separated namespaces for knowledge, skills, learnings and agents (e.g. common,checkout); env, hooks, mcp, models and docs 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 every resource type
-    - `--remove-namespaces <ns>` — Comma-separated namespaces to remove from every resource type
+    - `--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)
@@ -192,7 +194,11 @@ Generated: do not edit by hand. Regenerate with
     - `--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
+    - `--role <ns>` — Write to env/<ns>/env.yaml instead of env/env.yaml
+    - `--project <id>` — Write to the project's env namespace (resources.env in manifest/projects.yaml)
   - `teamai env remove <key>` — Remove a team environment variable
+    - `--role <ns>` — Remove from env/<ns>/env.yaml instead of env/env.yaml
+    - `--project <id>` — Remove from the project's env namespace (resources.env in manifest/projects.yaml)
 
 ## hooks
 
@@ -342,7 +348,7 @@ Generated: do not edit by hand. Regenerate with
 - `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
+  - `--project <name>` (hidden) — Project slug for --extract (defaults to the directory name; a checkout's root uses the repo's 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

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

@@ -97,11 +97,20 @@ The doc lands in the team's `learnings/` and appears for teammates on their next
    new rule and a new agent land in that namespace too (a project resolves each
    from its own axis — `knowledge` for rules, `agents` for agents). Without one,
    a new resource whose namespace cannot be resolved stays at the shared root and
-   reaches the whole team. Use `--branch <name>` when a new push must target a
+   reaches the whole team. 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. 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`).

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

@@ -48,6 +48,21 @@ This is the #1 onboarding issue. In order:
    belongs in the team repo's `manifest/roles.yaml` or `manifest/projects.yaml`,
    which the error names by entry — tell the user to ask a team admin. Do not
    delete the manifest or edit the local clone to get past it.
+   `recall` still searches learnings and warns once (`Recall indexed learnings
+   only…` or `Recall indexed the shared learnings only…`): what it names is
+   missing from results until the manifest is fixed and `teamai pull` rebuilds
+   the index, so do not report that the team has none of it. If recall also says
+   `Recall skips the older index at <path>…`, the smaller index could not be
+   written and that scope was not searched at all: resolve the error it names
+   (for example a read-only file or a full disk), then fix the manifest and pull.
+7. **`pull` says `Nothing was synced: <file>: <reason>`.** The project's teamai
+   config exists but cannot be read, so no scope syncs there, not even the user
+   scope, and the session-start hook syncs nothing either. Show the user the
+   file and the reason; `teamai doctor` checks another config and can pass
+   here. Moving it aside and re-running `teamai init` replaces their settings
+   for that project: do it only with their consent.
+   `recall` refuses the same way with `Nothing was searched: <file>: <reason>`:
+   no team knowledge was searched, so do not report that the team has none.
 
 ## Permission / access denied
 
@@ -74,9 +89,11 @@ teamai init https://git.example.com/yourgroup/yourrepo
 
 ## Which tools actually get hooks
 
-`teamai hooks inject` always prints **"Hooks injected into all AI tool settings"**,
-even for tools where it wrote nothing. **Do not take that line as proof.** Verify
-per-tool instead:
+`teamai hooks inject` prints **"Hooks injected into all AI tool settings"** even
+for tools where it wrote nothing. **Do not take that line as proof.** (When the
+team hooks cannot be resolved it exits 1 with the reason instead: the built-in
+hooks are installed, the team hooks are left as they were.) Verify per-tool
+instead:
 
 ```bash
 teamai doctor          # flags tools whose hooks are missing

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

@@ -92,15 +92,39 @@ above, each of which opens a PR (`--dry-run` previews). After `projects remove`,
 keep the project's content in the team repo until members have pulled: that is
 what lets their next pull clean up the copies they deployed.
 
-Every namespace that names a directory — `knowledge`, `skills` and `agents` in
-either manifest, and `learnings` in `projects.yaml` (a role's `learnings:` is
+Every namespace that names a directory — `knowledge`, `skills`, `agents`, `env`,
+`hooks`, `mcp`, `models` and `docs` 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
+`.` or space, and not a Windows device name (`CON`, `NUL`, `COM1`, …). `team-codebase`
+cannot be a `docs` namespace (`docs/team-codebase/` is the legacy codebase output). 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.
 
+An item in an active namespace replaces the root item of the same name, whole:
+a skill by directory name (including a root skill a member gets through a tag),
+an agent by file stem, a rule by first-level file name (`rules/<ns>/<name>.md`
+replaces `rules/<name>.md`), and a `claudemd/<ns>/<name>.md` file replaces
+`claudemd/<name>.md`. Use this to give a project its own version of a shared
+item under the same name, and keep that shared item at the root rather than in
+a namespace every role activates: `rules/code-style.md` is replaced by
+`rules/checkout/code-style.md` for checkout members, while a
+`rules/common/code-style.md` would reach them alongside it. The same skill or
+agent name in two namespaces one member has active is an error naming both
+files; two namespace rules or claudemd files of one name are both delivered.
+A replacement must be usable to replace anything: a skill directory needs its
+`SKILL.md` (pull names one without it), and while an agent file does not parse
+the root agent stays installed. `teamai doctor` lists each replacement as a note. Teams without roles or
+projects are unaffected.
+
+Docs have no override. A top-level `docs/<ns>/` that any role or project lists
+under `resources.docs` reaches only members with that namespace active; a
+`docs/<dir>/` nobody lists stays shared with everyone. When a member leaves the
+namespace, their next pull removes its docs that still match the team copy and
+keeps (and names) the ones they edited. Recall and `teamai doctor` follow the
+same filter.
+
 ## Team dashboard (web UI)
 
 ```bash
@@ -122,15 +146,45 @@ teamai packages install code-review@claude-plugins-official   # Claude plugin
 teamai push                                 # share the updated teamai.yaml
 ```
 
-## Shared environment variables
+## Shared environment variables, hooks and MCP servers
 
 ```bash
-teamai env list              # list (values masked)
+teamai env list              # what reaches this directory, each with its namespace (values masked)
 teamai env list --reveal     # show values in plaintext
-teamai env add <KEY> <VALUE> # add or update
-teamai env remove <KEY>      # remove
+teamai env add <KEY> <VALUE> # add or update in env/env.yaml
+teamai env add <KEY> <VALUE> --project <id>   # or --role <ns>: in that namespace's env/<ns>/env.yaml (warns if nothing declares <ns>)
+teamai env remove <KEY>      # remove (same --role / --project)
+teamai remove mcp <name>     # root mcp/mcp.yaml if it has the name, else the one namespace file; --role / --project pick a namespace
 ```
 
+Env variables, team hooks and MCP servers are scoped like skills: the root file
+(`env/env.yaml`, `hooks/hooks.yaml`, `mcp/mcp.yaml`) reaches everyone, and
+`env/<ns>/env.yaml`, `hooks/<ns>/hooks.yaml`, `mcp/<ns>/mcp.yaml` reach only
+members whose role or project lists `<ns>` under `resources.env`, `resources.hooks`
+or `resources.mcp`. A namespace entry replaces the root entry of the same key, hook
+id or server name. Hooks and MCP servers have no add command, and `teamai push`
+does not pick up `hooks/` or `mcp/`: edit the file in the team repo, then commit
+and push it with git. `teamai doctor` lists each override.
+
+- A name twice in one file, in two active namespaces, or an active file that does
+  not parse: that type is not applied for affected members and their installed
+  state is kept. Fix the file the warning names. A hooks or MCP file with none of
+  its top-level keys (`server:` for `servers:`) counts as one that does not parse.
+- Per-entry `projects:` (and `roles:` on env) no longer works: such an entry reaches
+  nobody. `roles:` on hooks and MCP still filters for one more minor release. Pull
+  and `teamai doctor` name the namespace file each entry belongs in; move it there.
+- An env, hook or MCP entry with a key its schema does not know (a mistyped `role:`)
+  also reaches nobody. Pull and `teamai doctor` name the file, entry and key; correct
+  the key or remove it. A key a later teamai version adds is unknown to an older one,
+  so upgrade every member before the team uses a new entry key.
+- Team model profiles work the same way: `models/<ns>/models.yaml`, declared under
+  `resources.models`, replaces the root profile with the same `id` for members who
+  have `<ns>` active. A member's API key is bound to the profile's gateway origin:
+  when an override points at another host, their pull leaves the agent alone and
+  asks them to run `teamai models switch team:<id>` to set the key for it.
+- Have every member upgrade before declaring `env`, `hooks`, `mcp`, `models` or `docs` in a
+  manifest: teamai 0.25.0 and the 0.26.0 betas reject those keys and their pull stops.
+
 ## When sync fails
 
 Run `teamai doctor` first. If it reports hook or path problems, load