permdock 0.3.1 → 0.5.0

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

@@ -5,14 +5,19 @@ Owning pages: [JWT adapter](https://permdock.com/docs/adapters/jwt), [authentica
 ## Access tokens — `permdock/jwt`
 
 ```ts
-import { subjectFromJwt } from "permdock/jwt";
+import { jwtSubjectResolver } from "permdock/jwt";
 
-const subject = await subjectFromJwt(token, {
+// One resolver per issuer for the life of the process: it caches Discovery and the JWKS.
+const resolve = jwtSubjectResolver({
   discovery: "https://issuer.example.com",
   audience: "https://api.example.com",
 });
+
+const subject = await resolve(token, request);
 ```
 
+`subjectFromJwt(token, options)` takes the same options but builds a new verifier per call, so each call fetches Discovery and the JWKS again. Use it for a one-off check such as a CLI or a test.
+
 - Prefer `discovery: '<issuer>'` over a hand-copied `jwks` URL. Set `audience` to the resource identifier. Write algorithms as `Ed25519`, `ES256` or `PS256`; never `EdDSA`, `none` or `RSA1_5`.
 - Keep the default `accept: 'access-token'`, so an ID token never authorises an API call.
 - `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`.
@@ -34,7 +39,9 @@ const decision = await decideCredential(
     tenant: "o_1",
     roles: ["developer"],
     permissions: [permissions.repo.read],
-    expiresAt: Math.floor(Date.now() / 1000) + 30 * 86_400,
+    expiresAt: Temporal.Now.instant()
+      .add({ hours: 30 * 24 })
+      .toString(), // RFC 3339
   },
   { settings },
 );
