@fitzzero/quickdraw-skills 5.1.1 → 5.1.2

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.2",
   "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,80 @@ 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 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 +156,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 +200,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 +225,12 @@ 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 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 +259,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

@@ -41,15 +41,21 @@ export function Providers({ children }: { readonly children: React.ReactNode })
   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.
   `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
 

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`, or a context field made from
+  them); in development a read of one of the first three 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.
@@ -135,6 +146,22 @@ 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`.
+- 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.
+
 ## Writes are tracked; frames are derived
 
 Entity frames, collection deltas and change topics are computed from the
@@ -169,9 +196,12 @@ 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). 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 +231,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
@@ -223,9 +260,12 @@ Contract halves come from `@fitzzero/quickdraw-core`, handlers from
   `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 +281,33 @@ 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.
 - 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
@@ -283,9 +337,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

@@ -157,15 +157,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,18 @@ 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.
 
 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.