permdock 0.6.0 → 0.7.0

package/schemas/supabase-manifest-v1.json

@@ -7,13 +7,8 @@
   "required": [
     "$schema",
     "version",
-    "hook",
     "helpers",
     "tenantClaim",
-    "budget",
-    "claims",
-    "authzVersion",
-    "memberships",
     "rls",
     "decidingColumns",
     "markers"
@@ -22,14 +17,22 @@
     "$schema": {
       "const": "https://permdock.com/schemas/supabase-manifest-v1.json"
     },
-    "version": { "const": 1 },
+    "version": {
+      "const": 1
+    },
     "hook": {
       "type": "object",
       "required": ["schema", "function", "out"],
       "properties": {
-        "schema": { "$ref": "#/$defs/identifier" },
-        "function": { "const": "custom_access_token_hook" },
-        "out": { "type": "string" },
+        "schema": {
+          "$ref": "#/$defs/identifier"
+        },
+        "function": {
+          "const": "custom_access_token_hook"
+        },
+        "out": {
+          "type": "string"
+        },
         "schemas": {
           "enum": ["pg-delta", "migra", "migrations"],
           "description": "How the project turns SQL into migrations: pg-delta (supabase db schema declarative sync), migra (supabase db diff) or hand-written migrations. Absent means pg-delta."
@@ -47,20 +50,31 @@
       "type": "object",
       "required": ["schema", "functions"],
       "properties": {
-        "schema": { "$ref": "#/$defs/identifier" },
+        "schema": {
+          "$ref": "#/$defs/identifier"
+        },
         "functions": {
           "type": "array",
-          "items": { "$ref": "#/$defs/helperName" }
+          "items": {
+            "$ref": "#/$defs/helperName"
+          }
         }
       }
     },
-    "tenantClaim": { "$ref": "#/$defs/identifier" },
+    "tenantClaim": {
+      "$ref": "#/$defs/identifier"
+    },
     "budget": {
       "type": "object",
       "required": ["bytes", "measure"],
       "properties": {
-        "bytes": { "type": "integer", "minimum": 1 },
-        "measure": { "type": "string" }
+        "bytes": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "measure": {
+          "type": "string"
+        }
       }
     },
     "claims": {
@@ -69,28 +83,60 @@
         "type": "object",
         "required": ["name", "source", "budget"],
         "properties": {
-          "name": { "$ref": "#/$defs/identifier" },
+          "name": {
+            "$ref": "#/$defs/identifier"
+          },
           "source": {
             "type": "string",
             "pattern": "^(permdock|[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*)$"
           },
-          "budget": { "type": "boolean" }
+          "budget": {
+            "type": "boolean"
+          }
         }
       }
     },
-    "authzVersion": { "type": "boolean" },
+    "authzVersion": {
+      "type": "boolean"
+    },
+    "managementApi": {
+      "description": "The Management API fields that make a hosted project call the generated hook, as `permdock supabase inspect` prints and `--out` writes them.",
+      "type": "object",
+      "required": [
+        "hook_custom_access_token_enabled",
+        "hook_custom_access_token_uri",
+        "jwt_exp"
+      ],
+      "properties": {
+        "hook_custom_access_token_enabled": { "const": true },
+        "hook_custom_access_token_uri": { "type": "string" },
+        "jwt_exp": {
+          "description": "The access token lifetime in seconds: `[auth] jwt_expiry` of `supabase/config.toml`, or 3600 when it is unset.",
+          "type": "integer"
+        }
+      },
+      "additionalProperties": false
+    },
     "authzVersionBump": {
       "type": "object",
       "required": ["schema", "function", "args"],
       "properties": {
-        "schema": { "$ref": "#/$defs/identifier" },
-        "function": { "const": "permdock_bump_authz_version_for" },
-        "args": { "const": "p_users uuid[]" }
+        "schema": {
+          "$ref": "#/$defs/identifier"
+        },
+        "function": {
+          "const": "permdock_bump_authz_version_for"
+        },
+        "args": {
+          "const": "p_users uuid[]"
+        }
       }
     },
     "memberships": {
       "type": "array",
-      "items": { "$ref": "#/$defs/membership" }
+      "items": {
+        "$ref": "#/$defs/membership"
+      }
     },
     "rls": {
       "type": "object",
@@ -103,18 +149,32 @@
         "memberships"
       ],
       "properties": {
-        "schema": { "$ref": "#/$defs/identifier" },
-        "mode": { "enum": ["jwt", "database"] },
-        "tenantClaim": { "$ref": "#/$defs/identifier" },
+        "schema": {
+          "$ref": "#/$defs/identifier"
+        },
+        "mode": {
+          "enum": ["jwt", "database"]
+        },
+        "tenantClaim": {
+          "$ref": "#/$defs/identifier"
+        },
         "scopes": {
           "type": "array",
           "items": {
             "type": "object",
             "required": ["name", "type"],
             "properties": {
-              "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
-              "type": { "type": "string" },
-              "within": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_]*$"
+              },
+              "type": {
+                "type": "string"
+              },
+              "within": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_]*$"
+              }
             }
           }
         },