@@ -51,27 +58,28 @@ if (decision.outcome === "granted") {
 
 - Guard the endpoint that creates keys with its own permission (`apiKey.create`).
 - 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`.
+- Tenant rules come from a `SettingsSource` (`memorySettingsSource({ 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.
+- A feed is `kind: 'feed'` with `on: { resource, id }`, `roles` and `permissions`. `generateFeedKey` returns `pdfeed_<id>_<secret><checksum>`, all lowercase. `expiresAt` is optional. `subjectFromApiKey(key, { kinds: ['feed'] })` accepts feed keys only. A feed cannot approve or create a key. See [feeds](https://permdock.com/docs/concepts/credentials#feeds).
 
 Resolve keys on each request:
 
 ```ts
 import { apiKeyVerifier, subjectFromApiKey } from "permdock/server";
 
-const resolveKey = subjectFromApiKey({
+const keys = {
   verifier: apiKeyVerifier({ find: (id) => findKeyRow(id) }), // returns { credential, hash }
   permissions,
-  owner: (id) => loadOwner(id), // the live owner of a user key
+  principals, // a PrincipalSource: the live owner of a user key
   revoked: (id) => isRevoked(id),
   settings,
   sink,
-});
+};
 
-const subject = await resolveKey(bearer, { tenant });
+const subject = await subjectFromApiKey(bearer, { ...keys, 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.
+Never pass a `memberships` source to `createPermDock` for a service-key subject: its one membership comes from the credential. `memoryCredentialStore()` 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.
 
@@ -114,7 +122,8 @@ const subject = await subjectFromCapability(token, {
 
 - The result is a `kind: 'link'` principal with one `{ on, roles, via: 'link' }` membership. It never holds a scope or global role.
 - `linkPolicy` returns the tenant's `LinkPolicy` (`maxLifetime`, `redeemers`, `once`). Passing the same policy to `signCapability` refuses to mint a link the resolver would refuse.
-- Never an unguessable id without expiry, and never a security-definer RPC for the guest page.
+- Never an unguessable id without expiry, and never a security-definer RPC that reads the guest page's rows.
+- The one exception is resolving a stored link. When links live in better-supabase's share-links block, its `resolve_share_link` is `security definer` and reads only the link table. `subjectFromShareLink(token, { shareLinks, links, ttl })` from `permdock/better-supabase` turns the row into the same link subject. The page's rows are then read through `exchangeCapability` and RLS, as for a signed link. `links` maps each `subjectType` to a resource and maps the row's role to PermDock roles. An unmapped type or role, and a revoked or expired row, are anonymous. A link pinned to a version is refused, because a capability reads the current rows; read it through better-supabase's `versions.getShared(token)`. See [row-backed links](https://permdock.com/docs/concepts/capabilities#row-backed-links).
 
 With Supabase, let RLS serve the link through an exchange, never the link token itself:
 

package/skills/permdock-data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: permdock-data
-description: Enforces PermDock permissions in database queries and Postgres row-level security. Use when listing rows with permdock.where() and filter(), compiling conditions with toWhere from permdock/drizzle, permdock/prisma or permdock/kysely, guarding Convex functions with permdock/convex, generating or verifying RLS with permdock rls generate, verify or migrate, modelling folders, sub-teams or reporting lines with parent and relation() through a RelationSource, loadRelations or whoCan, or proving query and database parity with ormParity and rlsParity. Also for doctor PD027, PD028, PD031 and PD032.
+description: Enforces PermDock permissions in database queries and Postgres row-level security. Use when listing rows with permdock.where() and filter(), compiling conditions with toWhere from permdock/drizzle, permdock/prisma or permdock/kysely, guarding Convex functions with permdock/convex, generating or verifying RLS with permdock rls generate, verify or migrate, modelling folders, sub-teams or reporting lines with parent and relation() through a RelationSource, prefetchRelations or whoCan, or proving query and database parity with testOrmParity and testRlsParity. Also for doctor PD027, PD028, PD031 and PD032.
 license: MIT
 metadata:
   author: ScaleDockHQ
@@ -32,13 +32,13 @@ The same portable conditions decide `can()` in memory, narrow list queries throu
 
 1. **Narrow list queries.** Compile `permdock.where(permission)` with the ORM's `toWhere`, then run `filter` and `pick` on the rows. -> [references/queries-and-rls.md](references/queries-and-rls.md)
    ✓ A user with no grant gets an empty list, and the query compiles without `non-portable-condition`.
-2. **Model hierarchies, when the product has them.** Give the resource a `parent`, declare the relations principals hold, add `restricted` where rows must not inherit, and grant with `relation(resource, name, { through: 'parent' })`. Pass a `RelationSource` as `relations` and call `loadRelations` before `can` / `filter` when it is async. Use `whoCan` for share dialogs. -> [references/relationships.md](references/relationships.md)
+2. **Model hierarchies, when the product has them.** Give the resource a `parent`, declare the relations principals hold, add `restricted` where rows must not inherit, and grant with `relation(resource, name, { through: 'parent' })`. Pass a `RelationSource` as `relations` and call `prefetchRelations` before `can` / `filter` when it is async. Use `whoCan` for share dialogs. -> [references/relationships.md](references/relationships.md)
    ✓ `permdock doctor --only graph` is clean, and a viewer of a parent folder can read a child document.
 3. **Generate or adopt RLS.** Run `permdock rls generate` from the policy, or keep SQL as the authority with `sqlFunction` twins and `rls.functions`, or move hand-written helpers with `permdock rls migrate`. -> [references/queries-and-rls.md](references/queries-and-rls.md#generate-and-verify-rls)
    ✓ `permdock rls generate --check` passes in CI.
-4. **Verify against a real database.** Run `permdock rls verify --db $DATABASE_URL` with fixtures, `--tree` for graph grants, and `--introspect` against a deployed database.
+4. **Verify against a real database.** Run `permdock rls verify` with fixtures, `--tree` for graph grants, and `--introspect` against a deployed database.
    ✓ Every verify run exits `0`.
-5. **Prove parity in tests.** Add `ormParity(policy, scenarios, { run, id })` for each list endpoint and `rlsParity(policy, options)` for RLS tables, from `permdock/testing` ([testing adapter](https://permdock.com/docs/adapters/testing)). Run `testRelationSource` on a custom `RelationSource`.
+5. **Prove parity in tests.** Add `testOrmParity(policy, scenarios, { run, id })` for each list endpoint and `testRlsParity(policy, options)` for RLS tables, from `permdock/testing` ([testing adapter](https://permdock.com/docs/adapters/testing)). Run `testRelationSource` on a custom `RelationSource`.
    ✓ The query and the database return exactly the rows `filter()` keeps.
 
 ## Verify before done
@@ -48,10 +48,10 @@ The same portable conditions decide `can()` in memory, narrow list queries throu
 - [ ] No `opaque` RLS grant wraps a named helper; use `sqlFunction` with a twin and map it in `rls.functions`.
 - [ ] No condition the database must enforce reads `context.*` (PD027); on Supabase, `supabase.hook.attrs` lists only server-owned values (PD028).
 - [ ] Graph declarations are walked by a grant (PD031) and nameable in SQL (PD032).
-- [ ] Every list endpoint has an `ormParity` run, every RLS table an `rlsParity` or `rls verify --db` run, and a custom `RelationSource` passes `testRelationSource`.
+- [ ] Every list endpoint has an `testOrmParity` run, every RLS table an `testRlsParity` or `rls verify --db-url-stdin` run, and a custom `RelationSource` passes `testRelationSource`.
 
 ## Reference index
 
 - [references/queries-and-rls.md](references/queries-and-rls.md): `toWhere` per ORM, `checkRow`, `withSubject`, Convex, `rls generate` / `import` / `verify` / `migrate` flags and config, field views, SQL as the authority.
-- [references/relationships.md](references/relationships.md): `parent`, relation kinds, `restricted`, `links`, `relation(..., { through })`, `RelationSource`, `loadRelations`, `whoCan`, the closure table and `--tree`.
+- [references/relationships.md](references/relationships.md): `parent`, relation kinds, `restricted`, `links`, `relation(..., { through })`, `RelationSource`, `prefetchRelations`, `whoCan`, the closure table and `--tree`.
 - Docs: [conditions](https://permdock.com/docs/concepts/conditions), [relationships](https://permdock.com/docs/concepts/relationships), [RLS adapter](https://permdock.com/docs/adapters/rls), [`permdock rls`](https://permdock.com/docs/cli/rls), [Postgres RLS](https://permdock.com/docs/standards/postgres-rls).

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

@@ -31,11 +31,11 @@ pnpm exec permdock rls generate --target sql --dialect supabase --out migrations
 pnpm exec permdock rls generate --target drizzle --dialect supabase
 pnpm exec permdock rls import --sql migrations/rls.sql --out src/permissions.generated.ts
 pnpm exec permdock rls verify --fixtures rls.fixtures.json
-pnpm exec permdock rls verify --db $DATABASE_URL --fixtures rls.fixtures.json
-pnpm exec permdock rls verify --introspect --db $DATABASE_URL
+printf %s "$DATABASE_URL" | pnpm exec permdock rls verify --db-url-stdin --fixtures rls.fixtures.json
+pnpm exec permdock rls verify --introspect
 ```
 
-- List the scope instances a permission reaches in process with `permittedIds(permdock, permission, scope, { within })`, never a loop of `can` over memberships with a made-up row.
+- 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).
 - 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.
@@ -43,20 +43,25 @@ pnpm exec permdock rls verify --introspect --db $DATABASE_URL
 - `--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.
 - `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.
+- 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.
 - 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`.
-- Index suggestions (the `indexes` part of `--split`, or `index suggestion` warnings) cover only the columns the policies and helpers look rows up by. Add `--db $DATABASE_URL` to `generate` so it leaves out indexes an existing index already leads with and columns the table lacks; never hand-copy a suggestion that duplicates an existing composite index.
+- Index suggestions (the `indexes` part of `--split`, or `index suggestion` warnings) cover only the columns the policies and helpers look rows up by. Pipe the URL to `generate --db-url-stdin` so it leaves out indexes an existing index already leads with and columns the table lacks; never hand-copy a suggestion that duplicates an existing composite index.
 - Never emit `service_role`. Fixtures may carry `memberships`, `tenant` and `customRoles`.
 
 ## SQL as the authority
 
-When the database already holds the rules, skip `generate`. Map each helper in `rls.functions`, write `sqlFunction` twins in the policy, and fail CI on `rls verify --db`. `--inline-functions` inlines the twin for targets that cannot call a SQL function.
+When the database already holds the rules, skip `generate`. Map each helper in `rls.functions`, write `sqlFunction` twins in the policy, and fail CI on `rls verify --db-url-stdin`. `--inline-functions` inlines the twin for targets that cannot call a SQL function.
 
-When hand-written policies call the app's own helpers (`org_ids_with_permission`, `has_org_permission`), map each under `rls.migrate.helpers` with its `form` (`ids`, `row`, `scoped`, `global`, `membership`) and the legacy keys under `rls.migrate.keys` or `prefixes`. Run `permdock rls migrate`, read the skipped calls, and apply with `--write`. Generate with `--helpers-only` while the policies stay hand-written. A `row-conditions` skip means that table's policy should be generated, not migrated.
+When hand-written policies call the app's own helpers (`org_ids_with_permission`, `has_org_permission`), map each under `rls.migrate.helpers` with its `form` (`ids`, `row`, `scoped`, `global`, `membership`) and the legacy keys under `rls.migrate.keys` or `prefixes`. Run `permdock rls migrate --dry-run`, read the skipped calls, and apply by running it without `--dry-run`. Generate with `--helpers-only` while the policies stay hand-written. A `row-conditions` skip means that table's policy should be generated, not migrated.
+
+When the old helpers read a permissions table that triggers keep in step (`user_permissions`), list it under `rls.migrate.tables`. `permdock rls migrate` then reports its refresh triggers and every policy, view or function that still reads it, and `permdock doctor` reports PD066 while the migrations still create it. Rewrite each reader, then run `permdock rls migrate --retire-out <migrations dir>/`, which exits `1` and writes nothing while a reader remains. Never hand-write the drop with `cascade` ([retire a materialised table](https://permdock.com/docs/cli/rls#retire-a-materialised-table)).
+
+Triggers the app owns on generated tables (an audit trigger, a notification) go in `rls.triggers` or `rls.audit`, so they live in the generated files; never in a migration that patches the generated tables afterwards ([triggers and audit](https://permdock.com/docs/cli/rls#triggers-and-audit)).
 
 ## Attributes RLS cannot see
 
-A grant condition on `context.*` cannot be enforced by the database (PD027). Compare with a server-set `principal.claims.*` claim instead, never one from `user_metadata`. On Supabase, `supabase.hook.attrs` lists only server-owned columns or `app_metadata.<key>` entries clients cannot update (PD028). A check that must refuse a sign-in (single sign-on enforcement, a locked account) goes in `supabase.hook.before` as a schema-qualified `(event jsonb) returns jsonb` function the generated hook calls first; never a second hook or a hand edit of the generated one. The hook, declarative schemas (`--split`) and `fromTable` / `fromJunction` membership sources are on the [Supabase adapter](https://permdock.com/docs/adapters/supabase) and [Supabase hook](https://permdock.com/docs/adapters/supabase-hook) pages.
+A grant condition on `context.*` cannot be enforced by the database (PD027). Compare with a server-set `principal.claims.*` claim instead, never one from `user_metadata`. On Supabase, `supabase.hook.attrs` lists only server-owned columns or `app_metadata.<key>` entries clients cannot update (PD028). A check that must refuse a sign-in (single sign-on enforcement, a locked account) goes in `supabase.hook.before` as a schema-qualified `(event jsonb) returns jsonb` function the generated hook calls first; never a second hook or a hand edit of the generated one. Declarative schemas (`--split`) default to pg-delta (Declarative Schemas 2.0); `supabase.schemas: 'migra'` or `'migrations'` opts out ([schema workflow](https://permdock.com/docs/cli/rls#schema-workflow)). The hook, declarative schemas and `tableMembershipSource` / `junctionMembershipSource` membership sources are on the [Supabase adapter](https://permdock.com/docs/adapters/supabase) and [Supabase hook](https://permdock.com/docs/adapters/supabase-hook) pages.

package/skills/permdock-data/references/relationships.md

@@ -49,18 +49,18 @@ Add `requires: permissions.file.read` to a graph grant to count a share only whe
 
 ## Load
 
-Pass `relations: memoryRelations(permissions, { rows, edges })` in tests, or a `RelationSource` (`ancestors`, `related`) over the app's tables, to `createPermDock`. Evaluation stays synchronous; with an async source, call `await permdock.loadRelations(permission, rows)` before `can` or `filter`. Without a source, or with one that threw, graph checks deny with `relation-unavailable`; a chain past `depth` denies with `relation-depth`. Answers are cached per instance, never at module level.
+Pass `relations: memoryRelationSource(permissions, { rows, edges })` in tests, or a `RelationSource` (`ancestors`, `related`) over the app's tables, to `createPermDock`. Evaluation stays synchronous; with an async source, call `await permdock.prefetchRelations(permission, rows)` before `can` or `filter`. Without a source, or with one that threw, graph checks deny with `relation-unavailable`; a chain past `depth` denies with `relation-depth`. Answers are cached per instance, never at module level.
 
 ## Share dialogs
 
-`const { holders, complete } = await permdock.whoCan(permission, row)` lists who holds a permission on one object and how. Show `complete: false` honestly: some holders could not be listed. `whoCan` never grants.
+`const { holders, complete } = await whoCan(permdock, permission, row)` lists who holds a permission on one object and how. Show `complete: false` honestly: some holders could not be listed. `whoCan` never grants.
 
 ## In Postgres
 
 `permdock rls generate` emits the `permdock_closure` table, its statement triggers and `permitted_<resource>_ids(relation)` helpers. Snapshots carry no graph: graph grants are `portable: false` on the client and go to the decision endpoint. Check with:
 
 ```bash
-pnpm exec permdock rls verify --tree --db $DATABASE_URL
+pnpm exec permdock rls verify --tree
 pnpm exec permdock doctor --only graph
 ```
 

package/skills/permdock-tenancy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: permdock-tenancy
-description: Models tenants, memberships and role rules in PermDock. Use when declaring named scopes (organizations, workspaces, customers inside an organization), loading memberships through a MembershipSource, putting a role on one scope, keeping an owner per organization with min, max or transferOnly, controlling who hands out which role with assigns and for, checking a membership change with decideRoleChange, letting tenant admins define custom roles with customRoles and validateCustomRole, or fixing doctor PD023, PD025 or PD026 and denials such as tenant-mismatch, last-holder or not-assignable-by.
+description: Models tenants, memberships, contacts and support sessions in PermDock. Use when declaring named scopes (organizations, workspaces, customers inside an organization), loading memberships through a MembershipSource, putting a role on one scope, keeping an owner per organization with min, max or transferOnly, controlling who hands out which role with assigns and for, checking a membership change with decideRoleChange, letting tenant admins define custom roles with customRoles and validateCustomRole, giving external customer contacts portal access as kind contact principals found through a PrincipalSource and principalByIdentity, letting support staff view the app as a customer with decideSupportSession, signSupportSession and subjectFromSupportSession, or fixing doctor PD023, PD025 or PD026 and denials such as tenant-mismatch, last-holder, not-assignable-by or reason-required.
 license: MIT
 metadata:
   author: ScaleDockHQ
@@ -19,14 +19,18 @@ A policy declares its scopes in order (an organization, the customers inside it)
 - The membership kinds (`via`): staff, contact, guest, partner, support.
 - Which role manages each scope, who may hand out which role, and which roles a contact or guest may never hold.
 - Whether tenant admins define their own roles.
+- Whether external people (customer contacts, portal users) are accounts in the auth provider or rows in the app's own contacts table, and whether email delivery or a chat bot must reach them.
+- Whether support staff view the app as a customer, who approves that, and where the app records a session ending early.
 
 ## Invariants
 
-1. Memberships and custom roles come only from a `subjectFrom*` provider, the policy's `subject` or `context` function, a `MembershipSource` or a `RoleSource`. Never from a request body, an unsigned header, a model argument or a CLI flag.
+1. Memberships and custom roles come only from a `subjectFrom*` provider, the policy's `subject` or `context` function, a `MembershipSource` or a `CustomRoleSource`. Never from a request body, an unsigned header, a model argument or a CLI flag.
 2. A requested tenant with no matching membership is no tenant, never a default one. Team and tenant ids are identifiers, never display names.
 3. No cascade. An organization owner sees no customer portal unless they also hold a contact membership, and a global role never reaches scoped rows. An instance check without a row answers from first-scope memberships only; a nested membership needs the row or `permdock.team(id)`. A collection check (`create`, `list`) still answers from any membership in the tenant; for a staff-only guard pass `{ scope: '<first scope>' }` as the decide option.
 4. Role rules live on the role (`min`, `assigns`, `for`), not in handlers. `decideRoleChange` takes the actor from the instance and never writes.
 5. A custom role never exceeds the ceiling of declared `assignable` roles in its scope. Its grants carry no condition, approval or limit of their own; a `level` picks a condition the resource declares in code.
+6. A `kind: 'contact'` principal keeps only its `{ on }` resource memberships and is read-only unless a role's `for` lists `'contact'`; a scope role such as the `customer`-scope `contact` role below never reaches it. It never approves or creates keys. An email address or chat author with no identity link the app wrote is no principal, never a guest.
+7. A support session keeps the customer as principal and the staff member as a `support` actor, needs a reason and, by default, an approval by someone else, and is checked live on every request. A support actor never approves.
 
 ## Workflow
 
@@ -58,11 +62,15 @@ A policy declares its scopes in order (an organization, the customers inside it)
 
    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)).
 
-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 `permdock.decideRoleChange(...)` 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)
+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`.
-5. **Custom roles, when tenant admins define roles.** Keep declared roles small and mark them in `defineRoles` (`editor: { on: 'organization', assignable: true }`). Pass a `RoleSource` as `customRoles`, build the editor from `useAssignablePermissions()`, and save through a server action that runs `validateCustomRole`. -> [references/ownership-and-custom-roles.md](references/ownership-and-custom-roles.md#custom-roles)
+5. **Custom roles, when tenant admins define roles.** Keep declared roles small and mark them in `defineRoles` (`editor: { on: 'organization', assignable: true }`). Pass a `CustomRoleSource` as `customRoles`, build the editor from `useAssignablePermissions()`, and save through a server action that runs `validateCustomRole`. -> [references/ownership-and-custom-roles.md](references/ownership-and-custom-roles.md#custom-roles)
    ✓ PD023 is clean, and saving a role with a permission outside the ceiling is refused.
-6. **Test.** Add `describePolicy` rows for a member of another tenant, a contact reaching an organization row, and a role change that breaks `min` ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). Run `testMembershipSource` and `testRoleSource` from `permdock/testing` on custom sources. For list queries and RLS over scoped tables, follow the `permdock-data` skill.
+6. **Contact principals, when external people sign in or receive messages.** Pick the model: a signed-in user with a `via: 'contact'` membership on the `customer` scope, or a `kind: 'contact'` principal with `{ on: { resource, id }, roles }` memberships on the rows it is a party to. Give a contact a write only through a resource role with `for: ['contact']`. Pass a `PrincipalSource` as `principals` (`memoryPrincipalSource({ principals, identities })` in tests, `principalSource` from `permdock/better-supabase` there) and implement `principalByIdentity` over identity links the app writes after a signed-in link flow or a verified address, so [delivery](https://permdock.com/docs/concepts/delivery) and [chat](https://permdock.com/docs/concepts/chat) reach the contact ([contact principals](https://permdock.com/docs/concepts/subject#contact-principals)). -> [references/contacts-and-support-sessions.md](references/contacts-and-support-sessions.md)
+   ✓ A contact's write without a `for: ['contact']` role denies with `not-delegated`, and an unlinked address resolves to `null`.
+7. **Support sessions, when staff view the app as a customer.** Start each session with `decideSupportSession(staff, { id, principal, reason })`, record an approval by someone else and decide again with `{ approved: token, approvedBy }`. Sign the granted record with `signSupportSession(session, signer)` and resolve each request with `subjectFromSupportSession(token, { verifier, principals, permissions, sessions })` from `permdock/server`, where `sessions` is a `SupportSessionSource` that ends a session early. Send `supportSessionEvent` to the sink on start and end. On better-supabase, pass `supportPolicy` as the `authorize` option of `supportSessions` ([support sessions](https://permdock.com/docs/concepts/support-sessions)). -> [references/contacts-and-support-sessions.md](references/contacts-and-support-sessions.md#support-sessions)
+   ✓ An empty reason denies with `reason-required`, and a token for a session the source reports `ended` resolves to the anonymous subject.
+8. **Test.** Add `describePolicy` rows for a member of another tenant, a contact reaching an organization row, a contact principal writing without an opt-in role, and a role change that breaks `min` ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). Run `testMembershipSource`, `testCustomRoleSource`, `testPrincipalSource` and `testSupportSessionSource` from `permdock/testing` on custom sources. For list queries and RLS over scoped tables, follow the `permdock-data` skill.
    ✓ The tests pass.
 
 ## Verify before done
@@ -72,9 +80,14 @@ A policy declares its scopes in order (an organization, the customers inside it)
 - [ ] No `assigns` list lets a role appoint a role ranked above it.
 - [ ] Every server action that writes a membership role calls `decideRoleChange` with a `holders` count from the store, never a guess.
 - [ ] Every custom-role save runs `validateCustomRole` and checks `assignablePermissions()`. No single assignable `admin` role makes the ceiling the whole product.
-- [ ] Custom `MembershipSource` and `RoleSource` implementations pass `testMembershipSource` / `testRoleSource`.
+- [ ] Custom `MembershipSource`, `CustomRoleSource`, `PrincipalSource` and `SupportSessionSource` implementations pass `testMembershipSource` / `testCustomRoleSource` / `testPrincipalSource` / `testSupportSessionSource`.
+- [ ] A `kind: 'contact'` principal gets portal access only through `{ on }` memberships, and every write it may make comes from a role whose `for` lists `'contact'`. When contacts query the database directly, their memberships are kept out of the tables the RLS functions read, or writes are gated in the application.
+- [ ] `principalByIdentity` reads only identity links the app wrote after a signed-in link flow or a verified address. No code creates a principal, a guest or a default role for an unlinked address or chat author.
+- [ ] Every support session goes through `decideSupportSession` with a reason, and approval stays on unless the app approves elsewhere; `approvedBy` is never the staff member.
+- [ ] Session requests resolve with `subjectFromSupportSession` and a `SupportSessionSource`, never by signing in as the customer, and `supportSessionEvent` is sent on start and end.
 
 ## Reference index
 
 - [references/ownership-and-custom-roles.md](references/ownership-and-custom-roles.md): role options, `decideRoleChange` input and denial reasons, the SQL objects RLS uses, and the custom-role shape, ceiling and editor.
-- Docs: [named scopes](https://permdock.com/docs/concepts/scopes), [tenancy](https://permdock.com/docs/concepts/tenancy), [ownership](https://permdock.com/docs/concepts/ownership), [custom roles](https://permdock.com/docs/concepts/custom-roles), [extension interfaces](https://permdock.com/docs/concepts/extension-interfaces).
+- [references/contacts-and-support-sessions.md](references/contacts-and-support-sessions.md): the two contact models, contact principal rules, `PrincipalSource` and identity links for delivery and chat, the support-session start, token, live check and events, `supportPolicy`, and how support sessions differ from `supportAccess`.
+- Docs: [named scopes](https://permdock.com/docs/concepts/scopes), [tenancy](https://permdock.com/docs/concepts/tenancy), [ownership](https://permdock.com/docs/concepts/ownership), [custom roles](https://permdock.com/docs/concepts/custom-roles), [contact principals](https://permdock.com/docs/concepts/subject#contact-principals), [support sessions](https://permdock.com/docs/concepts/support-sessions), [elevated access](https://permdock.com/docs/concepts/elevated-access), [extension interfaces](https://permdock.com/docs/concepts/extension-interfaces).

package/skills/permdock-tenancy/references/contacts-and-support-sessions.md

@@ -0,0 +1,122 @@
+# Contact principals and support sessions
+
+Owning pages: [contact principals](https://permdock.com/docs/concepts/subject#contact-principals), [support sessions](https://permdock.com/docs/concepts/support-sessions), [extension interfaces](https://permdock.com/docs/concepts/extension-interfaces#principalsource).
+
+## Two kinds of contact
+
+| Who                                                         | Principal         | Membership                                                              | Reaches                                                             |
+| ----------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| A signed-in app user holding a portal role on a scope       | `kind: 'user'`    | `{ scope: 'customer', id, within, roles: ['contact'], via: 'contact' }` | What the `customer`-scope role grants                               |
+| An external person the app stores in its own contacts table | `kind: 'contact'` | `{ on: { resource, id }, roles }`                                       | Only the rows those resource memberships name, read-only by default |
+
+A `kind: 'contact'` principal keeps only its `{ on }` memberships, each rewritten to `via: 'contact'`. Its scope memberships, global `roles`, `plans`, membership `entitlements` and `tenant` are dropped, so `permdock.tenants()` is empty and a `customer`-scope role never applies to it. Model a customer contact this way when they are not an account in the app's auth provider, or when they must never see more than the rows they are a party to.
+
+## Contact principal rules
+
+- Only `{ on }` memberships count. Grant portal access with a role on a resource and a membership on one row of it.
+- An allow reaches a contact only when the permission is read-only (`meta.readOnly`, or the `read` and `list` actions), or the role's `for` lists `'contact'`. Every other allow denies with `not-delegated`. Top-level grants and relation grants never open a write to a contact.
+- A contact never approves, reviews access or accepts an approval delegation: `assertApprover` throws `approver-not-eligible`.
+- A contact never creates a key: `decideCredential` denies with `exceeds-creator` and `detail.creator: 'contact'`.
+- A contact never publishes a policy, a catalog or a hosted document.
+- The narrowing applies to `can()`, `where()`, `snapshot()` and `decideFor()`. Generated RLS does not know the principal kind: when contacts query the database directly, keep their memberships out of the tables the RLS functions read, or gate writes in the application.
+
+```ts
+role("payer", [allow(permissions.invoice.pay)], {
+  on: permissions.invoice,
+  for: ["contact"], // the only way a contact gets a write
+});
+
+const contact: Principal = {
+  id: "c_42",
+  kind: "contact",
+  memberships: [{ on: { resource: "invoice", id: "inv_1" }, roles: ["payer"] }],
+};
+```
+
+## Reaching a contact
+
+A contact is loaded through the `PrincipalSource` passed as `principals`. It is the one identity lookup for `decideFor`, delivery and chat:
+
+```ts
+type PrincipalSource = {
+  principal(
+    id: string,
+    options?: { tenant?: string },
+  ): Principal | null | Promise<Principal | null>;
+  principalByIdentity?(identity: {
+    kind: "email" | "chat";
+    provider?: string; // the chat platform; absent for email
+    value: string; // the address or the platform user id
+    workspace?: string;
+  }): Principal | null | Promise<Principal | null>;
+};
+```
+
+- `null`, a throw, a rejection or a missing `principalByIdentity` is no principal. Emails compare trimmed and case-insensitively.
+- An identity link is app data: one row per `kind`, `provider`, `value` and `workspace`, written when a signed-in person connects a chat account or verifies an address. Never create a link from an inbound message.
+- `permdock.decideFor(principalId, permission, row)` decides for a contact in the caller's tenant even though the contact holds no tenant membership.
+- [Delivery](https://permdock.com/docs/concepts/delivery): a `{ principal, channel, address }` recipient is decided with `decideFor`; a `{ channel, address }` recipient resolves through `principalByIdentity`, and an address with no link fails with `unlinked`.
+- [Chat](https://permdock.com/docs/concepts/chat): `subjectFromChat(author, { principals })` resolves the author through `principalByIdentity({ kind: 'chat', provider, value, workspace })`. An unlinked author is the anonymous subject, so every check denies with `anonymous`.
+- An unlinked address or chat author is never a guest. Do not invent a fallback contact or a default portal role for it.
+
+Sources:
+
+- `memoryPrincipalSource({ principals, identities })` from `permdock` holds principals and links (`{ identity, principal: '<id>' }`) in process, for tests and single-replica apps.
+- On better-supabase, `principalSource({ claims, identities?, subject? })` from `permdock/better-supabase` loads users from the claims better-supabase mints. `identities(identity)` returns `{ user: id }` or `{ contact: principal }`; a contact link is accepted only for `kind: 'contact'` ([better-supabase principals](https://permdock.com/docs/adapters/better-supabase#principals)).
+- Run `testPrincipalSource(source, { principals, identities })` from `permdock/testing` on a custom source.
+
+## Support sessions
+
+A support session lets a staff member view the app as one person, inside that person's tenant, for a stated reason and a bounded time. The person stays the principal and the staff member is an actor with `kind: 'support'`.
+
+### Start
+
+```ts
+import { decideSupportSession } from "permdock";
+const decision = await decideSupportSession(
+  staff,
+  {
+    id: crypto.randomUUID(),
+    principal: "u_customer",
+    reason: "Ticket 4411: invoice totals look wrong",
+    // tenant?: defaults to the staff member's active tenant
+    // permissions?: defaults to every readOnlyHint permission the staff member can use
+    // expiresIn?: seconds, default 3600, at most 86400
+    // reference?: the app's ticket id
+  },
+  { settings, approved, approvedBy }, // approval: false only when the app approves elsewhere
+);
+// { outcome: 'granted', session } | { outcome: 'approval-required', session, token } | { outcome: 'denied', denials }
+```
+
+- The staff member must be a `user` acting for themselves (no credential, run ticket or actor), with `exceeds-creator` otherwise. They must be a member of the tenant (`tenant-mismatch`) and able to use every listed permission (`exceeds-creator`).
+- An empty reason denies with `reason-required`.
+- Approval is on by default. Store the request, let an approver who is not the staff member accept, then decide again with `{ approved: token, approvedBy }`. `approvedBy` equal to the staff member denies.
+- The tenant's `supportSessions` setting from a `SettingsSource` only tightens: `disabled` refuses every session, `maxTtl` caps `expiresIn`, `readOnly` refuses a write permission with `not-delegated`.
+
+### Use
+
+- `signSupportSession(session, signer)` from `permdock/server` signs a granted record as a `vnd.permdock.support-session+jwt` (`sub` the viewed principal, `act` the staff member, `jti` the session id) that expires with the session.
+- `subjectFromSupportSession(token, { verifier, principals, permissions, sessions? })` resolves it on every request: the viewed principal and the staff member are loaded live through `principals`, the actor is `{ id, kind: 'support' }`, the session's permissions become the `delegation`, and `subject.context.supportSession` carries the id, reason, `approvedBy` and `reference` for audit. Every failure is the anonymous subject, reported through `onAuth` with a cause such as `expired`, `session-ended`, `principal-unavailable` or `actor-unavailable`.
+- A `SupportSessionSource` (`session(id)` returning `{ id, ended? }` or `null`) passed as `sessions` lets the app end a session before it expires. An unknown id, `ended: true` or a throw is `session-ended`. Check it with `testSupportSessionSource(source, { sessions })` from `permdock/testing`.
+- A support actor never approves: `assertApprover` throws `approver-not-eligible`.
+- A policy delegation to `actor('support')` narrows what any session reaches.
+
+### Events
+
+`supportSessionEvent({ operation, session })` builds an `access` event with `via: 'support-session'`, the session id and the permissions. Sinks send it as `com.permdock.support-session.started` or `com.permdock.support-session.ended`; a session ended early (`revoked`) goes out as `.ended` and keeps the difference in `data.operation`.
+
+### better-supabase
+
+`supportPolicy({ policy, subject?, options?, writable?, approval?, approved? })` from `permdock/better-supabase` is the `authorize` option of better-supabase's `supportSessions`. It decides each start with `decideSupportSession` as the admin; a `readOnly: false` start needs `writable`, and an `approval-required` start passes once `approved(input, pending)` returns `{ approvedBy }` for `pending.token` ([better-supabase support sessions](https://permdock.com/docs/adapters/better-supabase#support-sessions)).
+
+### Support sessions and supportAccess
+
+`supportAccess` ([elevated access](https://permdock.com/docs/concepts/elevated-access#support-access-with-tenant-consent)) is the other model: the vendor is the principal and holds a consented, time-bound `{ via: 'support' }` membership that a tenant owner grants through an `ApprovalRequest`. Use it for a vendor team working inside a tenant. Use a support session to see what one person sees.
+
+| Model           | Principal               | Actor                         | Granted by                              |
+| --------------- | ----------------------- | ----------------------------- | --------------------------------------- |
+| Support session | The viewed person       | Staff, `kind: 'support'`      | `decideSupportSession` plus an approval |
+| `supportAccess` | The vendor staff member | Required with `actorRequired` | Tenant owner consent                    |
+
+Both share the `com.permdock.support-session.*` event family. A support-session actor satisfies `actorRequired`, which accepts any actor.

package/skills/permdock-tenancy/references/ownership-and-custom-roles.md

@@ -42,7 +42,8 @@ roles: [
 ## Checking a role change
 
 ```ts
-const result = permdock.decideRoleChange({
+import { decideRoleChange } from "permdock";
+const result = decideRoleChange(permdock, {
   kind: "assign", // 'assign' | 'revoke' | 'transfer'
   role: roles.admin,
   scope: "organization",
@@ -61,7 +62,7 @@ The actor is the instance's own subject; nothing in the change stands in for it.
 
 For a role on a nested scope that the subject holds nothing at, pass `within` and `{ trusted: true }` only after loading the ancestors from the app's own store.
 
-Generated RLS applies the same rules at commit, with triggers on the scope's `rls.memberships` table or on the tables of its `fromTable` / `fromJunction` sources (base tables, not views). Map `rls.memberships.scopes.<scope>.via` so the helpers apply `for`, and use `permdock_can_assign(role, organization_id::text)` in the membership table's own insert policy, or `permdock_can_assign_any(role, organization_id, 'organization', organization_id::text)` when the role may be a custom one. Set `rls.assignments` to have triggers check every client write to the membership tables, the global-roles table `rls.roles` and an invitations table, and `ownRole: 'refuse'` to refuse a client write to the caller's own row; never keep a hand-written trigger for either. The SQL is owned by the `permdock-data` skill.
+Generated RLS applies the same rules at commit, with triggers on the scope's `rls.memberships` table or on the tables of its `tableMembershipSource` / `junctionMembershipSource` sources (base tables, not views). Map `rls.memberships.scopes.<scope>.via` so the helpers apply `for`, and use `permdock_can_assign(role, organization_id::text)` in the membership table's own insert policy, or `permdock_can_assign_any(role, organization_id, 'organization', organization_id::text)` when the role may be a custom one. Set `rls.assignments` to have triggers check every client write to the membership tables, the global-roles table `rls.roles` and an invitations table, and `ownRole: 'refuse'` to refuse a client write to the caller's own row; never keep a hand-written trigger for either. The SQL is owned by the `permdock-data` skill.
 
 ## Custom roles
 
@@ -80,10 +81,11 @@ type CustomRole = {
 - An own allow inherits the conditions of the ceiling grants for that permission. To keep a narrower condition ("own posts only"), include the declared role that has it.
 - A resource may declare `levels: { own: { ownerId: principal.id }, team: { teamId: { in: principal.teamIds } }, all: {} }`. A grant `{ permission: 'job.read', level: 'team' }` ANDs that condition into the ceiling grant. An undeclared level, or a level on a collection action, is dropped as `unknown-level` and removes the permission; a level on a deny is `condition-not-allowed`. `permdock.assignableLevels(leaf)` lists the levels the subject may hand out.
 - An own deny removes the permission from this custom role only. Deny it in code when it must win across roles.
-- Pass a `RoleSource` (`memoryRoleSource(roles)` in tests), or a `RoleSourceFactory` `(subject) => RoleSource` when the source reads one principal's roles, as `customRoles` on `createPermDock` or any adapter. To add every role of a tenant on a role-management request, `await permdock.derive({ customRoles })` instead of building a second instance. Build it with `customRoleSource({ rolesOf })`, where `rolesOf(tenant)` reads every custom role of the tenant, not only the held ones: `assignableRoles` and `decideRoleChange` see only what the source returns. `{ read: 'held', policy }` skips the read on requests that never manage roles. Check it with `testRoleSource(source, { every })`.
+- Pass a `CustomRoleSource` (`memoryCustomRoleSource(roles)` in tests), or a `CustomRoleSourceFactory` `(subject) => CustomRoleSource` when the source reads one principal's roles, as `customRoles` on `createPermDock` or any adapter. To add every role of a tenant on a role-management request, `await permdock.derive({ customRoles })` instead of building a second instance. Build it with `customRoleSource({ rolesFor })`, where `rolesFor(tenant)` reads every custom role of the tenant, not only the held ones: `assignableRoles` and `decideRoleChange` see only what the source returns. `{ read: 'held', policy }` skips the read on requests that never manage roles. Check it with `testCustomRoleSource(source, { every })`.
 - `permdock.assignableRoles({ tenant })` lists declared roles, then the tenant's custom roles whose every permission and level the subject may hand out at the custom role's scope. `decideRoleChange` assigns and revokes a custom role like a declared one, with no holder count; it inherits `for` and `exclusiveWith` from its included roles.
 - `permdock.assignablePermissions({ tenant })` is the ceiling intersected with what the subject holds. `useAssignablePermissions()` in `permdock/react` builds the editor from it.
 - The save action runs `validateCustomRole(policy, role)` and refuses the role when `ok` is false or `permissions` contains a key outside `assignablePermissions()`. `dropped` names each entry left out (`unknown-permission`, `outside-ceiling`, `condition-not-allowed`, `unknown-level`, `unknown-role`).
-- A platform custom role (`scope: 'global'`, no `tenant`, `team` or `id`) is held through `principal.roles` and capped by the allows of declared global roles marked `assignable`. `RoleSource.globalRoles({ held })` returns them; `customRoleSource(reader, { read: 'held', policy })` skips that read while every held global role is declared.
+- A platform custom role (`scope: 'global'`, no `tenant`, `team` or `id`) is held through `principal.roles` and capped by the allows of declared global roles marked `assignable`. `CustomRoleSource.globalRoles({ held })` returns them; `customRoleSource(reader, { read: 'held', policy })` skips that read while every held global role is declared.
 - A stored grant under a key renamed with `definePermissions(..., { renamed })` still resolves; `validateCustomRole` lists it in `renamed` as `{ from, to }`, and `permdock doctor` PD055 prints the `update` that rewrites it.
 - For generated RLS, add `--custom-roles` (or `rls.customRoles: true`) to `permdock rls generate`. Platform roles are rows with `scope = 'global'` and a null `tenant_id`, or the top-level `role_grants` claim in `jwt` mode. With levels, `custom_role_permissions` gains a `level` column and the claim writes `key@level`.
+- To adopt custom roles the app already stores in its own tables, set `rls.customRoles.from` and `rls.customRoleWrites.roles`, then run `permdock rls generate --backfill-out <migrations dir>/`. The migration saves each role through the trusted replace function, drops entries outside the ceiling with a warning, and skips roles that already have rows; never write the copy by hand ([backfill](https://permdock.com/docs/cli/rls#backfill-from-existing-tables)).

package/skills/permdock-wire/SKILL.md

@@ -14,10 +14,11 @@ Three files and one guard: `src/permissions.ts` (definitions), `src/policy.ts` (
 
 ## Inputs (find out, or ask before starting)
 
-- The framework: Next.js, Hono, Express, Fastify, Elysia, Nest, Node, tRPC, oRPC, an AuthZEN PDP, Vite with React, Vue, Svelte or Solid, React Native, or a collect-only framework (Nuxt, Astro, React Router, TanStack Start, Effect).
+- The framework: Next.js, Hono, Express, Fastify, Elysia, Nest, Node, tRPC, oRPC, SvelteKit, Astro, SolidStart, TanStack Start, h3 (also Nitro and Nuxt server routes), an AuthZEN PDP, Vite with React, Vue, Svelte or Solid, React Native, or a collect-only framework (React Router, Effect).
 - The Standard Schema validator already in the repo: Zod, Valibot, ArkType, Effect Schema.
 - Where the signed-in user comes from (the session or a verified token) and which roles and plans exist.
 - The first path to guard.
+- Whether the app is new (start from a preset) or already has its own checks (adopt beside them).
 
 ## Invariants
 
@@ -29,9 +30,11 @@ Three files and one guard: `src/permissions.ts` (definitions), `src/policy.ts` (
 
 ## Workflow
 
-1. **Detect.** Find the framework and the validator. Collect-only frameworks use `permdock/unplugin` for collect and `permdock/server` (or the matching HTTP adapter) at runtime; never add a per-vendor package.
+1. **Start.** A new app starts from a preset: the user's code from [permdock.com/create](https://permdock.com/create), or flags. Run `npx permdock init --preset <code> --dry-run`, show the file list, then run it without `--dry-run`; it never overwrites a file unless `--force` is passed. It writes the owned files the steps below describe; review them instead of writing them. An app with its own checks keeps them and adopts beside them with `shadowMode` and `permdock scan` ([existing apps](https://permdock.com/docs/getting-started/existing-apps)). -> [references/presets-and-recipes.md](references/presets-and-recipes.md)
+   ✓ Either `permdock init` wrote the files and printed the install line, or the legacy checks are listed and none was removed.
+2. **Detect.** Find the framework and the validator. Collect-only frameworks use `permdock/unplugin` for collect and `permdock/server` (or the matching HTTP adapter) at runtime; Nuxt collects the same way and runs on `permdock/h3`. Never add a per-vendor package.
    ✓ The adapter import path (`permdock/<framework>`) and the validator import are named.
-2. **Define.** Create `src/permissions.ts`. Importable everywhere; no rules, no secrets.
+3. **Define.** Create `src/permissions.ts`. Importable everywhere; no rules, no secrets.
 
    ```ts
    import {
@@ -41,6 +44,7 @@ Three files and one guard: `src/permissions.ts` (definitions), `src/policy.ts` (
      resource,
      crud,
    } from "permdock";
+
    import { Post } from "./schemas";
 
    export const permissions = definePermissions({
@@ -52,10 +56,11 @@ Three files and one guard: `src/permissions.ts` (definitions), `src/policy.ts` (
 
    ✓ Every resource the first guard needs has a leaf; instance actions sit in `actions`, list and create in `collection`.
 
-3. **Policy.** Create `src/policy.ts`. Prefer `grants` with `to:` selectors (`anyone()`, `authenticated()`, `relation()`, a role or plan leaf, `actor()`, `assurance()`); `role(roles.member, …)` sugar also works.
+4. **Policy.** Create `src/policy.ts`. Prefer `grants` with `to:` selectors (`anyone()`, `authenticated()`, `relation()`, a role or plan leaf, `actor()`, `assurance()`); `role(roles.member, …)` sugar also works.
 
    ```ts
    import { definePolicy, role, allow, principal, relation } from "permdock";
+
    import { permissions, roles } from "./permissions";
 
    const member = role(roles.member, [
@@ -75,7 +80,7 @@ Three files and one guard: `src/permissions.ts` (definitions), `src/policy.ts` (
      { permissions, roles },
      {
        roles: [member],
-       principal: (user) => user && { id: user.id, roles: user.roles },
+       subject: (user) => user && { id: user.id, roles: user.roles },
      },
    );
    ```
@@ -83,19 +88,19 @@ Three files and one guard: `src/permissions.ts` (definitions), `src/policy.ts` (
    Short policy features that need no other skill -> [references/policy-options.md](references/policy-options.md): usage limits, `disclosure: 'hide'`, plan gates, `validFrom` / `validUntil`, step-up with `assurance()`.
    ✓ At least one role grants the first guard's permission, and no client entry imports `policy.ts`.
 
-4. **Factory.** Create `src/permdock/server.ts` (or the adapter's documented factory file) with `createPermDock` from `permdock/<framework>`. Copy the exact return names. -> [references/adapters.md](references/adapters.md)
+5. **Factory.** Create `src/permdock/server.ts` (or the adapter's documented factory file) with `createPermDock` from `permdock/<framework>`. Copy the exact return names. -> [references/adapters.md](references/adapters.md)
    ✓ The factory file compiles and exports the adapter's public members.
-5. **Guard.** Add one check on the path the user asked for: `assert` or `protect` / `getPermission` with a permission reference on the server, `<Protected permission={permissions.post.update}>` inside `PermDockProvider` in React.
+6. **Guard.** Add one check on the path the user asked for: `assert` or `protect` / `getPermission` with a permission reference on the server, `<Protected permission={permissions.post.update}>` or `useGate` inside `PermDockProvider` in React. For a gated button, approval dialog, tenant switcher or role picker, add the recipe from the `@permdock` registry rather than writing one. -> [references/presets-and-recipes.md](references/presets-and-recipes.md#recipes)
    ✓ That path cannot run without a `granted` decision, and the adapter handles a denial (Problem Details or fallback UI).
-6. **Check.** Run `permdock collect`, `permdock catalog`, `permdock usage` and `permdock doctor`, and add `permdock collect --check` to CI. For a Vite SPA, Expo or another framework without `'use client'`, set `doctor.clientEntries` to the client source globs so PD001 checks them. When client code lives outside `collect.srcPath`, list every source folder in `doctor.srcPath` instead of widening the catalog. Add a `describePolicy` suite from `permdock/testing` ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). -> [references/policy-options.md](references/policy-options.md#cli-starting-points)
+7. **Check.** Run `permdock collect`, `permdock catalog`, `permdock usage` and `permdock doctor`, and add `permdock collect --check` to CI. For a Vite SPA, Expo or another framework without `'use client'`, set `doctor.clientEntries` to the client source globs so PD001 checks them. When client code lives outside `collect.srcPath`, list every source folder in `doctor.srcPath` instead of widening the catalog. Add a `describePolicy` suite from `permdock/testing` ([scenario testing](https://permdock.com/docs/guides/scenario-testing)). -> [references/policy-options.md](references/policy-options.md#cli-starting-points)
    ✓ Collect and doctor findings are fixed, or the three files typecheck and one matrix test passes.
 
 ## Next skills
 
 Install each with `npx skills add ScaleDockHQ/PermDock --skill <name>` when the app needs it:
 
-- `permdock-agents`: AI SDK, Claude Agent SDK, Eve, OpenAI Agents SDK, MCP, A2A and WebMCP tool maps, actors and `delegation`.
-- `permdock-approvals`: `approval: { by }`, quorum, escalation, `staleOn`, approval stores and the resume flow.
+- `permdock-agents`: AI SDK, Claude Agent SDK, Eve, OpenAI Agents SDK, MCP, A2A and WebMCP tool maps, actors and `delegation`, automations (`permdock/workflow`, `permdock/workflow-sdk`) and chat bots (`permdock/chat`, `permdock/chat-sdk`).
+- `permdock-approvals`: `approval: { by }`, quorum, escalation, `staleOn`, approval stores, the resume flow, and approval prompts by email or chat (`permdock/delivery`, `permdock/resend`, `permdock/chat-sdk`).
 - `permdock-tenancy`: named scopes, memberships, ownership rules (`min`, `assigns`, `for`) and custom roles.
 - `permdock-data`: `where()` and `filter()` in ORM queries, generated RLS, relationship graphs, parity tests.
 - `permdock-credentials`: `subjectFromJwt`, API keys and service accounts, share links.
@@ -110,7 +115,8 @@ Install each with `npx skills add ScaleDockHQ/PermDock --skill <name>` when the
 
 ## Reference index
 
-- [references/adapters.md](references/adapters.md): factory shapes for Next.js, HTTP frameworks, RPC frameworks, UI frameworks, AuthZEN, OpenAPI, OpenTelemetry, SCIM, Cloud, Better Auth, Clerk, Supabase, the remote PDP and collect-only frameworks.
-- [references/policy-options.md](references/policy-options.md): limits, disclosure, plans, validity windows, step-up, and CLI starting points (OpenAPI import, Arazzo, Cloud push).
+- [references/adapters.md](references/adapters.md): factory shapes for Next.js, HTTP frameworks, meta-framework servers (SvelteKit, Astro, SolidStart, TanStack Start, h3 for Nitro and Nuxt), RPC frameworks, UI frameworks, AuthZEN, OpenAPI, OpenTelemetry, SCIM, Cloud, the Resend, Chat SDK and Workflow SDK implementation entries, Better Auth, Clerk, Supabase and better-supabase, the remote PDP, collect-only frameworks, and the `deniedResponse`, `context` and `wrap` adapter hooks.
+- [references/presets-and-recipes.md](references/presets-and-recipes.md): `permdock init` and preset codes, what the package owns and what the app owns, and the `@permdock` shadcn recipes for React and React Native.
+- [references/policy-options.md](references/policy-options.md): limits, disclosure, plans, validity windows, step-up, app data and app obligations, and CLI starting points (OpenAPI import, Arazzo, Cloud push).
 - The `permdock` skill: the mental model, `explain` for an unexpected denial, and the docs MCP.
 - Docs: [policies](https://permdock.com/docs/concepts/policies), [conditions](https://permdock.com/docs/concepts/conditions), [decisions](https://permdock.com/docs/concepts/decisions), [adapters](https://permdock.com/docs/adapters).