feat(projects): extend project isolation to knowledge/docs/agents/env/hooks/mcp

[jeff-r2026]

Background

Project-namespace isolation currently covers only skills / learnings (plus the knowledge axis shared with roles). docs / agents / env / hooks / mcp are still synced to the whole team with no way to scope them per project.

Goal

Make all resource types support project-namespace isolation, aligned with how skills already works, delivered in a single PR:

• Unified layout: <type>/<namespace>/... = synced + cleaned up per active project; <type>/ root = shared team-wide, always synced.
• Union across active projects; duplicate name = error (same as the existing skills conflict rule).

Per-resource directory layout (team repo)

skills/       already isolated   skills/<name>/…            skills/alpha/<name>/…
learnings/    already isolated   learnings/*.md             learnings/alpha/*.md
rules/        knowledge axis     rules/common/*.md          rules/alpha/*.md
claudemd/     knowledge axis     claudemd/common/*.md       claudemd/alpha/*.md
agents/       to do              agents/*.md                agents/alpha/*.md
docs/         to do              docs/*.md (whole bundle)    docs/alpha/*.md
env/          to do              env/env.yaml               env/alpha/env.yaml
hooks/        to do              hooks/hooks.yaml           hooks/alpha/hooks.yaml
mcp/          to do              mcp/mcp.yaml               mcp/alpha/mcp.yaml

Left column = root (shared team-wide, behavior unchanged). Right column = namespace subdirectory (synced only when the matching project is active). alpha is an example project id.

Compatibility (non-breaking)

With no projects.yaml, or with resources kept at the <type>/ root, behavior is completely unchanged (shared team-wide). Isolation is opt-in: a team enables it only by moving resources into a namespace subdirectory. The existing single-file resources (env/env.yaml, hooks/hooks.yaml, mcp/mcp.yaml) naturally fall under "root = shared", so existing teams need zero migration.

[SaulMoro]

Status on main (1496855): everything but docs has shipped.

team repo          scoped by                      status
skills/<ns>/       namespace dir                  done
learnings/<ns>/    namespace dir                  done
rules/<ns>/        namespace dir (knowledge)      done
claudemd/<ns>/     namespace dir (knowledge)      done
agents/<ns>/       namespace dir (agents axis)    done   #577, #698
env/env.yaml       per-entry `projects:`          done   #700
hooks/hooks.yaml   per-entry `projects:`          done   #700
mcp/mcp.yaml       per-entry `projects:`          done   #700
docs/              -                              open

env / hooks / mcp: open question, refactor to the same layout as skills / agents / rules / docs?

today (#700, per-entry key)        option: namespace dir, like the rest
env/env.yaml                       env/env.yaml             shared
  - key: CHECKOUT_DB_URL           env/checkout/env.yaml    checkout only
    projects: [checkout]

• Gain: one scoping model across every resource type.
• Condition: replace the projects: key, not add a second way to scope the same entry.
• Cost: migration for teams already using projects: from feat: scope hooks, MCP servers and env variables by logical project #700.

docs: the remaining scope.

 # manifest/projects.yaml
 projects:
   - id: checkout
     resources:
       agents: [checkout]
+      docs: [checkout]

 pull docs
-  copy docs/** to everyone                # docs/<dir>/ already reaches everyone today
+  copy docs/ root to everyone
+  copy docs/<ns>/ only when <ns> is a declared docs namespace
+  remove docs of namespaces no longer active (byte-equal only)

• A declared docs axis keeps it non-breaking: undeclared subdirs stay shared.
• DocsHandler.pullItem never deletes today, so the cleanup step is new work.

Remaining scope: docs, plus the env / hooks / mcp layout decision above.

[SaulMoro]

Proposal: env / hooks / mcp use the same namespace layout as skills / agents / rules.

manifest/roles.yaml, manifest/projects.yaml
  resources:
    agents: [checkout]
    env:    [checkout]        # new
    hooks:  [checkout]        # new
    mcp:    [checkout]        # new
    docs:   [checkout]        # new

team repo
  env/env.yaml                shared
  env/checkout/env.yaml       only where the checkout namespace is active

 pull env / hooks / mcp
-  one file, each entry filtered by `roles:` AND `projects:`
+  root file plus <type>/<ns>/ for each active namespace (role ∪ project)
+  a key, server or hook name defined in two files is an error, as with skills

• One scoping model for every resource type, and src/membership.ts goes away.
• Role and project namespaces combine as a union, the same as skills. [feat] Scope hooks, MCP servers and env variables by project: a project's entries reach every member of the role #668's case still holds: a project's servers stop reaching everyone in the role as long as the role does not declare that namespace.
• tools: stays per entry. It selects the target tool, not the member.
• push and env add take --role / --project to pick the file, as fix(push): namespace new rules and agents from --role/--project (#649) #698 did for rules and agents.

Migration

• projects: has only shipped in the 0.26.0 betas. Removing it before 0.26.0 is stable means no stable release ever has it.
• roles: on hooks and MCP servers is in 0.25.0. Keep reading it for one minor release with a warning that names the target path, then remove it.

Plan

1. Remove projects: before 0.26.0.
2. Add the env / hooks / mcp axes, with the roles: deprecation warning.
3. Add the docs axis, with the scope from the previous comment.

[SaulMoro]

@jeff-r2026 I'm taking this. It will land as a single PR covering the three steps in the proposal above: remove projects:, add the env / hooks / mcp axes, and add the docs axis.

Could you hold the 0.26.0 stable release until it merges? If 0.26.0 ships with per-entry projects:, we end up deprecating two scoping keys (roles: and projects:) instead of one.

[SaulMoro]

Spec: one namespace model for every resource type

This replaces the plan in the previous comment. It covers the three steps in a single PR and adds models and the override rule.

Problem Statement

Team admins scope resources to a role or project in two different ways. Skills, agents, rules, claudemd and learnings use <type>/<ns>/ directories declared in resources:. Env, hooks and MCP use per-entry roles: / projects: keys. Docs and model profiles cannot be scoped at all. Admins have to learn both models, and a project that needs a different value for something the company shares (an API_BASE, a gateway, a rule) has no way to say so: agents reject a same-name item as an error, and the other types either deliver both copies or pick one silently.

Members see the result: project-only servers or variables reach the wrong people, contradictory rules are loaded side by side, and search returns skills and docs they do not have.

Solution

Every resource type uses the same layout and the same conflict rule.

<type>/                 root, shared
<type>/<ns>/            delivered only where <ns> is active (role ∪ project) in resources.<type>
namespace vs root       the namespace item replaces the root item, whole, no merge
namespace vs namespace  error; that type is not applied this run, installed state is kept
broken active file      that type is not applied this run, installed state is kept
duplicate in one file   error
legacy mode             (no roles, no projects) unchanged; doctor lists repeated names as info

Type	Axis	Override key	Notes
env	new env	variable key
hooks	new hooks	hook name
mcp	new mcp	server name	tools: stays per entry
models	new models	profile id	stored API key is bound to the base_url origin
docs	new docs	none: each namespace is its own subtree	undeclared docs/<dir>/ stays shared
skills	existing	skill name	root stays the tag catalog in role/project mode
agents	existing	stem	root + namespace stops being an error
rules	knowledge	first-level file name	also for Hermes' concatenated block
claudemd	knowledge	file name
learnings	existing	none: ids cannot collide

Per-entry projects: (env, hooks, mcp) and roles: on env only exist in the 0.26.0 betas and are removed before 0.26.0 is stable. roles: on hooks and MCP shipped in 0.25.0 and keeps working for one minor release with a deprecation warning.

User Stories

1. As a team admin, I want to put env, hooks, MCP servers, model profiles and docs under <type>/<ns>/, so that I scope every resource type the same way.
2. As a team admin, I want to declare env, hooks, mcp, models and docs namespaces in resources: of a role or project, so that I control who receives each subtree from the manifest, as I already do for agents.
3. As a team admin, I want a project to override a company-wide env variable such as API_BASE, so that members working on that project get the project value without a second variable name.
4. As a team admin, I want a project to override a shared MCP server or hook by name, so that the project can point the same tool integration at its own backend.
5. As a team admin, I want a project to override a shared model profile by id, so that members on that project use the project's gateway automatically.
6. As a team admin, I want a project to override a shared agent, rule or claudemd fragment by name, so that contradictory versions are never loaded side by side.
7. As a team admin, I want a skill in an active namespace to replace a root skill of the same name that a member receives through a tag, so that the override rule is the same as for every other type.
8. As a team admin, I want two active namespaces that define the same name to fail with a message naming both files, so that no member silently receives an arbitrary one.
9. As a team admin, I want a duplicate name inside a single file to be an error, so that last-one-wins never hides a mistake.
10. As a member, I want a broken namespace file to leave my installed env, hooks, servers or profiles untouched for that run, so that one bad commit does not wipe or silently downgrade my setup.
11. As a member, I want my overridden items to switch back to the root version when a namespace deactivates, so that I keep the shared item instead of losing it.
12. As a member, I want items that only existed in a deactivated namespace to be removed, so that I stop receiving project config I no longer work on.
13. As a member, I want an exported env variable from a deactivated namespace to disappear even when the root env file is missing or empty, so that stale values do not stay in my shell.
14. As a member, I want doctor to list each override (which namespace replaces which root item) as information, so that I can answer "why do I have this value?" without it looking like a problem.
15. As a member, I want status, env list, mcp list, hooks list and models list to show which namespace each entry comes from, so that I can see where my configuration originates.
16. As a member, I want recall to return only the skills and docs I actually receive, so that search results match what is installed.
17. As a member switched to a team model profile, I want the API key I configured for the company gateway never to be sent to a project gateway on a different origin, so that an override cannot leak my credential.
18. As a member whose project gateway has a new origin, I want pull to skip updating that agent and tell me to run teamai models switch team:<id>, so that I can set the right key once.
19. As a member leaving a project whose model profile has no root counterpart, I want my agent settings kept and a message saying the profile is no longer active in my namespaces, so that TeamAI does not change my agent config without being asked.
20. As a team admin, I want an undeclared docs/<dir>/ to keep reaching everyone, so that existing docs subdirectories keep working.
21. As a team admin, I want a declared docs namespace delivered only to members who have it active, so that project docs stop reaching the whole team.
22. As a member, I want docs of a deactivated namespace removed locally when they are unchanged, and kept with a line when I edited them, so that cleanup never destroys my edits.
23. As a team admin, I want team-codebase rejected as a docs namespace name, so that it does not collide with the legacy codebase output.
24. As a team admin, I want doctor and the search index to follow the same docs namespace filter as pull, so that doctor does not report missing files a member is not supposed to have.
25. As a team admin, I want env add and env remove to accept --role / --project, so that I can write to a namespace file from the CLI.
26. As a team admin, I want push to pick up changes to any env/<ns>/env.yaml, so that namespace env files are pushed like the root file.
27. As a team admin, I want remove mcp <name> to find the server in whichever file defines it, and to ask for --role / --project when several files do, so that removal is unambiguous.
28. As a member editing an overridden skill, agent or rule, I want push to write back to the namespace it came from, so that a project edit never replaces the company-wide version.
29. As a member, I want push for skills to consider project namespaces as well as role namespaces, so that project skills are pushable at all.
30. As a team admin using per-entry projects: from a 0.26.0 beta, I want those entries to reach nobody and a warning naming the target file, so that project-only values never leak to the whole team after the upgrade.
31. As a team admin using roles: on env from a 0.26.0 beta, I want the same fail-closed treatment, so that there is only one deprecation to track.
32. As a team admin using roles: on hooks or MCP from 0.25.0, I want it to keep filtering for one minor release while pull and doctor tell me the exact target paths, so that I have time to move entries by hand.
33. As a team admin whose entry lists several roles, I want the warning to name every target file, so that I know the entry must be copied into each.
34. As a member on an older CLI, I want the release notes to say that the new axes require every member to upgrade first, so that my team does not break my pull by declaring them early.
35. As a team admin on this version or later, I want an unknown key in resources: to produce a warning instead of failing the scope, so that the next axis does not break older members again.
36. As a team without roles or projects, I want pull to behave exactly as before, so that this change does not touch me.
37. As a reviewer, I want the PR body to show the per-type consistency table, so that I can check the rule is the same everywhere and where it deliberately differs.

Implementation Decisions

• One namespace resolver. A new module owns the rule for every type. Input: root items and items per namespace, each with a name and its source file, plus the member's active namespace set. Output: the resolved items with their origin, or a tagged conflict value that names the item and both source files. The per-type code supplies how to parse a file into named items and how to apply the result. The existing agents and skills duplicate checks are replaced by it.
• Active set. Role ∪ project, from the existing namespace resolution. Legacy mode (no roles, no projects configured) does not go through the override or conflict rules.
• Override is whole-item. Env replaces by key, MCP by server name (command, args, env and tools: together), hooks by hook name, models by profile id, agents by stem, rules and claudemd by first-level file name, skills by skill directory. There is no field-level merge. An override without tools: reaches every tool.
• Skills install replaces the directory. The skills copy removes files the new source does not have, so switching between root and namespace versions leaves nothing behind. There is no new local-edit protection on overwrite; this matches every other pull today.
• Skills in role/project mode. Root skills remain the tag catalog and are not delivered by default. A root skill that arrives through a subscribed tag is overridden by an active namespace skill of the same name.
• Manifest schema. resources: in roles and projects manifests gains env, hooks, mcp, models and docs, each a list of namespace segments that defaults to empty. Unknown keys in resources: become a warning instead of an error from this version on.
• Failure policy. A file in the active set that does not parse, a duplicate name inside one file, or the same name in two active namespaces all stop that type for the current run and keep the installed state. The message names the file and the fix. This also replaces the current hooks and MCP behaviour, where an invalid file reconciles to an empty set and removes every managed entry.
• Env delivery. The env export files are regenerated from the resolved set on every pull, including when the root env file is missing or declares nothing, so a deactivated namespace's variables are removed. MCP ${VAR} lookup reads the same resolved set.
• Hooks and MCP delivery. They keep using the existing ownership-based reconcile, which already removes entries that are no longer desired.
• Models. Team profiles are loaded from the root file plus active models/<ns>/models.yaml. A stored team API key is bound to the profile id and the origin of its base_url. When an override changes the origin, pull does not update that agent and prints a line to run teamai models switch team:<id>. When a profile only existed in a deactivated namespace, the agent keeps its settings and the existing removed-profile message is reworded to "is no longer active in your namespaces".
• Docs. Declared means listed in resources.docs of any role or project. A declared namespace is delivered only where active. An undeclared subdirectory stays shared. Docs of a deactivated namespace are removed when byte-equal to the team source, and kept with a line otherwise. team-codebase is rejected as a docs namespace. The search index and doctor use the same filter.
• Search index. Skills and docs are indexed from the resolved set, the same one pull delivers.
• Removed keys. Per-entry projects: on env, hooks and MCP, and roles: on env, are detected explicitly (not left to schema stripping). Such an entry reaches nobody and a warning names the target file for each listed id. The per-entry membership module is deleted once nothing uses it.
• Deprecated key. roles: on hooks and MCP keeps filtering for one minor release. Pull warns once per run and doctor has a check whose fix names every target file. After that release it gets the removed-key treatment. There is no automatic migration.
• Push. Write-back goes to the origin the resolver reports: an overridden item is written to its namespace file, never to the root. The agents placement record no longer withdraws when a root file of the same stem exists. The skills push scan uses role ∪ project namespaces. push detects changes in any env/<ns>/env.yaml.
• Commands. env add / env remove accept --role / --project (mutually exclusive, like push). remove mcp <name> searches every file and requires --role / --project when the name is in more than one. No new add commands for MCP or hooks. status, the list subcommands and doctor show each entry's namespace; overrides are reported with the info log level, not as warnings.
• Docs to update. Usage guide (both languages), product overview (both languages), the multi-project design doc (its section saying no precedence logic should be added is rewritten for namespace-over-root), the admin setup reference in skill-data, CHANGELOG, and the generated commands reference. README is not changed.

Testing Decisions

• Tests assert observable behaviour: what a member has installed, exported or configured after a command, and what the command prints. They do not assert internal helpers other than the resolver's public interface.
• Seam 1, teamai pull end to end against a temporary team repo, for every type: activating a namespace applies its items and overrides; deactivating restores root versions and removes namespace-only items; two active namespaces with the same name fail with both file names; a broken active file keeps the installed state; legacy mode is unchanged. Prior art: the multi-project and project-scoped-delivery e2e suites, and the role-filter and project-cleanup pull tests.
• Seam 2, the namespace resolver, with property tests: the result does not depend on the order files are read; an active namespace item always wins over root; any name defined in two active namespaces always yields a conflict naming both. This adds fast-check as a dev dependency, which the repo does not have yet.
• Seam 3, teamai push end to end: an edited overridden skill, agent or rule is written to its namespace, and the root file is untouched. Prior art: the push namespace e2e and push role tests.
• Existing tests that encode "root + namespace is an error" (agents), the placement-record withdrawal, and role-mode push scans change to the new rule. Tests for namespace-vs-namespace errors stay and are checked for wording.
• Before the PR: npm run build and one representative real-CLI run (a checkout namespace overriding API_BASE and an MCP server, activated then deactivated), with the output in the PR body.

Out of Scope

• Protecting local edits on every pull overwrite (today no pull checks for them; adding it for override transitions only would need new per-item source state).
• Automatic migration of per-entry roles: into namespace files.
• New add commands for MCP or hooks.
• Delivering root skills by default in role/project mode.
• Field-level merge of overridden entries.
• Override for learnings and docs, where names cannot collide.
• Schema stripping of mistyped per-entry keys (a role: typo reaches everyone), and pull --dry-run not printing hooks/MCP warnings. Both are pre-existing and get their own issues.

Further Notes

• Timing: per-entry projects: (feat: scope hooks, MCP servers and env variables by logical project #700) and model profiles (feat(models): manage team and local model profiles #675) are only in the 0.26.0 betas. Landing this before 0.26.0 is stable means neither ships in a stable release with the old shape, and only roles: on hooks/MCP needs a deprecation.
• Compatibility: 0.25.0 and the betas reject unknown resources: keys, so a team that declares a new axis breaks pull for members still on those versions. The release notes must say to upgrade every member first.
• The PR body carries the consistency table above, including the three deliberate differences (skills root as tag catalog, no override for docs and learnings, legacy mode unchanged) and why.

---

Tickets

All six land in one PR, in this order. Each one updates its own sections of the usage guide (both languages) and skill-data, and regenerates the commands reference when it changes flags.

01 ─┬─ 02 ─┬─ 03 ─┐
    │      └─ 05 ─┼── 06
    └─ 04 ────────┘

01: Namespace resolver

What to build: one pure resolver for the namespace rule. It takes root items and items per namespace (each with a name and source file) plus the active set, and returns the resolved items with their origin, or a tagged conflict naming the item and both files. The existing agents and skills duplicate checks move onto it with no change in behaviour or messages.

Acceptance criteria

• An active namespace item replaces the root item of the same name.
• A name in two active namespaces yields a conflict naming both files.
• Property tests (fast-check, new dev dependency) show the result does not depend on read order.
• Current agents and skills pull behaviour and messages are unchanged.

Blocked by: None (can start immediately).

02: Env, hooks and MCP by namespace

What to build: admins scope env variables, hooks and MCP servers with <type>/<ns>/ files declared in resources:, and a project can override a shared key, hook or server. Per-entry scoping goes away.

Acceptance criteria

• resources: accepts env, hooks and mcp; an unknown resources: key warns instead of failing the scope.
• Pull delivers root plus active namespace files; a namespace entry replaces the root entry of the same key, hook name or server name, whole.
• Two active namespaces with the same name, a duplicate inside one file, or a broken active file stop that type for the run and keep the installed state; hooks and MCP no longer remove every managed entry on an invalid file.
• Deactivating a namespace removes its entries and restores overridden root entries; env.sh is regenerated even when the root env file is missing or empty.
• MCP ${VAR} lookup reads the resolved env set.
• Per-entry projects: (env, hooks, MCP) and roles: on env reach nobody and warn with the target file per listed id.
• roles: on hooks and MCP keeps filtering, warns once per pull and has a doctor check, both naming every target file.
• env add / env remove accept --role / --project; push detects env/<ns>/env.yaml; remove mcp searches every file and asks for --role / --project when the name is in more than one.
• env list, mcp list, hooks list, status and doctor show each entry's namespace; doctor lists overrides at info level.
• The per-entry membership module is deleted.

Blocked by: 01.

03: Model profiles by namespace

What to build: admins publish models/<ns>/models.yaml, and members switched to a team profile follow the project's version of that profile while the namespace is active, without their API key reaching a different host.

Acceptance criteria

• resources: accepts models; a namespace profile replaces the root profile with the same id.
• Conflict and broken-file rules match 02.
• A stored team API key is bound to the profile id and the base_url origin; when an override changes the origin, pull leaves that agent alone and prints the teamai models switch team:<id> line.
• Deactivating returns switched agents to the root profile when one exists; otherwise they keep their settings with "is no longer active in your namespaces".
• models list shows each profile's namespace.

Blocked by: 02.

04: Override for skills, agents, rules and claudemd

What to build: the namespace-over-root rule applies to the types that already have namespaces, and edits to an overridden item push back to its namespace.

Acceptance criteria

• Agents: root + active namespace with the same stem delivers the namespace agent; deactivating restores the root agent; the placement record is no longer withdrawn by a same-stem root file.
• Skills: a root skill received through a tag is replaced by an active namespace skill of the same name; installing replaces the whole directory; root skills are still not delivered by default in role/project mode.
• Rules: rules/<ns>/<name>.md suppresses rules/<name>.md, including in Hermes' concatenated block; deeper paths are unaffected.
• Claudemd: claudemd/<ns>/<name>.md replaces claudemd/<name>.md in the managed block.
• Push writes an edited overridden skill, agent or rule to its namespace and leaves the root untouched; the skills push scan uses role ∪ project namespaces.
• Recall indexes skills from the resolved set.
• Legacy mode is unchanged; doctor lists repeated names and overrides at info level.
• Tests that encode "root + namespace is an error" and placement withdrawal are updated to the new rule.

Blocked by: 01.

05: Docs axis

What to build: admins declare docs namespaces so project docs reach only members with that namespace active, while existing undeclared subdirectories keep reaching everyone.

Acceptance criteria

• resources: accepts docs; a namespace declared anywhere is delivered only where active; an undeclared docs/<dir>/ stays shared.
• Deactivating removes that namespace's local docs when byte-equal to the team source and keeps edited ones with a line.
• team-codebase is rejected as a docs namespace.
• The search index and doctor apply the same filter.

Blocked by: 02.

06: Cross-cutting docs and PR verification

What to build: the documentation, changelog and release notes describe one scoping model, and the PR carries real-CLI evidence.

Acceptance criteria

• The multi-project design doc's "no precedence logic" section is rewritten for namespace-over-root; product overview updated in both languages; skill-data admin reference lists the new axes.
• CHANGELOG drops the feat: scope hooks, MCP servers and env variables by logical project #700 per-entry projects: entry and adds the new behaviour; release notes say to upgrade every member before declaring the new axes.
• A grep for the old per-entry and duplicate-error wording finds nothing stale.
• npm run build plus one real-CLI run: a checkout namespace overriding API_BASE and an MCP server, activated then deactivated, with the output in the PR body.
• The PR body includes the per-type consistency table and the three deliberate differences.

Blocked by: 02, 03, 04, 05.

---

Decisions after publication (the code in #816 follows these)

• Rules and claudemd: two active namespaces with one name are both delivered. A conflict means two items competing for one slot.
• Skills install removes only files another team version of the skill tracks; files a member added survive.
• Overridable shared content lives at the root (rules/x.md), not in common/.
• A conflict or broken file stops only that type; skills and agents no longer abort the scope.
• Legacy mode: env, hooks and MCP read the root file only; agents keep rejecting stem clashes.
• Model API keys bind to the gateway origin for root and namespace profiles; a beta key binds once to the origin it was last sent to.
• remove mcp <name> targets the root by default; --role / --project pick a namespace.