@fitzzero/quickdraw-skills 5.0.0 → 5.1.0

package/README.md

@@ -24,14 +24,15 @@ 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       |
+| 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                                                                                                                                 |
+| `.claude/skills/quickdraw-api-docs`    | describes on every contract member, and the API docs kept current: committed and checked, or regenerated on each push by the workflow file it ships (`docs-api.yml`, which an app copies into `.github/workflows`) |
 
 Each rule's `paths` frontmatter follows the quickdraw template's layout
 (`apps/api`, `apps/web`, `packages/shared`), so Claude Code loads it while

package/package.json

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

package/rules/quickdraw-access.md

@@ -36,6 +36,45 @@ Every method's `{ access, handler }` names one form:
 - Never guard inline (`if (!ctx.principal) throw ...`): declare the form. The
   `no-inline-auth-guard` lint rule reports it.
 
+## Which kinds of principal may call
+
+An app whose principals come in kinds (`principal.kind`: a user, an agent's
+token, a runner) declares which kinds may call with `kinds`, beside `access`,
+never inside a form:
+
+```ts
+export const qd = initQuickdraw<{ db: typeof db; principal: AppPrincipal }>({
+  kinds: ["user", "agent"], // every service, unless it narrows them
+});
+
+export const tokenService = qd.defineService(token, {
+  kinds: ["user", "agent"], // its methods, subscriptions and channels
+  methods: {
+    mint: { access: "authenticated", kinds: ["user"], handler: mint }, // this method alone
+    heartbeat: { access: "authenticated", handler: beat }, // the service's kinds
+  },
+});
+```
+
+- Each level only narrows the one above it: a method's list within its
+  service's, a service's within the app's. The types refuse a name that is
+  no kind of the app's principal, and `defineService` refuses a wider or
+  empty list when the service is defined.
+- A principal of another kind, or without a `kind`, gets `FORBIDDEN` before
+  the form is asked. No grant passes the check, a service-wide `Admin` grant
+  included: a token acting with its user's grants is what it stops.
+- An anonymous caller is left to the form (`UNAUTHENTICATED` wherever it
+  needs a principal). So a `"public"` method takes no `kinds` of its own: a
+  caller of a refused kind would call it signed out. It keeps its service's
+  list, which holds for signed-in callers.
+- A service's list also refuses other kinds on `qd:sub`, `qd:col:sub`,
+  `qd:watch` and `qd:stream:sub`, and its channels drop their messages.
+- Never check the kind in a handler (`if (ctx.principal.kind !== "user")
+throw ...`; `no-inline-auth-guard` reports it) or in a `custom` form:
+  `kinds` combines with any form (`{ entry: "Moderate" }` and
+  `kinds: ["user"]`), where `custom` would have to check the row by hand.
+  A check on a claim, such as a token's `scope`, stays `custom`.
+
 ## A method that takes a row id
 
 On a service with a policy, a method whose input has `id` reads or writes
@@ -54,7 +93,8 @@ defined. Fix the form, not the error:
   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
+  without JSON Schema (a Zod 3 schema) or one that names no keys (a
+  `todoSchema` without `keys`), a bare string that is the id itself
   and a row named by another key (`taskId`, `ids`) are not checked, so the
   form is all yours there (`{ entry: L, id: "taskId" }` names another key).
 
