teamshare-bridge 0.22.6 → 0.22.7

package/skills/codebase-design/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Matt Pocock
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/diagnosing-bugs/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Matt Pocock
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/domain-modeling/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Matt Pocock
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/improve-codebase-architecture/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Matt Pocock
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/recover/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 JavaScript Mastery
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 JavaScript Mastery
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/review/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 JavaScript Mastery
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 JavaScript Mastery
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/tdd/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Matt Pocock
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/teamshare-auth-rbac/SKILL.md

@@ -1,79 +1,79 @@
----
-name: teamshare-auth-rbac
-description: TeamShare auth & authorization rules for every endpoint you write or change. Pick the correct guard stack (@Permissions for human-only, @Public + AgentsDualAuthGuard + @ApiKeyScopes for agent+human surfaces, @Public for truly public, ApiKeyGuard + canUseTool for MCP). Enforce capability + key scope + project access (never less than two layers). Use envelope + zod validation + UPPER_SNAKE error codes, and write AgentLog rows for every agent action.
----
-
-# TeamShare Auth & Authorization (RBAC)
-
-Every endpoint in `teamshare-backend` must declare its access story. Use this
-decision table; never leave an endpoint with default guards and no metadata.
-
-## 1. Choose the guard stack
-
-| Who calls it | What to use on the route |
-|---|---|
-| Human JWT only (company/team/env-var/roles/webhooks/invitations/attachments) | Leave global guards, add `@Permissions('<entity>.<action>')` (e.g. `document.create`) |
-| Agents AND humans (tasks, comments, chat, documents, search, projects, agents self-service) | Class-level `@Public()` + `@UseGuards(AgentsDualAuthGuard)` + per-route `@ApiKeyScopes('<entity>:read' \| '<entity>:write')` |
-| Truly public (auth, verify, reset, billing webhook, run-token redeem) | `@Public()` only |
-| MCP tools (`/mcp`) | `ApiKeyGuard` + per-tool `canUseTool(capabilities, keyScopes, required)` |
-
-`AgentsDualAuthGuard` accepts `X-Api-Key` (enforces `@ApiKeyScopes`) OR a
-`Bearer` JWT. **Do not combine `@Permissions` with `AgentsDualAuthGuard` on the
-same route** — global RbacGuard runs before the route guard can set
-`request.user` for key callers. Dual-auth routes delegate access to the
-service layer.
-
-## 2. The three enforcement layers (never less than two)
-
-For every agent action: **capability** (`Agent.capabilities`) + **API-key
-scope** (`@ApiKeyScopes`, minted by `scopesForCapabilities`) + **project
-access** (`assertProjectAccess`). Never gate access on env vars.
-
-- MCP tool → `ctx.canUse('<capability>')` (capability + scope) then the shared
-  service runs `assertProjectAccess` as the agent user.
-- Agent REST → `@ApiKeyScopes` (scope) then the service runs
-  `assertProjectAccess` (project role).
-- Service layer helpers: `assertProjectAccess(prisma, projectId, userId,
-  minRole)`, `assertCompanyMembership`, `isCompanyOwnerOrAdmin`.
-
-## 3. Permission vocabulary (CRUDL)
-
-- `src/common/constants/rbac.ts`: `ENTITIES` (17) × `ACTIONS`
-  (`create | read | list | update | delete`) → `Permission = entity.action`
-  plus `SPECIAL_PERMISSIONS` (`env_var.reveal`, `env_var.export`, ...).
-- Static role matrices: `COMPANY_ROLE_PERMISSIONS`
-  (owner/admin/member/secret_manager/viewer) and `PROJECT_ROLE_PERMISSIONS`
-  (owner/member/viewer). Dynamic roles add `companyPermissions` claims.
-- Agent capabilities live in `src/common/constants/enums.ts`
-  (`AGENT_CAPABILITIES`, `CAPABILITY_SCOPES`). A key never exceeds its
-  agent's capabilities and a capability never exceeds the key's scopes.
-- Add a new capability → add its scope in `API_KEY_SCOPES` + a mapping in
-  `CAPABILITY_SCOPES`, so `scopesForCapabilities` mints the right key.
-
-## 4. Error codes & envelope
-
-- Throw `new XxxException({ code: 'UPPER_SNAKE', message, details? })`
-  (`VALIDATION_ERROR`, `PROJECT_NOT_FOUND`, `INSUFFICIENT_PROJECT_ROLE`,
-  `API_KEY_SCOPE_MISSING`, `DOCUMENT_UPDATE_DENIED`, ...). Secrets never
-  appear in messages/logs.
-- Responses: `{ success: true, data, pagination? }` /
-  `{ success: false, error: { code, message, details? } }` (global
-  interceptor/filter — your handler returns raw data).
-
-## 5. AgentLog — never bypass
-
-Every agent mutation logs an `AgentLog` row via the shared services:
-`logAgentActionIfAgent(prisma, userId, { action, taskId?, detail })`
-(best-effort; humans skipped). Actions are in `AGENT_LOG_ACTIONS`
-(`task_created`, `comment_created`, `document_created`, `document_updated`,
-`subtask_updated`, `wake_sent`, ...). If you add an agent-facing mutation,
-wire the log in the service — never in the controller.
-
-## 6. Checklist for a new endpoint
-
-- [ ] Guard stack chosen from the table; metadata declared on the route.
-- [ ] zod `ZodValidationPipe` on body/query/param; generated zod for enums.
-- [ ] Service re-checks project/company access (guards are a first filter).
-- [ ] Envelope-compliant return; UPPER_SNAKE error codes.
-- [ ] Agent actions write `AgentLog` via `logAgentActionIfAgent`.
+---
+name: teamshare-auth-rbac
+description: TeamShare auth & authorization rules for every endpoint you write or change. Pick the correct guard stack (@Permissions for human-only, @Public + AgentsDualAuthGuard + @ApiKeyScopes for agent+human surfaces, @Public for truly public, ApiKeyGuard + canUseTool for MCP). Enforce capability + key scope + project access (never less than two layers). Use envelope + zod validation + UPPER_SNAKE error codes, and write AgentLog rows for every agent action.
+---
+
+# TeamShare Auth & Authorization (RBAC)
+
+Every endpoint in `teamshare-backend` must declare its access story. Use this
+decision table; never leave an endpoint with default guards and no metadata.
+
+## 1. Choose the guard stack
+
+| Who calls it | What to use on the route |
+|---|---|
+| Human JWT only (company/team/env-var/roles/webhooks/invitations/attachments) | Leave global guards, add `@Permissions('<entity>.<action>')` (e.g. `document.create`) |
+| Agents AND humans (tasks, comments, chat, documents, search, projects, agents self-service) | Class-level `@Public()` + `@UseGuards(AgentsDualAuthGuard)` + per-route `@ApiKeyScopes('<entity>:read' \| '<entity>:write')` |
+| Truly public (auth, verify, reset, billing webhook, run-token redeem) | `@Public()` only |
+| MCP tools (`/mcp`) | `ApiKeyGuard` + per-tool `canUseTool(capabilities, keyScopes, required)` |
+
+`AgentsDualAuthGuard` accepts `X-Api-Key` (enforces `@ApiKeyScopes`) OR a
+`Bearer` JWT. **Do not combine `@Permissions` with `AgentsDualAuthGuard` on the
+same route** — global RbacGuard runs before the route guard can set
+`request.user` for key callers. Dual-auth routes delegate access to the
+service layer.
+
+## 2. The three enforcement layers (never less than two)
+
+For every agent action: **capability** (`Agent.capabilities`) + **API-key
+scope** (`@ApiKeyScopes`, minted by `scopesForCapabilities`) + **project
+access** (`assertProjectAccess`). Never gate access on env vars.
+
+- MCP tool → `ctx.canUse('<capability>')` (capability + scope) then the shared
+  service runs `assertProjectAccess` as the agent user.
+- Agent REST → `@ApiKeyScopes` (scope) then the service runs
+  `assertProjectAccess` (project role).
+- Service layer helpers: `assertProjectAccess(prisma, projectId, userId,
+  minRole)`, `assertCompanyMembership`, `isCompanyOwnerOrAdmin`.
+
+## 3. Permission vocabulary (CRUDL)
+
+- `src/common/constants/rbac.ts`: `ENTITIES` (17) × `ACTIONS`
+  (`create | read | list | update | delete`) → `Permission = entity.action`
+  plus `SPECIAL_PERMISSIONS` (`env_var.reveal`, `env_var.export`, ...).
+- Static role matrices: `COMPANY_ROLE_PERMISSIONS`
+  (owner/admin/member/secret_manager/viewer) and `PROJECT_ROLE_PERMISSIONS`
+  (owner/member/viewer). Dynamic roles add `companyPermissions` claims.
+- Agent capabilities live in `src/common/constants/enums.ts`
+  (`AGENT_CAPABILITIES`, `CAPABILITY_SCOPES`). A key never exceeds its
+  agent's capabilities and a capability never exceeds the key's scopes.
+- Add a new capability → add its scope in `API_KEY_SCOPES` + a mapping in
+  `CAPABILITY_SCOPES`, so `scopesForCapabilities` mints the right key.
+
+## 4. Error codes & envelope
+
+- Throw `new XxxException({ code: 'UPPER_SNAKE', message, details? })`
+  (`VALIDATION_ERROR`, `PROJECT_NOT_FOUND`, `INSUFFICIENT_PROJECT_ROLE`,
+  `API_KEY_SCOPE_MISSING`, `DOCUMENT_UPDATE_DENIED`, ...). Secrets never
+  appear in messages/logs.
+- Responses: `{ success: true, data, pagination? }` /
+  `{ success: false, error: { code, message, details? } }` (global
+  interceptor/filter — your handler returns raw data).
+
+## 5. AgentLog — never bypass
+
+Every agent mutation logs an `AgentLog` row via the shared services:
+`logAgentActionIfAgent(prisma, userId, { action, taskId?, detail })`
+(best-effort; humans skipped). Actions are in `AGENT_LOG_ACTIONS`
+(`task_created`, `comment_created`, `document_created`, `document_updated`,
+`subtask_updated`, `wake_sent`, ...). If you add an agent-facing mutation,
+wire the log in the service — never in the controller.
+
+## 6. Checklist for a new endpoint
+
+- [ ] Guard stack chosen from the table; metadata declared on the route.
+- [ ] zod `ZodValidationPipe` on body/query/param; generated zod for enums.
+- [ ] Service re-checks project/company access (guards are a first filter).
+- [ ] Envelope-compliant return; UPPER_SNAKE error codes.
+- [ ] Agent actions write `AgentLog` via `logAgentActionIfAgent`.
 - [ ] Swagger `@ApiOperation` mentions the RBAC; `@errs(...)` lists the codes.