permdock 0.1.0 → 0.2.0

package/schemas/supabase-manifest-v1.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://permdock.dev/schemas/supabase-manifest-v1.json",
+  "$id": "https://permdock.com/schemas/supabase-manifest-v1.json",
   "title": "PermDock Supabase hook manifest v1",
   "description": "What `permdock supabase inspect --json` prints and `--out` writes: the generated hook, the SQL helpers, the claims, the membership sources and the columns that decide them. Fields are only added within v1.",
   "type": "object",
@@ -20,7 +20,7 @@
   ],
   "properties": {
     "$schema": {
-      "const": "https://permdock.dev/schemas/supabase-manifest-v1.json"
+      "const": "https://permdock.com/schemas/supabase-manifest-v1.json"
     },
     "version": { "const": 1 },
     "hook": {
@@ -29,7 +29,14 @@
       "properties": {
         "schema": { "$ref": "#/$defs/identifier" },
         "function": { "const": "custom_access_token_hook" },
-        "out": { "type": "string" }
+        "out": { "type": "string" },
+        "before": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+          }
+        }
       }
     },
     "helpers": {
@@ -128,6 +135,69 @@
         "memberships": {
           "type": "array",
           "items": { "$ref": "#/$defs/membership" }
+        },
+        "customRoles": { "type": "boolean" },
+        "roles": {
+          "type": "object",
+          "required": ["table", "user", "role"],
+          "additionalProperties": false,
+          "properties": {
+            "table": { "type": "string" },
+            "user": { "$ref": "#/$defs/column" },
+            "role": {
+              "oneOf": [
+                { "$ref": "#/$defs/role" },
+                {
+                  "type": "array",
+                  "minItems": 2,
+                  "items": { "$ref": "#/$defs/role" }
+                }
+              ]
+            }
+          }
+        },
+        "suspension": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "users": { "$ref": "#/$defs/activeRow" },
+            "scopes": {
+              "type": "object",
+              "additionalProperties": { "$ref": "#/$defs/activeRow" }
+            },
+            "memberships": {
+              "type": "object",
+              "required": ["keep"],
+              "additionalProperties": false,
+              "properties": {
+                "keep": {
+                  "description": "The permission keys a membership whose disabledAt column is set still holds.",
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+        "assignments": {
+          "type": "object",
+          "required": ["tables"],
+          "additionalProperties": false,
+          "properties": {
+            "tables": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "apiKeys": {
+          "type": "object",
+          "required": ["claim", "scopes", "tenant", "roles", "serviceRoles"],
+          "additionalProperties": false,
+          "properties": {
+            "claim": { "type": "string" },
+            "scopes": { "type": "string" },
+            "tenant": { "type": "string" },
+            "roles": { "type": "string" },
+            "serviceRoles": { "type": "array", "items": { "type": "string" } }
+          }
         }
       }
     },
@@ -145,6 +215,26 @@
         "hook": { "const": "v1" },
         "grants": { "const": "v1" }
       }
+    },
+    "requires": {
+      "description": "The supabase/sdk capability-matrix feature ids the hook, the helpers and subjectFromSupabase depend on, as of the matrix release tag.",
+      "type": "object",
+      "required": ["matrix", "capabilities"],
+      "additionalProperties": false,
+      "properties": {
+        "matrix": {
+          "type": "string",
+          "pattern": "^capability-matrix-v1\\.[0-9]+\\.[0-9]+$"
+        },
+        "capabilities": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*\\.[a-z0-9_]+\\.[a-z0-9_]+$"
+          }
+        }
+      }
     }
   },
   "$defs": {
@@ -156,10 +246,19 @@
           "type": "string",
           "pattern": "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
         },
-        "user": { "$ref": "#/$defs/column" },
+        "user": { "$ref": "#/$defs/user" },
         "scope": { "$ref": "#/$defs/value" },
         "id": { "$ref": "#/$defs/column" },
