create-questpie 2.0.2 → 2.0.4

package/skills/questpie/references/rules.md

@@ -16,6 +16,14 @@ Access rules are defined per-collection via `.access()`. Each operation accepts
 
 When no `.access()` is defined, all operations default to `({ session }) => !!session` — **authenticated users only**. You must explicitly set `read: true` for public collections.
 
+Every operation resolves through the same chain, with no hidden framework grants above your config:
+
+1. Collection/global `.access()` rule for that operation
+2. App-level `defaultAccess` (`appConfig({ access })` in `config/app.ts`)
+3. Framework fallback: require session
+
+A deny-all `defaultAccess` (`{ read: false, create: false, update: false, delete: false }`) closes the entire REST surface — including upload-row listing and schema/meta introspection — until collections opt in.
+
 ### Collection Access
 
 ```ts
@@ -26,7 +34,7 @@ export default collection("posts")
 	.fields(({ f }) => ({
 		title: f.text().label("Title").required(),
 		content: f.richText().label("Content"),
-		author: f.relation("users"),
+		author: f.relation("user"),
 	}))
 	.access({
 		read: true, // Public read
@@ -38,12 +46,34 @@ export default collection("posts")
 
 ### Operations
 
-| Operation | When checked                 |
-| --------- | ---------------------------- |
-| `read`    | Listing and fetching records |
-| `create`  | Creating new records         |
-| `update`  | Updating existing records    |
-| `delete`  | Deleting records             |
+| Operation    | When checked                                                     |
+| ------------ | ---------------------------------------------------------------- |
+| `read`       | Listing and fetching records                                      |
+| `create`     | Creating new records                                              |
+| `update`     | Updating existing records                                         |
+| `delete`     | Deleting records                                                  |
+| `transition` | Workflow stage transitions (falls back to `update`)               |
+| `serve`      | Upload file bytes by key (`GET /:collection/files/:key`)          |
+| `introspect` | Schema/meta routes (`GET /:collection/{schema,meta}`)             |
+
+Two operations have specialized chains:
+
+- **`serve`** (upload collections): `serve` → explicit collection `read`
+  (row-aware, `ctx.data` is the upload row) → `defaultAccess.serve` → allow.
+  `defaultAccess.read` is deliberately NOT consulted — listing rows and
+  fetching bytes by key are distinct permissions. `visibility: "public"`
+  means bytes are servable by key; `"private"` files always require the
+  signed token in addition to any serve rule.
+- **`introspect`**: `introspect` → `defaultAccess.introspect` → visible iff
+  at least one CRUD operation is allowed for the current user. Create-only
+  public collections keep their validation schema readable; deny-all apps
+  expose no schemas. Denied requests get 401 (anonymous) or 403
+  (authenticated).
+
+`f.upload()` fields populate through the PARENT row's read decision — a
+publicly readable gallery shows its assets (with `url`) to anonymous readers
+even when the assets collection itself is unlistable. Field-level read rules
+on the upload collection still apply inside population.
 
 ### Global Access
 
@@ -83,11 +113,78 @@ Return a where clause object instead of a boolean to restrict operations to matc
 
 Access functions receive `AppContext` with these properties:
 
-| Property      | Description                             |
-| ------------- | --------------------------------------- |
-| `session`     | Current auth session (null if unauthed) |
-| `db`          | Database instance                       |
-| `collections` | Typed collection API                    |
+| Property      | Description                                                  |
+| ------------- | ------------------------------------------------------------ |
+| `session`     | Current auth session (null if unauthed)                      |
+| `db`          | Database instance                                            |
+| `collections` | Typed collection API                                         |
+| `request`     | Current HTTP `Request` (headers, URL)                        |
+| `data`        | The existing row — typed, non-optional in `update`/`delete` rules |
+| `input`       | Typed insert shape in `create` rules; typed patch in `update` rules |
+| _extensions_  | Keys returned by `appConfig({ context })`, flat (see below)  |
+
+`data`/`input` are typed **per operation** by the builder — no casts, no annotations inside the defining collection. For shared rule helpers and every other "I need type X" case, see `references/type-inference.md`.
+
+### Derived Request Context in Rules
+
+`appConfig({ context })` runs once per HTTP request; its result arrives **flat** on every access rule ctx (collections, globals, routes, field access, transitions), typed by inference:
+
+```ts
+// config/app.ts
+export default appConfig({
+	context: async ({ request }) => ({
+		workspaceId: request.headers.get("x-workspace") || null,
+	}),
+});
+
+// collections/projects.ts — destructure flat, narrow before use
+.access({
+	read: ({ workspaceId }) =>
+		workspaceId ? { workspace: workspaceId } : false,
+})
+```
+
+Extensions are typed `Partial<…>` — absent for non-HTTP contexts (jobs, seeds, system scripts), so rules must handle `undefined`. See `references/multi-tenancy.md` for the full pattern (membership validation, closure memoization, scope UI).
+
+Access functions may be async. Use `request` for request-scoped checks such as headers, tenant scope, CAPTCHA tokens, or signed public form tokens:
+
+```ts
+import type { AccessContext } from "questpie";
+import { ApiError } from "questpie/errors";
+import { isAdminRequest } from "@questpie/admin/shared";
+
+// AccessContext is the sanctioned shared-helper param — never hand-roll a
+// structural ctx type (see references/type-inference.md)
+async function canCreatePublicSubmission({ request, session }: AccessContext) {
+	if (session?.user) return true;
+	if (request && isAdminRequest(request)) {
+		throw ApiError.unauthorized();
+	}
+
+	const token = request?.headers.get("x-captcha-token");
+	const valid = token ? await verifyCaptchaToken(token) : false;
+	if (valid) return true;
+
+	throw ApiError.forbidden({
+		operation: "create",
+		resource: "public_submissions",
+		reason: "CAPTCHA verification failed",
+	});
+}
+
+export default collection("public_submissions")
+	.fields(({ f }) => ({
+		message: f.textarea().required(),
+	}))
+	.access({
+		read: false,
+		create: canCreatePublicSubmission,
+	});
+```
+
+For public anti-abuse checks, bypass already authenticated users before requiring a CAPTCHA token. Admin-origin requests should not be asked for CAPTCHA either, but remember that `isAdminRequest()` is a caller-intent signal, not authentication; if an admin-origin request reaches this rule without a session, fail it as unauthorized instead of accepting it.
+
+Prefer throwing `ApiError.*` from access rules when callers need a specific structured error response. Returning `false` is fine for generic denial, but it produces the default forbidden message.
 
 ### System Access Mode
 
@@ -136,7 +233,7 @@ import { collection } from "#questpie/factories";
 
 export default collection("appointments")
 	.fields(({ f }) => ({
-		customer: f.relation("users"),
+		customer: f.relation("user"),
 		barber: f.relation("barbers"),
 		service: f.relation("services"),
 		scheduledAt: f.datetime().required(),
@@ -204,6 +301,17 @@ export default collection("appointments")
 | `db`          | All hooks                                 | Database instance                |
 | `session`     | All hooks                                 | Current auth session             |
 | `services`    | All hooks                                 | Custom services from `services/` |
+| _extensions_  | All hooks                                 | `appConfig({ context })` result, flat (HTTP requests only) |
+
+Derived request context also reaches hooks and any nested code via `getContext<App>()` — including CRUD calls a hook triggers (AsyncLocalStorage carries it):
+
+```ts
+.hooks({
+  beforeChange: async ({ data, operation, workspaceId }) => {
+    if (operation === "create" && workspaceId) data.workspace = workspaceId;
+  },
+})
+```
 
 ### Context-First Pattern
 
@@ -322,6 +430,25 @@ Live preview sessions use token-based authentication. When a preview iframe load
 - Access rules (`.access()`) still apply to all data fetched during preview, including prefetched relations and block data.
 - Row-level access (AccessWhere) filters are enforced even in preview context — a user cannot preview records they cannot read.
 
+### Workflow Published Reads
+
+For publishable collections that use workflow stages, do not use `read: true` when public client or HTTP access is available. Gate anonymous reads to the published stage:
+
+```ts
+.access({
+	read: ({ session, input }) => {
+		if (session?.user) return true;
+		return input?.stage === "published";
+	},
+	create: ({ session }) => !!session?.user,
+	update: ({ session }) => !!session?.user,
+	delete: ({ session }) => !!session?.user,
+	transition: ({ session }) => !!session?.user,
+})
+```
+
+Public frontend code must pass `stage: "published"`. Preview/draft-mode reads may omit `stage` only when the request has an authorized editor session.
+
 ### System Access and Preview
 
 Do not use `accessMode: "system"` to serve preview data. Preview requests should go through normal session-based access, with the preview token resolving to the editor's session. This ensures previewed content respects the same visibility rules as the final published page.

package/skills/questpie/references/sandbox.md

@@ -0,0 +1,110 @@
+# Sandboxed Code Execution (ctx.executor)
+
+Use the executor when an app must run **untrusted or dynamically-authored code** — agent-written scripts, user plugins, knowledge mini-apps — under a default-deny capability model. `ctx.executor.run()` is the primitive (top-level on AppContext; there is no `ctx.sandbox`).
+
+Unconfigured = disabled: without an `executor` key in `questpie.config.ts`, `ctx.executor.run` throws a clear "not configured" error. An app that never runs dynamic code simply does not configure it.
+
+## Two Isolation Modes
+
+| Mode | Runs in | For |
+| --- | --- | --- |
+| `"sandboxed"` (default) | fresh, hardened **Deno** subprocess per request (scoped net/import, fs/env/run/ffi denied, memory bound) | untrusted code (user/AI mini-apps) |
+| `"trusted"` | in-process (Bun) with a soft timeout | code you already own (code-mode agents, scheduled scripts) |
+
+Untrusted-by-default: omitting `isolation` means `"sandboxed"`; trusted callers opt in explicitly.
+
+## Install And Configure
+
+The sandboxed adapter comes from the opt-in `@questpie/sandbox` package; the engine is a standalone Deno service your app reaches over HTTP (the app ships no Deno):
+
+```bash
+bun add @questpie/sandbox
+```
+
+```ts
+// questpie.config.ts
+import { httpSandboxAdapter } from "@questpie/sandbox/adapter";
+import { runtimeConfig } from "questpie/app";
+
+export default runtimeConfig({
+	executor: {
+		sandboxed: httpSandboxAdapter({
+			url: process.env.SANDBOX_URL ?? "http://127.0.0.1:8787",
+		}),
+		// TRUSTED internal URL of this app's own broker endpoint — required only
+		// for the untrusted app-bindings path. NEVER derive from request Host.
+		brokerUrl: process.env.SANDBOX_BROKER_URL,
+		// defaultTimeoutMs: 10_000,
+	},
+});
+```
+
+`executor.trusted` defaults to the built-in in-process adapter — override only to customize.
+
+## Running Code
+
+The guest source must `export default` a function of `input`:
+
+```ts
+const result = await ctx.executor.run({
+	source: `export default async function (input) {
+		const res = await fetch("https://api.example.com/data?since=" + input.since);
+		const data = await res.json();
+		return { count: data.length };
+	}`,
+	capabilities: {
+		net: ["api.example.com"], // fetch() egress allowlist
+		timeoutMs: 5_000,
+		memoryMb: 128,
+	},
+	input: { since: "2026-01-01" },
+});
+// → { ok: true, output: { count: 42 }, logs: [...], ms: 312 }
+```
+
+Result shape: `{ ok, output?, logs, error?, timedOut?, ms? }`.
+
+## The Capability Model
+
+Every run declares a manifest; anything not granted is denied (default-deny):
+
+| Axis | Grants | Enforced by |
+| --- | --- | --- |
+| `net` | `fetch()` host allowlist (`host[:port]`) | sandbox engine |
+| `import` | remote module-import host allowlist (independent of `net`) | sandbox engine |
+| `timeoutMs` / `memoryMb` | hard wall-clock / per-guest memory bounds | sandbox engine |
+| `files` | read/write path globs into the file store | bindings broker |
+| `data.collections` | per-collection verbs (`read`/`create`/`update`/`delete`) | bindings broker |
+| `data.globals` / `data.stores` | per-global and per-`document_store`-namespace verbs | bindings broker |
+| `services` / `jobs` / `workflows` | allowed service names / enqueueable jobs / triggerable workflows | bindings broker |
+
+`secrets: Record<string, string>` injects secrets into the guest without embedding them in source.
+
+## App Bindings (the `questpie` Proxy)
+
+A plain `ctx.executor.run` is **compute-only** (plus granted `net`). To let the guest reach app data, the caller passes an `appBindings` target plus `brokerUrl` — the service mints a per-run scoped token, and the guest's `globalThis.questpie` proxy RPCs through a host **broker** that enforces the capability manifest per call and dispatches under a non-privileged principal (never `system`):
+
+```ts
+// inside the guest source — only the granted surface resolves
+const posts = await questpie.collections.posts.find({ limit: 10 });
+const file = await questpie.files.read({ path: "company/data/report.json" });
+```
+
+The broker endpoint is a route the host app mounts (product layers like Autopilot's mini-app runner do this); the guest never imports your app. For trusted in-process runs, `bindings` injects host globals directly instead.
+
+## Deployment
+
+The sandbox engine runs as its own service/container reachable at `SANDBOX_URL`; `brokerUrl` must point at the app's own loopback/internal address (the supervisor is trusted) — never at anything request-derived:
+
+```bash
+deno run --allow-net --allow-read packages/sandbox/src/sandbox-server.ts
+```
+
+## Rules
+
+- Do not use the executor for trusted first-party logic — routes, jobs, and services are the right tools.
+- Never grant `net`/`import` hosts or data verbs a run does not need; capabilities are per-run, not global.
+- Never pass `isolation: "trusted"` for code you did not author — there is no sandbox in that mode.
+- Source `brokerUrl` from config/env only; a request-derived broker URL lets a spoofed Host exfiltrate the per-run token.
+
+Full reference: docs page `backend/business-logic/code-execution`.

package/skills/questpie/references/tanstack-query.md

@@ -1,6 +1,7 @@
 ---
 name: questpie-tanstack-query
-description: QUESTPIE TanStack Query integration - createQuestpieQueryOptions option builders, useQuery useMutation queryOptions mutationOptions, collections globals routes, streamedQuery SSE realtime subscriptions, batch helpers, type inference AppConfig createClient, React data fetching caching, framework adapters TanStack Start Next.js Hono Elysia, frontend client SDK querying where orderBy pagination with select
+description:
+  QUESTPIE TanStack Query integration - createQuestpieQueryOptions option builders, useQuery useMutation queryOptions mutationOptions, collections globals routes, streamedQuery SSE realtime subscriptions, batch helpers, type inference AppConfig createClient, React data fetching caching, framework adapters TanStack Start Next.js Hono Elysia, frontend client SDK querying where orderBy pagination with select
   - questpie-core
 ---
 
@@ -401,11 +402,11 @@ const post = await client.collections.posts.findOne({
 	with: { author: true },
 });
 await client.collections.posts.create({ title: "Hello", status: "draft" });
-await client.collections.posts.update({
+await client.collections.posts.updateById({
 	id: "abc",
 	data: { status: "published" },
 });
-await client.collections.posts.delete({ id: "abc" });
+await client.collections.posts.deleteById({ id: "abc" });
 const settings = await client.globals.siteSettings.get();
 const result = await client.routes.createBooking({
 	barberId: "abc",
@@ -416,11 +417,22 @@ client.setLocale("sk"); // Set locale for localized content
 
 ## Realtime
 
-Pass `{ realtime: true }` as the second argument to `find()`, `count()`, or `get()` to enable SSE-based live updates. Requires a realtime adapter in `questpie.config.ts`:
+Pass `{ realtime: true }` as the **typed** second argument (`RealtimeQueryConfig`) to `find()`, `count()`, or `get()` — initial data via a normal fetch, then the server pushes full access-controlled snapshots on every matching change. `findOne()` and `findVersions()` have no realtime form (a second argument there is a compile error).
+
+```tsx
+const { data } = useQuery(
+	q.collections.posts.find(
+		{ where: { status: "published" }, limit: 20 },
+		{ realtime: true },
+	),
+);
+```
+
+Works zero-config (2s polling); add a realtime adapter for instant push:
 
 ```ts
