feat(mcpd): make AgentProject real — an agent joins many projects

The AgentProject junction has existed since the data-model commit and nothing
read it. `grep -c agentProject src/mcpd/src/services/chat.service.ts` returned
0; chat resolved an agent's project from the legacy single `Agent.projectId`
scalar. So the schema claimed "an agent is a person who joins zero, one, or
many projects" (docs/agentic-teams.md §4) while the running system still gave
every agent exactly one project. A schema that lies about behaviour is worse
than a missing feature: it reads as done, so nobody builds it.

This makes the junction load-bearing.

Membership is now a real surface (task 152):

  GET    /api/v1/agents/:name/projects          memberships
  POST   /api/v1/agents/:name/projects/:project join, body {role?, llm?}
  DELETE /api/v1/agents/:name/projects/:project leave
  GET    /api/v1/projects/:name/memberships     the roster, with roles

`role` is TEXT (developer|qa|security|sre in v1) and is validated in the
service layer, not the database — production provisions with `prisma db push`,
so a CHECK constraint written into a migration would never run there. Adding a
fifth role stays a one-line change.

RBAC: joining/leaving is `edit:agents:<name>`, not the `create:agents` the
default method→action mapping would have produced. Minting a whole new agent
and adding an existing one to a team are not the same authority; this mirrors
project↔server attach/detach already being `edit:projects`. Reading a roster is
`view:` on the side you asked from.

Chat honours it. `prepareContext` resolves the project from the membership when
the caller names one, and the resolution runs *before* the Llm lookup so a
per-membership `llmId` can replace the agent's pinned brain — and therefore its
whole failover pool — rather than patching the dispatch list afterwards. That
override is why the brain-ownership question (§15 Q1) can still go either way
without a migration: today the answer is per membership.

Naming a project the agent has not joined is an error that names the fix, not a
silent fallback. Answering from a *different* project's tools and prompts than
the one asked for is the failure mode worth being loud about.

