@fitzzero/quickdraw-skills 5.1.1 → 5.1.3

package/README.md

@@ -41,9 +41,12 @@ working on matching files.
 ## The command
 
 - `quickdraw-skills link` writes each link as a relative symlink into
-  `node_modules/@fitzzero/quickdraw-skills` (or into the package wherever it
-  is installed, when it is not at the repo root) in the nearest directory
-  above the working directory that holds `.git`. It replaces or prunes only
+  `node_modules/@fitzzero/quickdraw-skills`, in the project that installs
+  the package: the nearest directory above the working directory with a
+  `package.json` and `node_modules/@fitzzero/quickdraw-skills`, whatever
+  `.git` is around it. It fails when there is none, and refuses to link
+  into the home directory, whose `.claude` holds every project's settings.
+  It replaces or prunes only
   links that point into this package (through
   `@fitzzero/quickdraw-skills/`, or landing in its directory): a real file
   or directory, or another package's link, is left alone with a warning,

package/bin/cli.mjs

@@ -25,6 +25,13 @@
 // or `.claude/<kind>` is a symlink, or resolves outside the repo, that kind is
 // left alone with a warning, since relative links written through it would
 // land elsewhere (a shared or global directory) and resolve against it.
+//
+// The repo is the project that installs this package: the nearest directory
+// above the working directory with a `package.json` and
+// `node_modules/@fitzzero/quickdraw-skills`, whatever `.git` is around it (the
+// 5.1 audit's CLIENT-7: run by a consumer's `prepare` inside a dotfiles repo
+// in the home directory, it linked into `~/.claude`). It never links into the
+// home directory itself, whose `.claude` holds every project's settings.
 
 import {
   existsSync,
@@ -36,6 +43,7 @@ import {
   rmSync,
   symlinkSync,
 } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
@@ -45,8 +53,10 @@ const PACKAGE = "@fitzzero/quickdraw-skills";
 const USAGE = `Usage: quickdraw-skills link [--check]
 
   link            link this package's rules into .claude/rules and its skills
-                  into .claude/skills of the repo around the working directory,
-                  and prune links to rules or skills it no longer ships
+                  into .claude/skills of the project that installs the package
+                  (the nearest package.json above the working directory with
+                  node_modules/@fitzzero/quickdraw-skills), and prune links to
+                  rules or skills it no longer ships
   link --check    change nothing; exit 1 when a link is missing, stale or dangling
 `;
 
@@ -65,22 +75,33 @@ function fail(message) {
   process.exit(1);
 }
 
-/** The nearest directory above `start` that holds `.git`, else the nearest that holds `package.json`. */
-function findRepoRoot(start) {
-  for (const marker of [".git", "package.json"]) {
-    let dir = start;
-    for (;;) {
-      if (existsSync(join(dir, marker))) {
-        return dir;
-      }
-      const parent = dirname(dir);
-      if (parent === dir) {
-        break;
-      }
-      dir = parent;
+/**
+ * The nearest directory from `start` up that has a `package.json` and
+ * installs this package (`node_modules/@fitzzero/quickdraw-skills/package.json`):
+ * the project whose install runs the link. A `.git` around it plays no part.
+ */
+function findProjectRoot(start) {
+  const installed = join("node_modules", ...PACKAGE.split("/"), "package.json");
+  let dir = start;
+  for (;;) {
+    if (existsSync(join(dir, "package.json")) && existsSync(join(dir, installed))) {
+      return dir;
     }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return undefined;
+    }
+    dir = parent;
+  }
+}
+
+/** True when `dir` is the home directory, through any symlink. */
+function isHome(dir) {
+  try {
+    return realpathSync(dir) === realpathSync(homedir());
+  } catch {
+    return false;
   }
-  return undefined;
 }
 
 function isSymlink(path) {
@@ -125,17 +146,23 @@ const { check } = parseArgs(process.argv.slice(2));
 // This package's own directory, through any install symlink (bun and pnpm may
 // install it as a link into their store).
 const packageDir = realpathSync(dirname(dirname(fileURLToPath(import.meta.url))));
-const repoRoot = findRepoRoot(process.cwd());
+const repoRoot = findProjectRoot(process.cwd());
 if (repoRoot === undefined) {
-  fail("found no repo root (a .git or package.json) above the working directory");
+  fail(`found no package.json above the working directory that installs ${PACKAGE}`);
+}
+if (isHome(repoRoot)) {
+  fail(
+    "refusing to link into the home directory (~/.claude holds every project's settings): run quickdraw-skills link from the app's repo",
+  );
 }
 
 /**
  * What one kind links: its entries, where the links go, and the directory
- * they point into. Links prefer the stable `node_modules/@fitzzero/quickdraw-skills`
- * path, so committed links never embed a package store's hashed path; without
- * it (the package not installed at the repo root) they point at the package
- * where it is.
+ * they point into. Links name the project's stable
+ * `node_modules/@fitzzero/quickdraw-skills` path, which the project root
+ * always installs, so committed links never embed a package store's hashed
+ * path; only an installed copy that lacks this kind's directory (a broken
+ * install) makes them point at the package that runs.
  */
 function planKind(kind) {
   const sourceDir = join(packageDir, kind.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitzzero/quickdraw-skills",
-  "version": "5.1.1",
+  "version": "5.1.3",
   "description": "Agent rules and skills for quickdraw 5.0 apps, linked into .claude/ by the quickdraw-skills command",
   "keywords": [
     "agents",

package/rules/quickdraw-access.md

@@ -18,15 +18,15 @@ unknown level or a malformed access list denies.
 
 Every method's `{ access, handler }` names one form:
 
-| Form                              | Passes when                                                                                 |
-| --------------------------------- | ------------------------------------------------------------------------------------------- |
-| `"public"`                        | always, with or without a principal                                                         |
-| `"authenticated"`                 | a principal exists                                                                          |
-| `{ service: L }`                  | the principal's service-wide grant is at least `L`                                          |
-| `{ entry: L, id? }`               | the policy gives the principal at least `L` on the row (`id` defaults to `input.id`)        |
-| `{ service: L1, entry: L2, id? }` | either of the two                                                                           |
-| `{ scope: L, of: contract, id }`  | at least `L` on a row of another service, whose id is `input[id]` (create and list methods) |
-| `custom((ctx, input) => boolean)` | the function resolves `true` (a principal is required first)                                |
+| Form                              | Passes when                                                                                                                        |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `"public"`                        | always, with or without a principal                                                                                                |
+| `"authenticated"`                 | a principal exists                                                                                                                 |
+| `{ service: L }`                  | the principal's service-wide grant is at least `L`                                                                                 |
+| `{ entry: L, id? }`               | the policy gives the principal at least `L` on the row (`id` defaults to `input.id`)                                               |
+| `{ service: L1, entry: L2, id? }` | either of the two                                                                                                                  |
+| `{ scope: L, of: contract, id }`  | at least `L` on a row of another service, whose id is `input[id]` (create and list methods)                                        |
+| `custom((ctx, input) => boolean)` | the function resolves `true` (a principal is required first); it replaces the row check, and a service-wide `Admin` grant skips it |
 
 - Levels are `"Read" < "Moderate" < "Admin"` (`AccessLevel` also has
   `"Public"`). `id` is an input key (type-checked) or a function of the input.
@@ -69,34 +69,127 @@ export const tokenService = qd.defineService(token, {
   list, which holds for signed-in callers.
 - A service's list also refuses other kinds on `qd:sub`, `qd:col:sub`,
   `qd:watch` and `qd:stream:sub`, and its channels drop their messages.
+- Kinds separate only what the hooks label: label an MCP caller
+  `kind: "agent"` in the bridge's `principal` hook (`bearerAuth` with
+  `loadPrincipal: (userId) => ({ userId, kind: "agent" })`), or a method
+  with `kinds: ["user"]` lets it in as a user. An MCP custom tool obeys the
+  app's kinds too, and takes `kinds` of its own within them, never a kind
+  check in its handler.
 - Never check the kind in a handler (`if (ctx.principal.kind !== "user")
 throw ...`; `no-inline-auth-guard` reports it) or in a `custom` form:
   `kinds` combines with any form (`{ entry: "Moderate" }` and
   `kinds: ["user"]`), where `custom` would have to check the row by hand.
-  A check on a claim, such as a token's `scope`, stays `custom`.
+  A check on a claim, such as a token's `scope`, is `claims`, never
+  `custom` (below).
+
+## A requirement on the caller's claims
+
+A check on the caller's verified claims (`principal.claims`, a token's
+`scope`) is `claims`, beside `access` on the method:
+
+```ts
+triage: {
+  // Moderate on the task's project, from a token that may triage: claims add to the form
+  access: { entry: "Moderate" },
+  claims: (claims, input) => claims?.scope === "triage" && input.status !== "archived",
+  handler: ({ input, db }) =>
+    db.task.update({ where: { id: input.id }, data: { status: input.status } }),
+},
+```
+
+- It adds to the form: `triage` needs Moderate on the task's project and a
+  triage token. Never write it as `custom`: that form replaces the row
+  check, so any token holding the claim would write every tenant's rows,
+  and a service-wide `Admin` grant skips it.
+- It runs right after `kinds`, outside the access engine, so no grant passes
+  it, a service-wide `Admin` grant included. Without a principal the call
+  is `UNAUTHENTICATED`; when it returns anything but `true`, `FORBIDDEN`.
+- It is synchronous, and a `"public"` method takes none.
+- A token narrowed by `claims` is narrowed only on the methods that declare
+  it; elsewhere it acts with its user's grants (`kinds` keeps a kind of
+  token out).
+
+## A row the form cannot name
+
+A check of the caller's level on a row no declared form names (a parent
+the input names, a key that is optional) is a `custom` form that asks
+`ctx.access`: never a check in the handler, and never a module that holds
+the dispatcher.
+
+```ts
+assigned: {
+  // Read on the project the input names, asked through ctx.access; none named, the caller's
+  // own that they may still read
+  access: custom(
+    async (ctx, input) =>
+      input.projectId === undefined || (await ctx.access.can(project, input.projectId, "Read")),
+  ),
+  handler: async ({ input, ctx, db }) => {
+    const readable = await ctx.access.where(task, "Read");
+    if (readable === "none") return [];
+    return db.task.findMany({
+      where: { AND: [{ assigneeId: ctx.principal.userId, projectId: input.projectId }, readable] },
+      take: 100,
+    });
+  },
+},
+```
+
+- `ctx.access.can(service, id, level)`, `levelsFor(service, ids)` and
+  `where(service, level)` count levels as `{ entry }` does, for
+  `ctx.principal` with the grants the call runs with: never load the user's
+  grants again. `service` is a contract or a service name.
+- A list the form lets through without its key still follows the row
+  policy: add `ctx.access.where(service, "Read")` to its `findMany` with
+  `AND` (`"none"` lists nothing). Never spread it into `where`: the filter
+  and the input share a column (`inherit`'s `projectId`), so whichever
+  comes last replaces the other. The filter's widens the keyed list to
+  every project the caller reads; the input's `undefined` drops the policy
+  from the list without a key.
+- Prefer a declared form when one says it: `{ entry: L }` for the method's
+  own row, `{ scope: L, of, id }` for a parent whose key is always there.
+  A `ctx.access` form counts a service-wide `Admin` grant on the service it
+  asks (the parent's); `{ scope, of }` counts only one on the method's own
+  service. `custom` replaces the row check and a
+  service-wide `Admin` grant skips it, so a method whose input has `id`
+  still needs `rowless: true` beside it (below).
+- An anonymous caller has no level anywhere (`false`, an empty map,
+  `"none"`). `qd` has no `access`: a job asks `server.dispatcher.access`.
 
 ## A method that takes a row id
 
 On a service with a policy, a method whose input has `id` reads or writes
-the row that id names. Under a form that checks no row (`"public"`,
-`"authenticated"`, `{ service: L }` below `Admin`), anyone the form admits
-reaches any row by its id, so `defineService` refuses it when the service is
-defined. Fix the form, not the error:
+the row that id names. Under a form that asks the policy nothing about that
+row, anyone the form admits reaches any row by its id, so `defineService`
+refuses it when the service is defined. Those forms are the ones that check
+no row (`"public"`, `"authenticated"`, `{ service: L }` below `Admin`),
+`custom(fn)`, `{ scope, of, id }` (a row of another service) and
+`{ entry, id }` naming another key. Fix the form, not the error:
 
 - Give it `{ entry: L }` (`"Read"` for a read, `"Moderate"` for a change),
   or `{ service: L, entry: L }` to keep a service grant: the policy decides.
 - Only when every caller the form admits may reach any row on purpose (a
-  public profile, a lookup by an id that tells nothing) say so with
-  `rowless: true` on the method, or `rowless: ["get"]` in a kit's options
-  (`crud.handlers`, `admin.handlers`, `sharing.handlers`).
-- The read/write kit's `update`, `delete`, `reorder` and `create` check the
-  row themselves and need neither.
+  public profile, a lookup by an id that tells nothing), or when `id` names
+  a row the method creates (an id the client made, under a `scope` form),
+  say so with `rowless: true` on the method, or `rowless: ["get"]` in a
+  kit's options (`crud.handlers`, `admin.handlers`, `sharing.handlers`). A
+  `rowless` query under a form that checks no row also answers "not
+  modified" for any `id`.
+- The read/write kit's `update`, `delete` and `reorder` check the row
+  themselves and need neither. `create` makes a new row and checks no row of
+  its own: it checks the anchors it writes (each `inherit` parent and
+  anchored collection's scope column, from what `prepare` returns) at the
+  method's row level, and takes a column the policy reads only from
+  `prepare` (`ownerId: ctx.principal.userId`), unless the caller holds a
+  service-wide `Admin` grant. Give it
+  `{ scope: "Moderate", of: project, id: "projectId" }`.
 - The check reads the input's keys from its JSON Schema: an `id` in any
   branch of a union counts, as does one beside a `Date` or a `Set`. An input
   without JSON Schema (a Zod 3 schema) or one that names no keys (a
-  `todoSchema` without `keys`), a bare string that is the id itself
-  and a row named by another key (`taskId`, `ids`) are not checked, so the
-  form is all yours there (`{ entry: L, id: "taskId" }` names another key).
+  `todoSchema` without `keys`), a bare string that is the id itself, a row
+  named by another key (`taskId`, `ids`) on an input without `id`, and an
+  `entry` form whose `id` is a function are not checked, so the form is all
+  yours there (`{ entry: L, id: "taskId" }` names another key).
 
 ## Service-wide grants
 
@@ -110,8 +203,9 @@ its first call. With
 tracked write to that column refreshes the user's open sockets, and an
 in-process caller loads the grants again at its next call.
 
-- A service-wide `Admin` grant passes every check on its service
-  (`adminBypass: false` on the service turns that off).
+- A service-wide `Admin` grant passes every access form on its service
+  (`adminBypass: false` on the service turns that off), though not `kinds`
+  or `claims`.
 - A grant below `Admin` counts only where the form names `service`: a `Read`
   grant does not read every row through an `entry` form.
 
@@ -153,7 +247,23 @@ compile time.
   job, alone or in `anyOf`.
 - Lookups are batched per call: checking 60 ids costs what one does.
   `createServer({ access: { cacheMs } })` keeps them across calls; tracked
-  writes to the columns and tables a policy reads evict them.
+  writes to the columns and tables a policy reads evict them. A lookup
+  inside a transaction always reads the database.
+- Membership and junction tables need an `id` column
+  (`id String @id @default(cuid())`, the pair unique by `@@unique`), never a
+  composite `@@id`: the write tracker keys rows by `id`, so such a table is
+  never tracked and a removed member is never revoked. `createServer` logs
+  `[quickdraw:untracked-access-model]` as an error for one, and a strict
+  test app fails to start. A foreign key set through a relation on the
+  written row (`task.update({ data: { project: { connect } } })`) revokes
+  like a scalar one; one set from the parent's side
+  (`project.update({ data: { tasks: { connect } } })`) is a nested write
+  whose rows are not tracked: write the foreign key on the row itself.
+- Never pass Socket.IO's `connectionStateRecovery` in `createServer({ socket })`:
+  a recovered socket comes back with its principal and rooms without
+  authenticating again, so a revoked session or a lowered grant would
+  return. `createServer` refuses it; clients resume by revision on every
+  reconnect.
 
 ## One policy, every surface
 
@@ -162,10 +272,18 @@ collection scopes (through the collection's `anchor`), the rows the kits'
 `list`, `getMany`, `search` and bulk methods return or write, streams and
 channel `requires`.
 
-- Everyone who may open a collection scope sees every item in it, stripped
-  at the collection's `access` level (default `Read`). Per-row policies and
-  field tiers do not apply inside a collection: give the item service
-  `inherit` from the anchor, or use separate scopes.
+- Everyone who may open an anchored collection scope sees every item in it,
+  stripped at the collection's `access` level (default `Read`). Per-row
+  policies and field tiers do not apply inside an anchored scope: give the
+  item service `inherit` from the anchor, or use separate scopes. A self
+  scope (`scopeAccess: "self"`) is the exception: its items follow the item
+  service's policy, so its user gets only the rows they may read.
+- A list whose methods need a service-wide grant (`{ service: "Read" }`)
+  needs it too: `requires: { service: "Read" }` beside its `anchor` or
+  `scopeAccess`, in `defineService`'s `collections`. Both checks apply (a
+  service-wide `Admin` passes either), a scope without the grant is
+  `FORBIDDEN`, and a reload of the user's grants below it revokes the scope
+  on their sockets. Without it a self list opens for any signed-in user.
 - A hand-written method that reads many rows authorizes the parent
   (`{ scope: "Read", of: project, id: "projectId" }`) and filters by it, or
   uses the read/write kit's `list` or a collection, which filter by policy.
@@ -194,7 +312,19 @@ channel `requires`.
 
 - Change access lists and memberships with the sharing kit
   (`sharing.contract({ mode: "acl" | "members" })`), which refuses granting
-  above the caller's own level and removing the last `Admin`.
+  above the caller's own level, changing or removing a user above it (equal
+  may; roles that map to one level are peers, so protect an owner with an
+  owner column), and removing the last `Admin`. Its `resolveUser` returns
+  exactly one user or `null`: an email with `findUnique`, a name only when
+  `findMany({ where: { name }, take: 2 })` finds one; never `findFirst` by
+  name. Without a
+  service-wide `Admin` grant, the read/write and admin kits refuse a
+  membership table's entry, user and role columns, whichever policy reads
+  them. They also refuse a column the policy reads. That holds even for a
+  column an anchored collection scopes by.
+- Give a bulk method (`bulkUpdate`, `bulkDelete`) a form with a row level,
+  or the same form as `update` or `delete`: under a form that names none,
+  it takes the counterpart's row level only from an `{ entry: L }` form.
 - Write policy columns and membership rows through the tracked `db`: the
   flush then revokes what a demoted user held (`qd:revoked`), moves them to
   their new field tier, and updates `via` collections. A write the tracked

package/rules/quickdraw-client.md

@@ -34,22 +34,37 @@ export function Providers({ children }: { readonly children: React.ReactNode })
   (`qd.taskService.board`); the examples here key theirs short (`qd.task`).
 - `auth` is a token (sent as `auth.token`) or handshake fields; leave it out
   for cookie sessions. Changing it reconnects, and a hello naming another
-  user empties everything quickdraw cached.
+  user empties everything quickdraw cached, the placeholder a member's
+  `useQuery` or `useSearch` would make from it (`keepPreviousData`, the
+  last results) included.
 - `useQuickdraw()` gives
   `{ connection, status, isConnected, isKnown, reconnecting, userId, serviceAccess, hello, refusal, isRateLimited }`.
   Gate on `isKnown` (the server's hello named the user; `userId` is then
   final, `null` meaning signed out), never on `isConnected` or `userId`
   alone: `userId` is `null` before the hello too, `isConnected` turns true
   before it and false while reconnecting, and `reconnecting` keeps the user.
+  While `isKnown` is false, `status` `"disconnected"` or `"refused"` means
+  signed out: the server ended the session (signed out elsewhere, revoked,
+  expired) or refused a connect for it, the hello is gone and quickdraw's
+  cache is empty; any other status is still connecting. Never keep showing
+  data the app holds itself once `isKnown` turns false. A server that could
+  not check the credentials (its session store down: the handshake is
+  refused `INTERNAL`) signs nobody out: the connection keeps the user and
+  the cache, stays `connecting` (`reconnecting` once it had connected) and
+  connects again by itself, so never treat that as a sign-out. On the
+  server, `authenticate` refuses credentials only by throwing
+  `QuickdrawError("UNAUTHENTICATED")` (or `"FORBIDDEN"`); anything else it
+  throws is an outage.
   `hello.serverId` changes when the server restarts (or the socket lands
   on another node): compare it to tell a new server from a network blip.
 - Sign-in and out in the browser go through the auth routes kit's routes:
   `authProviders()` lists the sign-ins the API serves (render a button for
   those only, never from build-time flags), `signInUrl(provider, {
 returnTo })` is the provider button's link, `signOut()` and
-  `signOutEverywhere()` end the session (they reject when refused). Never
-  call `/auth/...` by hand; 4.x's `getOAuthUrl`, `logout` and
-  `logoutAllDevices` are gone.
+  `signOutEverywhere()` end the session (they reject when refused); then
+  call `connection.close()` and `open()` (or reload), since a socket keeps
+  its user until it connects again. Never call `/auth/...` by hand; 4.x's
+  `getOAuthUrl`, `logout` and `logoutAllDevices` are gone.
 
 ## Reading
 
@@ -151,6 +166,35 @@ await rename.mutateAsync({ id, title }); // resolves with the output, rejects wi
   the user's say). Never join from a plain `useQuery` or a
   mount effect: a reconnect leaves the socket out of the room while the
   cached answer still looks fine. Without React, `connection.onHello`.
+- Peer links: on a server created with `peers: true`,
+  `createPeerLink(connection, { room, to, offerer })` (in React,
+  `useQuickdraw().connection`) links two sockets of an app room over
+  WebRTC data channels, or over the server's relay when those cannot form.
+  The peer's socket id comes from the app (an event carrying
+  `ctx.socketId`, a method's answer); `onPeerRequest(connection, listener)`
+  answers a peer that linked first. Send input at a tick rate on `fast`
+  (unordered, never resent) and state on `rel` (ordered, reliable). A link
+  dies with its socket: open it again on every connection, as `useJoin`
+  joins again. What a peer sends is the peer's word, never checked by the
+  server: parse each message with its schema as untrusted input. Never
+  send `qd:peer` or `qd:relay` by hand (`no-raw-socket`). To play over a
+  bad network in a browser test or a bench, `link.setLag({ ms, jitter,
+loss })` lags the link's own messages both ways on its real path (`rel`
+  never lost, `stats.simulatedLoss` for the rest); never a proxy or a
+  hand-made delay around `send`.
+- Host mode: a player's `useStream` and `useChannel` of a host-served
+  member (`serve: "host"`) reach the room's host over a link, with no
+  change in the app; a channel's messages go on `fast`, so send input
+  every frame, never once. The host's client serves the members with
+  `defineHost(contract, { channels, streams }).serve(connection, { room })`
+  while `hostOf(connection, room)` is its own socket's id
+  (`onHostChange(connection, listener)` hears it change), and calls
+  `close()` when it is not. A host checks what players send it against the
+  contract, but each message stays that player's word, and what the host
+  sends is the host's word. Each of `host.peers` (and a handler's
+  `ctx.peer`) has `link`: read a player's round trip from
+  `link.clock.rtt`, and give the host's own play its players' lag with
+  `setLag` on the host's own entry, whose link is in process.
 - Admin screens: `qd.task.admin.adminList.useQuery(input)` and the other
   admin kit members; `useAdminServices(qd)` lists the services whose
   `adminMeta` answers the user, asking only those the hello's grants allow
@@ -158,9 +202,14 @@ await rename.mutateAsync({ id, title }); // resolves with the output, rejects wi
   `adminMeta` wider). A screen served from metadata for every service takes
   `adminOf(qd, key)`, one shape typed by field name: never cast
   `qd[key].admin`. The kit's rows are not live: after the screen's own
-  write, `onSuccess: () => qd.invalidate(qd.task.admin.adminList)`. A
-  generic form shows the fields whose `showInForm` is not `false`; a user's
-  grants field says `kind: "grants"`: find it by that, never by its name.
+  write, read the page again (`qd.invalidate(qd.task.admin.adminList)`)
+  and put the row the write returned in the cache
+  (`qd.task.admin.adminGet.setData({ id: row.id }, row)`; `adminOf`'s
+  query members have `setData` too), never in React state. Its reads of
+  rows default to `staleTime: 0`, read again on every mount (`adminMeta`
+  stays cached): pass a `staleTime` only to keep a page longer. A generic
+  form shows the fields whose `showInForm` is not `false`; a user's grants
+  field says `kind: "grants"`: find it by that, never by its name.
 
 ## Server components and other runtimes
 
@@ -171,10 +220,13 @@ await rename.mutateAsync({ id, title }); // resolves with the output, rejects wi
   `caller.task.get.prefetch(queryClient, input)` fills the keys the hooks
   read, for `dehydrate` and `HydrationBoundary`.
 - React Native uses the same client and provider (no DOM is needed).
-  React-free code (a Node script, a worker) makes a connection with
+  React-free code (a Node script, a CLI, a worker) imports
+  `@fitzzero/quickdraw-core/client/core`, which needs neither React nor
+  TanStack Query installed: it makes a connection with
   `createQuickdrawConnection({ url, auth })`, calls `open()`, and calls
-  `callData(connection, { service: "taskService", method: "get", input })`
-  from `./client`; `liveDataOf(connection, queryClient)` holds live rows.
+  `callData(connection, { service: "taskService", method: "get", input })`.
+  `./client` re-exports the same functions. Live rows need a TanStack
+  `QueryClient`: `liveDataOf(connection, queryClient)` from `./client`.
 - A client in another language (a Godot game, a native app) speaks the wire
   itself: `docs/protocol-v5.md` in the quickdraw repository is the
   specification, `examples/godot` a GDScript client written from it, and

package/rules/quickdraw-services.md

@@ -49,7 +49,8 @@ export const task = defineContract("taskService", {
 - Methods, collections, streams, channels and events share one namespace
   (`qd.<service>.<name>` on the client). `subscribe`, `unsubscribe`, `call`,
   `then`, `useEntity`, `useEntities`, `admin` and `$`-names are reserved.
-  A contract without `entity` is an RPC-only service.
+  A contract without `entity` is an RPC-only service. A service name holds
+  no `:` or `@` (it is part of every room name of the service).
 
 ## The service implements it
 
@@ -82,6 +83,16 @@ export const taskService = qd.defineService(task, {
   quickdraw-access.md), `timeoutMs`, and for queries `share` (`"caller"` or
   `"all"`), `ttlMs` and `version`. A service takes `kinds` too: the kinds of
   principal its methods and subscriptions admit.
+- `share: "all"` runs one handler for every caller, with the first caller's
+  `ctx`, and gives every caller its result: use it only for a result that
+  depends on the input alone. Its handler reads nothing of the caller
+  (`ctx.principal`, `ctx.services`, `ctx.mcp`, `ctx.access`, or a context
+  field made from them); in development a read of one of the first four warns
+  `[quickdraw:shared-principal]`. It is refused with `custom` access and on
+  the kit methods whose result depends on the caller (the read/write kit's
+  `list` and `getMany`, `search`, the sharing kit's `listShares` and
+  `listMembers`, the admin kit's `adminList` and `adminGet`): give those
+  `share: "caller"`.
 - A handler receives `{ input, ctx, db }`: the parsed input, the context
   (`principal`, `signal`, `log`, `requestId`, `transport`, `touch`, `rooms`,
   `presence`, `mcp`, `services`) and the tracked client.
@@ -100,6 +111,10 @@ export const taskService = qd.defineService(task, {
   and is cancelled with `ctx.signal`; it is typed by the app's `contracts`
   (`initQuickdraw<{ ...; contracts }>()`). Never write another service's
   model directly to skip its access checks.
+- A call through `ctx.services` carries this call's `ctx.mcp`, nested calls
+  too, so in an MCP call the method it reaches sees the token's fields. Its
+  `ctx.transport` is `"internal"`: tell a token's call apart by `ctx.mcp`,
+  never by `ctx.transport === "mcp"`.
 
 ## REST routes call the services
 
@@ -135,6 +150,35 @@ principal that carries `serviceAccess` keeps exactly those grants. Never
 read `req.userId` through a cast, and never build a principal with grants
 by hand to get past a check.
 
+Authentication goes through the auth routes kit's helpers, which check the
+session store on every call, so a signed-out or revoked session stops at
+once:
+
+- `socketAuth(...)` is `createServer`'s `authenticate`: the session cookie
+  from an allowed page (the Origin rule), or a bearer token.
+- `requireSession(keys)` guards the app's own REST routes.
+- `bearerAuth(...)` is for a hook handed a bearer token alone: the MCP
+  bridge's `principal`, an `authenticate` that reads `auth.token`.
+- An app's own MCP transport, or an in-process assistant, that signs the
+  caller in itself (with `requireSession`, say) passes that caller to the
+  registry: `registry.callMethod(service, method, input, { request, principal })`.
+  The registry's `principal` hook is not asked (`null` calls anonymously),
+  the `context` hook and bound arguments see that principal, and its grants
+  load as `qd.caller`'s do. Never take it from a request body, and never
+  smuggle the user to the hook some other way (a map keyed by the request).
+- Never `verifyJWT` alone: it checks the signature and expiry, not the
+  session store.
+- A custom `authenticate` takes the session cookie only from
+  `request.sessionCookie` (HTTP), after `cookieOriginAllowed(request,
+allowedOrigins)`, and checks it with `liveSession`; `auth.token` holds
+  only a bearer token for it.
+- `authenticate` refuses credentials only by throwing
+  `QuickdrawError("UNAUTHENTICATED")` (or `"FORBIDDEN"`). Anything else it
+  or `loadServiceAccess` throws is an outage (the store or the database
+  down): a socket's handshake is refused `INTERNAL`, and the client keeps
+  the user and connects again by itself. Never throw a plain `Error` for
+  bad credentials, which the client would retry for ever.
+
 ## Writes are tracked; frames are derived
 
 Entity frames, collection deltas and change topics are computed from the
@@ -145,6 +189,16 @@ writes made through `db`, after the response is sent:
   wrap the work in `qd.run(async (ctx) => ...)`, which flushes before it
   returns; a boot-time seed may run it before `createServer` too (its writes
   then reach no subscriber). Never write through the untracked client.
+- A helper that writes takes the tracked client by its type:
+  `client: Tracked<PrismaClient>`, or `TrackedTransaction<PrismaClient>`
+  when it may run inside `db.$transaction(async (tx) => ...)` (`tx` is
+  one, and so is `db`). `trackPrisma` returns a `Tracked<PrismaClient>`;
+  the untracked client is none, so passing it is a type error. Both types
+  are on `@fitzzero/quickdraw-core/prisma` and the root export. Never type
+  such a parameter `PrismaClient`, which the untracked client is too;
+  `no-untracked-write` reads the type, whatever the parameter's name. A
+  `db` declared `PrismaClient` (a lazy `Proxy`, say) carries no mark:
+  declare it `Tracked<PrismaClient>` to pass it to such a helper.
 - Background work a handler starts and does not await (a push sent after
   the reply) runs in `qd.run(fn, { detached: true })`: a unit of its own,
   flushed when `fn` settles. Without `detached` it joins the handler's unit,
@@ -157,7 +211,10 @@ writes made through `db`, after the response is sent:
   `db.$transaction(async (tx) => ...)` when they must commit together.
 - Raw SQL writes and database cascades are not seen: record them with
   `ctx.touch("task", ids)` (`{ removed: true }` for deleted rows); `qd.run`
-  passes `fn` the same `touch`.
+  passes `fn` the same `touch`. Before deleting a row whose dependents the
+  database deletes or clears (`onDelete: Cascade`, `SetNull`), delete or
+  clear them through `db` first, in the same transaction, so the lists
+  holding them are told; for the admin kit, in its `prepare`.
 - A write to one row that changes how another service's row looks (a
   parent's counts) declares `affects: [{ service: task, id: "parentTaskId" }]`.
 
@@ -169,9 +226,16 @@ in `id`), and optionally `where`, `limit`, `maxLimit`, `index` (small fields
 sent for the whole scope), `views` (`(row, who) => boolean` over index rows)
 and `access`. The service says who may open a scope: `{ anchor: project }`
 (the level on the row the scope value names) or `{ scopeAccess: "self" }`
-(the subscriber's own user id). Everyone in a scope sees every item, so
-derive the item service's access from the anchor (`inherit`). An item that
-reads its `via` junction (a member count) declares
+(the subscriber's own user id), plus `requires: { service: "Read" }` when
+the list must need the service-wide grant its methods ask for
+(`{ scopeAccess: "self", requires: { service: "Read" } }`: the user's own
+rows, for holders of the Read grant); both checks then apply, and a socket
+whose grants reload below it leaves the scope. Everyone in an anchored scope sees every
+item, so derive the item service's access from the anchor (`inherit`); a
+self scope's items follow the item service's policy, so its user gets only
+the rows they may read. A `via` scope over the item service's own `members`
+table counts only links whose role gives at least the collection's
+`access`. An item that reads its `via` junction (a member count) declares
 `via({ model, entry, scope, refreshEntry: true })`, or the count goes stale
 in every scope but the one a membership write links.
 
@@ -201,10 +265,17 @@ Contract halves come from `@fitzzero/quickdraw-core`, handlers from
   `admin.contract` too, so the input schemas and MCP tools name only those):
   every other field is read-only, and a write naming one is `VALIDATION`.
   Without it the kit writes every field it shows but `id` and the
-  timestamps, owner and foreign-key columns included.
+  timestamps, owner and foreign-key columns included. No kit ever writes a
+  relation field or a nested write (`{ connect }`, `{ update }`): either is
+  `VALIDATION`, whoever the caller, and `adminMeta` shows a relation field
+  (one a projection selects with a nested select) as read-only.
   On a users service, `admin.handlers(user, { grants: true })` lets the admin
-  screen edit `serviceAccess` through `adminUpdate` (service-wide Admins
-  only); never hand-write a `setServiceAccess` method for it. `adminMeta`
+  screen edit `serviceAccess` (or the column `auth.serviceAccessSource`
+  names, whatever its name) through `adminUpdate` (service-wide Admins
+  only); never hand-write a `setServiceAccess` method for it. A dispatcher
+  made without `createServer` (HTTP only, an MCP process) names that column
+  as `createDispatcher({ serviceAccessSource })`. Without
+  `grants: true` the kit hides that column. `adminMeta`
   marks that field `kind: "grants"`; an app with a grants editor of its own
   keeps it out of the generic form with
   `fieldOverrides: { serviceAccess: { showInForm: false } }`. What an admin
@@ -213,19 +284,33 @@ Contract halves come from `@fitzzero/quickdraw-core`, handlers from
   `onCommitted`, which runs once it committed, in a unit of its own (a
   game applying an edited definition to its running simulation, so a
   rolled-back edit is never applied); never wrap the kit's handlers.
+  What must happen before an edit goes in `prepare(call, ctx, db)`, in
+  the same transaction: a column the server computes (a content hash) is
+  returned from it and written over the caller's data, even a hidden or
+  read-only one (never `id`, a timestamp or a relation; a parent it sets
+  needs the caller's row level on it, as in the read/write kit), so it
+  need not be an editable field of the entity; and before an `adminDelete`
+  it deletes or clears through `db` the rows the database would cascade,
+  so their subscribers and lists are told.
 
 ## Realtime
 
 - Streams: `streams: { logs: { item, scope: "taskId", seed: 50, access } }`;
   push with `qd.stream(task, "logs").push(taskId, item)`, and several items
-  at once with `pushMany(taskId, items)`, never `push` in a loop. When the
+  at once with `pushMany(taskId, items)`, never `push` in a loop. A job that
+  skips feeds nobody watches asks
+  `await qd.stream(task, "logs").subscribers(taskId)` (the sockets on every
+  node), never Socket.IO's adapter rooms, which hold one node's. When the
   items are deltas (a game's ticks), give the service a computed seed,
   `streams: { world: { seed: (worldId, ctx) => [snapshotOf(worldId)] } }`,
   never a bootstrap call beside the stream; `validate: "development"` there
   skips the per-item schema check in production for a hot stream. A feed
-  only a room's sockets may read takes `access: { room }` (a name,
-  `{ prefix }`, or `(scope) => room`), never an entry policy that repeats
-  the room's membership.
+  only a room's sockets may read takes `access: { room }`, never an entry
+  policy that repeats the room's membership: a scoped stream computes the
+  room from its scope, ``{ room: (worldId) => `world:${worldId}` }``, and
+  only a global stream names it or takes `{ prefix }` (on a scoped stream
+  those would let a socket in one world read every world, so
+  `defineContract` refuses them).
 - A query over a model the service only `writes` (no service owns it)
   declares `watch: { service: ["gameScore"] }`, naming the models it reads
   (the service's `model` and its `writes`), with `watchAccess` on the
@@ -241,19 +326,65 @@ Contract halves come from `@fitzzero/quickdraw-core`, handlers from
   computes it, `{ room: { prefix: "world:" } }` takes any room with that
   prefix. The handler reads the matched room as `ctx.room`; never repeat a
   world's id in every input frame. 4.x's `requireRoom` becomes `{ room }`.
+  Give every channel a `requires`: without one any signed-in user may send
+  it, about any room its payload names, and the server warns
+  `channel-without-requires`. A handler that relays a message emits to
+  `ctx.room`, never to a room built from the payload. Only when any
+  signed-in user may send it, say so on the service:
+  `channels: { ping: { access: "authenticated", handler } }`.
 - A game loop asks `qd.rooms.size(room)` (this node's sockets, spectators
   included, synchronous) at its tick rate, never Socket.IO's adapter;
   `ctx.socketId` names the calling socket in a method.
+- Peer links: `createServer({ peers: true })` lets two clients of an app
+  room link directly (`createPeerLink` on the client). The server forwards
+  their signals and relays their messages only between signed-in sockets
+  of the room, and ends a player's links when they leave it or
+  `rooms.leave(room, { userId })` takes them out. Tell players each other's
+  socket ids with an event or a method's answer (`ctx.socketId`). The
+  server never sees what a link carries: a method that records what a
+  client reports from a link (a score, a winner) checks it as untrusted
+  input, and its contract's `describe` says so.
+- Host mode: a channel or stream declared `serve: "host"` is served by the
+  room's host, one player's client (`defineHost` on the client), over peer
+  links; the server needs `peers: true` and never handles it. A
+  host-served channel declares `requires: { room }` and a host-served
+  stream a scope and `access: { room: (scope) => room }`. Give a
+  host-served channel no handler and a host-served stream no options or
+  seed: `defineService` refuses them. Pick the host in a method,
+  `ctx.rooms.setHost(room)` for the calling socket (after a check of the
+  app's own: a seat, a role), never by election; read it with
+  `ctx.rooms.hostOf(room)`, clear it with `clearHost(room)`, and decide
+  what follows in `onHostLeave({ room, socketId, principal, reason })`.
+  Behind a cluster adapter, a node that dies without closing its sockets
+  leaves the hosts it held recorded on the other nodes until each room's
+  host is set or cleared again, and no `onHostLeave` runs for them. So
+  when the app picks a host only while `hostOf(room)` is `null`, also let
+  a player take over a host that stops answering: a method that calls
+  `setHost(room)` or `clearHost(room)` after a timeout of the app's own.
+  The server never sees what a host and its players send each other: what
+  a host reports to a method (a result, a score) is one player's word,
+  checked as untrusted input, and the contract's `describe` says so. The
+  service's `kinds` does not reach host-served members: any signed-in
+  socket of the room can link to the host, so guard the method that joins
+  the room.
 - Events: `events: { moved: { payload } }`, sent with
   `ctx.rooms.emit(room, task, "moved", payload)` to an app room
-  (`ctx.rooms.join(room)` in a method puts the caller's socket in one).
+  (`ctx.rooms.join(room)` in a method puts the caller's socket in one), and
+  to a user's sockets with `ctx.rooms.emitToUser(userId, ...)`, never
+  `emit("user:...")` (refused, as are `qd:` rooms). Name app rooms with a
+  prefix (`doc:${id}`), never a bare 20-character id: a name with the shape
+  of a Socket.IO socket id is refused.
   Code that is not a handler (a game loop, a timer, a job) sends with
   `qd.rooms.emit(room, task, "moved", payload)`; never keep the `io` server
   to emit by hand.
 - When a user loses the right to a room (removed from a chat, kicked from a
   game), `await ctx.rooms.leave(room, { userId })` (or `qd.rooms.leave`)
   takes all their sockets out on every node, before anything they must not
-  hear is sent. 4.x's "emit to the user instead of the room" workaround is
+  hear is sent; a sharing kit's `onChange` does it for a user a change left
+  below the room's join check (`change.after === null`, or with custom
+  `members` `levels`, a role below that level too), inside the change's
+  transaction (a join racing the commit can put them back until they
+  disconnect). 4.x's "emit to the user instead of the room" workaround is
   not needed.
 - React to a socket leaving with the service's own `onRoomLeave`
   (`defineService(game, { onRoomLeave })`, beside `methods`), never with
@@ -268,8 +399,10 @@ Contract halves come from `@fitzzero/quickdraw-core`, handlers from
 
 Bound every `findMany` with `take`; batch per-item reads with `in:` filters;
 filter in `where`, not after loading. Write many rows in one statement when
-they all get the same data (`updateMany`, `createMany`). When each row's
-data differs, loop over the rows inside an interactive
+they all get the same data (`updateMany`, `createMany`); a large insert may
+go in fixed-size `createMany` chunks, which neither `no-db-call-in-loop` nor
+the N+1 warning counts. When each row's data differs, loop over the rows
+inside an interactive
 `db.$transaction(async (tx) => ...)` and await one `tx.task.update(...)` by
 id per row, not an array-form `$transaction([...])`, which cannot read a
 moved row inside its batch. A projection's relation count selects the
@@ -283,9 +416,11 @@ matches no row or has nothing to write (`data: {}`) signals nothing; every
 other write signals, one that sets a column to the value it already holds
 too, so re-ensure a row with that upsert rather than by writing its values
 again.
-`share: "caller"` for hot queries;
-`versionColumn: "updatedAt"` answers "not modified" cheaply. The quickdraw
-lint rules enforce most of this file (`no-untracked-write`,
+`share: "caller"` for hot queries (`"all"` only for a result that depends
+on the input alone); `versionColumn: "updatedAt"` answers "not modified"
+cheaply, for a query whose form checked the row its `id` names (an `entry`
+form on `id`), or that says `rowless: true` under a form that checks no
+row. The quickdraw lint rules enforce most of this file (`no-untracked-write`,
 `no-foreign-write`, `no-nested-write`, `no-raw-sql-write`, `no-manual-emit`,
 `no-unbounded-read`, `no-db-call-in-loop`, `no-load-then-filter`,
 `prefer-kit`): fix the code, not the rule. In development the server also

package/rules/quickdraw-testing.md

@@ -51,6 +51,16 @@ await app.close();
   `{ call, socket, hello, close }` once the server said hello. Pass `null`
   for an anonymous caller. Both callers are keyed by service name
   (`taskService`), where the web client uses the contract map's keys.
+- Test a guard that reads `ctx.mcp` (an agent token's scopes) or
+  `ctx.transport` in process too, never through `app.server.dispatcher.call`:
+  `app.as(agent, { transport: "mcp", mcp: { scopes: [] } })` calls as an
+  MCP tool call arrives, its `mcp` typed by the app's
+  `QuickdrawTypes["mcp"]`, and `{ mcp }` alone as a call an MCP call made
+  through `ctx.services`. `transport` takes `"internal"` (the default),
+  `"http"` or `"mcp"`; a socket's call is `app.connect`'s. Bound arguments
+  and the registry's `principal` and `context` hooks belong to the MCP
+  registry: test them through
+  `registry.callMethod(service, method, input, { request })`.
 - `app.frames(match?)` lists every frame the server sent, each with its
   `event`, `data`, `socketId`, `userId` and `at`;
   `frames.waitFor(match, timeoutMs?)` waits for one, `frames.clear()`
@@ -157,15 +167,19 @@ await expectBudget(() => app.as(ada).taskService.list({ limit: 20 }), { name: "l
 `createTestApp({ strictWarnings: true })` (under vitest or jest) throws each
 development warning raised in that app's method calls (`n-plus-one`,
 `unbounded-read`, `oversized-response`, `nested-write`, `batch-read`,
-`batch-create-many`) as a `DevWarningError` where it happens, failing the
-test that caused it (an oversized reply fails an in-process `app.as(...)`
-call; over a socket or HTTP the reply was already sent, so it is logged, not
-thrown). Warnings outside its calls (an `ambient-write` while seeding) are
+`batch-create-many`, `shared-principal`) as a `DevWarningError` where it
+happens, failing the test that caused it (an oversized reply fails an
+in-process `app.as(...)` call; over a socket or HTTP the reply was already
+sent, so it is logged, not thrown). Warnings outside its calls (an `ambient-write` while seeding) are
 logged, and `app.close()` ends it. `tiered-field-in-output` (a method's own
-output schema declares a tiered field, at any depth) and
-`resolver-without-reads` (a `resolver` policy declares no `reads`) are
-thrown by `createTestApp` itself: answer `"entity"` from that method, or
-declare the resolver's `reads`, rather than turning strictness off.
+output schema declares a tiered field, at any depth),
+`resolver-without-reads` (a `resolver` policy declares no `reads`),
+`untracked-access-model` (a membership or junction table without an `id`)
+and `channel-without-requires` (a channel with neither `requires` nor a
+declared `access`) are thrown by `createTestApp` itself: answer `"entity"`
+from that method, declare the resolver's `reads`, give the table an `id`,
+or give the channel a `requires` (or `access: "authenticated"` when any
+signed-in user may send it), rather than turning strictness off.
 Turn it on for service suites.
 `createRecordingSink()` passed as `flushSink` records what each flush wrote.
 

package/skills/quickdraw-migrate-v5/SKILL.md

@@ -95,12 +95,21 @@ guide's sections as the report sends you to them.
    `[v4-api]`: instance state, the 4.x context, `throw new Error(message)`
    in handlers (5.0 answers it with a generic `INTERNAL`: throw
    `QuickdrawError(code, message)` where the caller should see the message),
-   channels, the server set-up (`qd.createServer`, with `legacyWire: true`
+   channels (each `[channel]` marker needs a `requires`, often a room a
+   new joining method puts the socket in: 4.x channels took any signed-in
+   socket's message, and 5.1 warns `channel-without-requires`), the server
+   set-up (`qd.createServer`, with `legacyWire: true`
    while 4.x clients remain, or `legacyWire: { aliases: { old: "new" } }`
    when you renamed a service they still call).
    A hand-built sign-in (unmarked: the codemod leaves it) moves onto the
    auth routes kit last, with its `Session` table migration (MIGRATION.md,
-   "Hand-built auth to the auth routes kit").
+   "Hand-built auth to the auth routes kit"). Until then the server's
+   interim `authenticate` checks the app's session store on every handshake
+   and call, and the session cookie's `Origin` (`cookieOriginAllowed`);
+   never `verifyJWT` alone, which a signed-out session still passes. It
+   refuses by throwing `QuickdrawError("UNAUTHENTICATED")`, never a plain
+   `Error`, which a socket's handshake answers `INTERNAL` (an outage, which
+   the client retries, keeping the user).
 
 4. **Delete each marker when its item is done**, and run the codemod again:
    it changes no code a second time and rewrites the report from the markers

package/skills/quickdraw-new-service/SKILL.md

@@ -45,6 +45,12 @@ model Label {
 }
 ```
 
+A membership or junction table (`projectMember`, `taskLabel`) gets the same
+`id` and keeps its pair unique with `@@unique([projectId, userId])`, never a
+composite `@@id`: the write tracker keys rows by `id`, so a table without one
+is never tracked, and removing a member would never revoke them (the server
+names such a table at start).
+
 Then, in `packages/db`, create the migration and generate the client, in
 that order: `bun run db:migrate --name add_labels` (`prisma migrate dev`,
 which writes `prisma/migrations/<time>_add_labels/migration.sql` and applies
@@ -140,14 +146,19 @@ export const labelService = qd.defineService(labelContract, {
   other model the handlers write in `writes`; return rows for projection
   outputs. Throw `QuickdrawError` with a code for expected failures.
 - A method whose input has `id` names a row: give it `{ entry: L }`.
-  `defineService` refuses `"public"`, `"authenticated"` or `{ service: L }`
-  below `Admin` there unless the method says `rowless: true` (every caller
-  the form admits may reach any row, on purpose).
+  `defineService` refuses `"public"`, `"authenticated"`, `{ service: L }`
+  below `Admin`, `custom(fn)`, `{ scope, of, id }` and `{ entry, id }`
+  naming another key there unless the method says `rowless: true` (every
+  caller the form admits may reach any row, on purpose).
 - A method or service that only some kinds of principal may call says so
   with `kinds` beside `access` (`kinds: ["user"]`), within the app's
   `initQuickdraw({ kinds })`: never with a check of `ctx.principal.kind` in
   the handler or in a `custom` form. Other kinds get `FORBIDDEN`, whatever
   their grants (see quickdraw-access.md).
+- A check on the caller's claims (a token's `scope`) is `claims` beside
+  `access` (`claims: (claims) => claims?.scope === "triage"`): it adds to
+  the form, and no grant passes it. Never write it as `custom`, which
+  replaces the row check.
 - Reach for a kit before hand-writing CRUD, search, sharing or admin; lint's
   `prefer-kit` warns on a hand-written `get`, `list`, `create` or
   `getLabel`-style method in a service that uses no kit.