-import { runtimeConfig } from "questpie";
-import { pgNotifyAdapter } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { pgNotifyAdapter } from "questpie/adapters/pg-notify";
 
 export default runtimeConfig({
 	realtime: {
@@ -429,7 +441,16 @@ export default runtimeConfig({
 });
 ```
 
-Channel patterns: `collections:<name>:*` (all changes), `collections:<name>:<id>` (specific record), `globals:<name>`.
+Subscriptions are query-shaped topic objects (`{ resourceType, resource, where?, with? }`) — there are no channel strings. Outside React, use the typed live form of the same query: `client.collections.posts.live(options, onSnapshot)` / `liveIter(options)` (see AGENTS.md §19 Realtime).
+
+To build those topic objects yourself — e.g. manual cache invalidation or a raw `client.realtime.subscribe` call that must match the topic a query subscribed with — use the exported builders instead of hand-writing the shape:
+
+```ts
+import { buildCollectionTopic, buildGlobalTopic } from "@questpie/tanstack-query"; // re-exported from questpie/client
+
+const topic = buildCollectionTopic("posts", { where: { status: "published" }, limit: 20 });
+const settingsTopic = buildGlobalTopic("siteSettings");
+```
 
 For multi-instance deployments, create a Redis client and use `redisStreamsAdapter({ client })`.
 
@@ -439,7 +460,7 @@ For multi-instance deployments, create a Redis client and use `redisStreamsAdapt
 
 ```ts title="src/routes/api/$.ts"
 import { createAPIFileRoute } from "@tanstack/react-start/api";
-import { createFetchHandler } from "questpie";
+import { createFetchHandler } from "questpie/http";
 import { app } from "#questpie";
 const handler = createFetchHandler(app, { basePath: "/api" });
 export const Route = createAPIFileRoute("/api/$")({
@@ -448,12 +469,14 @@ export const Route = createAPIFileRoute("/api/$")({
 });
 ```
 
-**Next.js**: `import { questpieNextRouteHandlers } from "@questpie/next"` -- export `GET`, `POST`, `PATCH`, `DELETE` from `app/api/[...slug]/route.ts`.
+**Next.js**: `import { questpieNextRouteHandlers } from "@questpie/next"` -- export `GET`, `POST`, `PATCH`, `DELETE` from `app/api/[...slug]/route.ts`. The lower-level `questpieNext(app, config)` returns a single fetch-style handler.
 
 **Hono**: `import { questpieHono } from "@questpie/hono/server"` -- `server.route("/api", questpieHono(app))`.
 
 **Elysia**: `import { questpieElysia } from "@questpie/elysia/server"` -- `.use(questpieElysia(app, { basePath: "/api" }))`.
 
+For server-side calls in the same process (SSR loaders, tests), `createClientFromHono` (`@questpie/hono/client`) and `createClientFromEden` (`@questpie/elysia/client`) build the typed client over the live server instance instead of HTTP.
+
 ## Common Mistakes
 
 ### HIGH: Creating the QUESTPIE client without proper base URL
@@ -495,8 +518,8 @@ const { docs } = await client.collections.posts.find({ limit: 10 });
 Collection changes do not auto-refresh when realtime is enabled but no adapter is configured. Add a realtime adapter in `questpie.config.ts`:
 
 ```ts
-import { runtimeConfig } from "questpie";
-import { pgNotifyAdapter } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { pgNotifyAdapter } from "questpie/adapters/pg-notify";
 
 export default runtimeConfig({
 	realtime: {

package/skills/questpie/references/type-inference.md

@@ -0,0 +1,167 @@
+# Type Inference Reference
+
+The schema is the single source of types. If you are hand-writing a type that restates a schema (a row shape, a session shape, a payload), stop — there is a sanctioned inference one-liner for it. Hand-rolled structural types drift silently (real schema `string | null` vs hand-rolled `string | undefined`) and structural mirrors of the CRUD generics produce deep error walls at every call site.
+
+## The Map — "I Need Type X"
+
+| # | You need | Write exactly this | Notes |
+| --- | --- | --- | --- |
+| 1 | Row of **another** collection | `import type { CollectionDoc } from "#questpie"` → `CollectionDoc<"toys">` | Type-only import. See cycle rules below |
+| 2 | Own row inside `.access()` / `.hooks()` | Nothing — `ctx.data` / `ctx.input` are already typed by the builder | Never name your own doc type inside the defining collection |
+| 3 | Shared access-helper parameter | Collection-imported helper: `AccessContext` from `"questpie"`. Anywhere else: `AccessRuleContext<"posts">` from `#questpie` (narrows `ctx.data`) | See cycle rules below |
+| 4 | Shared hook-helper parameter | `HookContext` from `"questpie"` (collection-imported) or `HookRuleContext<"posts">` from `#questpie` | Same rules as #3 |
+| 5 | App/services in a function without a ctx param | `getContext<App>()` with `import type { App } from "#questpie"` | Type-only `App` import — no runtime cycle |
+| 6 | Global doc | `import type { GlobalDoc } from "#questpie"` → `GlobalDoc<"siteSettings">` | Same cycle rules as `CollectionDoc` |
+| 7 | Session / user shape | In handlers: `ctx.session?.user` is typed. Standalone: `import type { AppSession, AppSessionUser } from "#questpie"` | Generated from the app auth config |
+| 8 | Route input/output in the handler | Nothing — inferred from `.schema()` / return type | |
+| 9 | Route input/output standalone | `InferRouteInput<typeof def>` / `InferRouteOutput<typeof def>` / `InferRouteParams<typeof def>` from `questpie/types` | tRPC-style; `def` is the route file's default export |
+| 10 | Client-side types | `createClient<AppConfig>()` — everything flows from the generic | See `references/tanstack-query.md` |
+| 11 | Job payload in the handler | Nothing — `payload` is typed from `schema` | |
+| 12 | Job payload standalone | `InferJobPayload<typeof jobDef>` from `questpie/queue` (or `z.infer<typeof jobDef.schema>`) | |
+| 13 | `db` / `session` inside job/workflow handlers | Honest gap: generated job context types them `unknown` today | Use `collections` (typed) or narrow explicitly; do not restate schemas |
+| 14 | Publishing jobs outside job files | `ctx.queue.<name>.publish(payload)` — payload typed | |
+| 15 | Relation target autocomplete | Nothing — codegen populates `Questpie.CollectionKeys` from discovered files; `f.relation("…")` autocompletes after `questpie generate` | Plain strings always compile |
+| 16 | Realtime payloads | `live()` / `liveIter()` snapshots are typed; raw `client.realtime.subscribe` data is untyped — annotate with `CollectionDoc<"posts">` | Typed realtime contract is planned |
+| 17 | Env vars | `env.ts` / `env.client.ts` with `env()` — see `references/env.md` | Never `process.env.X!` |
+| 18 | Field-level rule ctx (`.access({ fields })`) | `doc` is typed as the row, `user` is typed from the generated session — destructure, don't annotate | |
+| 19 | Derived request context (tenant, role) | `appConfig({ context })` result is inferred and arrives flat on rules — see `references/rules.md` | |
+| 20 | Select-option unions | `CollectionDoc<"events">["type"]` (server-side) | No client-safe union export yet; clients infer from SDK responses |
+
+## The Two Cycle Rules
+
+Type inference flows through the generated index (`#questpie`), and collections are part of that graph. Two rules keep every inference path compiling:
+
+**Rule 1 — inside the defining collection, trust builder inference.** `ctx.data` and `ctx.input` are already typed per operation (table below). Naming your own doc type (`CollectionDoc<"production_orders">` inside `collections/production-orders.ts`, or `ctx.data as OrderDoc`) forces TypeScript to resolve `typeof <own default export>` while that export's type is still being inferred — TS2456/TS7022, or worse, a silently degraded type.
+
+**Rule 2 — helpers imported by collections must not import generated aliases, and must cut the inference loop with an explicit return annotation.** The verified pattern (from `examples/toy-factory-backend/src/questpie/server/lib/access.ts`):
+
+```ts
+// lib/access.ts — imported by a collection, so:
+//  - the helper param is the package-level AccessContext (cycle-safe)
+//  - the return type is annotated explicitly with a CROSS-collection
+//    CollectionDoc (type-only) — this cut breaks the inference loop that
+//    otherwise forms when the helper dereferences ctx.collections back
+//    into the module graph (TS7022/TS2502 without it)
+import type { AccessContext } from "questpie";
+import type { CollectionDoc } from "#questpie";
+
+export async function resolveOrderToy(
+	ctx: AccessContext,
+	toyId: string,
+): Promise<{ toy: CollectionDoc<"toys"> | null; userId: string | null }> {
+	const toy = await ctx.collections.toys.findOne(
+		{ where: { id: toyId } },
+		{ accessMode: "system" },
+	);
+	return { toy, userId: ctx.session?.user.id ?? null };
+}
+
+/** Narrow `data` structurally when the helper only reads a few fields. */
+export function canCancelOrder(ctx: AccessContext<{ priority?: string | null }>) {
+	if (ctx.data?.priority === "rush") return !!ctx.session?.user;
+	return true;
+}
+```
+
+`ctx.app`, `ctx.collections`, and `ctx.session` are fully typed on `AccessContext` through the (lazily merged) AppContext augmentation — the explicit return annotation stays mandatory in collection-imported helpers (it cuts the inference loop).
+
+Helpers **not** imported by any collection (scripts, routes, services, jobs) may freely use `CollectionDoc<K>` in parameters and locals — Rule 2 only binds files that collections import.
+
+## Per-Operation Access Rule Typing
+
+`.access()` rules are typed per operation by the builder — no annotations, no casts:
+
+| Rule | `ctx.data` | `ctx.input` |
+| --- | --- | --- |
+| `read` | not loaded (return `AccessWhere` to filter) | — |
+| `create` | — (no row exists yet) | typed insert shape (pre-validation) |
+| `update` | the existing row — **non-optional** | typed update patch |
+| `delete` | the existing row — **non-optional** | — |
+| `transition` / `serve` | the existing row — non-optional | — |
+
+```ts
+export default collection("production_orders")
+	.fields(({ f }) => ({
+		toy: f.relation("toys").required(),
+		priority: f.select([{ value: "normal" }, { value: "rush" }]),
+	}))
+	.access({
+		create: ({ session, input }) => !!session && input?.priority !== "rush",
+		update: async (ctx) => {
+			ctx.data;  // typed row, non-optional — no `as` cast, no isRecord() dance
+			ctx.input; // typed patch
+			return (await resolveOrderToy(ctx, ctx.data.toy)).userId !== null;
+		},
+	});
+```
+
+The package-level helper types are exported from `questpie/types` (also re-exported from `questpie`): `AccessContext`, `RowAccessRule`, `AccessRule`, `AccessWhere`, `CollectionAccess`, `HookContext`, `FieldAccessRule`, `FieldAccessRuleContext`.
+
+## Typed `getContext<App>()`
+
+For functions that need the app without threading a ctx parameter (and for Better Auth callbacks — see `references/auth.md`):
+
+```ts
+import { getContext } from "questpie";
+import type { App } from "#questpie"; // type-only — no runtime cycle
+
+async function logActivity(action: string) {
+	const { app, session, locale } = getContext<App>();
+	await app.collections.activity_log.create({
+		user: session?.user.id,
+		action,
+		locale,
+	});
+}
+```
+
+Untyped `getContext()` returns the bare context; the `<App>` generic types `app`, `session`, and the derived request-context extensions.
+
+## Standalone Route And Job Types
+
+```ts
+import type { InferRouteInput, InferRouteOutput } from "questpie/types";
+import type { InferJobPayload } from "questpie/queue";
+import createBooking from "../routes/create-booking";
+import sendReminder from "../jobs/send-reminder";
+
+type BookingInput = InferRouteInput<typeof createBooking>;
+type BookingResult = InferRouteOutput<typeof createBooking>;
+type ReminderPayload = InferJobPayload<typeof sendReminder>;
+```
+
+## Key Registries (Advanced, Optional)
+
+Names-only registries give `f.relation()` target autocomplete without entering the type graph (no imports — they cannot cycle). Codegen does **not** populate them yet; augment manually when you want the autocomplete:
+
+```ts
+// types/questpie-keys.d.ts (any ambient file)
+declare global {
+	namespace Questpie {
+		interface CollectionKeys { toys: unknown; production_orders: unknown }
+		interface GlobalKeys { factorySettings: unknown }
+		interface JobKeys { sendReminder: unknown }
+	}
+}
+export {};
+```
+
+`f.relation("toys")` then autocompletes, while arbitrary strings keep compiling (`(string & {})` fallback) — this is autocomplete, not strictness. `KnownCollectionKey` / `KnownGlobalKey` / `KnownJobKey` from `questpie/types` consume the registries in your own signatures.
+
+## Escape Hatches (When Inference Needs Help)
+
+For columns whose value type the field cannot infer, stay declarative — see `references/field-types.md`:
+
+- `.zod(schema)` — type **and** runtime validation (preferred for `f.json()`)
+- `.$type<T>()` — type-only narrowing
+- `.drizzle(fn)` — raw column builder; `$type` on it narrows the value type
+
+## Never Do
+
+| Anti-pattern | Why | Instead |
+| --- | --- | --- |
+| Hand-rolled `EventDoc = { id: string; ownerUser?: string }` | Silent nullability drift vs the real schema | `CollectionDoc<"events">` (row 1) |
+| `ctx.data as MemberDoc` inside own `.access()` | Builder already types it; self-key casts can cycle (TS2456) | Trust `ctx.data` (row 2) |
+| Hand-rolled `CollectionsLike` / `AccessRuleCtx` ctx mirrors | Structural matching of CRUD generics → deep error walls, tsc 5.9 crashes | `AccessContext` param (row 3) |
+| Module-level `app` singleton for callbacks | Import cycles; stale instance in tests | `getContext<App>()` (row 5) |
+| Collection-imported helper returning unannotated `ctx.collections` results | TS7022/TS2502 self-reference | Explicit return annotation (Rule 2) |