@@ -88,7 +128,7 @@ compile time.
 | `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         |
+| `resolver({ levelsFor, where?, reads })`               | your code, one batched read for all ids         |
 | `everyone("Read")`                                     | every signed-in user, on every row; no read     |
 
 - `entry` forms need a policy and `scope` forms a `model`; a service without
@@ -100,6 +140,17 @@ compile time.
   `anyOf(owner("id"), everyone("Read"))`, never a hand-written `resolver`
   answering `Read` for every id: `rowless: true` covers one method, not
   subscriptions.
+- A `resolver` declares what its levels depend on, or nothing re-checks it
+  and a removed member keeps their live rows:
+  `reads: { columns: ["visibility"], memberships: [{ model: "teamMember", entry: "projectId", user: "userId", level: "role" }] }`
+  (columns of the service's model; membership tables as `members` takes
+  them, `entry` holding this service's row id). Tracked writes to them then
+  revoke and re-check as for the other policies, and `tools.rows(ids)` reads
+  the declared columns. `reads: "none"` only when nothing a tracked write
+  changes can change a level (the principal's grants alone). Without either
+  the server warns `[quickdraw:resolver-without-reads]` and a strict test
+  app fails to start. A level from another service's row is `inherit`'s
+  job, alone or in `anyOf`.
 - Lookups are batched per call: checking 60 ids costs what one does.
   `createServer({ access: { cacheMs } })` keeps them across calls; tracked
   writes to the columns and tables a policy reads evict them.
@@ -153,4 +204,11 @@ channel `requires`.
 
 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.
+as owner, member, stranger and anonymous, through the real dispatcher, and
+on a service with `kinds`, as a principal of each kind it refuses (each
+cell records its principal's `kind`). Before changing a form, a policy or
+the kinds of principal, record the whole table with `snapshotAccessMatrix`
+(every method, entity subscribe and collection scope, in
+`__access__/<test file>.json`): each cell the change moves then fails,
+saying whether it opens or closes access, until
+`QD_UPDATE_ACCESS_SNAPSHOT=1` accepts it.

package/rules/quickdraw-services.md

@@ -17,6 +17,7 @@ without server code. Everything else is typed from it.
 
 ```ts
 export const task = defineContract("taskService", {
+  describe: "Tasks on a project's board.", // what the service is for
   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
@@ -26,15 +27,23 @@ export const task = defineContract("taskService", {
       input: z.object({ projectId: z.string() }),
       output: z.number(),
       watch: { collection: "board", scope: (input) => input.projectId },
+      describe: "Counts the tasks on a project's board.",
     }),
   },
-  collections: { board: { scope: "projectId", item: "card", order: byOrdinal } }, // ends in "id"
+  collections: {
+    board: { describe: "A project's tasks.", scope: "projectId", item: "card", order: byOrdinal },
+  },
 });
 ```
 
 - 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`.
+- Give the contract and every member a `describe`: a sentence or two on what
+  it is for (each method, collection, stream, channel and event). The MCP
+  bridge uses a method's as its tool's description, and `quickdraw-docs`
+  leads each section with it. Lint's `require-describe` warns on each one
+  missing; kits' contract halves write their own.
 - 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