@@ -124,9 +184,15 @@
             "type": "object",
             "required": ["name", "args", "returns", "execute"],
             "properties": {
-              "name": { "$ref": "#/$defs/helperName" },
-              "args": { "type": "string" },
-              "returns": { "type": "string" },
+              "name": {
+                "$ref": "#/$defs/helperName"
+              },
+              "args": {
+                "type": "string"
+              },
+              "returns": {
+                "type": "string"
+              },
               "execute": {
                 "type": "array",
                 "items": {
@@ -138,23 +204,35 @@
         },
         "memberships": {
           "type": "array",
-          "items": { "$ref": "#/$defs/membership" }
+          "items": {
+            "$ref": "#/$defs/membership"
+          }
+        },
+        "customRoles": {
+          "type": "boolean"
         },
-        "customRoles": { "type": "boolean" },
         "roles": {
           "type": "object",
           "required": ["table", "user", "role"],
           "additionalProperties": false,
           "properties": {
-            "table": { "type": "string" },
-            "user": { "$ref": "#/$defs/column" },
+            "table": {
+              "type": "string"
+            },
+            "user": {
+              "$ref": "#/$defs/column"
+            },
             "role": {
               "oneOf": [
-                { "$ref": "#/$defs/role" },
+                {
+                  "$ref": "#/$defs/role"
+                },
                 {
                   "type": "array",
                   "minItems": 2,
-                  "items": { "$ref": "#/$defs/role" }
+                  "items": {
+                    "$ref": "#/$defs/role"
+                  }
                 }
               ]
             }
@@ -164,10 +242,14 @@
           "type": "object",
           "additionalProperties": false,
           "properties": {
-            "users": { "$ref": "#/$defs/activeRow" },
+            "users": {
+              "$ref": "#/$defs/activeRow"
+            },
             "scopes": {
               "type": "object",
-              "additionalProperties": { "$ref": "#/$defs/activeRow" }
+              "additionalProperties": {
+                "$ref": "#/$defs/activeRow"
+              }
             },
             "memberships": {
               "type": "object",
@@ -177,7 +259,9 @@
                 "keep": {
                   "description": "The permission keys a membership whose disabledAt column is set still holds.",
                   "type": "array",
-                  "items": { "type": "string" }
+                  "items": {
+                    "type": "string"
+                  }
                 }
               }
             }
@@ -188,19 +272,40 @@
           "required": ["tables"],
           "additionalProperties": false,
           "properties": {
-            "tables": { "type": "array", "items": { "type": "string" } }
+            "tables": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
           }
         },
+        "tokenScopes": {
+          "type": "boolean"
+        },
         "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" } }
+            "claim": {
+              "type": "string"
+            },
+            "scopes": {
+              "type": "string"
+            },
+            "tenant": {
+              "type": "string"
+            },
+            "roles": {
+              "type": "string"
+            },
+            "serviceRoles": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
           }
         }
       }
@@ -216,8 +321,12 @@
       "type": "object",
       "required": ["hook", "grants"],
       "properties": {
-        "hook": { "const": "v1" },
-        "grants": { "const": "v1" }
+        "hook": {
+          "const": "v1"
+        },
+        "grants": {
+          "const": "v1"
+        }
       }
     },
     "requires": {
@@ -250,22 +359,34 @@
           "type": "string",
           "pattern": "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$"
         },