The legacy scalar keeps working this release, as the schema comment promises:
`--project` accepts a membership *or* a legacy pin naming that same project,
bare `mcpctl chat <agent>` is unchanged, and `GET /projects/:p/agents` returns
the union of members and legacy-pinned agents so nothing disappears from a
project mid-migration (mcplocal's agents plugin reads that endpoint).

CLI: `mcpctl chat <agent> --project <p>` (previously rejected as "not both"),
plus `attach-agent` / `detach-agent` alongside the existing attach-server pair,
`get agents --project`, and `get memberships` with ROLE and BRAIN columns.
Completions come from the generator, not hand-edits.

Threads stay scoped to the agent, not to (agent, project) — §4 wants the
latter, but that needs a schema change and a story for what happens to those
threads when a membership is revoked. Deliberately not decided here.

Tests: 51 new (43 mcpd, 8 CLI). Full suite 2514 pass. Lint unchanged at
794 errors / 77 warnings.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/agents.md

@@ -80,7 +80,11 @@ POST   /api/v1/agents/:name/chat       chat — non-streaming or SSE (run:agents
 POST   /api/v1/agents/:name/threads    create thread (run:agents:<name>)
 GET    /api/v1/agents/:name/threads    list threads (run:agents:<name>)
 GET    /api/v1/threads/:id/messages    replay history (view:agents)
-GET    /api/v1/projects/:p/agents      project-scoped list (view:projects:<p>)
+GET    /api/v1/projects/:p/agents      project roster — members + legacy pins (view:projects:<p>)
+GET    /api/v1/agents/:name/projects   memberships (view:agents:<name>)
+POST   /api/v1/agents/:name/projects/:p    join, body {role?, llm?} (edit:agents:<name>)
+DELETE /api/v1/agents/:name/projects/:p    leave (edit:agents:<name>)
+GET    /api/v1/projects/:p/memberships     roster with roles (view:projects:<p>)
 ```
 
 The chat endpoint reuses the SSE pattern from `llm-infer.ts` exactly: same
@@ -93,6 +97,37 @@ framing, same `[DONE]` terminator. SSE chunk types:
 - `{type:'final', threadId, turnIndex}` — terminal turn
 - `{type:'error', message}` — fatal error in the loop
 
+## Team membership (an agent joins many projects)
+
+An agent is a **person**, not a project's property: it joins zero, one, or many
+projects (`docs/agentic-teams.md` §4). Membership lives in the `AgentProject`
+junction and carries two per-project facts the `Agent` row cannot:
+
+- **`role`** — the persona worn on this team. v1: `developer` (default), `qa`,
+  `security`, `sre`. TEXT in the schema, validated in the service layer, so
+  adding a role later is not a migration.
+- **`llm`** — an optional **brain override**. When set, that Llm answers for
+  this project instead of the agent's pinned one; the agent keeps its own brain
+  everywhere else.
+
+```bash
+mcpctl attach-agent alice --project sre --role sre --llm qwen3-thinking
+mcpctl attach-agent alice --project payments --role security
+mcpctl get memberships alice           # every team alice is on
+mcpctl get memberships --project sre   # the sre roster, with roles
+mcpctl get agents --project sre        # the same roster as plain agent rows
+mcpctl detach-agent alice --project sre
+```
+
+Joining is idempotent — re-running `attach-agent` updates the role/brain
+instead of failing, so repeated applies converge.
+
+**Transition:** the legacy single `Agent.projectId` pin still works this
+release. `mcpctl chat <agent> --project <p>` accepts a membership *or* a legacy
+pin naming that same project; anything else is an error rather than a silent
+answer from the wrong project's context. `GET /projects/:p/agents` returns the
+union of both, so nothing disappears from a project mid-migration.
+
 ## Tool-use loop
 
 When the agent's project has MCP servers attached, mcpd's `ChatService` lists
@@ -113,10 +148,15 @@ Recommended:
 - `view:agents` — list / describe
 - `create:agents` / `edit:agents` / `delete:agents` — CRUD
 - `run:agents:<name>` — drive a chat turn or manage its threads
+- `edit:agents:<name>` — join/leave a project team (NOT `create:agents`, which
+  mints whole agents; this mirrors project↔server attach/detach being `edit`)
 
 Project-attached agents do not implicitly inherit project RBAC. If a project
 member should be able to chat with the project's agents, grant them
-`run:agents:<each-name>` (or wildcard `run:agents`) explicitly.
+`run:agents:<each-name>` (or wildcard `run:agents`) explicitly. The reverse also
+holds: membership grants the *agent* project context, not the *caller* project
+permissions — `run:agents:<name>` is still the only check on
+`mcpctl chat <agent> --project <p>`.
 
 ## YAML round-trip
 

docs/chat.md

@@ -8,6 +8,7 @@ create one.
 
 ```bash
 mcpctl chat <agent>                 # interactive REPL, new thread
+mcpctl chat <agent> --project <p>   # same agent, viewing project p
 mcpctl chat <agent> --thread <id>   # interactive REPL, resume thread
 mcpctl chat <agent> -m "hi"         # one-shot, prints reply, no REPL
 mcpctl chat <agent> -m "hi" --no-stream  # one-shot, single JSON response (no SSE)
@@ -17,6 +18,35 @@ Streaming is on by default. Text deltas land on stdout as they arrive; tool
 calls and tool results print to stderr in dim brackets so the chat output
 stays clean.
 
+## Two lenses on the same agent
+
+`mcpctl chat alice` is the person **on their own** — their system prompt, their
+own pinned brain, no project tools.
+
+`mcpctl chat alice --project sre` is the **same person viewing one of their
+teams**: the project's Prompts join the system block, the project's MCP servers
+become callable tools, and if that membership carries a brain override, that
+Llm answers instead of alice's pinned one.
+
+```bash
+mcpctl attach-agent alice --project sre --role sre   # join first
+mcpctl chat alice --project sre
+```
+
+The agent must actually be a member. Naming a project it has not joined is an
+error naming the fix, not a silent fallback to some other project's context:
+
+```
+Agent 'alice' is not a member of project 'payments'.
+Join it with: mcpctl attach-agent alice --project payments
+```
+
+(The legacy single-project pin on the agent still counts as membership in that
+one project for this release — see [agents.md](agents.md#team-membership-an-agent-joins-many-projects).)
+
+Threads stay scoped to the **agent**, not to (agent, project) — switching
+`--project` mid-conversation changes the context layer, not the history.
+
 ## Project chat
 
 Chat directly with a **project** — no Agent needed. The session sees the