@@ -65,12 +74,14 @@ export const taskService = qd.defineService(task, {
 
 - `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
+  `ctx`; `kinds: ["user", "agent"]` the kinds of principal every service
+  admits). `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`.
+  `{ access, handler }`, plus `kinds` and `rowless` (see
+  quickdraw-access.md), `timeoutMs`, and for queries `share` (`"caller"` or
+  `"all"`), `ttlMs` and `version`. A service takes `kinds` too: the kinds of
+  principal its methods and subscriptions admit.
 - 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.
@@ -186,6 +197,11 @@ Contract halves come from `@fitzzero/quickdraw-core`, handlers from
 - `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).
+  Name what an admin may change with `editable: ["title", "status"]` (on
+  `admin.contract` too, so the input schemas and MCP tools name only those):
+  every other field is read-only, and a write naming one is `VALIDATION`.
+  Without it the kit writes every field it shows but `id` and the
+  timestamps, owner and foreign-key columns included.
   On a users service, `admin.handlers(user, { grants: true })` lets the admin
   screen edit `serviceAccess` through `adminUpdate` (service-wide Admins
   only); never hand-write a `setServiceAccess` method for it. `adminMeta`

package/rules/quickdraw-testing.md

@@ -4,6 +4,7 @@ paths:
   - "apps/**/*.test.tsx"
   - "apps/**/__tests__/**"
   - "apps/**/__budgets__/**"
+  - "apps/**/__access__/**"
 ---
 
 # quickdraw 5.0: testing
@@ -30,7 +31,7 @@ The template runs two lanes, and a file's name picks its lane:
 
 A test that boots the app but is named `<name>.test.ts` runs in the unit
 lane and fails at its first query. Budgets go to `__budgets__/` beside the
-test file that measures them.
+test file that measures them, and access snapshots to `__access__/`.
 
 ## The test app
 
@@ -95,6 +96,45 @@ await describeAccessMatrix(app, {
   (`input: async () => ({ id: await newTask() })`), which makes a fresh row
   for every cell; never order the principals so the allowed one goes last.
 
+## Pin the whole matrix with a snapshot
+
+Before a migration, a policy refactor or a new kind of principal, record
+every cell once and let each change fail until someone accepts it:
+
+```ts
+const report = await snapshotAccessMatrix(app, {
+  principals: (seeded) => ({ owner: seeded.ada, member: seeded.bo, stranger: seeded.ed }),
+  reset: async () => {
+    await resetDatabase(prisma); // from @fitzzero/quickdraw-core/testing/prisma
+    return await seed(); // the app's seed: users, a project, a task in it and one outside it
+  },
+  rows: (seeded) => ({
+    projectService: seeded.projectId,
+    taskService: { own: seeded.taskId, other: seeded.otherTaskId },
+  }),
+});
+expect(report.inconclusive).toEqual([]);
+```
+
+- It runs every method of the app's services (or `services`), each entity
+  subscribe and each collection scope, as every principal and anonymously,
+  and writes `__access__/<test file>.json` beside the test on the first run:
+  commit it. Each cell is the exact outcome (`"ok"` or the error code).
+- `reset` runs first and after every mutation access let through, so no cell
+  sees another's writes. `principals` may be a function of what `reset`
+  returned, for ids the seed makes. `rows` names every service a form,
+  subscribe or anchor reads (a row id, or variants such as `{ own, other }`).
+- Inputs are made from each input's JSON Schema with the row where the form
+  reads it; give the ones that cannot be made with
+  `inputs: (ref, board) => ...` (`ref.service`, `ref.method`, `ref.row`).
+  Cells never called are `VALIDATION` and listed in `report.inconclusive`:
+  keep it empty.
+- A changed cell fails, saying whether it opens or closes access. When the
+  change is meant, rerun with `QD_UPDATE_ACCESS_SNAPSHOT=1` and commit the
+  file; never set it in CI, which also fails a missing file and added or
+  removed cells. Leave out methods whose outcome varies with
+  `exclude: ["<service>.<method>"]`. One snapshot per test file.
+
 ## Hot methods get a budget
 
 ```ts
@@ -122,9 +162,10 @@ test that caused it (an oversized reply fails an in-process `app.as(...)`
 call; over a socket or HTTP the reply was already sent, so it is logged, not
 thrown). Warnings outside its calls (an `ambient-write` while seeding) are
 logged, and `app.close()` ends it. `tiered-field-in-output` (a method's own
-output schema declares a tiered field, at any depth) is thrown by
-`createTestApp` itself: answer `"entity"` from that method rather than
-turning strictness off.
+output schema declares a tiered field, at any depth) and
+`resolver-without-reads` (a `resolver` policy declares no `reads`) are
+thrown by `createTestApp` itself: answer `"entity"` from that method, or
+declare the resolver's `reads`, rather than turning strictness off.
 Turn it on for service suites.
 `createRecordingSink()` passed as `flushSink` records what each flush wrote.
 
@@ -166,7 +207,8 @@ Turn it on for service suites.
 
 ## What a new service's tests cover
 
-1. The access matrix of every method.
+1. The access matrix of every method (`describeAccessMatrix`), or its
+   snapshot (`snapshotAccessMatrix`).
 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.

package/skills/quickdraw-api-docs/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: quickdraw-api-docs
+description: Keep a quickdraw 5.0 app's API docs (the quickdraw-docs pages, which MCP clients and agents read) current - write a describe on every contract member, then either commit the pages and check them in pull-request CI, or install the docs-on-push workflow that regenerates them on every push to the base branch. Use when asked to "set up API docs", "document the MCP tools", "keep docs/api up to date", when generated docs conflict in merges, or when lint reports quickdraw/require-describe.
+---
+
+# Keep the API docs current
+
+`quickdraw-docs` writes one Markdown page per service from its contract, and
+an index. A page leads with the contract's `describe`; each method shows its
+`describe`, its kind, its default MCP tool name (`{service}_{method}`; an
+app's registry can rename tools, and `bind` can take arguments out of a
+tool's schema, which the docs cannot see) and, for a query, the MCP
+read-only hint; with `--services`, also who may call it, and each page
+says which other services it depends on (with a graph on the index). The
+command and its options are in the README's "API docs from contracts"
+section (`node_modules/@fitzzero/quickdraw-core/README.md`).
+
+## 1. Write the describes
+
+The docs and the MCP tools are only as useful as the prose in the contract.
+Give every member a `describe` of a sentence or two that says what it is
+for: the contract, each `query` and `mutation`, each collection, stream,
+channel and event. The MCP bridge uses a method's describe as its tool's
+description; without one an agent sees only `taskService.rename (mutation)`.
+
+```ts
+export const taskContract = defineContract("taskService", {
+  describe: "Tasks on a project's board.",
+  methods: {
+    rename: mutation({ input: renameInput, output: "entity", describe: "Renames a task." }),
+  },
+  collections: {
+    board: {
+      describe: "A project's tasks, in board order.",
+      scope: "projectId",
+      item: "entity",
+      order: [["id", "asc"]],
+    },
+  },
+});
+```
+
+Lint's `quickdraw/require-describe` (a warning in the base config) lists
+each member without one, and each static describe under 3 words. The 4.x
+codemod writes none, so a migrated app starts with one warning per member.
+Once the list is empty, set the rule to `"error"` in the app's
+`.oxlintrc.json` so new members cannot land without one. Kits' contract
+halves (`...crud.contract(...)`) write their own.
+
+## 2. Pick where the pages live
+
+| The repo                                                         | Do this                                                                                     |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Few pull requests at a time                                      | Commit the pages (`--out docs/api`) and run `quickdraw-docs ... --check` in pull-request CI |
+| Many pull requests at a time, or agents that each change methods | Install the docs-on-push workflow below, and never commit the pages by hand                 |
+
+A committed generated file changes in every pull request that touches a
+contract, so two such pull requests conflict on it even when their
+contracts do not. The workflow moves the pages out of pull requests: they
+are regenerated after each push to the base branch.
+
+## 3. Install the docs-on-push workflow
+
+1. Copy `node_modules/@fitzzero/quickdraw-skills/skills/quickdraw-api-docs/docs-api.yml`
+   to `.github/workflows/docs-api.yml`. GitHub reads only committed
+   workflows, so `quickdraw-skills link` cannot install it.
+2. Set it to the app:
+   - `on.push.branches`: the base branch pull requests merge into.
+   - `on.push.paths`: where the contracts and services live, and the
+     workflow itself.
+   - `env`: `CONTRACTS` (the module exporting the contracts), `SERVICES`
+     (the module exporting the services) and `OUT` (the pages' folder).
+   - The build step: the packages the services module imports, by the
+     names in their `package.json` (the template's are `@project/db`, with
+     its Prisma client, and `@project/shared`).
+3. Remove any `quickdraw-docs --check` step from pull-request CI, and remove
+   `OUT` from `.gitignore` if it is there.
+4. Merge it, then run it once from the Actions tab (`workflow_dispatch`): the
+   first run commits the pages.
+
+### Rules
+
+- **Never commit the pages by hand once the workflow is installed.** They
+  belong to the workflow; a hand edit conflicts with its next commit and is
+  overwritten by it. Change the contract instead.
+- **The services module imports without secrets.** The `generate` job has
+  none: importing the module must not read a required environment
+  variable, connect to the database or start the server. Move such work
+  into the function that starts the server.
+- **Keep the two jobs.** The job that can write (`commit`, with
+  `contents: write`) runs no dependency code: no install, no build, only
+  git. The job that runs dependency code (`generate`) has a read-only token. Never
+  trigger it with `pull_request_target`, and never give `generate` a secret.
+- **Keep `GITHUB_TOKEN` for the push.** A push made with it starts no
+  workflow run, so the docs commit never starts CI or this workflow again.
+  On a protected branch that `GITHUB_TOKEN` cannot push to, mint a GitHub
+  App token in the `commit` job only (`actions/create-github-app-token`),
+  give it to that job's checkout, and add `[skip ci]` to the commit
+  message: a push made with an app token does start workflows.
+
+## 4. Check it
+
+After the merge, the Actions tab shows an "API docs" run for each push that
+touched a contract or a service. A run commits only when a page changed,
+as `github-actions[bot]`. A failing `generate` step prints what
+`quickdraw-docs` refused: usually a module that needs a build or a secret
+at import.

package/skills/quickdraw-api-docs/docs-api.yml

@@ -0,0 +1,104 @@
+# API docs on push: regenerates the quickdraw-docs pages from the contracts on
+# every push to the base branch, and commits them when they changed. Copied
+# into an app by the quickdraw-api-docs skill
+# (node_modules/@fitzzero/quickdraw-skills/skills/quickdraw-api-docs/SKILL.md):
+# set the branch, the paths, the env block and the build step to the app's own.
+#
+# Two jobs, so the job that can write to the repository runs no dependency
+# code: `generate` installs, builds and runs quickdraw-docs with a read-only
+# token and no secrets, and hands the pages over as an artifact; `commit`
+# only downloads them and runs git.
+
+name: API docs
+
+on:
+  push:
+    branches: [dev]
+    paths:
+      - "packages/shared/src/**"
+      - "apps/api/src/services/**"
+      - ".github/workflows/docs-api.yml"
+  workflow_dispatch:
+
+# The latest push wins: an older run would commit pages a newer one replaces.
+concurrency:
+  group: docs-api-${{ github.ref_name }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  # The module exporting the contracts, and the one exporting the services
+  # (importing it must not start the server, and must not need a secret).
+  CONTRACTS: packages/shared/src/index.ts
+  SERVICES: apps/api/src/services/index.ts
+  OUT: docs/api
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: package.json
+
+      - run: bun install --frozen-lockfile
+
+      # What the services module imports loads from its built output: the db
+      # package (with its Prisma client) and the shared package.
+      - name: Build what the services module imports
+        run: bunx turbo run build --filter=@project/db --filter=@project/shared
+
+      - name: Generate the API docs
+        run: bunx quickdraw-docs "$CONTRACTS" --services "$SERVICES" --out "$OUT"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: docs-api
+          path: ${{ env.OUT }}
+          if-no-files-found: error
+          retention-days: 1
+
+  commit:
+    needs: generate
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      # GITHUB_TOKEN on purpose: a push made with it starts no workflow run, so
+      # the docs commit never starts this workflow or CI again.
+      - uses: actions/checkout@v7
+
+      # The whole folder as generate left it: a page of a removed service goes.
+      - name: Replace the pages with the generated ones
+        run: rm -rf "$OUT"
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs-api
+          path: ${{ env.OUT }}
+
+      - name: Commit the pages when they changed
+        run: |
+          git add --all -- "$OUT"
+          if git diff --cached --quiet; then
+            echo "The API docs are current."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898283+github-actions[bot]@users.noreply.github.com"
+          git commit -m "docs(api): regenerate from the contracts"
+          git push origin "HEAD:$GITHUB_REF_NAME"

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

@@ -53,17 +53,28 @@ guide's sections as the report sends you to them.
    It expects the template's layout (`packages/shared`, `apps/api`,
    `apps/web`, `packages/db`); `--shared`, `--api`, `--web` and
    `--db-package` move each part. It formats its output with the app's
-   formatter. Commit its output untouched, then run
-   `quickdraw-lint baseline -c .oxlintrc.json` and commit the baseline, so
-   lint passes and reports only new violations. Add each file the report
-   lists under "Carve-outs" to the template's carve-out script
+   formatter. On an app of more than 1,500 source files it starts itself
+   again with a larger heap (75% of the memory, at most 16384 MiB) and says
+   so; pass `--heap <MiB>` when other work shares the memory, smaller after
+   a SIGKILL, larger after running out of heap. Commit its output
+   untouched, then run `quickdraw-lint baseline -c .oxlintrc.json` and
+   commit the baseline, so lint passes and reports only new violations. Add
+   each file the report lists under "Carve-outs" to the template's carve-out
+   script
    (`scripts/strip-game.mjs`'s delete list).
 
 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:
+   about. First the "Services" section (`[service]`), when it has one: a
+   contract whose class implements none of its method map was read from
+   the wrong class, so settle these before anything else. Then 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).
+      `todoSchema`; check each method's kind (chosen from its name). The
+      codemod writes no `describe` (4.x had no per-method prose): write one
+      for the contract and each method, collection, stream, channel and
+      event, which lint's `require-describe` lists. MCP tools and the API
+      docs read them.
    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
@@ -85,7 +96,8 @@ guide's sections as the report sends you to them.
    in handlers (5.0 answers it with a generic `INTERNAL`: throw
    `QuickdrawError(code, message)` where the caller should see the message),
    channels, the server set-up (`qd.createServer`, with `legacyWire: true`
-   while 4.x clients remain).
+   while 4.x clients remain, or `legacyWire: { aliases: { old: "new" } }`
+   when you renamed a service they still call).
    A hand-built sign-in (unmarked: the codemod leaves it) moves onto the
    auth routes kit last, with its `Session` table migration (MIGRATION.md,
    "Hand-built auth to the auth routes kit").
@@ -95,7 +107,8 @@ guide's sections as the report sends you to them.
    left. Run `quickdraw-lint baseline` again when `no-unused-baseline` warns.
 5. **Check**: `quickdraw-lint check` (`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,
+   every hand-written method a kit implements; `require-describe` every
+   member without a `describe`), 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, lint is clean without

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

@@ -20,6 +20,9 @@ and the Prisma model the rows live in. Decide:
   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.
+- **Which kinds of principal may call**: when the app's principals come in
+  kinds (a user, an agent's token, a runner), which of them the service and
+  each method admit. These are `kinds` lists, beside `access`.
 - **What a client lists**: which scopes (a project's tasks, a user's chats).
   Each is a collection, not a list method.
 
@@ -62,6 +65,7 @@ import { z } from "zod";
 const label = z.object({ id: z.string(), projectId: z.string(), name: z.string() });
 
 export const labelContract = defineContract("labelService", {
+  describe: "Labels a project puts on its tasks.",
   entity: label,
   methods: {
     ...crud.contract({ entity: label, get: true, create: { input: label.omit({ id: true }) } }),
@@ -73,6 +77,7 @@ export const labelContract = defineContract("labelService", {
   },
   collections: {
     byProject: {
+      describe: "A project's labels, by name.",
       scope: "projectId",
       item: "entity",
       order: [
@@ -86,8 +91,10 @@ export const labelContract = defineContract("labelService", {
 
 - 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.
+- Use Zod 4.2 or later for every schema. Give the contract and each of its
+  methods, collections, streams, channels and events a `describe` sentence:
+  MCP clients and the generated API docs read it, and lint's
+  `require-describe` warns on each one missing.
 - Export the contract from `packages/shared/src/contracts/index.ts`, next to
   the others, and add it to the `contracts` map there: that map types the
   web client and `qd.caller`.
@@ -136,6 +143,11 @@ export const labelService = qd.defineService(labelContract, {
   `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).
+- A method or service that only some kinds of principal may call says so
+  with `kinds` beside `access` (`kinds: ["user"]`), within the app's
+  `initQuickdraw({ kinds })`: never with a check of `ctx.principal.kind` in
+  the handler or in a `custom` form. Other kinds get `FORBIDDEN`, whatever
+  their grants (see quickdraw-access.md).
 - 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.
@@ -196,7 +208,11 @@ Components rendered against the server go in
 `apps/web/src/__tests__/<name>.int.test.tsx`.
 
 - `describeAccessMatrix` over every method, as an owner, a member, a
-  stranger and anonymously.
+  stranger and anonymously, plus a principal of each kind the service or a
+  method refuses; or `snapshotAccessMatrix`, which records every method,
+  entity subscribe and collection scope of the service in
+  `__access__/<test file>.json` (commit it, and keep its report's
+  `inconclusive` empty).
 - One live test: a write by one user reaches another user's collection or
   entity (`app.frames.waitFor`, or a component through
   `renderWithQuickdraw`).
@@ -211,5 +227,6 @@ Components rendered against the server go in
 Run the app's lint (the quickdraw rules catch untracked writes, foreign
 writes, unbounded reads and raw socket use), typecheck and the unit and
 integration tests. If the app generates API docs with `quickdraw-docs`
-(with `--services`, its pages also say who may call each method),
+(with `--services`, its pages also say who may call each method and which
+services each depends on),
 regenerate them and commit the result.