-        "user": { "$ref": "#/$defs/user" },
-        "scope": { "$ref": "#/$defs/value" },
-        "id": { "$ref": "#/$defs/column" },
+        "user": {
+          "$ref": "#/$defs/user"
+        },
+        "scope": {
+          "$ref": "#/$defs/value"
+        },
+        "id": {
+          "$ref": "#/$defs/column"
+        },
         "role": {
           "oneOf": [
-            { "$ref": "#/$defs/role" },
+            {
+              "$ref": "#/$defs/role"
+            },
             {
               "type": "array",
               "minItems": 2,
-              "items": { "$ref": "#/$defs/role" }
+              "items": {
+                "$ref": "#/$defs/role"
+              }
             }
           ]
         },
         "within": {
           "oneOf": [
-            { "$ref": "#/$defs/column" },
+            {
+              "$ref": "#/$defs/column"
+            },
             {
               "type": "object",
               "required": ["columns"],
@@ -273,61 +394,128 @@
               "properties": {
                 "columns": {
                   "type": "object",
-                  "additionalProperties": { "$ref": "#/$defs/identifier" }
+                  "additionalProperties": {
+                    "$ref": "#/$defs/identifier"
+                  }
                 }
               }
             }
           ]
         },
-        "via": { "$ref": "#/$defs/value" },
-        "expiresAt": { "$ref": "#/$defs/column" },
-        "disabledAt": { "$ref": "#/$defs/column" },
+        "via": {
+          "$ref": "#/$defs/value"
+        },
+        "expiresAt": {
+          "$ref": "#/$defs/column"
+        },
+        "disabledAt": {
+          "$ref": "#/$defs/column"
+        },
         "columns": {
           "type": "array",
-          "items": { "$ref": "#/$defs/identifier" }
+          "items": {
+            "$ref": "#/$defs/identifier"
+          }
         }
       }
     },
