@fitzzero/quickdraw-core 5.0.0-rc.2 → 5.0.0-rc.4

package/README.md

@@ -25,7 +25,7 @@ single hand-written event.
 - **Testing**: a real test server, access matrices, performance budgets that
   count statements and bytes, strict development warnings.
 
-Design record: [`docs/rfcs/0003-v5.md`](../../docs/rfcs/0003-v5.md).
+Design record: [`docs/rfcs/0003-v5.md`](https://github.com/fitzzero/quickdraw/blob/dev/docs/rfcs/0003-v5.md).
 
 ## Install
 
@@ -710,13 +710,18 @@ export const taskService = qd.defineService(task, {
   (`adminBypass: false` turns that off). A grant below `Admin` counts only
   where the form names `service`: a `Read` grant does not read every row.
 - Grants come from `principal.serviceAccess`, as `authenticate` returns it or
-  `createServer({ auth: { loadServiceAccess } })` loads it. With
+  `createServer({ auth: { loadServiceAccess } })` loads it for a principal
+  that carries none: at a socket's handshake, for each HTTP call, and for
+  an in-process caller (`qd.caller`) at its first call. With
   `auth.serviceAccessSource: { model: "user", column: "serviceAccess" }`, a
   tracked write to that column refreshes the user's open sockets
-  (`qd:access`).
+  (`qd:access`), and in-process callers load the grants again.
 - Policies: `owner(field)`, `jsonAcl(field, { owner? })`,
   `members({ model, entry, user, level, levels? })`, `inherit({ from, via })`,
-  `anyOf(...)` and `resolver({ levelsFor, where? })`. Their column names are
+  `anyOf(...)`, `resolver({ levelsFor, where? })` and `everyone(level)`
+  (every signed-in user has `level` on every row, reading nothing: public
+  profiles are `anyOf(owner("id"), everyone("Read"))`; unlike `rowless: true`
+  on a method, it covers subscriptions and lists too). Their column names are
   checked against the Prisma client's models at compile time. A lookup is one
   batched query per table, memoized for the call, so checking 60 ids costs
   what checking one does. `entry` access needs a policy; a service without
@@ -766,7 +771,15 @@ tracked client as `db`; the server finds the rest on it.
   (`writes: ["taskLabel"]`); the `no-foreign-write` lint rule checks it.
 - Jobs, scripts and webhooks wrap their writes in `qd.run(fn)`, which
   flushes before it returns. A write made outside any unit of work flushes
-  on its own on the next tick, with a development warning.
+  on its own on the next tick, with a development warning. Inside a
+  handler `qd.run` joins the handler's unit; background work the reply does
+  not wait for (a push sent after a message, pruning what it reports dead)
+  runs in `qd.run(fn, { detached: true })`, a unit of its own that flushes
+  when `fn` settles (catch what the promise rejects with: nothing awaits it).
+  Before any server exists (a seed at boot, before `createServer`),
+  `qd.run(fn)` still runs `fn` in a unit of its own, and its writes reach no
+  one: no socket can be subscribed yet (behind a cluster, write after
+  `createServer` when other nodes' subscribers must hear of it).
 
 <!-- example: apps/api/src/jobs/overdue.ts#run -->
 
@@ -828,14 +841,16 @@ export const taskService = qd.defineService(task, {
   // a write to a subtask sends its parent again
   affects: [{ service: task, id: "parentTaskId" }],
   project: {
-    // a relation count: read with select, built by a pure, synchronous map
+    // a relation count: read with select, built by a pure, synchronous map. Read the relation's
+    // ids, which Prisma fetches for the rows read only; its _count aggregates the whole TaskLabel
+    // table (a GROUP BY over every row) on every snapshot and flush
     card: {
-      select: { title: true, status: true, _count: { select: { labels: true } } },
-      map: (row: { id: string; title: string; status: string; _count: { labels: number } }) => ({
+      select: { title: true, status: true, labels: { select: { id: true } } },
+      map: (row: { id: string; title: string; status: string; labels: { id: string }[] }) => ({
         id: row.id,
         title: row.title,
         status: row.status,
-        labelCount: row._count.labels,
+        labelCount: row.labels.length,
       }),
     },
   },
@@ -848,13 +863,19 @@ export const taskService = qd.defineService(task, {
       handler: ({ input, db }) =>
         db.task.findUniqueOrThrow({
           where: { id: input.id },
-          select: { id: true, title: true, status: true, _count: { select: { labels: true } } },
+          select: { id: true, title: true, status: true, labels: { select: { id: true } } },
         }),
     },
   },
 });
 ```
 
+- A count over a relation reads the relation's ids (`labels: { select: { id: true } }`)
+  and counts them in `map`: Prisma reads them for the rows read only (a
+  second SQL query, `WHERE "taskId" IN (...)`). Its `_count` compiles to a
+  `GROUP BY` over the whole relation table, joined in, on every snapshot,
+  page and flush that reads the projection. For a relation too large to read
+  (a chat's members), keep a counter column that the writes maintain.
 - A projection's keys come from its schema's JSON Schema (Zod 4.2 or later),
   or from `project: { <name>: { keys } }`; a service whose projection has
   neither fails when it is defined. A handler returning a projection returns
@@ -893,7 +914,7 @@ export const taskService = qd.defineService(task, {
   Valkey's clock in microseconds, so revisions from all nodes are one order;
   its key needs persistence or replication. A node whose Valkey connection
   comes back has its clients reconnect to catch up.
-  [docs/deploying.md](../../docs/deploying.md) has the wiring, what holds across
+  [docs/deploying.md](https://github.com/fitzzero/quickdraw/blob/dev/docs/deploying.md) has the wiring, what holds across
   nodes, what it costs, and what happens when a node or Valkey stops
   answering.
 
@@ -959,6 +980,11 @@ export const taskService = qd.defineService(task, {
   ends in `id`; `limit` (default 100) and `maxLimit` (default 500) size its
   pages; `where` is an equality filter on membership; `access` is the level
   needed on the anchor (default `Read`).
+- A junction write adds or removes its entry in the one scope it links.
+  When the item reads the junction (a chat's `memberCount`), declare
+  `via({ model, entry, scope, refreshEntry: true })`: every junction write
+  then also sends the entry again, `updated`, to each scope that still
+  holds it, for one more read of the item per flush.
 - `qd:col:sub { s, c, scope }` authorizes the scope through its anchor's
   policy, then answers a page and joins the scope's room; flushes send `qd:c`
   deltas to it (`added`, `updated`, `patched`, `removed`, or `reset` for more
@@ -981,7 +1007,9 @@ export const taskService = qd.defineService(task, {
   scope after a change tracked writes cannot describe.
 - `qd:watch { s, topic }` joins a change topic: `{collection}:{scope}`,
   authorized like a subscribe to that scope, or `service`, which changes
-  whenever any row of the service does. The service topic is closed
+  whenever any row of the service does, or a row of a model it lists in
+  `writes` (a game's high scores, which no service owns). A query declares
+  `watch: "service"` to be invalidated by it. The service topic is closed
   (`FORBIDDEN`) unless the service declares `watchAccess` (`"public"`,
   `"authenticated"` or `{ service: level }`). A watcher that loses access
   leaves the topic after one last `qd:changed`.
@@ -998,7 +1026,9 @@ over three transports (design: sections 3, 8 and 10):
 
 - **Socket.IO** (protocol 5): a client connects with
   `auth: { token, qd: { protocol: 5, client } }`, receives `qd:hello` with the
-  server's limits and who it acts for, and calls through `qd:call` and
+  server's limits, who it acts for and the server's id (`serverId`, new
+  each time a server starts: a reconnect that brings another one reached a
+  restarted server, or another node), and calls through `qd:call` and
   `qd:cancel`. Every socket gets the same few listeners however many methods
   the services have. The JSON-only parser is the default; `binary: true`
   restores the stock one. The socket rate limiter is on by default (600
@@ -1020,7 +1050,13 @@ over three transports (design: sections 3, 8 and 10):
   `./server/express`), which refuses with the `RATE_LIMITED` reply.
 - **In process**: `server.dispatcher.caller(principal)` or
   `qd.caller(principal)`: `await qd.caller(user).taskService.rename(input)`,
-  typed by the `contracts` of `initQuickdraw`'s types.
+  typed by the `contracts` of `initQuickdraw`'s types. A principal that
+  carries no `serviceAccess` gets the grants `auth.loadServiceAccess`
+  loads, as a socket's handshake and an HTTP call do: at the caller's first
+  call, and again at its next call after the server applied new grants to
+  a user (`server.access.refresh`, a tracked write to
+  `auth.serviceAccessSource`). One that carries grants (even `{}`) keeps
+  exactly those. A load that fails rejects the call with `INTERNAL`.
 
 `authenticate` takes one request (`{ transport, auth, headers, socket | req }`)
 for both transports and returns a principal, a user id, or nothing for an
@@ -1105,7 +1141,9 @@ createMcpStdioServer({ registry, name: "my-app", version: "1.0.0" });
 
 - **stdio** speaks JSON-RPC (MCP protocol version 2024-11-05). One process is
   one session: its queries share one concurrency lane, and
-  `notifications/cancelled` cancels a call. Start its module through
+  `notifications/cancelled` cancels a call. When stdin ends, the calls still
+  running finish and their replies are written before `closed` resolves
+  (`server.close()` cancels them instead). Start its module through
   `bootstrapMcpServer(new URL("./mcp-server.js", import.meta.url))`, which
   sends console output to stderr so only the protocol reaches stdout.
 - **HTTP**: `GET /mcp/tools` and `POST /mcp/invoke`, which takes
@@ -1115,6 +1153,11 @@ createMcpStdioServer({ registry, name: "my-app", version: "1.0.0" });
   `"public"` methods, and custom tools that declare `access: "public"`; any
   other tool answers `UNAUTHENTICATED` before it runs. A failed call reaches
   the agent as a tool error carrying the code.
+- The tool list is the registry's, the same for every caller: `tools/list`
+  and `GET /mcp/tools` are not filtered by the principal, so an agent sees
+  tools it may not call (and its call is refused). Keep a tool out of the
+  list with `exclude` or `include`, per registry, and serve agents of
+  different reach from separate registries.
 
 ## The client
 
@@ -1127,15 +1170,16 @@ the method's kind does not have, is a compile error.
 `QueryClient` (5-minute stale time by default), and works without DOM
 globals (React Native).
 
-| Member                                                                    | Gives                                                                                          |
-| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `qd.task.get.useQuery(input, options)`                                    | TanStack's `useQuery`; errors are `QuickdrawError` with a `code`                               |
-| `qd.task.rename.useMutation(options)`                                     | TanStack's `useMutation`; `mutate` returns nothing, `mutateAsync` the output                   |
-| `qd.task.useEntity(id)`, `useEntities(ids)`                               | live rows at the user's level: `{ data, isLoading, isRemoved, error }`                         |
-| `qd.task.board.useCollection(scope, { view, load, limit })`               | a live scope: `{ items, index, byId, totalCount, hasMore, isLoading, loadMore, refresh, ... }` |
-| `qd.task.get.call(input)`, `.key(input)`, `.prefetch(queryClient, input)` | a call over the mounted provider's connection, the cache key, a prefetch                       |
-| `qd.invalidate(qd.task.get, input?)`                                      | invalidates through the coordinator: a read in flight is never cancelled                       |
-| `useQuickdraw()`                                                          | `{ connection, status, isConnected, userId, serviceAccess, hello, refusal, isRateLimited }`    |
+| Member                                                                    | Gives                                                                                           |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `qd.task.get.useQuery(input, options)`                                    | TanStack's `useQuery`; errors are `QuickdrawError` with a `code`                                |
+| `qd.task.rename.useMutation(options)`                                     | TanStack's `useMutation`; `mutate` returns nothing, `mutateAsync` the output                    |
+| `qd.task.useEntity(id)`, `useEntities(ids)`                               | live rows at the user's level: `{ data, isLoading, isRemoved, error }`                          |
+| `qd.task.board.useCollection(scope, { view, load, limit })`               | a live scope: `{ items, index, byId, pending, totalCount, hasMore, isLoading, loadMore, ... }`  |
+| `qd.task.get.call(input)`, `.key(input)`, `.prefetch(queryClient, input)` | a call over the mounted provider's connection, the cache key, a prefetch                        |
+| `qd.invalidate(qd.task.get, input?)`                                      | invalidates through the coordinator: a read in flight is never cancelled                        |
+| `qd.task.get.setData(input, updater)`                                     | writes a cached result an event carries, at once; a read in flight is followed by one more      |
+| `useQuickdraw()`                                                          | `{ connection, status, isConnected, isKnown, reconnecting, userId, serviceAccess, hello, ... }` |
 
 <!-- example: apps/web/src/components/TaskDetail.tsx#detail -->
 
@@ -1176,12 +1220,18 @@ export function TaskDetail({ id }: { readonly id: string }) {
   collection items from the moment it is sent, are dropped if it fails, and
   give way to the server's frame. `optimistic: false` turns that off;
   `optimistic: (input, cache) => ...` writes its own layers with
-  `patchEntity`, `removeEntity` and `patchItem`.
+  `patchEntity`, `removeEntity` and `patchItem`, and adds rows with
+  `addItem` and `addEntity` (below).
 - Live rows and collections need no refetching: frames keep them current,
   and after a reconnect they resume by revision. A query whose result
   follows writes declares `watch` in its contract; the coordinator fetches
   it again once per change, with at most one read in flight per key. Do not
   call `refetch` or `invalidateQueries` on quickdraw keys after a mutation.
+- An event that carries a query's new result (a room's roster, a score)
+  writes it with `qd.<service>.<query>.setData(input, updater)` rather than
+  refetching: the hooks show it at once, under the overlays of optimistic
+  mutations, and a read of that key already in flight (which may predate
+  the event) is followed by one more, never cancelled.
 - After a reconnect, the queries that are watched (they missed the changes
   meanwhile) or stale are refetched, each after a random delay of up to
   `reconnectJitterMs` (2,000 ms by default), so clients that reconnect
@@ -1200,6 +1250,87 @@ export function TaskDetail({ id }: { readonly id: string }) {
 - A protocol mismatch reloads the page once per session by default
   (`onProtocolMismatch`); `RATE_LIMITED` answers back off with jitter per
   kind of work.
+- Server rendering: a server never connects, so `useQuickdraw()`,
+  `usePresence`, streams and overlays render the state a new connection has
+  (nobody known, no rooms, nothing loaded), and the browser hydrates that
+  same state even where the provider connected first (a Suspense boundary
+  that hydrates late), then renders the live one.
+
+A create shows its row before the server answers with `cache.addItem(collection,
+scope, item)`: the item appears in the scope at once, in its place by the
+collection's `order` (give it the order's fields; without them it goes
+last), and `useCollection`'s `pending` names it while the call is in flight.
+A refused call removes it. The reply's `id` (the created row's) and values
+replace the item's own, and once the scope's own copy arrives (its `added`
+delta, or a load) that copy shows in its place: never both, never a gap.
+`cache.addEntity(row)` adds a row to every collection of entity rows whose
+scope column (and `where`) it matches; a collection of a projection takes
+`addItem`. The item may give its own `id`, one the client made and the
+server keeps:
+
+<!-- example: apps/web/src/components/AddTask.tsx#add -->
+
+```tsx
+export function TaskList({ projectId }: { readonly projectId: string }) {
+  const { items, pending } = qd.task.board.useCollection(projectId);
+  const create = qd.task.create.useMutation({
+    // the new card shows at once, last on the board (its ordinal), until the server's arrives
+    optimistic: (input, cache) =>
+      cache.addItem("board", input.projectId, {
+        projectId: input.projectId,
+        title: input.title,
+        status: "open",
+        ordinal: Number.MAX_SAFE_INTEGER,
+        assigneeId: null,
+      }),
+  });
+  return (
+    <>
+      <ul>
+        {items.map((task) => (
+          // pending: the create is on its way; the card is the server's once it answers
+          <li key={task.id} style={{ opacity: pending.has(task.id) ? 0.5 : 1 }}>
+            {task.title}
+          </li>
+        ))}
+      </ul>
+      <button type="button" onClick={() => create.mutate({ projectId, title: "New task" })}>
+        Add
+      </button>
+      {create.error === null ? null : <p>{`Not added: ${create.error.code}`}</p>}
+    </>
+  );
+}
+```
+
+`useQuickdraw()` says who the connection acts for. `userId` is `null` both
+for an anonymous socket and before the server's hello, so a gate waits for
+`isKnown` (the hello on the current credentials arrived; false again from
+new credentials until theirs). `isConnected` turns true before the hello and
+false while the connection reconnects; `reconnecting` says the user and the
+page stay meanwhile:
+
+<!-- example: apps/web/src/components/AuthGate.tsx#gate -->
+
+```tsx
+export function AuthGate({ children }: { readonly children: ReactNode }) {
+  // isKnown: the server's hello named the user, so userId is final (null: signed out)
+  const { isKnown, userId, reconnecting } = useQuickdraw();
+  if (!isKnown) {
+    return <p>Connecting…</p>;
+  }
+  if (userId === null) {
+    return <SignIn />;
+  }
+  // a reconnect keeps the user and the page: say so, unmount nothing
+  return (
+    <>
+      {reconnecting ? <p role="status">Reconnecting…</p> : null}
+      {children}
+    </>
+  );
+}
+```
 
 ### Server components and other runtimes
 
@@ -1255,9 +1386,9 @@ such code, and `createInvalidationCoordinator(queryClient)` invalidates as
 the hooks do.
 
 A client in another language (a Godot game, a native app) speaks the wire
-itself: [`docs/protocol-v5.md`](../../docs/protocol-v5.md) is its specification,
-generated from the protocol's source, and [`examples/godot`](../../examples/godot)
-holds a GDScript client written from it. [`docs/clients.md`](../../docs/clients.md)
+itself: [`docs/protocol-v5.md`](https://github.com/fitzzero/quickdraw/blob/dev/docs/protocol-v5.md) is its specification,
+generated from the protocol's source, and [`examples/godot`](https://github.com/fitzzero/quickdraw/tree/dev/examples/godot)
+holds a GDScript client written from it. [`docs/clients.md`](https://github.com/fitzzero/quickdraw/blob/dev/docs/clients.md)
 compares the three ways in.
 
 ## Kits
@@ -1732,7 +1863,10 @@ export function AdminTasks() {
   // [{ key: "task", serviceName, displayName }]
   const { services } = useAdminServices(qd);
   const { data } = qd.task.admin.adminList.useQuery({ page: 1, sort: { field: "title" } });
-  const update = qd.task.admin.adminUpdate.useMutation();
+  const update = qd.task.admin.adminUpdate.useMutation({
+    // adminList is a query, not live data: read the page again after this screen's own write
+    onSuccess: () => qd.invalidate(qd.task.admin.adminList),
+  });
   return (
     <table aria-label={services[0]?.displayName}>
       <tbody>
@@ -1780,7 +1914,7 @@ export function AdminTasks() {
   value is checked by the entity schema itself, and a value the database
   refuses is `VALIDATION`. A missing row is `NOT_FOUND`.
 - `adminMeta()` returns `{ serviceName, displayName, fields }`, one
-  `{ name, type, label, required, editable, showInTable, sortable, filterable, enumValues?, relationService? }`
+  `{ name, type, label, required, editable, showInTable, sortable, filterable, enumValues?, relationService?, kind?, showInForm? }`
   per field: `type` is
   `string`, `number`, `boolean`, `date` (an ISO string with a date format),
   `enum` or `json` from the field's JSON Schema, and `relation` by override;
@@ -1789,6 +1923,29 @@ export function AdminTasks() {
   configurations written for 4.x still type); `id` and the
   timestamps come first and are not editable; `acl`, `serviceAccess` and
   `service_access` are hidden.
+- Grants: on a users service, `admin.handlers(user, { grants: true })`
+  shows and writes the entity's `serviceAccess` (a `json` field the entity
+  schema checks), so the admin screen edits grants through `adminUpdate`.
+  Only a caller whose own service-wide grant on that service is `Admin`
+  reads or writes it, whatever `access` gives the method: anyone else gets
+  rows without it and `FORBIDDEN` for a write, filter or sort naming it.
+  The write is tracked, so with `auth.serviceAccessSource` naming the column
+  the user's open sockets get the new grants at once, on every node. Such
+  an Admin can grant any service, themself included. The field's
+  configuration says `kind: "grants"`, so a screen with a grants editor of
+  its own finds it without its name, and
+  `fieldOverrides: { serviceAccess: { showInForm: false } }` keeps it out
+  of a generic create or edit form (a form shows the fields whose
+  `showInForm` is not `false`); the kit still reads and writes it.
+- `admin.handlers(contract, { onWrite })` runs `onWrite({ method, id,
+before?, after }, ctx, db)` after each `adminCreate`, `adminUpdate` and
+  `adminDelete`, in one transaction with the write (`db` is the
+  transaction's tracked client; a throw undoes the write and fails the
+  call): what an admin edit must set off, such as a game reloading its
+  tunables, without wrapping the kit's handlers. The rows are the entity,
+  every field. Without it the kit opens no transaction. Each handler
+  `admin.handlers` returns resolves with its method's output type, so a
+  wrapper reads the row and returns it with no cast.
 - `adminSubscribers({ id })` counts the sockets subscribed to a row per
   access level (`{ id, count, levels, complete }`; behind a Redis adapter
   the counts are this server's and `complete` is `false`), and
@@ -1798,6 +1955,21 @@ export function AdminTasks() {
   `qd.admin`, since `admin` is reserved per service). `useAdminServices(qd)`
   lists the client's services whose `adminMeta` answers the user, with their
   display names, sharing the cache of `qd.<service>.admin.adminMeta.useQuery()`.
+  It asks only the services the user's grants (from the server's hello)
+  allow: `Admin` by default, what the kit's methods require;
+  `useAdminServices(qd, { requires: "Moderate" })` for an `adminMeta` given
+  another form, `requires: null` for every service. A service that refused
+  is not asked again until the user's grant on it changes, reconnects
+  included.
+- The kit's rows are not live: `adminList` and `adminGet` are queries that
+  watch nothing, so a screen reads them again after its own writes (the
+  `onSuccess` above), and sees other admins' writes when it next reads.
+- A screen that serves every service from its metadata (the route names the
+  service) takes `adminOf(qd, key)`: the same members, keyed by what the kit
+  made them for and typed by field name (`AdminScreen`: rows are
+  `AdminRow`, `adminList` takes `{ page, pageSize, filter, sort: { field, direction } }`
+  with names read from `adminMeta`), so no cast is needed over a union of
+  keys; a method the contract does not expose is absent.
 
 ### Presence, streams and channels
 
@@ -1835,7 +2007,11 @@ export const task = defineContract("taskService", {
       requires: { room: (cursor) => `board:${cursor.projectId}` },
     },
   },
-  events: { cursorMoved: { payload: cursorSchema } },
+  events: {
+    cursorMoved: { payload: cursorSchema },
+    // a user's last socket left a board: `onRoomLeave` sends it
+    leftBoard: { payload: z.object({ projectId: z.string(), userId: z.string() }) },
+  },
 });
 ```
 
@@ -1859,6 +2035,16 @@ export const taskService = qd.defineService(task, {
       ctx.rooms.emit(`board:${payload.projectId}`, task, "cursorMoved", payload);
     },
   },
+  // once per socket that leaves app rooms, in every server this service runs in, in a unit of its own
+  onRoomLeave: ({ principal, rooms }) => {
+    for (const { room, last } of rooms) {
+      // last: no socket of the user is in the room any more (a second tab keeps it false)
+      if (principal !== null && last && room.startsWith("board:")) {
+        const projectId = room.slice("board:".length);
+        qd.rooms.emit(room, task, "leftBoard", { projectId, userId: principal.userId });
+      }
+    }
+  },
 });
 
 // in handlers, jobs and timers
@@ -1882,14 +2068,17 @@ export function TaskRoom({
   readonly projectId: string;
   readonly taskId: string;
 }) {
+  // the socket is in the board's room on every connection: a reconnect is a new socket in no room
+  const board = useJoin(qd.task.enterBoard, { projectId });
   const { items } = qd.task.logs.useStream(taskId, { max: 200 });
   const { send, isReady } = qd.task.cursor.useChannel();
   const [lastX, setLastX] = useState(0);
   qd.task.cursorMoved.useEvent((cursor) => setLastX(cursor.x));
-  // user ids, after enterBoard joined the room
+  // user ids, once enterBoard joined the room
   const here = usePresence(`board:${projectId}`);
+  const move = (x: number) => isReady && board.isJoined && send({ projectId, taskId, x });
   return (
-    <div onMouseMove={(event) => isReady && send({ projectId, taskId, x: event.clientX })}>
+    <div onMouseMove={(event) => move(event.clientX)}>
       <p>{`${String(here.length)} here; a cursor at ${String(lastX)}`}</p>
       <pre>{items.map((item) => item.line).join("\n")}</pre>
     </div>
@@ -1903,20 +2092,33 @@ export function TaskRoom({
   latest `seed` items per scope in memory on that process (at most 1,000 per
   scope and 10,000 scopes per stream; a restart empties them, and durable
   history is the app's: store the rows and expose a collection), and sends
-  `qd:stream { s, stream, scope?, item }` to the feed's subscribers,
-  volatile when the stream says so. `pushMany(scope, items)`
+  `qd:stream [service, stream, scope, item]` (`scope` null for a global
+  stream; positional, so a fast stream's frames carry no key names) to the
+  feed's subscribers, volatile when the stream says so. `pushMany(scope, items)`
   (`pushMany(items)` for a global stream) pushes several items to one feed
   at once: every item is checked before any is kept or sent, and each goes
   out as its own frame, in order; use it rather than `push` in a loop
   (`no-emit-in-loop`). `qd:stream:sub` is authorized with the
   stream's `access` through the access engine, the scope being the row an
-  `entry` or `scope` form checks; a stream without `access` is closed. The
-  answer is the seed; `useStream` then appends, keeps the latest `max`
-  (default 500), and subscribes again after a reconnect, when the seed
-  replaces what it held. A socket holds at most 500 feeds. A subscriber
-  whose access is lowered is authorized again; one refused leaves the feed
-  and gets `qd:revoked { kind: "stream", reason: "access", s, stream, scope? }`,
-  and `useStream` shows `FORBIDDEN` until the next connect.
+  `entry` or `scope` form checks; `access: { room }` (a name, `{ prefix }`,
+  or for a scoped stream a function of the scope) opens it to the sockets
+  in that app room instead, signed in or not, and a socket that leaves the
+  room, or is taken out, leaves the feed; a stream without `access` is
+  closed. The answer is the seed; `useStream` then appends, keeps the
+  latest `max` (default 500), and subscribes again after a reconnect, when
+  the seed replaces what it held. A socket holds at most 500 feeds. A
+  subscriber whose access is lowered is authorized again; one refused
+  leaves the feed and gets
+  `qd:revoked { kind: "stream", reason: "access", s, stream, scope? }`, and
+  `useStream` shows `FORBIDDEN` until the next connect.
+- A service's `streams: { <name>: { seed, validate } }` computes a stream's
+  seed per subscriber, `seed: (scope, ctx) => items` (the current state,
+  where the items that follow are deltas; on whichever node the subscriber
+  is on, under its principal, in the tick it joins the feed; a contract
+  `seed: n` and a seed function cannot both be declared), and
+  `validate: "development"` checks pushed items only while the dispatcher
+  checks outputs (`outputValidation`, off in production), for a hot stream:
+  unchecked, an item goes out as pushed, extra keys included.
 - Channels: each message is `qd:ch [service, channel, payload]`, sent
   volatile and never answered. Per socket and channel a token bucket
   (`ratePerSecond`, default 30; `burst`, default twice that) drops what is
@@ -1928,10 +2130,13 @@ export function TaskRoom({
   scope; `{ room }`: the app room, a name like `"world"` or a function of
   the payload, which a call over that same socket joined) is dropped.
   Nothing is logged per message; a handler's error is. The socket rate
-  limiter does not count channels. Every requirement is the sending
-  socket's own: a room another socket of the user joined does not count, a
-  reconnected socket must join again, and behind a cluster the check runs
-  on the node the socket is connected to, with no round trip.
+  limiter does not count channels. `{ room: { prefix: "world:" } }` takes
+  a socket in any app room whose name starts with the prefix (a game of many
+  worlds), and every room form gives the handler the room it matched as
+  `ctx.room`, so the payload need not repeat it. Every requirement is the
+  sending socket's own: a room another socket of the user joined does not
+  count, a reconnected socket must join again, and behind a cluster the
+  check runs on the node the socket is connected to, with no round trip.
 - Presence: `isOnline`, `lastSeen` (now while online, else when the user's
   last socket on this process disconnected), `count` and `users` (each user
   once, anonymous sockets left out; app rooms only) come from this process's
@@ -1939,13 +2144,81 @@ export function TaskRoom({
   `ctx.rooms.join(room)` and `leave` put the calling socket in an app room
   (calls without a socket get `false`; names starting with `qd:` or `user:`
   are refused with `VALIDATION`; at most 100 per socket; a method that shares
-  its runs, `share`, may not join or leave: `INTERNAL`), and the room's
-  sockets get `qd:presence` frames: the list on joining, then who joins and
-  who leaves. `usePresence(room)` shows them.
+  its runs, `share`, may not join or leave with its caller's socket:
+  `INTERNAL`), and the room's sockets get `qd:presence` frames: the list on
+  joining, then who joins and who leaves. `usePresence(room)` shows them.
 - Events: `ctx.rooms.emit(room, contract, event, payload)` and
   `emitToUser(userId, ...)` check the payload first (`INTERNAL`, nothing
   sent, when it fails), then send the validated payload as
   `qd:event [service, event, payload]`; `useEvent` hears them.
+- Rooms belong to a socket: a reconnect (a lost network, `qd:rotate`, new
+  credentials) is a new socket in no room, which hears none of its events
+  and whose channel messages requiring it are dropped. `useJoin(member,
+input, { enabled?, onJoined? })` (from `./client`) runs the joining call
+  (`enterBoard` above) on every `qd:hello` and when its input changes by
+  value, never on a re-render, and shows `status` (`idle` with no socket to
+  join with, `joining`, `joined`, `error`), `isJoined`, `data` and `error`;
+  a refusal stands until the next hello, `RATE_LIMITED` is tried again after
+  its backoff, and it never leaves the room itself.
+  `connection.onHello(listener)` is the same hook without React.
+
+Code that is not a handler (a game loop, a timer, a job) reaches rooms
+through `qd.rooms` (also `server.rooms`); the service's `onRoomLeave` (above)
+hears sockets leave:
+
+<!-- example: apps/api/src/services/kits/rooms.ts#rooms -->
+
+```ts
+const boardRoom = (projectId: string): string => `board:${projectId}`;
+
+// a timer or a game loop's tick, outside any handler: every socket in the room, on every node
+export function showCursor(projectId: string, taskId: string, x: number): void {
+  qd.rooms.emit(boardRoom(projectId), task, "cursorMoved", { projectId, taskId, x });
+}
+
+// a member removed from the project: their sockets leave its board on every node, so they hear
+// nothing more of it and its cursor channel drops their messages (also ctx.rooms.leave)
+export async function removeFromBoard(projectId: string, userId: string): Promise<void> {
+  await qd.rooms.leave(boardRoom(projectId), { userId });
+}
+
+// a tick loop's "is anyone watching?", at its tick rate: this node's sockets in the room,
+// anonymous ones too, with no promise (presence.count asks every node for users)
+export function hasAudience(projectId: string): boolean {
+  return qd.rooms.size(boardRoom(projectId)) > 0;
+}
+```
+
+- `qd.rooms.emit` and `emitToUser` are `ctx.rooms`' own, from anywhere,
+  reaching every node behind a cluster adapter.
+- `rooms.size(room)` (on `qd.rooms`, `server.rooms` and `ctx.rooms`) counts
+  the sockets in an app room on this node, anonymous ones included, at once:
+  a game loop can ask it every tick. It is local by design; `presence.count`
+  counts users on every node. A handler's `ctx.socketId` names the socket
+  its call arrived on (`undefined` over HTTP, MCP or in process).
+- `leave(room, { userId })` (on `qd.rooms`, and on `ctx.rooms` beside the
+  calling socket's own `leave(room)`) takes every socket of the user out of
+  an app room, on every node: they hear nothing more of it, a channel that
+  `requires` the room drops their messages, each gets
+  `qd:presence { room, users: [] }`, and the room hears `left`. Behind a
+  cluster it is broadcast and answered, so await it before sending what the
+  user must not receive. Joining again is the app's to refuse.
+- A service's `onRoomLeave` runs once per socket that leaves app rooms, in
+  every server the service runs in (`createTestApp` and a benchmark's
+  server included, with nothing to wire), beside every other service's and
+  `createServer({ onRoomLeave })`, the app's own; each runs in a unit of
+  work of its own, and one that throws stops none of the others. It hears
+  every app room a socket leaves, so check the room's name. It runs on
+  the node that held the socket: its own `leave` (`reason: "leave"`), a
+  removal (`"removed"`), or a disconnect, which leaves every app room it was
+  in (`"disconnect"`; `qd:rotate` reconnects with a new socket). Each room
+  comes with `last`: true when no socket of that user is in the room any
+  more, on any node, which is what a game's `playerLeft` waits for. It runs
+  in a unit of work of its own (never the unit of the handler that left), a
+  throw is logged, and `close()` waits for it. Behind a cluster `last` is
+  decided by asking every node once the socket left, so two sockets of one
+  user leaving two nodes at the same moment may both see the other (a
+  removal never misses: each node reports its own last socket).
 
 ### Auth routes kit
 
@@ -1981,7 +2254,8 @@ app.set("trust proxy", 1);
 app.use(
   createAuthRoutes({
     providers: [
-      google({ clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET }),
+      // nothing without its credentials: the routes skip it
+      google.optional({ clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET }),
       discord({ clientId: env.DISCORD_CLIENT_ID, clientSecret: env.DISCORD_CLIENT_SECRET }),
       // served only while isMockOAuthEnabled()
       mock({ listUsers: listSeededUsers }),
@@ -2030,7 +2304,7 @@ nothing is cached:
 | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
 | `GET /{provider}/start?returnTo=<url>` | 302 to the provider                                                                                                   |
 | `GET /{provider}/callback`             | 302 to `{origin}{successPath}` with the session cookie, or to `{origin}{errorPath}?error=state`, `denied` or `failed` |
-| `POST /guest`                          | `createUser(body)`, then `{ userId }` with the session cookie                                                         |
+| `POST /guest`                          | `createUser(body)`, then `{ userId, name? }` with the session cookie (and `token` with `guest({ token: true })`)      |
 | `GET /me`                              | `{ userId }`, or 401                                                                                                  |
 | `POST /logout`                         | 204: revokes the session, clears the cookie                                                                           |
 | `POST /logout-all`                     | 204: revokes every session of the user; 401 without a live session                                                    |
@@ -2079,6 +2353,27 @@ nothing is cached:
   `allowMissingOrigin: true` is set for native clients that keep cookies.
   Bearer tokens need no Origin, and HTTP calls are guarded by their JSON
   content type instead.
+- `socketAuth({ devCredentials })` signs a socket in by the user id its
+  handshake names (`auth: { userId }`, no token), as the function answers
+  (the principal, or `null` to refuse): for a game editor or load-test bots
+  in development. `socketAuth` throws when it is given while `NODE_ENV` is
+  `production`, and refuses such a handshake there anyway; pass it only
+  behind the app's own flag.
+- `google.optional(...)` and `discord.optional(...)` build nothing when
+  neither credential is set (only one is a misconfiguration, refused), and
+  `providers` skips `undefined`, `null` and `false` entries, so an
+  environment without a provider's app leaves it out in place.
+- A guest's `createUser` may return `{ userId, name }` when the name it gave
+  differs from the one asked (a numbered one after a collision), and the
+  route answers it; `guest({ createUser, token: true })` also answers the
+  session's token, for clients that keep no cookies (a game engine, a page
+  in a third-party iframe), at the cost of the token being readable by the
+  page's scripts.
+- `requireSession({ sessions, jwtSecret }, { loadPrincipal? })` guards the
+  app's own REST routes (below): the credential is read as `/me` reads it,
+  the JWT verified once and the session checked in the store; otherwise
+  401 `{ error: "UNAUTHENTICATED", message }`. 4.1's `createRequireAuth`
+  stays for token-keyed sessions.
 - Rate limits: the sign-in routes share `createAuthLimiter({ max: 60 })` (60
   requests per 15 minutes per IP) and the session routes
   `createAuthStatusLimiter()` (120); pass `rateLimit: { signIn, session }`
@@ -2123,6 +2418,83 @@ nothing is cached:
   session for an app's own sign-in flow (login codes, an embedded activity),
   and `liveSession` reads a token back; both work with `socketAuth`.
 
+From the browser, `./client` speaks to these routes: `signInUrl(provider,
+{ apiUrl, returnTo })` is the start route's URL (to navigate to; `returnTo`
+defaults to the current page's origin), and `signOut()` and
+`signOutEverywhere()` post to `logout` and `logout-all`. Each POST sends the
+session cookie (`credentials: "include"`, so the API's CORS must allow the
+web app's origin with credentials) with `Content-Type: application/json`,
+and the token `setAuthToken` stored, if any, as a bearer token; the stored
+token is forgotten either way, and a refusal or an unreachable server
+rejects with a `QuickdrawError`. A socket keeps the user it signed in as
+until it connects again, so reconnect the provider's connection after
+signing out (with a token in `auth`, clearing it does that):
+
+<!-- example: apps/web/src/components/SignIn.tsx#browser -->
+
+```tsx
+export function SignIn() {
+  // the kit's GET /auth/google/start: back to this page's origin with the session cookie
+  return <a href={signInUrl("google", { apiUrl: API_URL })}>Sign in with Google</a>;
+}
+
+export function SignOut() {
+  const { connection } = useQuickdraw();
+  const leave = async (): Promise<void> => {
+    // POST /auth/logout with the cookie: the session is revoked, the cookie cleared
+    await signOut({ apiUrl: API_URL });
+    // the socket keeps its user until it connects again, as nobody now
+    connection.close();
+    connection.open();
+  };
+  return (
+    <button type="button" onClick={() => void leave()}>
+      Sign out
+    </button>
+  );
+}
+```
+
+An app's own REST route (a service worker's renewal, a webhook) signs the
+user in with `requireSession` and calls the services in process, so the
+method's validation, access check and tracked writes are a socket call's.
+`sessionOf(req)` gives the route `{ userId, sessionId, principal }`, typed,
+with no cast of `req` (`sessionOf<AppPrincipal>(req)` when `loadPrincipal`,
+like `socketAuth`'s, builds the app's own principal; by default it is
+`{ userId, kind: "user" }`); they are also set as `req.userId`,
+`req.sessionId` and `req.principal`. `qd.caller(principal)` then loads the
+user's grants as the user's sockets get them, so a method behind
+`{ service: L }` passes or answers `FORBIDDEN` as it would over a socket:
+
+<!-- example: apps/api/src/auth/routes.ts#rest -->
+
+```ts
+import { httpStatus, toWire } from "@fitzzero/quickdraw-core";
+import { requireSession, sessionOf } from "@fitzzero/quickdraw-core/server/auth";
+
+// 401 without a live session; the principal built as socketAuth builds a socket's
+const signedIn = requireSession(
+  { sessions, jwtSecret: env.JWT_SECRET },
+  { loadPrincipal: (userId): AppPrincipal => ({ userId, kind: "user" }) },
+);
+
+app.get("/api/projects/:projectId/task-count", signedIn, (req, res) => {
+  void (async () => {
+    const { principal } = sessionOf<AppPrincipal>(req);
+    try {
+      // the method's validation, access check (with the user's grants) and writes, as over a socket
+      const count = await qd.caller(principal).taskService.countOnBoard({
+        projectId: req.params.projectId,
+      });
+      res.json({ count });
+    } catch (error) {
+      const failure = toWire(error);
+      res.status(httpStatus(failure.code)).json(failure);
+    }
+  })();
+});
+```
+
 `createMemorySessionStore()` keeps sessions in the process, for development
 and tests. In production, store them in the database. Sessions are not live
 data, so nothing needs their writes tracked: with the tracked client, the
@@ -2203,8 +2575,14 @@ it("sends a rename to the other members' boards", async () => {
 - `app.as(principal)` calls in process and `app.connect(principal)` over a
   real socket (`{ call, socket, hello, close }`); both are keyed by service
   name. `app.frames(match?)` lists every frame the server sent, with its
-  socket and user; `frames.waitFor(match)` waits for one. `emitWithAck` and
-  `waitForEvent` send raw frames and wait for events.
+  socket and user; `frames.waitFor(match)` waits for one. A query of one
+  event takes `where`, a predicate over its frames typed by the event
+  (`{ event: "qd:presence", where: ({ data }) => data.joined === id }`), and
+  `streamFrames(contract, stream, where?, scope?)` and
+  `eventFrames(contract, event, where?)` match one stream's items or one
+  event's payloads, typed by the contract, to spread beside `socketId` or
+  `userId`. `emitWithAck` and `waitForEvent` send raw frames and wait for
+  events.
 
 ### Access matrices
 
@@ -2236,7 +2614,11 @@ it("lets the owner rename, members read, and nobody else in", async () => {
 
 `"deny"` (the default for everyone `allow` does not name) means
 `UNAUTHENTICATED` without a principal and `FORBIDDEN` with one. Mutations run
-for real, once per allowed principal: give inputs that can run again.
+for real, once per allowed principal: give inputs that can run again, or
+`input` as a function of the cell (`({ name, principal }) => input`, sync or
+async), called before each cell's call, that makes a row of its own (a task
+to delete, an unused name), so no cell depends on the order of the
+principals.
 
 ### Performance budgets
 
@@ -2379,9 +2761,22 @@ async (Testing Library, an optional peer, is loaded lazily) and returns
 Testing Library's result plus `connection`, `queryClient`, `disconnect()`
 and `reconnect()`, which drop and restore the socket as a lost network does.
 
-For a component test without a server, `createMockClient(contracts)` gives
-the typed client's shape with stubs; give it to the components in place of
-the app's client (a module mock of the file that exports `qd`, say):
+The web app's test imports the API's services across apps, as above, and
+needs a database: run such tests in a jsdom project of their own, with the
+API's global setup (the template its test databases boot from, below) and a
+setup file that calls `installJsdomShims()` from `./testing/client`. That
+adds what jsdom lacks, and keeps what it has: `scrollTo`, `scrollBy` and
+`scrollIntoView` on elements (they do nothing; a list that follows its newest
+item calls them) and `Blob.prototype.arrayBuffer` (PGlite reads a database
+dump through it). This repository runs the README's example app that way:
+`packages/core/vitest.config.ts`, project `readme`, with
+`test/readme/globalSetup.ts` and `test/readme/workerSetup.ts`.
+
+For a component test or a story without a server, `createMockClient(contracts)`
+gives the typed client's shape with stubs; give it to the components in place
+of the app's client (a module mock of the file that exports `qd`, say). It
+comes from `./testing/client`, or from `@fitzzero/quickdraw-core/testing/mock`,
+which names no Testing Library, for a browser bundle (Storybook):
 
 <!-- example: apps/web/src/components/TaskBoard.test.tsx#mock -->
 
@@ -2401,14 +2796,52 @@ each test only when the test runner has a global `afterEach` (vitest with
 (`resetAfterEach: false` opts out); otherwise call `mock.$reset()` in an
 `afterEach` of your own, as above. Optimistic updates are not shown.
 
+The members' hooks need no provider. A component that reads the connection
+(`useQuickdraw()`, `usePresence(room)`) renders inside the mock's own
+provider, `mock.$Provider`, where those real hooks read the mock's session:
+who it acts for, set with `createMockClient(contracts, { session })` and
+`mock.$session({ userId, serviceAccess, isConnected, isKnown })` (each field
+left out keeps its starting value, and the reset after each test puts the
+starting session back), and the rooms `mock.$presence(room, userIds)` sets.
+Its views select members for the session's user:
+
+<!-- example: apps/web/src/components/TaskBoard.test.tsx#session -->
+
+```tsx
+it("lets a signed-in user through the gate", () => {
+  mock.$session({ userId: "ada", serviceAccess: { taskService: "Admin" } }); // useQuickdraw() shows it
+  render(<AuthGate>Board</AuthGate>, { wrapper: mock.$Provider });
+  expect(screen.getByText("Board")).toBeTruthy();
+});
+```
+
+In Storybook, a decorator renders every story inside `qd.$Provider`, and a
+story's `beforeEach` sets its session (`qd.$session(...)`) beside its data.
+
 ### Test databases
 
 `@fitzzero/quickdraw-core/testing/prisma` gives each vitest worker a database
 of its own: `createPrismaTestGlobalSetup` migrates a template once per run
 and clones a database per worker on PostgreSQL (`TEST_DATABASE_URL`), or
-boots PGlite from a cached dump without one; `workerDatabaseUrl` and
-`resetDatabase` (truncates every table) do the rest. Apply `trackPrisma` to
-the test client exactly as in production.
+builds a PGlite dump without one; `workerDatabaseUrl` and `resetDatabase`
+(truncates every table) do the rest. On PGlite each worker boots its own
+database from the dump with `openPgliteFromTemplate`, in milliseconds and
+under jsdom too (it reads the dump through Node's `Blob`); the app's db
+package gives its test client from it while tests run:
+
+<!-- example: packages/db/src/testing.ts#worker -->
+
+```ts
+// this worker's own database: the migrated template, loaded in milliseconds
+const pglite = await openPgliteFromTemplate(TEST_TEMPLATE);
+export const prisma = new PrismaClient({ adapter: new PrismaPGlite(pglite) });
+```
+
+`TEST_TEMPLATE` is `{ migrationsDir, cacheDir, templateName }`, the same the
+global setup builds with (`buildPgliteTemplate(TEST_TEMPLATE)`, or
+`createPrismaTestGlobalSetup`), and a setup file empties the database before
+each test (`beforeEach(() => resetDatabase(prisma))`). Apply `trackPrisma`
+to the test client exactly as in production.
 
 ## Observability
 
@@ -2461,17 +2894,30 @@ is also a server span named `service.method`, with an error status for
 
 ## API docs from contracts
 
-The `quickdraw-docs` command writes Markdown API docs from the contracts
-alone: one page per service (its entity and field tiers, projections,
-methods with their kind, input fields and output, collections, streams,
-channels and events, from the schemas' JSON Schema where they have one) and
-a `README.md` index. It reads contracts, never source code.
+The `quickdraw-docs` command writes Markdown API docs from the contracts:
+one page per service (its entity and field tiers, projections, methods
+with their kind, input fields and output, collections, streams, channels
+and events, from the schemas' JSON Schema where they have one) and a
+`README.md` index. It reads contracts (and, with `--services`, the
+services' definitions), never source code.
 
 ```bash
 quickdraw-docs packages/shared/src/index.ts --out docs/api           # write the pages
 quickdraw-docs packages/shared/src/index.ts --out docs/api --check   # exit 1 when they are stale
+quickdraw-docs packages/shared/src/index.ts --services apps/api/src/services/index.ts --out docs/api
 ```
 
+With `--services <module>` (a module exporting the services, each or in a
+list, as the server takes them; importing it must not start the server),
+each page also says who may call what, read from the services'
+definitions: an "Access" section with the row policy, whether a
+service-wide `Admin` grant passes every check, who may watch the change
+topic (`watchAccess`) and the field levels; each method's access form, in
+words, and its `rowless`; who may open a collection's scope; a channel's
+access; a stream's computed seed and when its items are checked. A
+contract the services module has no service for says so, and a service
+without a contract is an error. Pass the same flag to `--check`.
+
 The module may export each contract, or a map of them as given to
 `createQuickdrawClient`. A TypeScript module loads through Node's type
 stripping, or through `tsx` when the project has it installed (for
@@ -2483,7 +2929,7 @@ nothing. Run `--check` in CI next to the lint step.
 
 ## Lint rules and agent guidance
 
-[`@fitzzero/quickdraw-lint`](../../packages/lint) is the oxlint plugin and base
+[`@fitzzero/quickdraw-lint`](https://github.com/fitzzero/quickdraw/tree/dev/packages/lint) is the oxlint plugin and base
 config every 5.0 app extends: it reports untracked and foreign writes, nested
 and raw SQL writes, hand-sent frames, inline auth guards, unbounded reads,
 database calls and emits in loops, layering breaks, bypasses of the typed
@@ -2498,7 +2944,7 @@ takes an `id`, unless it says `rowless: true`); then lint; then a
 development warning as it happens (`repeated-call`, `repeated-mutation` and
 `repeated-invalidation` name a client loop before the rate limit does).
 
-[`@fitzzero/quickdraw-skills`](../../packages/skills) ships agent rules and skills
+[`@fitzzero/quickdraw-skills`](https://github.com/fitzzero/quickdraw/tree/dev/packages/skills) ships agent rules and skills
 for quickdraw apps and links them into `.claude/` with
 `quickdraw-skills link`, so every app's agents read the same, current
 guidance:
@@ -2514,11 +2960,11 @@ guidance:
 
 ## Migrating from 4.x
 
-[`@fitzzero/quickdraw-codemod`](../../packages/codemod) moves a 4.x app to 5.0:
+[`@fitzzero/quickdraw-codemod`](https://github.com/fitzzero/quickdraw/tree/dev/packages/codemod) moves a 4.x app to 5.0:
 contracts from the method maps, `defineService` from the service classes,
 the typed client for the hooks, and a report of everything left to decide.
-[`MIGRATION.md`](../../MIGRATION.md) explains each step, the access mapping and
-the defaults that changed; [`UPGRADE-PROMPT.md`](../../UPGRADE-PROMPT.md) is the
+[`MIGRATION.md`](https://github.com/fitzzero/quickdraw/blob/dev/MIGRATION.md) explains each step, the access mapping and
+the defaults that changed; [`UPGRADE-PROMPT.md`](https://github.com/fitzzero/quickdraw/blob/dev/UPGRADE-PROMPT.md) is the
 procedure for an agent. Both ship with the codemod, at
 `node_modules/@fitzzero/quickdraw-codemod/MIGRATION.md` and
 `node_modules/@fitzzero/quickdraw-codemod/UPGRADE-PROMPT.md`.
@@ -2533,7 +2979,7 @@ bunx @fitzzero/quickdraw-codemod@next v5 .
 | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `.`                | `defineContract`, `query`, `mutation`, `nullable`, `listOf`, `via`, the kits' contract halves, inference types, `QuickdrawError`, error codes, protocol types, room and topic names                                                             |
 | `./server`         | `initQuickdraw`, `createServer`, `createDispatcher`, `createHttpRouter`, policies, `custom`, the kits' handlers, `requireRow`, `nextOrdinal`, `storageOf`, dev warnings, the Redis adapter, the socket rate limiter, env and encryption helpers |
-| `./server/auth`    | `createAuthRoutes`, `socketAuth`, providers (`google`, `discord`, `mock`, `guest`), session stores, `issueSession`, `liveSession`, JWT, cookie and origin helpers                                                                               |
+| `./server/auth`    | `createAuthRoutes`, `socketAuth`, `requireSession` and `sessionOf`, providers (`google`, `discord`, `mock`, `guest`), session stores, `issueSession`, `liveSession`, JWT, cookie and origin helpers                                             |
 | `./server/express` | Express rate limits: `createAuthLimiter`, `createAuthStatusLimiter`, `createCallLimiter`, `createPublicApiLimiter`, `createWebhookLimiter`                                                                                                      |
 | `./server/mcp`     | `createMcpRegistry`, `describeTools`, `createMcpStdioServer`, `createMcpHttpRouter`, `bootstrapMcpServer`                                                                                                                                       |
 | `./server/otel`    | `otelOnCall`                                                                                                                                                                                                                                    |
@@ -2542,7 +2988,8 @@ bunx @fitzzero/quickdraw-codemod@next v5 .
 | `./utils`          | `createServerCaller`, cache keys (`methodKey`, `entityKey`, `collectionKey`), formatting, navigation, `parseJWTPayload`                                                                                                                         |
 | `./parser`         | the JSON-only Socket.IO parser                                                                                                                                                                                                                  |
 | `./testing`        | `createTestApp`, `describeAccessMatrix`, `expectBudget`, `createRecordingSink`, `DevWarningError`                                                                                                                                               |
-| `./testing/client` | `renderWithQuickdraw`, `createMockClient`                                                                                                                                                                                                       |
+| `./testing/client` | `renderWithQuickdraw`, and everything in `./testing/mock`                                                                                                                                                                                       |
+| `./testing/mock`   | `createMockClient` alone, without Testing Library: for browser bundles such as Storybook                                                                                                                                                        |
 | `./testing/prisma` | test databases on PostgreSQL or PGlite                                                                                                                                                                                                          |
 
 The package also ships the `quickdraw-docs` command.
@@ -2551,7 +2998,7 @@ The package also ships the `quickdraw-docs` command.
 
 A bun workspace with turbo: `packages/core` (this package), `packages/lint`,
 `packages/skills` and `packages/codemod`. See
-[CONTRIBUTING.md](../../CONTRIBUTING.md).
+[CONTRIBUTING.md](https://github.com/fitzzero/quickdraw/blob/dev/CONTRIBUTING.md).
 
 ```bash
 bun install