permdock 0.0.0 → 0.1.0

package/skills/permdock-data/SKILL.md

@@ -0,0 +1,57 @@
+---
+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.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.dev/docs/adapters/rls
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# PermDock data
+
+The same portable conditions decide `can()` in memory, narrow list queries through `where()`, and compile to Postgres RLS. Keep them portable and prove the three agree ([conditions](https://permdock.dev/docs/concepts/conditions), [RLS](https://permdock.dev/docs/adapters/rls)). Set up the policy and factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`); named scopes and memberships come from the `permdock-tenancy` skill.
+
+## Inputs (find out, or ask before starting)
+
+- The ORM or query layer: Drizzle, Prisma, Kysely, Convex, or raw SQL.
+- Whether Postgres RLS enforces access as well (clients reading tables directly, a data API), and whether the app's SQL or PermDock's policy is the authority.
+- Whether existing policies call hand-written helpers.
+- Object hierarchies: nested folders, sub-teams, reporting lines, account delegates, rows that must not inherit.
+- A test database for parity runs (a container or a branch database).
+
+## Invariants
+
+1. Portable first. Write `where` conditions with the portable operators; a closure is for checks they cannot express, and it is filtered in memory, never in SQL or RLS.
+2. A list query uses `where()` before the query and `filter()` after it. One row is loaded and checked with `assert` or the adapter's `protect`.
+3. Generated RLS never emits `service_role`, and a request runs as `authenticated` or `anon`.
+4. RLS cannot see request `context`. A condition the database must enforce compares a server-set `principal.claims.*` value, never `user_metadata`.
+5. Graph grants walk at most 32 hops (16 by default) and deny with `relation-unavailable` when the relation source is missing or unloaded.
+
+## Workflow
+
+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)
+   ✓ `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.
+   ✓ 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.dev/docs/adapters/testing)). Run `testRelationSource` on a custom `RelationSource`.
+   ✓ The query and the database return exactly the rows `filter()` keeps.
+
+## Verify before done
+
+- [ ] No closure only compares fields a portable operator covers (`eq`, `in`, `memberOf`, `sqlFunction`, …); rewrite those as JSON conditions.
+- [ ] An owner-equals-principal `where` on a resource with a matching relation uses `relation()` instead.
+- [ ] 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`.
+
+## 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`.
+- Docs: [conditions](https://permdock.dev/docs/concepts/conditions), [relationships](https://permdock.dev/docs/concepts/relationships), [RLS adapter](https://permdock.dev/docs/adapters/rls), [`permdock rls`](https://permdock.dev/docs/cli/rls), [Postgres RLS](https://permdock.dev/docs/standards/postgres-rls).

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

@@ -0,0 +1,54 @@
+# Queries and generated RLS
+
+Owning pages: [protected queries](https://permdock.dev/docs/concepts/policies#protected-queries), [RLS adapter](https://permdock.dev/docs/adapters/rls), [`permdock rls`](https://permdock.dev/docs/cli/rls), and the ORM pages [Drizzle](https://permdock.dev/docs/adapters/drizzle), [Prisma](https://permdock.dev/docs/adapters/prisma), [Kysely](https://permdock.dev/docs/adapters/kysely), [Convex](https://permdock.dev/docs/adapters/convex).
+
+## List queries
+
+```ts
+import { toWhere } from "permdock/drizzle"; // or permdock/prisma, permdock/kysely
+
+export async function listPosts(permdock: PermDock) {
+  const read = permissions.post.read;
+  const rows = await db
+    .select()
+    .from(posts)
+    .where(toWhere(permdock.where(read), posts));
+  return permdock.filter(read, rows).map((row) => permdock.pick(read, row));
+}
+```
+
+- `permdock.where(permission)` narrows the query before it runs. It leaves out closure grants and marks the result `partial`; `filter` then drops what a closure refuses, and `pick` redacts fields.
+- When nothing is granted, `toWhere` returns a constant false expression (no rows). A closure grant cannot compile: `toWhere` throws `PermDockValidationError`.
+- `toWhere(condition, table, { columns })` maps schema fields to differently named columns. Graph grants need `{ relations: { closure: 'permdock.permdock_closure' } }`, otherwise a `related` node throws `non-portable-condition`.
+- `checkRow` (Drizzle) answers one row as `{ found: false }` or `{ found: true, granted }`, so a handler can tell `404` from `403` with one query.
+- Prisma also exports `permdockExtension`. Drizzle, Prisma and Kysely export `withSubject`, which runs a transaction as the subject (`set local role` plus claims) so RLS sees it; its `dialect` must match `rls generate`.
+- Convex: `createPermDock` from `permdock/convex` returns `withPermDock` and `snapshotQuery`. Identity comes from `ctx` only; function arguments never influence the subject.
+
+## Generate and verify RLS
+
+```bash
+pnpm exec permdock rls generate --target sql --dialect supabase --out migrations/rls.sql
+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
+```
+
+- 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. 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. `--authorize jwt` reads token claims and stays stale until the token refreshes; keep the token lifetime at 3600 seconds or less (PD019).
+- `--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.
+- `--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.
+- 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 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.
+
+## 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). The hook, declarative schemas (`--split`) and `fromTable` / `fromJunction` membership sources are on the [Supabase adapter](https://permdock.dev/docs/adapters/supabase) and [Supabase hook](https://permdock.dev/docs/adapters/supabase-hook) pages.

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

@@ -0,0 +1,65 @@
+# Relationship graph
+
+Owning page: [relationships](https://permdock.dev/docs/concepts/relationships). Named scopes are tenancy (fixed levels); the graph is the objects under them, with no fixed depth.
+
+## Declare
+
+```ts
+export const permissions = definePermissions({
+  doc: resource(Doc, {
+    actions: ["read", "update"],
+    parent: { field: "folderId", resource: "folder" },
+    relations: { owner: "ownerId" },
+  }),
+  folder: resource(Folder, {
+    actions: ["read", "share"],
+    parent: { field: "parentId", resource: "folder" },
+    relations: {
+      editor: { edge: "folder_editors" },
+      viewer: { edge: "folder_viewers", expiresAt: "expires_at" },
+    },
+    restricted: "restricted",
+  }),
+});
+```
+
+| Relation   | Declared as                                                | Held when                                                                                |
+| ---------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Field      | `owner: 'ownerId'`                                         | the row's field is the principal's id                                                    |
+| Edge table | `{ edge, object?, subject?, expiresAt?, match?, groups? }` | a row of `edge` links the object and the principal, and has not expired                  |
+| Principal  | `{ principal, period? }`                                   | the row's column is the principal's id, inside `period` (a manager, an account delegate) |
+| Implied    | `{ includes: ['editor'] }`                                 | the principal holds a listed relation                                                    |
+
+A resource that parents itself makes a chain. `restricted` names a boolean column: a restricted row is reached only by grants on itself, never through its ancestors. `links` names to-one references a grant can cross with `through: ['folder', 'team']`.
+
+## Grant
+
+```ts
+grants: [
+  allow(permissions.doc.read, { to: relation(permissions.doc, 'owner') }),
+  allow(permissions.doc.read, {
+    to: relation(permissions.folder, 'viewer', { through: 'parent', depth: 16 }),
+  }),
+],
+```
+
+`depth` defaults to 16 and is at most 32. An array in `to:` is an intersection, so "owner or viewer" is two `allow` grants. Prefer `relation()` over `where: { authorId: principal.id }` when the resource declares the relation.
+
+## 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.
+
+## 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.
+
+## 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 doctor --only graph
+```
+
+`--tree` seeds a generated object graph in a rolled-back transaction and compares it with `can()` per principal. PD031 flags a self-parent no `through: 'parent'` grant walks, or a `restricted` column no graph grant reaches; PD032 flags a graph resource RLS cannot name.

package/skills/permdock-tenancy/SKILL.md

@@ -0,0 +1,77 @@
+---
+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.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.dev/docs/concepts/scopes
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# PermDock tenancy
+
+A policy declares its scopes in order (an organization, the customers inside it). A role is held at one scope, a membership names one instance of that scope, and a grant reaches a row only through that scope's key. Roles never cascade between scopes ([named scopes](https://permdock.dev/docs/concepts/scopes), [tenancy](https://permdock.dev/docs/concepts/tenancy)). Set up the policy and factory first with the `permdock-wire` skill (`npx skills add ScaleDockHQ/PermDock --skill permdock-wire`).
+
+## Inputs (find out, or ask before starting)
+
+- The tenant levels, outermost first, and the row column that holds each id (`organization_id`, `customer_id`).
+- Where memberships are stored and how the app loads them: token claims from a `subjectFrom*` provider, or the app's tables.
+- 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.
+
+## 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.
+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.
+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.
+
+## Workflow
+
+1. **Declare the scopes.** Add them to `definePolicy` in order, each with its row `key` and, after the first, `within`:
+
+   ```ts
+   definePolicy(
+     { permissions, roles },
+     {
+       scopes: {
+         organization: { key: "organization_id" },
+         customer: { key: "customer_id", within: "organization" },
+       },
+       roles: [
+         role(roles.admin, adminGrants, { on: "organization" }),
+         role(roles.contact, contactGrants, { on: "customer" }),
+       ],
+       subject,
+     },
+   );
+   ```
+
+   ✓ `definePolicy` accepts the scopes, and each role names one scope with `on`.
+
+2. **Give resources their scope keys.** Every resource a scoped grant touches declares a `memberOf` relation per scope key it carries, for example `relations: { organization: { field: 'organization_id', memberOf: 'organization' } }`.
+   ✓ `definePolicy` does not throw for a missing `memberOf` relation.
+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.
+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)
+   ✓ 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)
+   ✓ 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.dev/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.
+   ✓ The tests pass.
+
+## Verify before done
+
+- [ ] No membership, tenant or role is read from a request body, tool argument, unsigned header or `user_metadata`.
+- [ ] Each scope's managing role sets `min: 1` (PD026), and admin-like roles set `for` so contact, guest or partner memberships cannot hold them.
+- [ ] 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`.
+
+## 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.dev/docs/concepts/scopes), [tenancy](https://permdock.dev/docs/concepts/tenancy), [ownership](https://permdock.dev/docs/concepts/ownership), [custom roles](https://permdock.dev/docs/concepts/custom-roles), [extension interfaces](https://permdock.dev/docs/concepts/extension-interfaces).

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

@@ -0,0 +1,83 @@
+# Ownership and custom roles
+
+Owning pages: [ownership](https://permdock.dev/docs/concepts/ownership) and [custom roles](https://permdock.dev/docs/concepts/custom-roles).
+
+## Role options
+
+```ts
+const staff = { for: ["staff"], meta: { audience: "staff" } } as const;
+
+roles: [
+  role(roles.owner, ownerGrants, {
+    on: "organization",
+    ...staff,
+    min: 1,
+    assigns: ["owner", "admin", "member", "viewer", "contact"],
+  }),
+  role(roles.admin, adminGrants, {
+    on: "organization",
+    ...staff,
+    assigns: ["member", "viewer", "contact"],
+  }),
+  role(roles.contact, contactGrants, {
+    on: "customer",
+    for: ["contact"],
+    meta: { audience: "portal" },
+  }),
+];
+```
+
+| Option          | Meaning                                                                                                                                  |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `min`           | Fewest holders each scope instance keeps (default `0`). Removing the last owner is refused.                                              |
+| `max`           | Most holders an instance may have.                                                                                                       |
+| `transferOnly`  | Once an instance has holders, the role only moves from one holder to another.                                                            |
+| `assigns`       | Roles a holder may assign and revoke. Once any role declares `assigns`, this graph replaces the held-grant rule for `assignableRoles()`. |
+| `for`           | Membership kinds (`Membership.via`) that may hold the role. A membership with another `via`, or none, grants nothing through it.         |
+| `exclusiveWith` | Roles nobody may hold together with this one in the same instance (PD018).                                                               |
+| `meta.audience` | The surface the role's holders use; `permdock.audiences()` and `snapshot.audiences` report it and never grant.                           |
+
+`min`, `max` and `transferOnly` need a named-scope `on`.
+
+## Checking a role change
+
+```ts
+const result = permdock.decideRoleChange({
+  kind: "assign", // 'assign' | 'revoke' | 'transfer'
+  role: roles.admin,
+  scope: "organization",
+  id: "o_acme",
+  target: { id: "u_bob", via: "staff", roles: ["member"] }, // their membership there now
+  holders: 1, // how many hold the role in the instance now, from the app's store
+});
+// { outcome: 'granted', change, role } or { outcome: 'denied', change, denials }
+```
+
+The actor is the instance's own subject; nothing in the change stands in for it. `decideRoleChange` never writes. Without a valid `holders` count, a role with `min`, `max` or `transferOnly` is denied. Denial reasons: `last-holder`, `max-holders`, `transfer-only`, `not-assignable-by`, `self-demotion`, `not-allowed-for-membership`, `conflicting-role`.
+
+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. 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. The SQL is owned by the `permdock-data` skill.
+
+## Custom roles
+
+```ts
+type CustomRole = {
+  tenant: string; // absent when scope is 'global'
+  scope?: string; // default: the first scope; 'global' for a platform role
+  id?: string; // pins it to one instance
+  name: string;
+  includes?: string[]; // declared roles to start from
+  grants?: { permission: string; effect?: "allow" | "deny" }[];
+};
+```
+
+- The ceiling of a scope is the code allows of the declared roles marked `assignable` in that scope. A custom role never exceeds it, and hosted grants never widen it.
+- 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.
+- 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) as `customRoles` on `createPermDock`.
+- `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-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()` returns them.
+- 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.

package/skills/permdock-wire/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: permdock-wire
+description: Adds PermDock authorization to a TypeScript app, from definitions to the first guard. Use when installing permdock, adding permissions, roles, plans, RBAC or access control, writing definePermissions, definePolicy or createPermDock, guarding a route, Server Action, procedure or React component, adding usage limits, plan gates or time-limited grants, or running permdock collect and doctor for the first time.
+license: MIT
+metadata:
+  author: ScaleDockHQ
+  homepage: https://permdock.dev/docs/getting-started/quick-start
+  repository: https://github.com/ScaleDockHQ/permdock
+---
+
+# Wire PermDock
+
+Three files and one guard: `src/permissions.ts` (definitions), `src/policy.ts` (rules) and the factory file, then one check on the path the user asked for ([quick start](https://permdock.dev/docs/getting-started/quick-start)). Import paths and identifiers follow the [naming convention](https://permdock.dev/docs/getting-started/naming).
+
+## 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 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.
+
+## Invariants
+
+1. Permissions are references (`permissions.post.update`), never strings. Roles and plans are typed leaves (`roles.owner`, `plans.pro`).
+2. Outcomes are `granted`, `denied` or `approval-required`. Anything unknown, invalid or thrown denies, and a matching `deny` wins over every `allow`.
+3. `policy.ts` is server-only. Client entries import `permissions.ts`, snapshots and hooks only.
+4. The subject comes from a trusted resolver (`subjectFrom*` or the server session), never from a request body, header the client sets, or model output.
+5. Portable `where` conditions first; a closure only when no portable operator expresses the rule.
+
+## 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.
+   ✓ The adapter import path (`permdock/<framework>`) and the validator import are named.
+2. **Define.** Create `src/permissions.ts`. Importable everywhere; no rules, no secrets.
+
+   ```ts
+   import {
+     definePermissions,
+     defineRoles,
+     definePlans,
+     resource,
+     crud,
+   } from "permdock";
+   import { Post } from "./schemas";
+
+   export const permissions = definePermissions({
+     post: resource(Post, crud({ relations: { author: "authorId" } })),
+   });
+   export const roles = defineRoles({ member: {}, admin: {} });
+   export const plans = definePlans({ pro: {} });
+   ```
+
+   ✓ 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.
+
+   ```ts
+   import { definePolicy, role, allow, principal, relation } from "permdock";
+   import { permissions, roles } from "./permissions";
+
+   const member = role(roles.member, [
+     allow(permissions.post.read),
+     allow(permissions.post.list),
+     allow(permissions.post.create),
+     allow(permissions.post.update, {
+       to: relation(permissions.post, "author"),
+     }),
+     allow(permissions.post.delete, {
+       where: { authorId: principal.id },
+       approval: "human",
+     }),
+   ]);
+
+   export const policy = definePolicy(
+     { permissions, roles },
+     {
+       roles: [member],
+       principal: (user) => user && { id: user.id, roles: user.roles },
+     },
+   );
+   ```
+
+   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)
+   ✓ 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.
+   ✓ 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. Add a `describePolicy` suite from `permdock/testing` ([scenario testing](https://permdock.dev/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-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.
+- `permdock-audit`: review the result or a pull request.
+
+## Verify before done
+
+- [ ] No string permission keys in app code; every check passes a reference.
+- [ ] `policy.ts` is imported only from server code, and PD001 is clean.
+- [ ] The subject resolver reads only the server session or a verified token.
+- [ ] `permdock collect --check` runs in CI, and a `describePolicy` suite covers the new grants.
+
+## 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).
+- The `permdock` skill: the mental model, `explain` for an unexpected denial, and the docs MCP.
+- Docs: [policies](https://permdock.dev/docs/concepts/policies), [conditions](https://permdock.dev/docs/concepts/conditions), [decisions](https://permdock.dev/docs/concepts/decisions), [adapters](https://permdock.dev/docs/adapters).