-    "identifier": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "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" } },
+        "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" }
+          "items": {
+            "type": "string"
+          }
         }
       }
     },
     "helperName": {
       "type": "string",
-      "pattern": "^(permdock_has(_for)?|permitted_[a-z][a-z0-9_]*_(ids|permission_keys)(_for)?|permitted_[a-z][a-z0-9_]*_users|member_[a-z][a-z0-9_]*_ids(_for)?|permdock_can_assign(_any|_custom_role)?(_for)?|permdock_api_key_allows|permdock_actor_may_write|permdock_is_approver|permdock_user_id)$"
+      "pattern": "^(permdock_has(_for)?|permitted_[a-z][a-z0-9_]*_(ids|permission_keys)(_for)?|permitted_[a-z][a-z0-9_]*_users|member_[a-z][a-z0-9_]*_ids(_for)?|permdock_can_assign(_any|_custom_role)?(_for)?|permdock_api_key_allows|permdock_token_scope_allows|permdock_actor_may_write|permdock_is_approver|permdock_user_id)$"
     },
     "column": {
       "type": "object",
       "required": ["column"],
       "additionalProperties": false,
-      "properties": { "column": { "$ref": "#/$defs/identifier" } }
+      "properties": {
+        "column": {
+          "$ref": "#/$defs/identifier"
+        }
+      }
     },
     "role": {
-      "oneOf": [{ "$ref": "#/$defs/value" }, { "$ref": "#/$defs/through" }]
+      "oneOf": [
+        {
+          "$ref": "#/$defs/value"
+        },
+        {
+          "$ref": "#/$defs/through"
+        },
+        {
+          "$ref": "#/$defs/mapped"
+        }
+      ]
+    },
+    "mapped": {
+      "type": "object",
+      "required": ["column", "map"],
+      "additionalProperties": false,
+      "properties": {
+        "column": {
+          "$ref": "#/$defs/identifier"
+        },
+        "map": {
+          "type": "object",
+          "additionalProperties": {
+            "type": ["string", "null"]
+          }
+        }
+      }
     },
     "user": {
-      "oneOf": [{ "$ref": "#/$defs/column" }, { "$ref": "#/$defs/through" }]
+      "oneOf": [
+        {
+          "$ref": "#/$defs/column"
+        },
+        {
+          "$ref": "#/$defs/through"
+        }
+      ]
     },
     "through": {
       "type": "object",
       "required": ["column", "through"],
       "additionalProperties": false,
       "properties": {
-        "column": { "$ref": "#/$defs/identifier" },
+        "column": {
+          "$ref": "#/$defs/identifier"
+        },
         "through": {
           "type": "object",
           "required": ["table", "id", "column"],
@@ -337,15 +525,21 @@
               "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" }
+            "id": {
+              "$ref": "#/$defs/identifier"
+            },
+            "column": {
+              "$ref": "#/$defs/identifier"
+            }
           }
         }
       }
     },
     "value": {
       "oneOf": [
-        { "$ref": "#/$defs/column" },
+        {
+          "$ref": "#/$defs/column"
+        },
         {
           "type": "object",
           "required": ["value"],
@@ -353,8 +547,15 @@
           "properties": {
             "value": {
               "oneOf": [
-                { "type": "string" },
-                { "type": "array", "items": { "type": "string" } }
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
               ]
             }
           }

package/skills/permdock/SKILL.md

@@ -49,6 +49,7 @@ PermDock is typed permissions for TypeScript apps, APIs, databases and AI agents
 2. **Look identifiers up, never guess them.** Read the owning page through the docs MCP (`https://permdock.com/docs/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.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`).
+   For ids without loaded rows, `await permdock.decideIds(permission, ids, { data })` loads them through `data(ids)` and decides each in its own tenant.
    ✓ 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.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.

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

@@ -30,6 +30,8 @@ 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.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).
 
+To let the user fix a denial in the loop, pass `stepUp: { at: "https://app.example.com/reauth" }` (`at` optional). An `insufficient-user-authentication` denial, or one that activating a role the user is `eligible` for would grant, then becomes `{ type: 'user-approval', reason, stepUp }`. `stepUp` is `{ kind: 'authentication', acrValues, maxAge }` or `{ kind: 'activation', role, scope, id }`. For an activation, call `activate(permdock, { role, scope, id, reason })` and write `decision.elevation`. The SDK's re-check decides again and runs the tool only when `granted`. Never build a `withStepUp` wrapper. A step-up status has no `token`, so narrow with `'token' in status` before reading it.
+
 ## Claude Agent SDK — `permdock/claude-agent`
 
 ```ts
@@ -117,7 +119,7 @@ server.registerTool(
 );
 ```
 
-`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)).
+`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`, except an MCP Apps `ui://` view: it takes the permission of the tool whose `_meta.ui.resourceUri` names it, and a view no tool links is refused. Never give a view a looser permission than its tool. 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 `permdock.mayUse(permission)`, and decide each call with `permdock.decide(permission, args)` in its `authorize` hook. `mayUse` is a listing hint, never a decision.
 

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

@@ -31,7 +31,8 @@ The store's `ttl` is the window a request stays open when the call sets none; `r
 - `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.
+- Run `testApprovalStore(store, { reopen, capabilities: { expire } })` from `permdock/testing` on every custom store. `reopen` opens a second client over the same backend; `expire(token)` ages one record so the suite checks that a new ask replaces it.
+- `create` replaces a record only when its `status` is `expired` or its `expiresAt` has passed. A pending or resolved record stays, and nothing returns to `pending`.
 - `cancelApprovals` rejects matching pending requests (for example when a session ends).
 
 ## Approval policies as data

package/skills/permdock-data/references/queries-and-rls.md

@@ -38,14 +38,17 @@ pnpm exec permdock rls verify --introspect
 - List the scope instances a permission reaches in process with `permdock.permittedIds(permission, scope, { within })`, never a loop of `can` over memberships with a made-up row.
 - Generated policies call `permdock_has('<key>')` and one `permitted_<scope>_ids('<key>')` per declared scope, which Postgres runs once per statement. Hand-written policies that only need membership (an organization switcher) call `member_<scope>_ids()` instead of inventing a permission key. Trusted SQL that acts for a stored user (a job, a trigger, a deferred approval) calls `permdock_has_for(p_user, '<key>')` and `permitted_<scope>_ids_for(p_user, '<key>')` in `database` mode, or the generated `permitted_<resource>_rows_for`, never a hand-written function that rewrites `request.jwt.claims`. With `rls.rowHelpers`, a hand-written policy or function that needs the rows a permission reaches through the graph calls `permitted_<resource>_rows('<permission key>')` instead of restating closure walks, link hops and `includes`. A table's own `select` or `insert` policy calls the row-valued `permitted_<resource>_row(<table>, '<permission key>')` instead, so `insert ... returning` sees the new row. Hand-written policies and functions that apply no row condition call `permitted_<scope>_ids_by_permission('<permission key>')` or `permdock_has_permission('<permission key>')` instead of spelling a positional `#n` grant key. A screen or RPC that checks many permissions on one organization calls `permitted_<scope>_permission_keys(<id>)` once (or `(<id>, array['<key>', ...])` for a few keys) instead of one helper call per key. A role editor or admin screen lists a role's keys with `permdock_role_permissions(p_role, p_scope, p_tenant, p_scope_id)` (declared roles, and custom roles of the caller's tenant in `database` mode) and the catalog with `permdock_permission_keys()` (`permdock_permission_keys('<scope>')` for the keys a role on that scope can hold), instead of joining `role_permissions` and the custom-role tables by hand; server code reads any tenant's roles with `permdock_trusted_role_permissions`, granted through `rls.trustedReaders`. Set `--tenant-type` (or `rls.tenantType`, `rls.scopeTypes`) to the scope columns' types.
 - `--authorize database` (default) reads the membership tables per statement; map each under `rls.memberships.scopes.<scope>` with `columns` for its id and its ancestors', and `via` so roles with `for` apply: a column name, or `{ value: 'staff' }` when every row has that kind (never add a generated column for it). `--authorize jwt` reads token claims and stays stale until the token refreshes; keep the token lifetime at 3600 seconds or less (PD019).
+- When the role column holds values that are not role keys, give the membership source `role: { column, map: { value: 'role' } }`; a value mapped to `null` grants nothing. `permdock rls explain` prints the tables, membership sources, custom roles table and triggers a generate run binds to, without writing a file. `rls.seeds: 'function'` writes the `role_permissions` rows as `<schema>.seed()` instead of inserts; run `select <schema>.seed();` after each deploy, and PD054 checks the function body.
+- `permdock rls verify --kind pgtap` writes `supabase/tests/permdock_rls.test.sql` (or `--out`) and, in `database` mode, inserts each fixture's memberships before it switches role.
 - The helpers narrow to the tenant claim (`rls.tenantClaim`) whenever the token carries one; the Supabase hook writes it from `activeFrom`. When the app takes the tenant from the URL and one session spans tenants, set `rls.tenants: 'all'` so the database admits every member tenant, and keep filtering each query by the URL's tenant.
 - `--policy-per-role` keeps one policy per role for review. `--custom-roles` (or `rls.customRoles: true`) resolves tenant-defined roles inside the `permdock_ceiling` view. In `database` mode, save a custom role with `permdock_replace_custom_role_grants(tenant, scope, scope_id, role, allow, deny, include)` and rename or delete it with `permdock_rename_custom_role_grants` and `permdock_delete_custom_role_grants`, never with hand-written `security definer` functions or direct writes; failures raise `22023` or `42501` with the reason as the `hint`. A platform custom role passes a null tenant and scope `global`; a shared custom role passes a null tenant and scope id at its scope. Seeds, jobs and backends with no member caller use the `permdock_trusted_*` variants, which keep the definition checks; grant `execute` on them to a backend role in a migration of your own, never to `authenticated`. Set `rls.customRoleWrites.requires` to the permission your role editor asserts (or `'manageRoles'`) so the database refuses members who may not manage roles (`manage-roles`).
 - `--force` (or `rls.force: true`) only when the app connects as the table owner. Create views over RLS tables `with (security_invoker = true)` (PD022).
-- When read grants set `fields` and clients read tables directly, add `--fields views --revoke-columns`: clients read `<table>_visible`, whose restricted columns are null unless a grant covers them. PD030 names columns still readable.
+- When read grants set `fields` and clients read tables directly, add `--fields views --revoke-columns`: clients read `<table>_visible`, whose restricted columns are null unless a grant covers them. PD030 names columns still readable. When a `security definer` RPC or other owner-rights SQL returns those rows, use `--fields mask` and select through `cross join lateral permdock.<table>_mask(t) m`, never a hand-written `case` per column.
 - `rls.suspension` drops suspended users' roles and memberships of suspended scope instances, live in both modes. `scopes.<scope>.keep: [permissions.org.restore]` lets members of a suspended instance still hold those permissions (restore, cancel deletion, export) in the helpers, `authorize()`, the token hook and in process, where the membership carries `keep`; `doctor` PD061 lists them.
 - When support or impersonation tokens (an `act` claim) reach the Data API, set `rls.readOnlyActors: true`: each table and write command the policies grant gets a restrictive `{table}_{op}_read_only_actors` policy that refuses the write unless `act.read_only` is `false`. Never hand-write that policy per table. With `--helpers-only`, every hand-written insert, update and delete policy calls `(select permdock.permdock_actor_may_write())`, and `rls verify --introspect` names the ones that do not.
 - To list who holds a permission in one organization (notification fan-out, an approver list), server SQL calls `permitted_<scope>_users('<permission key>', <id>)` in `database` mode, never a hand-written join of memberships and `role_permissions`. No client role may execute it; grant it to the backend's Postgres role.
 - When a backend queries Postgres for a verified API key, set `rls.apiKeys` and put the key in the `api_key` claim (`scopes` as permission keys, `tenant` and `roles` for a key that belongs to a tenant): the helpers cap every allow at the scopes and treat a tenant key without `sub` as a service principal of that tenant. A user key whose claim names a `tenant` is held to that tenant even with `rls.tenants: 'all'`, and `permdock_has` is false for it. Never write a `has_scope` check per policy.
+- When OAuth clients, MCP clients or agents (a `client_id` or an agent `act` claim) reach the Data API, set `rls.tokenScopes: true`: the helpers and helper-free allows then pass a grant only when the token's `scope` claim reaches its permission, through the same map better-supabase's `delegation.scopes` reads. A policy delegation does not compile into SQL, so such a client needs permission scopes or `oauthScopes` in its token. Never hand-write a scope check per policy.
 - On Supabase every generated helper and policy reads the subject through `permdock_user_id()`: the `sub` in `request.jwt.claims`, and null for the empty `sub` of a tenant service key. It ignores the legacy `request.jwt.claim.sub` setting; SQL that impersonates a user sets `request.jwt.claims`. A hand-written policy such a token reaches calls `(select permdock.permdock_user_id())`, never `auth.uid()`, which fails the uuid cast.
 - `rls.assignments` puts a `permdock_assignment` trigger on each mapped membership table, the global-roles table `rls.roles` and each table in `tables`; `ownRole: 'refuse'` (or a map of tables) also refuses a client write to the caller's own row. `doctor` PD064 names a guarded table no migration puts the trigger on.
 - SQL that assigns roles calls `permdock_can_assign_any(role, tenant, scope, scope_id)`, which covers declared and custom roles; SQL acting later for a stored user (an invitation accept re-checking the inviter) calls `permdock_can_assign_any_for(user, ...)`. `permdock supabase inspect` lists both in the manifest's `rls.helpers`.

package/skills/permdock-tenancy/SKILL.md

@@ -60,7 +60,7 @@ A policy declares its scopes in order (an organization, the customers inside it)
 3. **Load memberships.** Return memberships as `{ scope, id, within, roles, via, expiresAt }` from the subject resolver, or pass a `MembershipSource` (one, or an array) as `memberships` on `createPermDock`. A person's access ending is the membership's `expiresAt`.
    ✓ `permdock doctor` reports no PD025 for the `doctor.memberships` fixture.
 
-   An organisation role that reaches only the principal's teams is an organisation role with `where: { team_id: { in: principal.claims.team_ids } }`, not a team role. On Supabase, write the claim with `supabase.hook.claims` ([team reach](https://permdock.com/docs/concepts/tenancy#organisation-roles-with-team-reach)).
+   An organisation role that reaches only the principal's teams is an organisation role with `where: { team_id: { in: claim("team_ids") } }` (`claim` from `permdock` is `principal.claims.team_ids`, typed under `noUncheckedIndexedAccess`), not a team role. On Supabase, write the claim with `supabase.hook.claims` ([team reach](https://permdock.com/docs/concepts/tenancy#organisation-roles-with-team-reach)).
 
 4. **Put ownership on the roles.** Set `min: 1` on the role that manages each scope, `assigns` for who hands out what, `for: ['staff']` on admin-like roles, and `meta.audience` for the surface. Every server action that changes a membership calls `decideRoleChange(permdock, ...)` with the target's current membership and the holder count before it writes. -> [references/ownership-and-custom-roles.md](references/ownership-and-custom-roles.md)
    ✓ PD026 is clean, and removing the last owner is denied with `last-holder`.