@fitzzero/quickdraw-skills 5.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present fitzzero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @fitzzero/quickdraw-skills
+
+Agent rules and skills for quickdraw 5.0 apps, and the `quickdraw-skills link`
+command that wires them into an app's `.claude/` directory. Every app reads
+the same guidance, written against the API as built, and it updates with
+the package instead of drifting per app.
+
+```bash
+bun add -d @fitzzero/quickdraw-skills@next
+```
+
+Until 5.0.0 is released, 5.0 is published under the `next` dist-tag,
+which the command names.
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "prepare": "quickdraw-skills link",
+  },
+}
+```
+
+Add the package to the repo's root `package.json`, so it installs at
+`node_modules/@fitzzero/quickdraw-skills` and the links stay the same
+whatever the version.
+
+## What it links
+
+| Link                                   | What it holds                                                                            |
+| -------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `.claude/rules/quickdraw-services.md`  | contracts, `defineService`, tracked writes, derived frames, `affects`, `ctx.touch`, kits |
+| `.claude/rules/quickdraw-access.md`    | access forms, row policies, service grants, failing closed, one policy on every surface  |
+| `.claude/rules/quickdraw-client.md`    | the typed client, live entities and collections, views, optimistic mutations, `watch`    |
+| `.claude/rules/quickdraw-testing.md`   | `createTestApp`, access matrices, budgets, strict warnings, component tests              |
+| `.claude/skills/quickdraw-new-service` | adding a service end to end: contract, service, registration, client, tests              |
+| `.claude/skills/quickdraw-migrate-v5`  | moving a 4.x app to 5.0 with `@fitzzero/quickdraw-codemod` and the migration guide       |
+
+Each rule's `paths` frontmatter follows the quickdraw template's layout
+(`apps/api`, `apps/web`, `packages/shared`), so Claude Code loads it while
+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
+  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,
+  even under one of this package's names. That is how an app keeps its own
+  version of a rule (with different `paths`, say): replace the link with a
+  copy.
+- It writes links only into real directories of the repo. When `.claude`,
+  `.claude/skills` or `.claude/rules` is a symlink (to a shared or global
+  directory, say) or resolves outside the repo, that kind is left alone
+  with a warning, since relative links written through it would land
+  elsewhere and resolve there.
+- `quickdraw-skills link --check` changes nothing and exits 1 when a link is
+  missing, stale (points elsewhere) or dangling, or when a link to a rule or
+  skill the package no longer ships is left; run it in CI.
+
+Commit the links. They are dead on a fresh clone, come alive at the first
+install, and always show the installed version's text. Claude Code skips a
+broken link.

package/bin/cli.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+// quickdraw-skills: links this package's agent rules and skills into a
+// consumer repo's `.claude/` as relative symlinks, the way
+// `@rallycry/conveyor-skills` links its skills:
+//
+//   .claude/skills/<name>     -> node_modules/@fitzzero/quickdraw-skills/skills/<name>
+//   .claude/rules/<name>.md   -> node_modules/@fitzzero/quickdraw-skills/rules/<name>.md
+//
+// Claude Code follows symlinks there and skips broken ones, so the links are
+// safe to commit: they are dead on a fresh clone and come alive at the first
+// install, and their content always matches the installed version.
+//
+// Usage:
+//   quickdraw-skills link           create or refresh the links, prune stale ones (the default)
+//   quickdraw-skills link --check   change nothing; exit 1 when a link is missing, stale or dangling
+//
+// Only links this package owns (their target has the path segments
+// `@fitzzero/quickdraw-skills/skills/` or `@fitzzero/quickdraw-skills/rules/`,
+// or lands in this package's directory) are ever replaced or pruned. A real
+// file or directory, and another package's link, are left alone with a
+// warning, even when they take the name of one of this package's rules or
+// skills: that is how an app keeps its own version of one.
+//
+// Links are only written into real directories of the repo: when `.claude`
+// 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.
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+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
+  link --check    change nothing; exit 1 when a link is missing, stale or dangling
+`;
+
+/** The two kinds of entry this package links: skill directories and rule files. */
+const KINDS = [
+  { name: "skills", isEntry: (entry) => entry.isDirectory() },
+  { name: "rules", isEntry: (entry) => entry.isFile() && entry.name.endsWith(".md") },
+];
+
+function warn(message) {
+  process.stderr.write(`quickdraw-skills: warning: ${message}\n`);
+}
+
+function fail(message) {
+  process.stderr.write(`quickdraw-skills: ${message}\n`);
+  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;
+    }
+  }
+  return undefined;
+}
+
+function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** True when `path` exists without following a symlink: a file, a directory, or a link. */
+function occupied(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The target of the symlink at `path`, with the platform's separator. */
+function targetOf(path) {
+  return readlinkSync(path).split("/").join(sep);
+}
+
+function parseArgs(args) {
+  const known = new Set(["link", "--check", "--help", "-h"]);
+  const unknown = args.find((arg) => !known.has(arg));
+  if (unknown !== undefined) {
+    process.stderr.write(`quickdraw-skills: unknown argument "${unknown}"\n\n${USAGE}`);
+    process.exit(2);
+  }
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+  return { check: args.includes("--check") };
+}
+
+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());
+if (repoRoot === undefined) {
+  fail("found no repo root (a .git or package.json) above the working directory");
+}
+
+/**
+ * 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.
+ */
+function planKind(kind) {
+  const sourceDir = join(packageDir, kind.name);
+  if (!existsSync(sourceDir)) {
+    fail(`no ${kind.name} directory at ${sourceDir} (a broken install?)`);
+  }
+  const stableDir = join(repoRoot, "node_modules", ...PACKAGE.split("/"), kind.name);
+  const names = readdirSync(sourceDir, { withFileTypes: true })
+    .filter((entry) => kind.isEntry(entry))
+    .map((entry) => entry.name)
+    .sort();
+  return {
+    kind: kind.name,
+    names,
+    sourceDir,
+    linkDir: join(repoRoot, ".claude", kind.name),
+    targetDir: existsSync(stableDir) ? stableDir : sourceDir,
+  };
+}
+
+/** True when the path `target` has the segments `@fitzzero/quickdraw-skills/<kind>/` in it. */
+function namesPackage(target, kind) {
+  const segments = target.split(sep);
+  const [scope, name] = PACKAGE.split("/");
+  return segments.some(
+    (segment, index) =>
+      segment === scope &&
+      segments[index + 1] === name &&
+      segments[index + 2] === kind &&
+      index + 3 < segments.length,
+  );
+}
+
+/** True when `path` lies inside `dir`. */
+function inside(path, dir) {
+  return path.startsWith(`${dir}${sep}`);
+}
+
+/**
+ * True when the symlink at `linkPath` belongs to this package: its target
+ * names the installed package, or it lands in this package's directory (as
+ * written, or through any symlink on the way).
+ */
+function ownedBy(plan, linkPath) {
+  const target = targetOf(linkPath);
+  if (namesPackage(target, plan.kind)) {
+    return true;
+  }
+  const landing = resolve(dirname(linkPath), target);
+  if (inside(landing, plan.sourceDir)) {
+    return true;
+  }
+  try {
+    return inside(realpathSync(landing), plan.sourceDir);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Why this package's links cannot go into `.claude/<kind>`, or `undefined`:
+ * `.claude` or `.claude/<kind>` is a symlink, or resolves outside the repo.
+ * A directory that does not exist yet is created inside the repo.
+ */
+function refusal(plan) {
+  const realRoot = realpathSync(repoRoot);
+  for (const [dir, shown] of [
+    [dirname(plan.linkDir), ".claude"],
+    [plan.linkDir, `.claude/${plan.kind}`],
+  ]) {
+    if (!occupied(dir)) {
+      return undefined;
+    }
+    if (isSymlink(dir)) {
+      return `${shown} is a symlink (to ${targetOf(dir)})`;
+    }
+    const real = realpathSync(dir);
+    if (!inside(real, realRoot)) {
+      return `${shown} resolves outside the repo (to ${real})`;
+    }
+  }
+  return undefined;
+}
+
+/** What `--check` and `link` found and did, for the summary. */
+const tally = { problems: 0, linked: 0, pruned: 0 };
+
+function problem(message) {
+  warn(message);
+  tally.problems += 1;
+}
+
+/** Leaves a real file or another package's link at `linkPath` alone, with a warning. */
+function leaveAlone(plan, name, linkPath) {
+  const shown = `.claude/${plan.kind}/${name}`;
+  if (isSymlink(linkPath)) {
+    warn(`${shown} is a link owned by something else (${targetOf(linkPath)}): left alone`);
+  } else {
+    warn(`${shown} exists and is not a link: left alone, so this package's ${name} is not linked`);
+  }
+}
+
+function linkOne(plan, name) {
+  const linkPath = join(plan.linkDir, name);
+  const desired = relative(plan.linkDir, join(plan.targetDir, name));
+  const isLink = isSymlink(linkPath);
+  if (isLink && targetOf(linkPath) === desired) {
+    if (!existsSync(linkPath)) {
+      problem(`link .claude/${plan.kind}/${name} is dangling (${desired})`);
+    }
+    return;
+  }
+  if (occupied(linkPath) && (!isLink || !ownedBy(plan, linkPath))) {
+    leaveAlone(plan, name, linkPath);
+    return;
+  }
+  if (check) {
+    problem(`link .claude/${plan.kind}/${name} is ${isLink ? "stale" : "missing"}`);
+    return;
+  }
+  try {
+    rmSync(linkPath, { force: true });
+    symlinkSync(desired, linkPath);
+    tally.linked += 1;
+    process.stdout.write(`linked .claude/${plan.kind}/${name} -> ${desired}\n`);
+  } catch (error) {
+    // A filesystem without symlinks (Windows without developer mode) gets a
+    // warning, not a failed install.
+    warn(`could not link ${name}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/** Removes (or, with `--check`, reports) this package's links to entries it no longer ships. */
+function pruneKind(plan) {
+  if (!existsSync(plan.linkDir)) {
+    return;
+  }
+  for (const entry of readdirSync(plan.linkDir)) {
+    const linkPath = join(plan.linkDir, entry);
+    if (plan.names.includes(entry) || !isSymlink(linkPath) || !ownedBy(plan, linkPath)) {
+      continue;
+    }
+    if (check) {
+      problem(
+        `link .claude/${plan.kind}/${entry} points to a ${plan.kind} entry this package no longer ships`,
+      );
+      continue;
+    }
+    try {
+      rmSync(linkPath);
+      tally.pruned += 1;
+      process.stdout.write(`pruned .claude/${plan.kind}/${entry}\n`);
+    } catch (error) {
+      warn(`could not prune ${entry}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+
+const plans = [];
+const leftAlone = [];
+for (const plan of KINDS.map(planKind)) {
+  const refused = refusal(plan);
+  if (refused !== undefined) {
+    warn(
+      `${refused}: left alone, since links written through it would not resolve in this repo; make it a real directory to link this package's ${plan.kind}`,
+    );
+    leftAlone.push(`.claude/${plan.kind}`);
+    continue;
+  }
+  plans.push(plan);
+  if (!check) {
+    mkdirSync(plan.linkDir, { recursive: true });
+  }
+  for (const name of plan.names) {
+    linkOne(plan, name);
+  }
+  pruneKind(plan);
+}
+
+const counts = plans.map((plan) => `${plan.names.length} ${plan.kind}`).join(" and ") || "nothing";
+const aside = leftAlone.length === 0 ? "" : `; ${leftAlone.join(" and ")} left alone`;
+if (check) {
+  if (tally.problems > 0) {
+    fail(`${tally.problems} link(s) out of date: run 'quickdraw-skills link'`);
+  }
+  process.stdout.write(`quickdraw-skills: ${counts} linked and up to date${aside}\n`);
+} else {
+  process.stdout.write(
+    `quickdraw-skills: ${counts} in .claude (${tally.linked} updated, ${tally.pruned} pruned)${aside}\n`,
+  );
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@fitzzero/quickdraw-skills",
+  "version": "5.0.0-rc.1",
+  "description": "Agent rules and skills for quickdraw 5.0 apps, linked into .claude/ by the quickdraw-skills command",
+  "keywords": [
+    "agents",
+    "claude-code",
+    "quickdraw",
+    "skills"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fitzzero/quickdraw.git",
+    "directory": "packages/skills"
+  },
+  "bin": {
+    "quickdraw-skills": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "rules",
+    "README.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "oxlint -c ../../.oxlintrc.json bin test",
+    "test": "node --test 'test/*.test.mjs'"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/rules/quickdraw-access.md

@@ -0,0 +1,136 @@
+---
+paths:
+  - "apps/api/**"
+  - "packages/shared/**"
+---
+
+# quickdraw 5.0: access control
+
+> From `@fitzzero/quickdraw-skills` (`quickdraw-skills link`). `paths` follow
+> the quickdraw template: contracts in `packages/shared`, the server in
+> `apps/api`. Another layout replaces this link with a copy and edits them.
+
+Access is declared, never coded inline, and everything fails closed: a
+method without `access` does not compile, and a missing row, a missing id, an
+unknown level or a malformed access list denies.
+
+## Who may call a method
+
+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)                                |
+
+- Levels are `"Read" < "Moderate" < "Admin"` (`AccessLevel` also has
+  `"Public"`). `id` is an input key (type-checked) or a function of the input.
+- Without a principal every form but `"public"` answers `UNAUTHENTICATED`; a
+  principal that fails gets `FORBIDDEN`. In a `"public"` handler
+  `ctx.principal` may be `null`; under every other form it is not.
+- Never guard inline (`if (!ctx.principal) throw ...`): declare the form. The
+  `no-inline-auth-guard` lint rule reports it.
+
+## 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:
+
+- 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.
+- 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), 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).
+
+## Service-wide grants
+
+`principal.serviceAccess` holds grants by service name,
+`{ taskService: "Admin" }`: returned by `authenticate`, or loaded by
+`createServer({ auth: { loadServiceAccess } })`. With
+`auth.serviceAccessSource: { model: "user", column: "serviceAccess" }`, a
+tracked write to that column refreshes the user's open sockets.
+
+- A service-wide `Admin` grant passes every check on its service
+  (`adminBypass: false` on the service turns that off).
+- A grant below `Admin` counts only where the form names `service`: a `Read`
+  grant does not read every row through an `entry` form.
+
+## Row policies
+
+The service's `access` option says how a principal's level on one of its rows
+is found. Column and model names are checked against the Prisma client at
+compile time.
+
+| Policy                                                 | Level from                                      |
+| ------------------------------------------------------ | ----------------------------------------------- |
+| `owner("ownerId")`                                     | `Admin` when the column is the user's id        |
+| `jsonAcl("acl", { owner: "ownerId" })`                 | a `[{ userId, level }]` JSON column, plus owner |
+| `members({ model, entry, user, level, levels? })`      | a membership table row                          |
+| `inherit({ from: projectContract, via: "projectId" })` | the level on the parent row in another service  |
+| `anyOf(policyA, policyB)`                              | the highest level any of them gives             |
+| `resolver({ levelsFor, where? })`                      | your code, one batched read for all ids         |
+
+- `entry` forms need a policy and `scope` forms a `model`; a service without
+  a model may use only `"public"`, `"authenticated"`, `{ service }` and
+  `custom`.
+- `inherit` uses the parent's policy only: grants on the parent's service do
+  not flow down.
+- 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.
+
+## One policy, every surface
+
+The same policy decides method calls, entity subscriptions (`useEntity`),
+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.
+- 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.
+- `fields: { notes: "Admin" }` in the contract strips a field from callers
+  below that level on the row, in replies and in live frames.
+- The service's change topic (`qd:watch` on `"service"`) is closed unless
+  the service declares `watchAccess` (`"public"`, `"authenticated"` or
+  `{ service: L }`). A stream without `access` in its contract is closed.
+  A channel takes `{ access: { service: L }, handler }` on the service and
+  `requires: { entity } | { collection, scope } | { room }` in the contract;
+  `{ room }` admits only a socket a method joined to that app room, so the
+  method's access decides who may send.
+
+## Changing access
+
+- 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`.
+- 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
+  client cannot see needs `ctx.touch`, or the revocation never happens.
+
+## Testing
+
+Pin every service's matrix with `describeAccessMatrix` from
+`@fitzzero/quickdraw-core/testing` (see quickdraw-testing.md): each method
+as owner, member, stranger and anonymous, through the real dispatcher.

package/rules/quickdraw-client.md

@@ -0,0 +1,140 @@
+---
+paths:
+  - "apps/web/**"
+  - "packages/shared/**"
+---
+
+# quickdraw 5.0: the typed client
+
+> From `@fitzzero/quickdraw-skills` (`quickdraw-skills link`). `paths` follow
+> the quickdraw template: the web app in `apps/web`, contracts in
+> `packages/shared`. Another layout replaces this link with a copy and edits
+> them.
+
+## One client, one provider
+
+```tsx
+// apps/web/src/lib/quickdraw.ts: the keys of this map become qd.<key>
+export const qd = createQuickdrawClient({ task, project });
+
+// apps/web/src/app/providers.tsx, a "use client" module
+export function Providers({ children }: { readonly children: React.ReactNode }) {
+  return (
+    <QuickdrawProvider client={qd} url={API_URL}>
+      {children}
+    </QuickdrawProvider>
+  );
+}
+```
+
+- `createQuickdrawClient` and `QuickdrawProvider` come from
+  `@fitzzero/quickdraw-core/client`; the contracts from the shared package.
+  Every member is typed from them: no wrapper hooks, no codegen.
+- `auth` is a token (sent as `auth.token`) or handshake fields; leave it out
+  for cookie sessions. Changing it reconnects, and a hello naming another
+  user empties everything quickdraw cached.
+- `useQuickdraw()` gives
+  `{ connection, status, isConnected, userId, serviceAccess, hello, refusal, isRateLimited }`.
+
+## Reading
+
+| Need                         | Use                                                                       |
+| ---------------------------- | ------------------------------------------------------------------------- |
+| one row, live                | `qd.task.useEntity(id)` → `{ data, isLoading, isRemoved, error }`         |
+| several rows, live           | `qd.task.useEntities(ids)` → `{ data, byId, isLoading, error, errors }`   |
+| a live list of one scope     | `qd.task.board.useCollection(projectId, { view, load: "all", limit })`    |
+| anything else a method reads | `qd.task.stats.useQuery(input, options)` (TanStack's result)              |
+| search as the user types     | `qd.task.search.useSearch(q, { scope, debounceMs })` (search kit methods) |
+| a feed of appended items     | `qd.task.logs.useStream(taskId, { max })` → `{ items, isLoading, error }` |
+
+- Prefer live data: `useEntity` and `useCollection` stay current from the
+  server's frames, resume by revision after a reconnect, and cost no refetch.
+- `useCollection` returns `items`, `index`, `byId`, `totalCount`,
+  `hasMore`, `isLoading`, `isLoadingMore`, `error`, `loadMore`, `loadItems`,
+  `refresh`, `clamped` and `indexTruncated`. `view` names a view the
+  contract declares (filtered on the client over the index); `load: "all"`
+  keeps every page loaded. A `null` scope or id holds nothing;
+  `enabled: false` subscribes to nothing.
+- A query whose result follows writes declares `watch` in its contract; the
+  client then joins that change topic and refetches when it changes.
+- Errors are `QuickdrawError` instances: switch on `error.code`
+  (`FORBIDDEN`, `NOT_FOUND`, `VALIDATION`, `RATE_LIMITED`, ...).
+
+## Writing
+
+```tsx
+const rename = qd.task.rename.useMutation();
+rename.mutate({ id, title }); // returns nothing: never await it
+await rename.mutateAsync({ id, title }); // resolves with the output, rejects with QuickdrawError
+```
+
+- A mutation whose input has `id` and whose output is `"entity"` is
+  optimistic by default: its input's fields show over the cached row and its
+  collection items at once, are dropped if the call fails, and give way to
+  the server's frame. `useMutation({ optimistic: false })` turns that off;
+  `optimistic: (input, cache) => cache.patchEntity(input.id, { ... })`
+  (`removeEntity(id)`, `patchItem(collection, id, fields)`) writes your own.
+- Never refetch or invalidate after a mutation by hand: the frames update
+  live rows and collections, and watched queries refetch themselves. For
+  anything else use `qd.invalidate(qd.task.stats, input?)`, never
+  `queryClient.invalidateQueries` on a quickdraw key.
+- Fire a mutation from an event handler, never from render or from an
+  effect that its own result runs again: that loops, and every round
+  writes. In development the client warns
+  `[quickdraw:repeated-mutation]` (one `useMutation` issuing more than 5
+  within a second, naming its component) and
+  `[quickdraw:repeated-invalidation]` (`qd.invalidate` asking for one query
+  key more than 20 times within a second; a busy watched topic is not
+  counted, the coordinator coalesces it), and the server
+  `[quickdraw:repeated-call]`.
+  An effect that must mutate runs once per change: give it the inputs as
+  dependencies and compare them with what it last sent.
+- Outside React, through the mounted provider's connection:
+  `qd.task.get.call(input)`, `qd.task.rename.call(input)`,
+  `qd.task.get.prefetch(queryClient, input)`; `qd.task.get.key(input)` is
+  the cache key, `["qd", "taskService", "m", "get", input]`.
+
+## Realtime
+
+- Channels: `const { send, isReady } = qd.task.cursor.useChannel();` sends
+  fire-and-forget messages (dropped over the channel's rate). A channel that
+  `requires` a room takes messages only from a socket a method joined to it:
+  the client that sends must make the joining call itself.
+- Events: `qd.task.cursorMoved.useEvent((payload) => ...)` hears the
+  contract's events sent to a room the socket is in.
+- Presence: `usePresence(room)` returns the user ids in an app room, after a
+  method joined the socket to it (`ctx.rooms.join`).
+- Admin screens: `qd.task.admin.adminList.useQuery(input)` and the other
+  admin kit members; `useAdminServices(qd)` lists the services whose
+  `adminMeta` answers the user.
+
+## Server components and other runtimes
+
+- A React server component or route handler cannot call `./client` (it
+  starts with `"use client"`): use
+  `createServerCaller(contracts, { url, headers })` from
+  `@fitzzero/quickdraw-core/utils`, whose
+  `caller.task.get.prefetch(queryClient, input)` fills the keys the hooks
+  read, for `dehydrate` and `HydrationBoundary`.
+- React Native uses the same client and provider (no DOM is needed).
+  React-free code (a Node script, a worker) makes a connection with
+  `createQuickdrawConnection({ url, auth })`, calls `open()`, and calls
+  `callData(connection, { service: "taskService", method: "get", input })`
+  from `./client`; `liveDataOf(connection, queryClient)` holds live rows.
+- A client in another language (a Godot game, a native app) speaks the wire
+  itself: `docs/protocol-v5.md` in the quickdraw repository is the
+  specification, `examples/godot` a GDScript client written from it, and
+  `docs/clients.md` compares the ways in.
+
+## Do not
+
+- Do not use the socket (`socket.emit`, `socket.on`) or hand-written
+  TanStack hooks around quickdraw calls; go through `qd.<service>`. For a
+  hook the typed client has none of (infinite scroll over `list` with
+  `useInfiniteQuery`, `useSuspenseQuery`, `useQueries`, `queryOptions`), key
+  it with the member's `key(input)` (a suffix may follow it) and fetch with
+  its `call(input)`.
+- Do not copy server data into React state to keep it current: read it from
+  the hooks, which share one cache.
+- The lint rules `no-raw-socket`, `no-untyped-client`, `no-manual-refetch`
+  and `no-await-void-mutate` report these.

package/rules/quickdraw-services.md

@@ -0,0 +1,179 @@
+---
+paths:
+  - "apps/api/**"
+  - "packages/shared/**"
+---
+
+# quickdraw 5.0: contracts and services
+
+> From `@fitzzero/quickdraw-skills` (`quickdraw-skills link`). `paths` follow
+> the quickdraw template: contracts in `packages/shared`, the server in
+> `apps/api`. Another layout replaces this link with a copy and edits them.
+
+## The contract comes first
+
+One contract per service, in the shared package, so the client imports it
+without server code. Everything else is typed from it.
+
+```ts
+export const task = defineContract("taskService", {
+  entity: taskSchema, // the full row; every row schema has `id: string`
+  projections: { card: cardSchema }, // named lean shapes; "entity" is implicit
+  fields: { notes: "Admin" }, // the level a caller needs to receive a field
+  methods: {
+    rename: mutation({ input: renameSchema, output: "entity", describe: "Renames a task." }),
+    count: query({
+      input: z.object({ projectId: z.string() }),
+      output: z.number(),
+      watch: { collection: "board", scope: (input) => input.projectId },
+    }),
+  },
+  collections: { board: { scope: "projectId", item: "card", order: byOrdinal } }, // ends in "id"
+});
+```
+
+- Every method is `query` or `mutation`, with `input` and `output`. `output`
+  is a schema or a projection: `"entity"`, `"card"`, `nullable("entity")`,
+  `listOf("card")`. Only a query may `watch`.
+- Schemas are any Standard Schema. Use Zod 4.2 or later: MCP tools, the admin
+  kit, projection keys and `quickdraw-docs` read their JSON Schema.
+- 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.
+
+## The service implements it
+
+```ts
+export const taskService = qd.defineService(task, {
+  model: "task", // the Prisma delegate the rows live in
+  access: inherit({ from: project, via: "projectId" }), // see quickdraw-access.md
+  collections: { board: { anchor: project } },
+  methods: {
+    count: {
+      access: { scope: "Read", of: project, id: "projectId" },
+      handler: ({ input, db }) => db.task.count({ where: { projectId: input.projectId } }),
+    },
+    rename: {
+      access: { entry: "Moderate" },
+      handler: ({ input, db }) =>
+        db.task.update({ where: { id: input.id }, data: { title: input.title } }),
+    },
+  },
+});
+```
+
+- `qd` comes from one `initQuickdraw<{ db: typeof db; principal: AppPrincipal }>()`
+  for the whole app (`context: (base) => ({...})` adds app fields to every
+  `ctx`). `db` is `trackPrisma(new PrismaClient({ adapter }))` from
+  `@fitzzero/quickdraw-core/prisma`, applied as the last extension.
+- `methods` implements exactly the contract's methods; each is
+  `{ access, handler }`, plus `timeoutMs`, `rowless` (see
+  quickdraw-access.md), and for queries `share` (`"caller"` or `"all"`),
+  `ttlMs` and `version`.
+- 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.
+- For a projection output, return the database row (a `Date` where the wire
+  has a string, extra columns allowed): the framework selects and projects
+  it. Never build the wire shape by hand. A relation or computed field is
+  `project: { card: { select, map } }` on the service, `map` synchronous.
+- Fail with `throw new QuickdrawError(code, message, data?)`: `NOT_FOUND`,
+  `CONFLICT`, `VALIDATION`, `FORBIDDEN`, and so on. Anything else thrown
+  reaches the caller as `INTERNAL`, except Prisma's unique violation
+  (`CONFLICT`) and missing row (`NOT_FOUND`, as from `findUniqueOrThrow`).
+- To use another service's method, call it through `ctx.services`, by
+  service name: `await ctx.services.projectService.get({ id })`. It runs as
+  the same principal with transport `"internal"`, checks that method's
+  access, joins this call's unit of work (its writes flush with this call's)
+  and is cancelled with `ctx.signal`; it is typed by the app's `contracts`
+  (`initQuickdraw<{ ...; contracts }>()`). Never write another service's
+  model directly to skip its access checks.
+
+## Writes are tracked; frames are derived
+
+Entity frames, collection deltas and change topics are computed from the
+writes made through `db`, after the response is sent:
+
+- Write through the handler's `db` (it may return `db.task.update(...)`
+  unawaited). In a job, script or webhook, import the tracked client and
+  wrap the work in `qd.run(async (ctx) => ...)`, which flushes before it
+  returns. Never write through the untracked client.
+- Never emit by hand: no `io.emit`, `socket.emit` or `qd:` event names.
+- List the other models a service writes: `writes: ["taskLabel"]`.
+- Nested writes (`data: { labels: { create: [...] } }`) are not tracked:
+  write each model through its own delegate, inside an interactive
+  `db.$transaction(async (tx) => ...)` when they must commit together.
+- Raw SQL writes and database cascades are not seen: record them with
+  `ctx.touch("task", ids)` (`{ removed: true }` for deleted rows); `qd.run`
+  passes `fn` the same `touch`.
+- A write to one row that changes how another service's row looks (a
+  parent's counts) declares `affects: [{ service: task, id: "parentTaskId" }]`.
+
+## Collections
+
+A contract collection has `scope` (a string column, or
+`via({ model, entry, scope })` for a junction table), `item`, `order` (ending
+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`).
+
+## Kits instead of hand-written CRUD
+
+Before writing `get`, `list`, `create`, `update`, `delete`, `search`,
+sharing or admin methods by hand, use the kit: it checks access on every row
+it touches, pages, filters by declared fields and stays live. Lint's
+`prefer-kit` warns on a hand-written method a kit implements (`get`,
+`list`, `create`, `getTask`, `listTasks`, `createTask`, `share`,
+`adminList`, ...) in a service that spreads no kit; when one must stay
+hand-written, say why right above it:
+`// quickdraw: hand-written because it answers null for a missing task`.
+Contract halves come from `@fitzzero/quickdraw-core`, handlers from
+`@fitzzero/quickdraw-core/server`, spread into `methods`:
+
+- `crud.contract({ entity, get: true, list: { item, filter, sort }, create: { input }, update: { input }, delete: true })`
+  (also `getMany`, `reorder`, `bulkUpdate`, `bulkDelete`) with
+  `crud.handlers(task, { access: { get: { entry: "Read" }, ... }, prepare })`.
+- `search.contract({ entity, fields, item?, scope? })` with `search.handlers(task, { access })`.
+- `sharing.contract({ mode: "acl" | "members" })` with `sharing.handlers(project)`,
+  on a service whose policy has a `jsonAcl` or `members`.
+- `admin.contract({ entity })` with `admin.handlers(task)` (`{ service: "Admin" }` by default).
+
+## Realtime
+
+- Streams: `streams: { logs: { item, scope: "taskId", seed: 50, access } }`;
+  push with `qd.stream(task, "logs").push(taskId, item)`, and several items
+  at once with `pushMany(taskId, items)`, never `push` in a loop.
+- Channels: `channels: { cursor: { payload, ratePerSecond, requires } }` in
+  the contract, `channels: { cursor: (payload, ctx) => ... }` on the service.
+  `requires` is what the sending socket must hold: `{ entity: "taskId" }` (a
+  subscription to the row the payload's key names), `{ collection, scope }`,
+  or an app room a method joined that socket to: `{ room: "world" }` names
+  the room itself (not a payload key), ``{ room: (p) => `lobby:${p.lobbyId}` }``
+  computes it. 4.x's `requireRoom` becomes `{ room }`.
+- Events: `events: { moved: { payload } }`, sent with
+  `ctx.rooms.emit(room, task, "moved", payload)` to an app room
+  (`ctx.rooms.join(room)` in a method puts the caller's socket in one).
+
+## Performance
+
+Bound every `findMany` with `take`; batch per-item reads with `in:` filters;
+filter in `where`, not after loading. Write many rows in one statement when
+they all get the same data (`updateMany`, `createMany`). When each row's
+data differs, loop over the rows inside an interactive
+`db.$transaction(async (tx) => ...)` and await one `tx.task.update(...)` by
+id per row, not an array-form `$transaction([...])`, which cannot read a
+moved row inside its batch. `share: "caller"` for hot queries;
+`versionColumn: "updatedAt"` answers "not modified" cheaply. 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
+names a client loop: `[quickdraw:repeated-call]` when one connection calls
+a method with the same input more than 10 times within a second, or is
+refused `RATE_LIMITED` more than 30 times within a minute. Find the client
+code that repeats it (quickdraw-client.md); never raise the rate limit to
+quiet it.

package/rules/quickdraw-testing.md

@@ -0,0 +1,124 @@
+---
+paths:
+  - "apps/**/*.test.ts"
+  - "apps/**/*.test.tsx"
+  - "apps/**/__tests__/**"
+  - "apps/**/__budgets__/**"
+---
+
+# quickdraw 5.0: testing
+
+> From `@fitzzero/quickdraw-skills` (`quickdraw-skills link`). `paths` follow
+> the quickdraw template: tests beside the code in `apps/api` and `apps/web`.
+> Another layout replaces this link with a copy and edits them.
+
+Test through the real server: the same dispatcher, access engine, tracked
+writes and frames production runs. Helpers come from
+`@fitzzero/quickdraw-core/testing`, `@fitzzero/quickdraw-core/testing/client`
+and `@fitzzero/quickdraw-core/testing/prisma`.
+
+## The test app
+
+```ts
+const app = await createTestApp({ services: [projectService, taskService], db });
+const task = await app.as(ada).taskService.create({ projectId, title: "Write the docs" });
+const { call, close } = await app.connect(bo); // a real protocol 5 socket
+await call.taskService.get({ id: task.id });
+await app.frames.waitFor({ event: "qd:e", userId: bo.userId });
+await app.close();
+```
+
+- `createTestApp` takes `createServer`'s options plus `strictWarnings`. A
+  socket acts as the principal it connects as, the rate limiter is off, and
+  the server listens on a free port of 127.0.0.1 (`app.url`).
+- `app.as(principal)` calls in process; `app.connect(principal)` resolves
+  `{ call, socket, hello, close }` once the server said hello. Pass `null`
+  for an anonymous caller. Both callers are keyed by service name
+  (`taskService`), where the web client uses the contract map's keys.
+- `app.frames(match?)` lists every frame the server sent, each with its
+  `event`, `data`, `socketId`, `userId` and `at`;
+  `frames.waitFor(match, timeoutMs?)` waits for one, `frames.clear()`
+  forgets them. Assert on frames, not internals.
+- The app's dispatcher becomes current for the services' `qd`, so
+  `qd.run`, `qd.stream(...).push` and `qd.presence` reach it.
+- `db` is the tracked client over a test database, made exactly as in
+  production (`trackPrisma(new PrismaClient({ adapter }))`). The
+  `./testing/prisma` helpers give each worker a database:
+  `createPrismaTestGlobalSetup`, `workerDatabaseUrl` and `resetDatabase`
+  (PostgreSQL, or PGlite when no `TEST_DATABASE_URL` is set).
+- Seed rows with the untracked client (`prisma`), or inside `qd.run` once an
+  app runs: a tracked write outside any unit of work flushes on its own with
+  an `ambient-write` warning.
+
+## Every service gets an access matrix
+
+```ts
+await describeAccessMatrix(app, {
+  service: taskService,
+  principals: { owner: ada, member: bo, stranger: ed },
+  cases: [
+    { method: "get", input: { id }, allow: ["owner", "member"] },
+    { method: "remove", input: { id }, expect: { owner: "allow", member: "FORBIDDEN" } },
+  ],
+});
+```
+
+- Each case runs as each principal and anonymously (`"deny"` means
+  `UNAUTHENTICATED` without a principal, `FORBIDDEN` with one). It rejects
+  listing every cell that differs; `via: "socket"` runs it over sockets.
+- Mutations run for real, once per allowed principal: give inputs that can
+  run again, or a fresh row per case.
+
+## Hot methods get a budget
+
+```ts
+await expectBudget(() => app.as(ada).taskService.list({ limit: 20 }), { name: "list a page" });
+```
+
+- It records SQL statements and bytes (never time) per call and for the
+  whole step, in `__budgets__/<test file>.json` beside the test: commit it.
+  A missing entry is written, a cheaper step rewrites its entry (under CI it
+  fails: rerun locally and commit), a costlier one fails naming each number
+  that grew. Statements must match exactly; bytes may move 5%.
+- Accept a deliberate rise with `QD_ALLOW_BUDGET_GROWTH=1` (every budget) or
+  `QD_ALLOW_BUDGET_GROWTH="list a page"` (the ones named), then commit the
+  file. Give each step of a test file its own name. Await everything the
+  step should cost inside `run`, measure one step at a time, and run a step
+  once first when it may pay a one-time read.
+
+## Development warnings
+
+`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
+logged, and `app.close()` ends it. Turn it on for service suites.
+`createRecordingSink()` passed as `flushSink` records what each flush wrote.
+
+## Components
+
+- Against the real server:
+  `const view = await renderWithQuickdraw(<Board projectId={id} />, { app, as: ada, client: qd })`
+  from `./testing/client` returns Testing Library's result plus
+  `connection`, `queryClient`, `disconnect()` and `reconnect()`. Change
+  data with `app.as(...)` and wait for the screen (`findByText`).
+- Without a server: `createMockClient({ task, project })` has the typed
+  client's shape with stubs: `qd.task.get.mockResolvedValue(row)`,
+  `mockRejectedValue(error)`, `mockImplementation(fn)`, `calls`;
+  `qd.task.useEntity.mockRow(row)` (and `mockRemoved`, `mockError`);
+  `qd.task.board.mockScope(scope, items)`; `mockItems` for a stream, `sent`
+  for a channel, `mockEmit` for an event. Everything set is forgotten
+  after each test only when the runner has a global `afterEach` (vitest
+  with `globals: true`, or jest); otherwise add
+  `afterEach(() => mock.$reset())`. It shows no optimistic updates.
+
+## What a new service's tests cover
+
+1. The access matrix of every method.
+2. Live behavior: a write by one user reaches another's entity or
+   collection (`frames.waitFor`, or a rendered component).
+3. A budget for each method a page calls on load, or in a loop.
+4. Errors callers rely on (`NOT_FOUND`, `CONFLICT`, `VALIDATION`) by code.

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

@@ -0,0 +1,81 @@
+---
+name: quickdraw-migrate-v5
+description: Move a quickdraw 4.x app to quickdraw 5.0 (BaseService classes, ServiceRegistry and useService hooks to contracts, defineService and the typed client) with @fitzzero/quickdraw-codemod and the migration guide. Use when asked to "upgrade quickdraw", "migrate to quickdraw 5", when the repo has a quickdraw-migration-report.md, or when lint reports quickdraw/no-v4-api.
+---
+
+# Migrate a quickdraw 4.x app to 5.0
+
+The codemod does the mechanical part; you work through what it marks. The
+details of every step are in the migration guide:
+`node_modules/@fitzzero/quickdraw-codemod/MIGRATION.md` (or `MIGRATION.md` at
+the root of the quickdraw repository). Read its sections as the report sends
+you to them.
+
+## Rules
+
+- **Never change who may call a method silently.** The codemod's access forms
+  admit exactly the callers 4.x admitted: `"Public"` became `"public"`, a
+  method with a row id `{ service: L, entry: L, id }` (never `{ entry: L }`:
+  4.x let a service grant pass the row check), `"Read"` without a row id
+  `"authenticated"` (marked: 4.x let every signed-in user call it), and
+  `"Moderate"` or `"Admin"` without one `{ service: L }`. Change a form only
+  as a decision the user agrees to.
+- **Keep every service name**: stored grants (`User.serviceAccess`, JSON
+  access lists) name them.
+- **One step per commit**, lint, typecheck and tests green after each.
+
+## Procedure
+
+1. **Prepare.** A clean tree on a new branch. Node 24, Prisma 7, Zod 3.25 or
+   later (4.2 or later where JSON Schema is read: MCP tools, the admin kit,
+   projection keys). Upgrade `@fitzzero/quickdraw-core` to 5.0 (`@next` until
+   5.0.0 ships) in every package that imports it, add
+   `@fitzzero/quickdraw-lint`, `@fitzzero/quickdraw-skills` and `oxlint` as
+   dev dependencies, extend `oxlint.base.jsonc`, add `quickdraw-skills link`
+   to `prepare`, and add `zod` to the shared package if it lacks it.
+2. **Run the codemod** from the repository root, first with `--dry-run`:
+
+   ```bash
+   bunx @fitzzero/quickdraw-codemod@next v5 . --dry-run
+   bunx @fitzzero/quickdraw-codemod@next v5 .
+   ```
+
+   It expects the template's layout (`packages/shared`, `apps/api`,
+   `apps/web`, `packages/db`); `--shared`, `--api`, `--web` and
+   `--db-package` move each part. Commit its output untouched.
+
+3. **Read `quickdraw-migration-report.md`.** Every item is a
+   `// quickdraw-migrate: review [kind] ...` marker above the code it is
+   about. Work through it in this order, one commit per step:
+   1. **Contracts** (`[contract]`): real schemas for the entity and each
+      `todoSchema`; check each method's kind (chosen from its name).
+   2. **Access** (`[access]`, `[access-override]`): decide the
+      `"authenticated"` forms and the `rowless: true` flags (keep one only
+      for a lookup open to anyone; else an `entry` form); port
+      `checkAccess`/`checkEntryACL` overrides into the service's policy
+      (`owner`, `jsonAcl`, `members`, `inherit`, `anyOf`, `resolver`).
+   3. **Emits** (`[emit]`, `[write]`, `[raw-sql]`, `[lifecycle]`,
+      `[collection]`, `[projection]`, `[admin]`, `[kit]`): write through
+      `db`, declare the collections (boards: `index`, `views`,
+      `useCollection`; never a fat query with `watch`), delete the hand
+      emits, turn `toDto` and protected fields into projections and
+      `fields`, use the admin kit, and move each method a kit implements to
+      its kit (or keep it with `// quickdraw: hand-written because ...`).
+   4. **Client** (`[client]`): declare the collections the web app reads,
+      settle dropped hook options (`invalidateOn` becomes `watch`), replace
+      the 4.x `QuickdrawProvider` props.
+
+   Then `[this]`, `[context]`, `[channel]`, `[server]` and `[v4-api]`:
+   instance state, the 4.x context, channels, the server set-up
+   (`qd.createServer`, with `legacyWire: true` while 4.x clients remain).
+
+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
+   left.
+5. **Check**: `oxlint` (`no-v4-api` lists every 4.x API left, with its
+   replacement; `no-todo-schema` every placeholder; `prefer-kit` every
+   hand-written method a kit implements), the typecheck, the tests, and the
+   running app (a change from a second session arrives live).
+
+Done when the report says nothing is left to review and lint, the
+typecheck and the tests are clean.

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

@@ -0,0 +1,161 @@
+---
+name: quickdraw-new-service
+description: Add a service to a quickdraw 5.0 app end to end - its contract in the shared package, the service on the server, registration in createServer, the typed client's hooks in the web app, and its tests (access matrix, live behavior, budgets). Use when asked to "add a service", "add a model to the API", "expose X to the client", or to add methods, collections or a kit to an existing service.
+---
+
+# Add a quickdraw service
+
+Five steps, in this order, because each one is typed by the one before it.
+Paths follow the quickdraw template (`packages/shared`, `apps/api`,
+`apps/web`); use the app's own if they differ. The rules
+`quickdraw-services.md`, `quickdraw-access.md`, `quickdraw-client.md` and
+`quickdraw-testing.md` (linked into `.claude/rules/`) hold the details.
+
+Before you start, read one existing service and its contract in this app,
+and the Prisma model the rows live in. Decide:
+
+- **Where its rows live**: a Prisma model, or none (an RPC-only service has
+  no `entity`, `model` or row policy).
+- **Who may see a row**: an owner column, a JSON access list, a membership
+  table, or the parent row's access (`inherit`). This is the row policy.
+- **What a client lists**: which scopes (a project's tasks, a user's chats).
+  Each is a collection, not a list method.
+
+## 1. The contract (`packages/shared/src/contracts/<name>.ts`)
+
+<!-- example: packages/shared/src/contracts/label.ts -->
+
+```ts
+import { crud, defineContract, mutation } from "@fitzzero/quickdraw-core";
+import { z } from "zod";
+
+const label = z.object({ id: z.string(), projectId: z.string(), name: z.string() });
+
+export const labelContract = defineContract("labelService", {
+  entity: label,
+  methods: {
+    ...crud.contract({ entity: label, get: true, create: { input: label.omit({ id: true }) } }),
+    rename: mutation({
+      input: z.object({ id: z.string(), name: z.string() }),
+      output: "entity",
+      describe: "Renames a label.",
+    }),
+  },
+  collections: {
+    byProject: {
+      scope: "projectId",
+      item: "entity",
+      order: [
+        ["name", "asc"],
+        ["id", "asc"],
+      ],
+    },
+  },
+});
+```
+
+- Service names end in `Service` and never change once deployed: they are
+  stored in users' grants and sent on the wire.
+- Use Zod 4.2 or later for every schema; give each method a `describe`
+  sentence when agents or MCP clients will call it.
+- Export the contract from the shared package's index, next to the others.
+
+## 2. The service (`apps/api/src/services/<name>.ts`)
+
+<!-- example: apps/api/src/services/label.ts -->
+
+```ts
+import { crud, inherit } from "@fitzzero/quickdraw-core/server";
+import { labelContract, projectContract } from "@project/shared";
+import { qd } from "../quickdraw";
+
+export const labelService = qd.defineService(labelContract, {
+  model: "label",
+  access: inherit({ from: projectContract, via: "projectId" }),
+  collections: { byProject: { anchor: projectContract } },
+  methods: {
+    ...crud.handlers(labelContract, {
+      access: {
+        get: { entry: "Read" },
+        create: { scope: "Moderate", of: projectContract, id: "projectId" },
+      },
+    }),
+    rename: {
+      access: { entry: "Moderate" },
+      handler: ({ input, db }) =>
+        db.label.update({ where: { id: input.id }, data: { name: input.name } }),
+    },
+  },
+});
+```
+
+- `qd` is the app's one `initQuickdraw` instance; import it, never create a
+  second one.
+- Every method declares `access`; write through the handler's `db`; list any
+  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).
+- 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.
+
+## 3. Register it (`apps/api/src/index.ts`)
+
+Add the service to `qd.createServer({ services: [...] })`. If the app has an
+MCP registry (`createMcpRegistry({ services, dispatcher })`), add it there
+too, or exclude the methods agents must not call.
+
+## 4. Use it from the web app
+
+Add the contract to the map given to `createQuickdrawClient` (the key you
+pick becomes `qd.<key>`), then use the hooks:
+
+<!-- example: apps/web/src/components/Labels.tsx -->
+
+```tsx
+"use client";
+
+import { qd } from "../lib/quickdraw";
+
+export function Labels({ projectId }: { readonly projectId: string }) {
+  const { items } = qd.label.byProject.useCollection(projectId);
+  const rename = qd.label.rename.useMutation();
+  return (
+    <ul>
+      {items.map((label) => (
+        <li key={label.id}>
+          <button type="button" onClick={() => rename.mutate({ id: label.id, name: "urgent" })}>
+            {label.name}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Read with `useEntity` and `useCollection` before `useQuery`; never refetch
+or invalidate after a mutation by hand.
+
+## 5. Test it (`apps/api/src/services/<name>.test.ts`)
+
+- `describeAccessMatrix` over every method, as an owner, a member, a
+  stranger and anonymously.
+- One live test: a write by one user reaches another user's collection or
+  entity (`app.frames.waitFor`, or a component through
+  `renderWithQuickdraw`).
+- `expectBudget` for each method a page calls on load; commit the
+  `__budgets__` file it writes.
+- `createTestApp({ ..., strictWarnings: true })`, so N+1 reads, unbounded
+  reads and nested writes in the service's calls fail the test that caused
+  them. Seed rows with the untracked client (`prisma`).
+
+## Finish
+
+Run the app's lint (the quickdraw rules catch untracked writes, foreign
+writes, unbounded reads and raw socket use), typecheck and tests. If the app
+generates API docs with `quickdraw-docs`, regenerate them and commit the
+result.