-        "role": { "$ref": "#/$defs/value" },
+        "role": {
+          "oneOf": [
+            { "$ref": "#/$defs/role" },
+            {
+              "type": "array",
+              "minItems": 2,
+              "items": { "$ref": "#/$defs/role" }
+            }
+          ]
+        },
         "within": {
           "oneOf": [
             { "$ref": "#/$defs/column" },
@@ -178,6 +277,7 @@
         },
         "via": { "$ref": "#/$defs/value" },
         "expiresAt": { "$ref": "#/$defs/column" },
+        "disabledAt": { "$ref": "#/$defs/column" },
         "columns": {
           "type": "array",
           "items": { "$ref": "#/$defs/identifier" }
@@ -185,9 +285,26 @@
       }
     },
     "identifier": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "activeRow": {
+      "type": "object",
+      "required": ["table", "id"],
+      "additionalProperties": false,
+      "properties": {
+        "table": { "type": "string" },
+        "id": { "$ref": "#/$defs/identifier" },
+        "disabledAt": { "$ref": "#/$defs/identifier" },
+        "status": { "$ref": "#/$defs/identifier" },
+        "active": { "type": "array", "items": { "type": "string" } },
+        "keep": {
+          "description": "A scope only: the permission keys members of a suspended instance still hold.",
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
     "helperName": {
       "type": "string",
-      "pattern": "^(permdock_has|permitted_[a-z][a-z0-9_]*_ids|member_[a-z][a-z0-9_]*_ids(_for)?)$"
+      "pattern": "^(permdock_has(_for)?|permitted_[a-z][a-z0-9_]*_(ids|permission_keys)(_for)?|member_[a-z][a-z0-9_]*_ids(_for)?|permdock_can_assign(_any|_custom_role)?(_for)?|permdock_api_key_allows|permdock_user_id)$"
     },
     "column": {
       "type": "object",
@@ -195,6 +312,33 @@
       "additionalProperties": false,
       "properties": { "column": { "$ref": "#/$defs/identifier" } }
     },
+    "role": {
+      "oneOf": [{ "$ref": "#/$defs/value" }, { "$ref": "#/$defs/through" }]
+    },
+    "user": {
+      "oneOf": [{ "$ref": "#/$defs/column" }, { "$ref": "#/$defs/through" }]
+    },
+    "through": {
+      "type": "object",
+      "required": ["column", "through"],
+      "additionalProperties": false,
+      "properties": {
+        "column": { "$ref": "#/$defs/identifier" },
+        "through": {
+          "type": "object",
+          "required": ["table", "id", "column"],
+          "additionalProperties": false,
+          "properties": {
+            "table": {
+              "type": "string",
+              "pattern": "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
+            },
+            "id": { "$ref": "#/$defs/identifier" },
+            "column": { "$ref": "#/$defs/identifier" }
+          }
+        }
+      }
+    },
     "value": {
       "oneOf": [
         { "$ref": "#/$defs/column" },

package/skills/permdock/SKILL.md

@@ -4,13 +4,13 @@ description: Explains how PermDock decides and routes to the right PermDock skil
 license: MIT
 metadata:
   author: ScaleDockHQ
-  homepage: https://permdock.dev/docs/for-ai-agents
+  homepage: https://permdock.com/docs/for-ai-agents
   repository: https://github.com/ScaleDockHQ/permdock
 ---
 
 # PermDock
 
-PermDock is typed permissions for TypeScript apps, APIs, databases and AI agents. Permissions are defined once, decided in process, compiled to queries and RLS, and serialised to client snapshots ([for AI agents](https://permdock.dev/docs/for-ai-agents)). This skill holds the model every other PermDock skill assumes, and says which one to load.
+PermDock is typed permissions for TypeScript apps, APIs, databases and AI agents. Permissions are defined once, decided in process, compiled to queries and RLS, and serialised to client snapshots ([for AI agents](https://permdock.com/docs/for-ai-agents)). This skill holds the model every other PermDock skill assumes, and says which one to load.
 
 ## Inputs (find out before starting)
 
@@ -44,13 +44,13 @@ PermDock is typed permissions for TypeScript apps, APIs, databases and AI agents
 
    ✓ The skill for the task is loaded, and `permdock-wire` has run first if the app has no factory file.
 
-2. **Look identifiers up, never guess them.** Read the owning page through the docs MCP (`https://permdock.dev/mcp`, tools `search`, `list_pages` and `get_page`), or append `.md` to any `https://permdock.dev/docs/...` URL. Every public name follows the [naming convention](https://permdock.dev/docs/getting-started/naming).
+2. **Look identifiers up, never guess them.** Read the owning page through the docs MCP (`https://permdock.com/mcp`, tools `search`, `list_pages` and `get_page`), or append `.md` to any `https://permdock.com/docs/...` URL. Every public name follows the [naming convention](https://permdock.com/docs/getting-started/naming).
    ✓ Each identifier written into the app appears on a docs page or in `node_modules/permdock`.
-3. **Read a decision.** `decide()` returns `{ outcome, denials: [{ reason, ... }], alternatives }`. `reason` is one of the closed list on [decisions](https://permdock.dev/docs/concepts/decisions); `alternatives` are permissions on the same resource the subject does hold. HTTP adapters answer RFC 9457 Problem Details ([errors](https://permdock.dev/docs/concepts/errors)); for the format, defer to the `problem-details` spec skill (`npx skills add ScaleDockHQ/scaledock-skills --skill problem-details`).
+3. **Read a decision.** `decide()` returns `{ outcome, denials: [{ reason, ... }], alternatives }`. `reason` is one of the closed list on [decisions](https://permdock.com/docs/concepts/decisions); `alternatives` are permissions on the same resource the subject does hold. HTTP adapters answer RFC 9457 Problem Details ([errors](https://permdock.com/docs/concepts/errors)); for the format, defer to the `problem-details` spec skill (`npx skills add ScaleDockHQ/scaledock-skills --skill problem-details`).
    ✓ Each denial the user asked about is named by its reason.
-4. **Explain an unexpected denial.** Run `permdock.explain(permission, data)` in a test or a script. `trace.denies[0]` is the deny that won (give denies a `name` so it reads as a rule), `trace.allows` the allows it overrode, `trace.skipped` the grants passed over and why ([explain](https://permdock.dev/docs/concepts/decisions#explain)). The trace never reaches the decision log. To preview a plan before acting, `simulate([[permission, data], ...])` returns every decision.
+4. **Explain an unexpected denial.** Run `permdock.explain(permission, data)` in a test or a script. `trace.denies[0]` is the deny that won (give denies a `name` so it reads as a rule), `trace.allows` the allows it overrode, `trace.skipped` the grants passed over and why ([explain](https://permdock.com/docs/concepts/decisions#explain)). The trace never reaches the decision log. To preview a plan before acting, `simulate([[permission, data], ...])` returns every decision.
    ✓ The cause is a named grant, condition or missing input, not a guess.
-5. **Check the project.** Run `pnpm exec permdock doctor` (`--json` for machine output). Each finding has a stable `PD0xx` code and a one-line fix ([doctor](https://permdock.dev/docs/cli/doctor)); the topic skills name the codes for their area.
+5. **Check the project.** Run `pnpm exec permdock doctor` (`--json` for machine output). Each finding has a stable `PD0xx` code and a one-line fix ([doctor](https://permdock.com/docs/cli/doctor)); the topic skills name the codes for their area.
    ✓ `permdock doctor` reports no error.
 
 ## Verify before done
@@ -63,4 +63,4 @@ PermDock is typed permissions for TypeScript apps, APIs, databases and AI agents
 ## Reference index
 
 - Skills: `permdock-wire`, `permdock-audit`, `permdock-agents`, `permdock-approvals`, `permdock-tenancy`, `permdock-data`, `permdock-credentials`, all from `npx skills add ScaleDockHQ/PermDock --skill <name>`.
-- Docs: [for AI agents](https://permdock.dev/docs/for-ai-agents), [naming](https://permdock.dev/docs/getting-started/naming), [policies](https://permdock.dev/docs/concepts/policies), [decisions](https://permdock.dev/docs/concepts/decisions), [threat model](https://permdock.dev/docs/security/threat-model), [doctor](https://permdock.dev/docs/cli/doctor), `https://permdock.dev/llms.txt`.
+- Docs: [for AI agents](https://permdock.com/docs/for-ai-agents), [naming](https://permdock.com/docs/getting-started/naming), [policies](https://permdock.com/docs/concepts/policies), [decisions](https://permdock.com/docs/concepts/decisions), [threat model](https://permdock.com/docs/security/threat-model), [doctor](https://permdock.com/docs/cli/doctor), `https://permdock.com/llms.txt`.

package/skills/permdock-agents/SKILL.md

@@ -4,13 +4,13 @@ description: Guards AI agent tool calls with PermDock subjects, actors and deleg
 license: MIT
 metadata:
   author: ScaleDockHQ
-  homepage: https://permdock.dev/docs/security/delegation
+  homepage: https://permdock.com/docs/security/delegation
   repository: https://github.com/ScaleDockHQ/permdock
 ---
 
 # PermDock agents
 
-An agent call has a principal (the user whose grants are evaluated), an actor (the agent making the call) and a delegation (what the user handed over). The decision is the principal's grants intersected with the delegation ([delegation](https://permdock.dev/docs/security/delegation)). Set up `permissions.ts`, `policy.ts` and the factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
+An agent call has a principal (the user whose grants are evaluated), an actor (the agent making the call) and a delegation (what the user handed over). The decision is the principal's grants intersected with the delegation ([delegation](https://permdock.com/docs/security/delegation)). Set up `permissions.ts`, `policy.ts` and the factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
 
 ## Inputs (find out, or ask before starting)
 
@@ -32,7 +32,7 @@ An agent call has a principal (the user whose grants are evaluated), an actor (t
 
 ## Workflow
 
-1. **Name the three parts per surface.** Write down the principal source, the actor source and the delegation source for each runtime from the Inputs. The adapter table on [delegation](https://permdock.dev/docs/security/delegation#how-adapters-fill-actor-and-delegation) shows what each adapter fills itself (MCP and A2A read token scopes; in-process runtimes take a `delegation` option).
+1. **Name the three parts per surface.** Write down the principal source, the actor source and the delegation source for each runtime from the Inputs. The adapter table on [delegation](https://permdock.com/docs/security/delegation#how-adapters-fill-actor-and-delegation) shows what each adapter fills itself (MCP and A2A read token scopes; in-process runtimes take a `delegation` option).
    ✓ Every surface has all three, and none reads from model-controlled input.
 2. **Map the tools.** Use the runtime's `createPermDock` with `subject`, `actor` and a `tools` map, and pass the returned hook to the runtime. -> [references/runtimes.md](references/runtimes.md)
    ✓ Every tool the agent can call has a `permission`, and every instance permission has a `data` loader that parses its arguments.
@@ -59,7 +59,7 @@ An agent call has a principal (the user whose grants are evaluated), an actor (t
    ✓ A destructive tool returns the runtime's approval outcome instead of running.
 5. **Wire the agent-facing surfaces.** A2A: serve `agentCard()` publicly, `extendedAgentCard(auth)` behind auth, and `protectSkill` on the task endpoint. WebMCP: `registerTools` from a snapshot, with the server re-checking. Web Bot Auth: `webBotAuth: (request) => verifyWebBotAuth(request, { verify: true, keys })` on the HTTP adapter. -> [references/runtimes.md](references/runtimes.md)
    ✓ Each surface passes the Verify list of its spec skill.
-6. **Test.** Add scenario tests with `permdock/testing` for one delegated grant, one `not-delegated` denial and one approval per destructive tool ([scenario testing](https://permdock.dev/docs/guides/scenario-testing)). Then review with the `permdock-audit` skill, which reports ASI02 and ASI03 per adapter.
+6. **Test.** Add scenario tests with `permdock/testing` for one delegated grant, one `not-delegated` denial and one approval per destructive tool ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). Then review with the `permdock-audit` skill, which reports ASI02 and ASI03 per adapter.
    ✓ The tests pass and the audit has no blocker.
 
 ## Verify before done
@@ -74,4 +74,4 @@ An agent call has a principal (the user whose grants are evaluated), an actor (t
 ## Reference index
 
 - [references/runtimes.md](references/runtimes.md): factory shapes and outcome mapping for AI SDK, Claude Agent SDK, Eve, OpenAI Agents SDK, MCP, A2A, WebMCP, Web Bot Auth and `permdock/terminal`.
-- Docs: [delegation](https://permdock.dev/docs/security/delegation), [subject](https://permdock.dev/docs/concepts/subject), [OWASP Agentic mapping](https://permdock.dev/docs/security/owasp-agentic), adapter pages under `https://permdock.dev/docs/adapters/<name>`.
+- Docs: [delegation](https://permdock.com/docs/security/delegation), [subject](https://permdock.com/docs/concepts/subject), [OWASP Agentic mapping](https://permdock.com/docs/security/owasp-agentic), adapter pages under `https://permdock.com/docs/adapters/<name>`.

package/skills/permdock-agents/references/runtimes.md

@@ -1,6 +1,6 @@
 # Agent runtimes
 
-Every agent adapter exports `createPermDock` from `permdock/<runtime>` and takes `subject`, `actor`, `delegation`, `tools` and `store`. One permission per tool. Instance actions load the row through `data`; tool input arrives as `unknown`, so parse it before loading. The current adapter page is `https://permdock.dev/docs/adapters/<name>`.
+Every agent adapter exports `createPermDock` from `permdock/<runtime>` and takes `subject`, `actor`, `delegation`, `tools` and `store`. One permission per tool. Instance actions load the row through `data`; tool input arrives as `unknown`, so parse it before loading. The current adapter page is `https://permdock.com/docs/adapters/<name>`.
 
 ## AI SDK — `permdock/ai-sdk`
 
@@ -27,7 +27,7 @@ export const { toolApproval, capabilityMiddleware, needsApproval } =
   });
 ```
 
-Pass `toolApproval` into `generateText` / `ToolLoopAgent`. Wrap the model with `wrapLanguageModel({ model, middleware: capabilityMiddleware({ user }) })` per caller. Use `needsApproval(permissions.post.delete)` only on `WorkflowAgent`. `denied` maps to `'denied'`, `approval-required` to `'user-approval'`, and `'not-applicable'` is never returned ([AI SDK adapter](https://permdock.dev/docs/adapters/ai-sdk)).
+Pass `toolApproval` into `generateText` / `ToolLoopAgent`. Wrap the model with `wrapLanguageModel({ model, middleware: capabilityMiddleware({ user }) })` per caller. Use `needsApproval(permissions.post.delete)` only on `WorkflowAgent`. `denied` maps to `'denied'`, `approval-required` to `'user-approval'`, and `'not-applicable'` is never returned ([AI SDK adapter](https://permdock.com/docs/adapters/ai-sdk)). Tools without a permission are hidden and denied unless `unmapped: 'allow'`; to combine PermDock with the app's own confirmation, pass `composeToolApproval(appApproval)` as `toolApproval` instead of wrapping the adapter: the app's function is asked only for calls PermDock grants, and its answer passes through (`undefined` stays not applicable; an unreadable answer denies).
 
 ## Claude Agent SDK — `permdock/claude-agent`
 
@@ -47,7 +47,7 @@ export const { canUseTool, permissionRequestHook } = createPermDock(policy, {
 });
 ```
 
-`canUseTool` returns `{ behavior: 'allow', updatedInput }` or `{ behavior: 'deny', message }`; approval-required is a deny whose message carries the pending token. Pass a `store`: once a reviewer approves, the retried call is allowed exactly once. `mcp__` tools are trusted only from `mcpSources` (default `['sdk']`). Pass `permissionRequestHook` under `hooks.PermissionRequest` ([Claude Agent adapter](https://permdock.dev/docs/adapters/claude-agent)).
+`canUseTool` returns `{ behavior: 'allow', updatedInput }` or `{ behavior: 'deny', message }`; approval-required is a deny whose message carries the pending token. Pass a `store`: once a reviewer approves, the retried call is allowed exactly once. `mcp__` tools are trusted only from `mcpSources` (default `['sdk']`). Pass `permissionRequestHook` under `hooks.PermissionRequest` ([Claude Agent adapter](https://permdock.com/docs/adapters/claude-agent)).
 
 ## Eve — `permdock/eve`
 
@@ -65,7 +65,7 @@ export const { approval, approvalFor, permdock } = createPermDock(policy, {
 });
 ```
 
-Pass `approval` as the tool's `approval`. Default subject and actor read `session.auth.initiator` / `current`. `approval.request(ctx)` maps granted to Eve's `not-applicable` (continue), approval-required to `user-approval`, denied to `{ type: 'denied', reason }`; Eve's re-check of a call nobody approved is denied. `approval.response(ctx)` maps the responder through the same `subject`. Use a durable `store` when replicas share sessions ([Eve adapter](https://permdock.dev/docs/adapters/eve)).
+Pass `approval` as the tool's `approval`. Default subject and actor read `session.auth.initiator` / `current`. `approval.request(ctx)` maps granted to Eve's `not-applicable` (continue), approval-required to `user-approval`, denied to `{ type: 'denied', reason }`; Eve's re-check of a call nobody approved is denied. `approval.response(ctx)` maps the responder through the same `subject`. Use a durable `store` when replicas share sessions ([Eve adapter](https://permdock.com/docs/adapters/eve)).
 
 ## OpenAI Agents SDK — `permdock/openai`
 
@@ -86,7 +86,7 @@ export const { needsApproval, guardTools, resolveInterruptions, permdock } =
   });
 ```
 
-`needsApproval(permission)` is the tool's `needsApproval`; it reads `runContext.context` and is true unless granted. `guardTools` drops tools with no grant. `resolveInterruptions(state, interruptions, { context })` approves or rejects each pause and returns the still-pending `ApprovalRequest`s. On resume, rebuild the context from the session and use `RunState.fromStringWithContext` ([OpenAI adapter](https://permdock.dev/docs/adapters/openai)).
+`needsApproval(permission)` is the tool's `needsApproval`; it reads `runContext.context` and is true unless granted. `guardTools` drops tools with no grant. `resolveInterruptions(state, interruptions, { context })` approves or rejects each pause and returns the still-pending `ApprovalRequest`s. On resume, rebuild the context from the session and use `RunState.fromStringWithContext` ([OpenAI adapter](https://permdock.com/docs/adapters/openai)).
 
 ## MCP — `permdock/mcp`
 
@@ -113,10 +113,12 @@ server.registerTool(
 );
 ```
 
-`actor.kind` is `'mcp-client'`, and `delegation` comes from the token's scopes and `authorization_details`. Every `registerTool` / `registerResource` / `registerPrompt` needs a `permission`. Lists are filtered per caller. A missing scope is an `insufficient_scope` step-up (HTTP `403`) naming only the scope the call needs. Set `resource` to the server's URL so tokens for another audience are refused. Denied calls return `isError: true` with Decision `structuredContent`. `approval-required` parks the call in `store` and returns `isError: true` with the token, or an `input_required` URL request when `approval.at` is set and the client declares URL elicitation; the retried call runs once after approval (token optional under `_meta["dev.permdock/approval"]`, never from tool arguments) ([MCP adapter](https://permdock.dev/docs/adapters/mcp)).
+`actor.kind` is `'mcp-client'` unless `actorKind` sets another (`'oauth-client'` makes the token the same actor kind `permdock/supabase` and `permdock/jwt` give it, so one delegation covers both), and `delegation` comes from the token's scopes and `authorization_details`. Every `registerTool` / `registerResource` / `registerPrompt` needs a `permission`. Lists are filtered per caller. A missing scope is an `insufficient_scope` step-up (HTTP `403`) naming only the scope the call needs. When the authorization server issues coarse scopes (`mcp:read`), declare them in `definePolicy({ oauthScopes })` instead of expanding scopes yourself: they are expanded into the delegation and named in challenges. Set `resource` to the server's URL so tokens for another audience are refused. Denied calls return `isError: true` with Decision `structuredContent`. `approval-required` parks the call in `store` and returns `isError: true` with the token, or an `input_required` URL request when `approval.at` is set and the client declares URL elicitation; the retried call runs once after approval (token optional under `_meta["dev.permdock/approval"]`, never from tool arguments) ([MCP adapter](https://permdock.com/docs/adapters/mcp)).
 
 An MCP server that is not an SDK `McpServer` cannot be wrapped: narrow the tool's `meta` with `isPermission`, filter its tool list with `mayUse(permdock, permission)` from `permdock`, and decide each call with `permdock.decide(permission, args)` in its `authorize` hook. `mayUse` is a listing hint, never a decision.
 
+When a tool's handler calls an oRPC procedure that runs `protect`, use `protectServer(server, { enforce: 'procedure', permissionFor: (name) => permissionOf(procedures.get(name)) })` with `permissionOf` from `permdock/orpc`. `tools/list` and annotations follow the permission; the call is not guarded, so each call decides once, in the procedure. `data` and `longRunning` throw in this mode, and the mode covers the whole server. When the same operations are REST routes, declare each permission once with `operationPermissions({ 'GET /customers/{id}': { permission, operationId } })` from `permdock/openapi` and pass `permissionFor: operations.forOperation`; the HTTP gate reads `operations.forRequest(method, path)` from the same object. When two operations share a permission but need different coarse scopes (reading an export with `mcp:read`, creating one with `mcp:write`), list the permission under both in `oauthScopes`, then narrow each operation with `oauthScopes: ['mcp:read']` on its entry (or on the tool config): pass `oauthScopesFor: operations.oauthScopesForOperation` to `protectServer`, and `operations` to `permdock/server` (or `protect`'s `oauthScopes`) for the REST routes, which then answer `insufficient_scope` naming that scope. A route that checks no permission but should still require a scope (a chat endpoint, setting the active organization) uses `protect(null, undefined, { oauthScopes: ['api:chat'] })` or an operation entry with only `oauthScopes`; never write an app-side rule that maps HTTP methods to scopes.
+
 ## A2A — `permdock/a2a`
 
 ```ts
@@ -151,7 +153,7 @@ app.post(
 );
 ```
 
-Identity comes from transport auth, never the task body. `actor.kind` is `'a2a'`, with `delegation` from the caller's token. Each skill's `securityRequirements` name the permission's `scope`. The public card is never filtered; `extendedAgentCard(auth)` keeps only skills the caller has a grant for. An instance-level skill without `data` throws at startup ([A2A adapter](https://permdock.dev/docs/adapters/a2a)).
+Identity comes from transport auth, never the task body. `actor.kind` is `'a2a'`, with `delegation` from the caller's token. Each skill's `securityRequirements` name the permission's `scope`. The public card is never filtered; `extendedAgentCard(auth)` keeps only skills the caller has a grant for. An instance-level skill without `data` throws at startup ([A2A adapter](https://permdock.com/docs/adapters/a2a)).
 
 ## WebMCP — `permdock/webmcp`
 
@@ -173,7 +175,7 @@ registerTools(document.modelContext, permissions.post, {
 });
 ```
 
-Never import a policy into this entry. A missing `document.modelContext` is a no-op. Tools re-register when the snapshot changes. The client check is a filter: the server adapter behind `api.posts` makes the decision. `onApprovalRequired` opens the page's own confirmation dialog ([WebMCP adapter](https://permdock.dev/docs/adapters/webmcp)).
+Never import a policy into this entry. A missing `document.modelContext` is a no-op. Tools re-register when the snapshot changes. The client check is a filter: the server adapter behind `api.posts` makes the decision. `onApprovalRequired` opens the page's own confirmation dialog ([WebMCP adapter](https://permdock.com/docs/adapters/webmcp)).
 
 ## Web Bot Auth on HTTP adapters
 
@@ -192,7 +194,7 @@ export const { permdock, protect } = createPermDock(policy, {
 });
 ```
 
-A verified RFC 9421 signer becomes the actor with `kind: 'web-bot-auth'`; `delegation` comes from a bearer token on the same request, otherwise it is empty. A failed signature throws `InvalidSignatureError`, never an anonymous actor ([Web Bot Auth](https://permdock.dev/docs/standards/web-bot-auth)).
+A verified RFC 9421 signer becomes the actor with `kind: 'web-bot-auth'`; `delegation` comes from a bearer token on the same request, otherwise it is empty. A failed signature throws `InvalidSignatureError`, never an anonymous actor ([Web Bot Auth](https://permdock.com/docs/standards/web-bot-auth)).
 
 ## Terminal — `permdock/terminal`
 
@@ -208,4 +210,4 @@ export const { permdock, protect, filterCommands, format, exitCode } =
   });
 ```
 
-For the app's own CLI; not the `permdock` binary. Never accept `--user` or `--actor` as identity. In CI, verify the job token with `subjectFromCiOidc(jwt, { provider: 'github', audience })` from `permdock/jwt`, which returns a `workload` principal, never a user. A `destructive` permission asks for the resource id to be typed, and exits `64` without a terminal unless `--yes` is passed; `--yes` never approves an `approval-required` call. `--dry-run` decides and exits with the outcome's code without running the action ([terminal adapter](https://permdock.dev/docs/adapters/terminal)).
+For the app's own CLI; not the `permdock` binary. Never accept `--user` or `--actor` as identity. In CI, verify the job token with `subjectFromCiOidc(jwt, { provider: 'github', audience })` from `permdock/jwt`, which returns a `workload` principal, never a user. A `destructive` permission asks for the resource id to be typed, and exits `64` without a terminal unless `--yes` is passed; `--yes` never approves an `approval-required` call. `--dry-run` decides and exits with the outcome's code without running the action ([terminal adapter](https://permdock.com/docs/adapters/terminal)).

package/skills/permdock-approvals/SKILL.md

@@ -4,13 +4,13 @@ description: Requires human approval on PermDock grants and resumes the approved
 license: MIT
 metadata:
   author: ScaleDockHQ
-  homepage: https://permdock.dev/docs/security/approvals
+  homepage: https://permdock.com/docs/security/approvals
   repository: https://github.com/ScaleDockHQ/permdock
 ---
 
 # PermDock approvals
 
-`approval-required` is the third outcome: the subject may do it, but a person other than the requester confirms each call. An approval never grants something the subject could not do, and a `deny` still wins ([approval security](https://permdock.dev/docs/security/approvals)). Set up the policy and factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
+`approval-required` is the third outcome: the subject may do it, but a person other than the requester confirms each call. An approval never grants something the subject could not do, and a `deny` still wins ([approval security](https://permdock.com/docs/security/approvals)). Set up the policy and factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
 
 ## Inputs (find out, or ask before starting)
 
@@ -61,7 +61,7 @@ metadata:
    ✓ `testApprovalPolicySource` from `permdock/testing` passes on the source.
 6. **Surface and resume.** Map the outcome to each runtime's approval hook and resume with the token: the `PermDock-Approval` header over HTTP, the runtime's own resume for agents. -> [references/stores-and-resume.md](references/stores-and-resume.md#surfaces)
    ✓ The approved call runs once; a second resume is denied with `approval-consumed`.
-7. **Test.** Add a scenario test per approval grant: the ask, an approval by an eligible user, a refused self-approval, and the single resume ([scenario testing](https://permdock.dev/docs/guides/scenario-testing)). Run `testApprovalStore` on a custom store.
+7. **Test.** Add a scenario test per approval grant: the ask, an approval by an eligible user, a refused self-approval, and the single resume ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). Run `testApprovalStore` on a custom store.
    ✓ The tests pass.
 
 ## Verify before done
@@ -77,4 +77,4 @@ metadata:
 ## Reference index
 
 - [references/stores-and-resume.md](references/stores-and-resume.md): `approvalsHandler` routes, custom stores, relation approvers, approval policies as data, the token, resume details and denial causes, the runtime surfaces table, delivery to chat and email.
-- Docs: [approval security](https://permdock.dev/docs/security/approvals), [approvals adapter](https://permdock.dev/docs/adapters/approvals), [wire formats](https://permdock.dev/docs/concepts/wire-formats).
+- Docs: [approval security](https://permdock.com/docs/security/approvals), [approvals adapter](https://permdock.com/docs/adapters/approvals), [wire formats](https://permdock.com/docs/concepts/wire-formats).

package/skills/permdock-approvals/references/stores-and-resume.md

@@ -1,6 +1,6 @@
 # Approval stores and the resume flow
 
-The API and the store contract are on the [approvals adapter](https://permdock.dev/docs/adapters/approvals); the token and the runtime table are on [approval security](https://permdock.dev/docs/security/approvals).
+The API and the store contract are on the [approvals adapter](https://permdock.com/docs/adapters/approvals); the token and the runtime table are on [approval security](https://permdock.com/docs/security/approvals).
 
 ## Store and handler
 
@@ -22,8 +22,11 @@ const handler = approvalsHandler(store, {
 app.all("/permdock/approvals/*", (c) => handler(c.req.raw));
 ```
 
-- `memoryApprovalStore` is per process. On serverless or with several replicas, implement `ApprovalStore` over the app's database; the Drizzle recipe on the adapter page is the template, and `cloud().approvals` from `permdock/cloud` is the hosted implementation of the same interface.
+The store's `ttl` is the window a request stays open when the call sets none; `resumeDecision({ ..., ttl })` sets it per call (milliseconds). A grant's `approval.ttl` only shortens either.
+
+- `memoryApprovalStore` is per process. On serverless or with several replicas, implement `ApprovalStore` over the app's database; the Drizzle recipe on the adapter page is the template, and `cloud().approvals` from `permdock/cloud` is the hosted implementation of the same interface. On Postgres or Supabase, set `rls.approvals: true` and use `supabaseApprovalStore(admin, { onOpen })` from `permdock/supabase` over the generated table and functions; grant the functions to the server's role, and put notifications and superseding older requests in `onOpen`.
 - A custom store calls `assertApprover(request, by, requireDistinct, now, verdict.relations)` in `resolve` and computes the next record with `applyApprovalVerdict`, which records each signature's `stage`. `verdict.relations` holds `approverRelationKey` values that the handler, or `resolveApproval(store, token, verdict, { relations, permissions })`, computed with `approverRelations`; a store never derives them. `consume` must be atomic: two concurrent calls never both succeed.
+- When the app's own rules decide who approves (a manager chain, delegates, a quorum it counts), record their verdict with `vouchApproval(store, token, { status, by, rule })` from `permdock/approvals` instead of mirroring those rules in `approvers` or copying the verdict into the request by hand. It resolves the request at once and records `vouched: rule`; the actor, requester and repeat checks still apply. Never take `vouched` from a request body.
 - Run `testApprovalStore(store, { reopen })` from `permdock/testing` on every custom store.
 - `cancelApprovals` rejects matching pending requests (for example when a session ends).
 
@@ -39,14 +42,16 @@ const permdock = await createPermDock(policy, user, {
       tenant: "o_acme", // absent: every tenant
       actors: ["agent"], // absent: every call
       where: { op: "gt", field: "amount", value: 1000 },
-      approval: { by: "finance" }, // no escalation in data
+      approval: { by: "finance" }, // an escalation here widens only this entry's stages
     },
   ]),
 });
 ```
 
+- Every adapter's `createPermDock` takes `approvalPolicies` (HTTP, MCP, A2A, AuthZEN, terminal and the agent adapters), so an entry also turns an agent call into `user-approval` or an MCP call into `approval-required`.
 - Entries are read once per instance and combine with the grant's own approval as stages (`sequential` if any part is, else `all`); the shortest `ttl` wins.
 - A throw or an invalid entry denies with detail `approval-policy-unavailable`. An unknown permission applies to nothing.
+- `where` reads the row, so it works only on instance permissions; on a collection permission the entry does not load. Use `check` (the proposed row) there. Validate entries where they are saved with `validateApprovalPolicy(policy, entry)` (`{ ok: false, problem }` names `unknown-permission`, `invalid`, `where-on-collection` or `stale-on-without-version`).
 - Client snapshots do not see the entries; the server's `decide` adds the approval.
 
 ## Resume
@@ -57,6 +62,8 @@ const permdock = await createPermDock(policy, user, {
 
 The token binds the permission key, the resource id (or a digest of the data when there is no id), the principal, the tenant, the actor and the matched grant's conditions. Under `staleOn: 'resource-change'` it also binds the row's `version`.
 
+A gate in your own code resumes the same way with `resumeDecision` from `permdock/approvals`, passing `token: carried ?? (await storedApprovalToken(store, decision))`: `storedApprovalToken` finds an approved or rejected request for the recomputed token, so the caller need not carry it. Do not reimplement it.
+
 Over HTTP, the client retries the same request with the `PermDock-Approval: <token>` header. In React, `approvalHeaders(token)` builds that header and `useApproval(decision)` requests and polls an approval from the UI.
 
 A bad resume is denied with detail `approval-not-found`, `approval-pending`, `approval-rejected`, `approval-expired`, `approval-consumed` or `approval-mismatch`; a changed row is `stale-approval`. `approvalsHandler` answers `403` for an ineligible approver (`approver-not-eligible`, the actor, or the principal without `distinct: false`) and `409` for a repeated one (`approver-repeated`).
@@ -80,4 +87,8 @@ For AG-UI event shapes, defer to the `ag-ui` spec skill (`npx skills add ScaleDo
 
 ## Delivery
 
-Notifying an approver is a listener on the `approval` event (`permdock.on('approval', …)`), never a package. A message or email carries only the token and links to a page where the approver signs in; the verdict goes through `approvalsHandler` with that session's subject. A link never approves on its own ([approvals adapter, Delivery](https://permdock.dev/docs/adapters/approvals#delivery)).
+Notifying an approver is a listener on the `approval` event (`permdock.on('approval', …)`), never a package. A message or email carries only the token and links to a page where the approver signs in; the verdict goes through `approvalsHandler` with that session's subject. A link never approves on its own ([approvals adapter, Delivery](https://permdock.com/docs/adapters/approvals#delivery)).
+
+## Approvers
+
+`by` takes roles, `user(id)`, `relation()`, `holder(permission)` and `anyOf(...)`. A list is all-of; use `anyOf(user(id), holder(permissions.x.approve))` for "this person or anyone who holds the permission". `holder()` needs `approvalsHandler(store, { permdockFor: (approver, request) => createPermDock(policy, approver, { customRoles }) })`, so custom roles count. Stages may carry their own `escalation`.

package/skills/permdock-audit/SKILL.md

@@ -4,7 +4,7 @@ description: Reviews an existing PermDock setup or a pull request that changes i
 license: MIT
 metadata:
   author: ScaleDockHQ
-  homepage: https://permdock.dev/docs/for-ai-agents
+  homepage: https://permdock.com/docs/for-ai-agents
   repository: https://github.com/ScaleDockHQ/permdock
 ---
 
@@ -42,7 +42,7 @@ Read the app's `permissions.ts`, `policy.ts`, factory file and every adapter gua
    ✓ Every item of every applicable Verify list has a pass or a finding.
 5. **Tests.** No `describePolicy` suite, or one with `exhaustive: false`, is a finding: a new permission can ship untested. A custom `ApprovalStore`, `DecisionSink`, `MembershipSource`, `RoleSource`, `SnapshotSource`, `LimitStore`, `RelationSource` or `DirectoryStore` without its `test<Interface>` runner from `permdock/testing` is a finding.
    ✓ Every policy and custom store has its runner, or a finding.
-6. **ASI02 and ASI03.** Map the inventory onto [OWASP Agentic](https://permdock.dev/docs/security/owasp-agentic); for the threat list itself, defer to the `owasp-agentic` spec skill (`npx skills add ScaleDockHQ/scaledock-skills --skill owasp-agentic`).
+6. **ASI02 and ASI03.** Map the inventory onto [OWASP Agentic](https://permdock.com/docs/security/owasp-agentic); for the threat list itself, defer to the `owasp-agentic` spec skill (`npx skills add ScaleDockHQ/scaledock-skills --skill owasp-agentic`).
    - **ASI02** (tool misuse): unmapped tools, a collection permission on a row handler, a destructive tool without `approval`, capability lists that include denied tools.
    - **ASI03** (identity and privilege abuse): a model-supplied subject or actor, an actor used as approver, `distinct: false` on a sensitive action, a resume token not bound to permission, resource, subject and actor, API keys stored in plain text or created outside `decideCredential`, keys without expiry (PD029), and a `memberships` source applied to service-key subjects.
      ✓ Each agent adapter in the app has an ASI02 line and an ASI03 line.
@@ -64,4 +64,4 @@ Read the app's `permissions.ts`, `policy.ts`, factory file and every adapter gua
 ## Reference index
 
 - Topic Verify lists: the `permdock-agents`, `permdock-approvals`, `permdock-tenancy`, `permdock-data` and `permdock-credentials` skills.
-- Docs: [OWASP Agentic mapping](https://permdock.dev/docs/security/owasp-agentic), [threat model](https://permdock.dev/docs/security/threat-model), [`permdock doctor`](https://permdock.dev/docs/cli/doctor), [`permdock usage`](https://permdock.dev/docs/cli/usage), [testing](https://permdock.dev/docs/adapters/testing).
+- Docs: [OWASP Agentic mapping](https://permdock.com/docs/security/owasp-agentic), [threat model](https://permdock.com/docs/security/threat-model), [`permdock doctor`](https://permdock.com/docs/cli/doctor), [`permdock usage`](https://permdock.com/docs/cli/usage), [testing](https://permdock.com/docs/adapters/testing).

package/skills/permdock-credentials/SKILL.md

@@ -4,13 +4,13 @@ description: Resolves PermDock subjects from access tokens, API keys and share l
 license: MIT
 metadata:
   author: ScaleDockHQ
-  homepage: https://permdock.dev/docs/concepts/authentication
+  homepage: https://permdock.com/docs/concepts/authentication
   repository: https://github.com/ScaleDockHQ/permdock
 ---
 
 # PermDock credentials
 
-Authentication is upstream: core never verifies a token. A `subjectFrom*` resolver verifies the material and hands core a `Subject`, and anything it cannot verify becomes the anonymous subject, never a throw ([authentication](https://permdock.dev/docs/concepts/authentication)). Set up the policy and factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
+Authentication is upstream: core never verifies a token. A `subjectFrom*` resolver verifies the material and hands core a `Subject`, and anything it cannot verify becomes the anonymous subject, never a throw ([authentication](https://permdock.com/docs/concepts/authentication)). Set up the policy and factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
 
 ## Inputs (find out, or ask before starting)
 
@@ -38,7 +38,7 @@ Authentication is upstream: core never verifies a token. A `subjectFrom*` resolv
    ✓ A revoked or expired key is anonymous, and a user key never exceeds its owner's current rights.
 4. **Share links, when the product has them.** Declare the link's roles on the resource, mint with `signCapability` behind a guard of its own, and resolve with `subjectFromCapability` and the tenant's `linkPolicy`. With Supabase RLS, exchange the link with `exchangeCapability` and generate with `--capabilities`. -> [references/tokens-keys-links.md](references/tokens-keys-links.md#share-links)
    ✓ An expired, revoked or replayed (`once`) link resolves to the anonymous subject.
-5. **Test.** Add scenario tests for each credential kind: a valid one, a forged or expired one, and a key or link used past its permissions ([scenario testing](https://permdock.dev/docs/guides/scenario-testing)). Run `permdock doctor`.
+5. **Test.** Add scenario tests for each credential kind: a valid one, a forged or expired one, and a key or link used past its permissions ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). Run `permdock doctor`.
    ✓ The tests pass and PD029 is clean.
 
 ## Verify before done
@@ -52,4 +52,4 @@ Authentication is upstream: core never verifies a token. A `subjectFrom*` resolv
 ## Reference index
 
 - [references/tokens-keys-links.md](references/tokens-keys-links.md): `subjectFromJwt` options, introspection, CI OIDC, `decideCredential`, key storage and resolution, tenant settings, `signCapability`, `subjectFromCapability`, `exchangeCapability`.
-- Docs: [authentication](https://permdock.dev/docs/concepts/authentication), [subject](https://permdock.dev/docs/concepts/subject), [JWT adapter](https://permdock.dev/docs/adapters/jwt), [API keys](https://permdock.dev/docs/concepts/credentials), [link capabilities](https://permdock.dev/docs/concepts/capabilities), [JOSE](https://permdock.dev/docs/standards/jose).
+- Docs: [authentication](https://permdock.com/docs/concepts/authentication), [subject](https://permdock.com/docs/concepts/subject), [JWT adapter](https://permdock.com/docs/adapters/jwt), [API keys](https://permdock.com/docs/concepts/credentials), [link capabilities](https://permdock.com/docs/concepts/capabilities), [JOSE](https://permdock.com/docs/standards/jose).

package/skills/permdock-credentials/references/tokens-keys-links.md

@@ -1,6 +1,6 @@
 # Tokens, API keys and share links
 
-Owning pages: [JWT adapter](https://permdock.dev/docs/adapters/jwt), [authentication](https://permdock.dev/docs/concepts/authentication), [API keys](https://permdock.dev/docs/concepts/credentials), [link capabilities](https://permdock.dev/docs/concepts/capabilities).
+Owning pages: [JWT adapter](https://permdock.com/docs/adapters/jwt), [authentication](https://permdock.com/docs/concepts/authentication), [API keys](https://permdock.com/docs/concepts/credentials), [link capabilities](https://permdock.com/docs/concepts/capabilities).
 
 ## Access tokens — `permdock/jwt`
 
@@ -18,6 +18,7 @@ const subject = await subjectFromJwt(token, {
 - `jose` is an optional peer. A failure is the anonymous subject, never a throw; the cause is reported through `on('auth')`. A claimed `act` chain that does not nest is anonymous with cause `invalid-chain`.
 - When the app already called RFC 7662 or RFC 9767 introspection, pass the response JSON to `subjectFromIntrospection`. `active` other than `true` is anonymous, and the HTTP call stays the app's.
 - In CI, `subjectFromCiOidc(jwt, { provider: 'github', audience })` returns a `workload` principal, never a user.
+- A Supabase OAuth server token is an `oauth-client` actor. `subjectFromSupabase` drops the OpenID Connect identity scopes (`openid`, `profile`, `email`, `address`, `phone`, `offline_access`) from its delegation, so a token with only those reaches nothing. Let a client act for users with a policy `delegations` entry whose `to` is `{ kind: 'oauth-client', client: '<name>' }`, and map the verified id to that name with `subjectFromSupabase(claims, { clients: { <name>: env.CLIENT_ID } })` (or a function for dynamically registered clients); a literal `{ kind, id }` also works but ties the policy to one environment, never by reading identity scopes as permissions ([Supabase provider](https://permdock.com/docs/adapters/supabase#oauth-server-tokens)).
 
 ## API keys and service accounts
 
@@ -49,7 +50,7 @@ if (decision.outcome === "granted") {
 ```
 
 - Guard the endpoint that creates keys with its own permission (`apiKey.create`).
-- Every key lists 1 to 64 permissions. A `user` key is its owner's live rights narrowed to the key; a `service` key is a `kind: 'service'` principal whose tenant, roles and permissions must be within the creator's `assignableRoles` / `assignablePermissions` (otherwise `exceeds-creator`). A key cannot mint keys.
+- Every key lists at least one permission, with no upper bound. A `user` key is its owner's live rights narrowed to the key, and with `tenant` to the owner's memberships inside that tenant and no global role (never put a tenant id in `ids`, which holds resource ids); a `service` key is a `kind: 'service'` principal whose tenant, roles and permissions must be within the creator's `assignableRoles` / `assignablePermissions` (otherwise `exceeds-creator`). A key cannot mint keys.
 - Tenant rules come from a `SettingsSource` (`memorySettings({ o_1: { credentials: { maxTtl, kinds, approval, allowNoExpiry } } })`). A key without `expiresAt` needs `allowNoExpiry`. `approval: true` makes creation `approval-required`; after approval, call `decideCredential` again with `approved: token`.
 - Store only `hashApiKey(key)`. The key is `pdk_<id>_<secret><checksum>`; `parseApiKey` rejects a bad checksum before any lookup.
 
@@ -72,6 +73,10 @@ const subject = await resolveKey(bearer, { tenant });
 
 Never pass a `memberships` source to `createPermDock` for a service-key subject: its one membership comes from the credential. `memoryCredentials()` is an in-process store for tests.
 
+When the backend then queries Postgres for the key, put the key's permission keys (and, for a service key, its tenant and roles) in an `api_key` claim and set `rls.apiKeys` in `permdock.config.ts`: the generated helpers cap every allow at the key's permissions and hold a key that names a tenant to that tenant, so RLS agrees with `can()`. The key itself never goes to the database.
+
+When the keys live in better-supabase's `api_keys` table, use `apiKeyVerifier({ keys, manifest, allPermissions })` from `permdock/better-supabase` instead, and create the keys with `createApiKeys({ transport, prefix: "pdk" })`: PermDock parses only its own prefix. A third-party token that better-supabase's `CredentialProvider` hands out goes through `credentialGuard(provider, { permdock, use, revoke? })` from the same entry, so PermDock decides each use.
+
 ## Share links
 
 ```ts