create-questpie 2.0.2 → 2.0.4

package/skills/questpie/AGENTS.md

@@ -57,7 +57,7 @@ QuestPie is a **headless CMS framework** for TypeScript. You define your content
 | Runtime  | **Bun**                                           |
 | Database | **PostgreSQL** via **Drizzle ORM**                |
 | Auth     | **Better Auth**                                   |
-| Storage  | **FlyDrive** (local FS, S3, R2, GCS)              |
+| Storage  | **Files SDK** (local FS, S3, R2, GCS)             |
 | Admin UI | **React** + **TanStack Router** + **Tailwind**    |
 | HTTP     | Custom trie-based router (no Express/Hono needed) |
 | Build    | **tsdown** (Rolldown-based) + **Turbo** monorepo  |
@@ -72,6 +72,7 @@ packages/
   hono/               ← Hono HTTP adapter
   next/               ← Next.js adapter
   openapi/            ← OpenAPI/Scalar plugin
+  mcp/                ← Model Context Protocol integration
   tanstack-query/     ← TanStack Query integration
   create-questpie/    ← Project scaffolder (bunx create-questpie)
 ```
@@ -89,11 +90,13 @@ A QuestPie project follows a **convention-over-configuration** file layout. The
     questpie/
       server/                       ← Server root (all data + behavior)
         questpie.config.ts          ← runtimeConfig({ db, app, storage, ... })
+        env.ts                      ← env({ server, client?, refine? }) — boot-validated
+        env.client.ts               ← clientEnv({ consumers, vars }) — client-safe vars
         modules.ts                  ← export default [adminModule, ...] as const
         app.ts                      ← re-export of .generated/index (stable import)
         config/
-          auth.ts                   ← authConfig({...})       (from "questpie")
-          app.ts                    ← appConfig({...})        (from "questpie", optional)
+          auth.ts                   ← authConfig({...})       (from "questpie/app")
+          app.ts                    ← appConfig({...})        (from "questpie/app", optional)
           admin.ts                  ← adminConfig({...})      (from "#questpie/factories")
         collections/                ← One file per collection
         globals/                    ← One file per global
@@ -115,6 +118,7 @@ A QuestPie project follows a **convention-over-configuration** file layout. The
         .generated/                 ← DO NOT EDIT (codegen output)
           index.ts
           factories.ts
+          env.client.<consumer>.ts  ← per-consumer typed client env (when env.client.ts exists)
       admin/                        ← Admin client config
         admin.ts
         modules.ts
@@ -145,6 +149,8 @@ A QuestPie project follows a **convention-over-configuration** file layout. The
 | `blocks/`      | **named** export          | `block("name")`      |
 | `migrations/`  | **default** export        | `migration({...})`   |
 | `seeds/`       | **default** export        | `seed({...})`        |
+| `env.ts`       | **default** export        | `env({...})`         |
+| `env.client.ts`| **default** export        | `clientEnv({...})`   |
 
 ---
 
@@ -156,24 +162,40 @@ A QuestPie project follows a **convention-over-configuration** file layout. The
 questpie.config.ts  →  modules.ts  →  codegen  →  .generated/index.ts  →  createApp()
 ```
 
-**Step 1** — `questpie.config.ts` declares infrastructure (DB, storage, email, etc.):
+**Step 1** — `env.ts` declares + validates environment variables (optional but recommended; see `references/env.md`), and `questpie.config.ts` declares infrastructure (DB, storage, email, etc.):
 
 ```ts
-import { runtimeConfig } from "questpie";
+// env.ts
+import { env } from "questpie/env";
+import { z } from "zod";
+
+export default env({
+	server: { DATABASE_URL: z.url() },
+});
+```
+
+```ts
+// questpie.config.ts
+import { runtimeConfig } from "questpie/app";
+import { ConsoleAdapter } from "questpie/adapters/console";
+
+import env from "./env";
 
 export default runtimeConfig({
 	app: { url: "http://localhost:3000" },
-	db: { url: process.env.DATABASE_URL },
+	db: { url: env.DATABASE_URL },
 	storage: { basePath: "/api" },
 	email: { adapter: new ConsoleAdapter() },
 });
 ```
 
+When `env.ts` exists, the generated app imports it FIRST — a misconfigured environment fails boot before adapters/auth/db init, with every offending var named (values never logged).
+
 **Step 2** — `modules.ts` declares which module packages to use:
 
 ```ts
-import { adminModule } from "@questpie/admin/server";
-import { openApiModule } from "@questpie/openapi";
+import { adminModule } from "@questpie/admin/modules/admin";
+import { openApiModule } from "@questpie/openapi/modules/openapi";
 
 export default [adminModule, openApiModule] as const;
 ```
@@ -200,7 +222,7 @@ export const app = await createApp(
 
 ```ts
 // src/routes/api/$.ts (TanStack Start example)
-import { createFetchHandler } from "questpie";
+import { createFetchHandler } from "questpie/http";
 import { app } from "@/questpie/server/app";
 import { createAPIFileRoute } from "@tanstack/react-start/api";
 
@@ -227,8 +249,7 @@ This single handler serves all collection CRUD, auth, search, realtime, storage,
 Modules are the **packaging unit** of the framework. They are plain static objects — no class instances, no runtime instantiation.
 
 ```ts
-import { module } from "questpie";
-
+import { module } from "questpie/app";
 export const billingModule = module({
 	name: "billing",
 	modules: [stripeModule], // sub-dependencies
@@ -269,6 +290,8 @@ export const billingModule = module({
 | `auditModule`   | `@questpie/admin`           | Audit log collection + cleanup job                                                          |
 | `openApiModule` | `@questpie/openapi`         | OpenAPI schema + Scalar docs UI                                                             |
 
+The starter/admin auth contract includes the canonical Better Auth `user` collection with `user.role` (`admin` or `user`). Built-in admin setup checks for `role = "admin"`, and the admin UI guard expects `session.user.role === "admin"`. Apps using `adminModule` must not replace `collection("user")` from scratch; merge `starterModule.collections.user` and extend it when custom user fields or admin layout are needed.
+
 ### Module Resolution
 
 Modules are resolved **depth-first**: sub-modules are processed before their parent. If two modules share the same `name`, the **last** occurrence wins (deduplication by name). This allows overriding.
@@ -295,8 +318,8 @@ export const posts = collection("posts")
 		title: f.text(255).required().label("Title"),
 		slug: f.text(255).required(),
 		content: f.richText().localized(),
-		status: f.select(["draft", "published"]).default("draft"),
-		author: f.relation("users"),
+		status: f.select(["internal", "featured"]).default("internal"),
+		author: f.relation("user"),
 		tags: f.relation("tags").manyToMany({ through: "post_tags" }),
 		cover: f.upload(),
 	}))
@@ -376,9 +399,9 @@ export const posts = collection("posts")
 					description: "It will become visible to all readers.",
 				},
 				handler: async ({ record, collections }) => {
-					await collections.posts.updateById({
+					await collections.posts.transitionStage({
 						id: record.id,
-						data: { status: "published" },
+						stage: "published",
 					});
 					return { type: "success", toast: { message: "Published!" } };
 				},
@@ -401,7 +424,7 @@ export const posts = collection("posts")
 | `.validation({...})`             | Zod validation overrides                                          |
 | `.upload({...})`                 | Turn into upload collection (see [Uploads](#16-uploads--storage)) |
 | `.set(key, value)`               | Plugin extension point                                            |
-| `.merge(other)`                  | Combine two builders                                              |
+| `.merge(other)`                  | Extend another builder of the same name (see below)               |
 | `.admin({...})`                  | Admin panel metadata (label, icon, group)                         |
 | `.list({...})`                   | List view config                                                  |
 | `.form({...})`                   | Form view config                                                  |
@@ -410,6 +433,24 @@ export const posts = collection("posts")
 
 > `.admin()`, `.list()`, `.form()`, `.preview()`, `.actions()` are added by the admin plugin — they're not available without `@questpie/admin`.
 
+### Extending Collections — `.merge()`
+
+Collections compose. To extend a collection a module already provides (starter `user`, `assets`, ...), **merge the module's builder — never redefine the collection from scratch** (registering the same key replaces the module's collection wholesale, dropping its fields, hooks, and auth wiring):
+
+```ts
+// collections/user.ts — extend the starter user
+import { starterModule } from "questpie/app";
+import { collection } from "#questpie/factories";
+
+export default collection("user")
+	.merge(starterModule.collections.user)
+	.fields(({ f }) => ({
+		internalNotes: f.textarea(),
+	}));
+```
+
+Semantics: fields/virtuals/relations/indexes/options/extension keys combine by key (merged-in builder wins on conflict); hooks concatenate (both run); `title`/`searchable`/`upload` take the merged-in value when set. `.fields()` after `.merge()` is cumulative — adds and overrides by key, never wipes. Everything stays fully typed (`$infer`, CRUD types include both sides).
+
 ---
 
 ## 6. Globals
@@ -515,21 +556,44 @@ f.text(255)
 		update: ({ session }) => session?.user.role === "admin",
 	})
 	.operators(ops) // override WHERE operator set for queries
-	.drizzle((col) => col) // escape hatch: modify Drizzle column
-	.zod((schema) => schema) // escape hatch: modify Zod schema
+	.drizzle((col) => col.unique()) // raw Drizzle column builder — constraints/defaults land in DDL; $type<T>() narrows value type
+	.zod((schema) => schema.refine(check)) // extend/replace Zod schema (output narrows value type)
+	.$type<Layout>() // explicitly set TS value type (type-level only; mainly for json)
 	.fromDb((value) => value) // transform after reading from DB
 	.toDb((value) => value) // transform before writing to DB
 	.set(key, value) // plugin extension point (e.g. admin, form config)
 	.derive(extra); // derive additional runtime state
 ```
 
+### Extending Fields — typed escape hatches
+
+Built-in fields don't box you in. All three hatches propagate types into CRUD select/insert types:
+
+```ts
+// extend Zod validation (type unchanged)
+slug: f.text().zod((s) => s.refine(isKebabCase, "must be kebab-case")),
+
+// replace the Zod schema — value type narrows to the schema output
+settings: f.json().zod(() => z.object({ theme: z.enum(["light", "dark"]) })),
+
+// extend the underlying Drizzle column — raw builder access, lands in DDL/migrations
+slug: f.text(255).drizzle((col) => col.unique()),
+viewCount: f.number().drizzle((col) => col.default(sql`0`)),
+total: f.number().drizzle((col) => col.$type<Cents>()), // narrows value type
+
+// explicitly type a json field (no runtime validation; pair with .zod() if needed)
+layout: f.json().$type<{ rows: { id: string; span: number }[] }>(),
+```
+
+Field schemas are enforced server-side: create/update validates each input key against its field's schema (incl. `.zod()` transforms, email format, select enums). System fields and relation/upload FKs validate against their column shape.
+
+
 ### Custom Field Types
 
 Define reusable field types with `fieldType()`:
 
 ```ts
-import { fieldType } from "questpie";
-
+import { fieldType } from "questpie/builders";
 export const colorField = fieldType("color", {
 	create: () => ({
 		type: "color",
@@ -554,8 +618,8 @@ All relationships are expressed via `f.relation(target)` with chain methods:
 
 ```ts
 // belongsTo (default) — FK on this table
-f.relation("users");
-// Column: authorId varchar(36) → FK to users.id
+f.relation("user");
+// Column: authorId varchar(36) → FK to user.id
 
 // hasMany — virtual, FK lives on the target table
 f.relation("comments").hasMany({
@@ -582,7 +646,7 @@ f.relation({ users: "users", teams: "teams" });
 ### Relation Targets
 
 ```ts
-f.relation("users"); // string (collection name)
+f.relation("user"); // string (collection name)
 f.relation(() => users); // lazy reference (avoids circular imports)
 f.relation({ users: "users", teams: "teams" }); // polymorphic map
 ```
@@ -590,7 +654,7 @@ f.relation({ users: "users", teams: "teams" }); // polymorphic map
 ### Additional Config
 
 ```ts
-f.relation("users")
+f.relation("user")
   .onDelete("cascade" | "set null" | "restrict" | "no action")
   .onUpdate("cascade" | ...)
   .relationName("postAuthor")  // disambiguate multiple relations to same target
@@ -794,6 +858,26 @@ await collections.posts.find({}, { accessMode: "user", session });
 await collections.posts.find({}, { accessMode: "system" });
 ```
 
+### Derived Request Context
+
+`appConfig({ context })` derives per-request context (tenant, role, memberships) **once per HTTP request**; the result travels with the request and arrives **flat** on access rules, hooks, route handlers, field access, and `getContext()`:
+
+```ts
+// config/app.ts
+appConfig({
+	context: async ({ request, session, collections }) => ({
+		workspaceId: request.headers.get("x-workspace") || null,
+	}),
+});
+
+// Any access rule — typed by inference, narrow before use (absent in jobs/seeds)
+access: {
+	read: ({ workspaceId }) => (workspaceId ? { workspace: workspaceId } : false),
+}
+```
+
+The resolver receives the typed system-mode service surface (`collections`, `globals`, `logger`, `kv`, `queue`, `t`, `services`). Throwing from it fails the request before any rule runs. See `references/multi-tenancy.md`.
+
 ---
 
 ## 11. Routes
@@ -801,8 +885,7 @@ await collections.posts.find({}, { accessMode: "system" });
 Custom HTTP routes for APIs that don't fit the collection CRUD pattern.
 
 ```ts
-import { route } from "questpie";
-
+import { route } from "questpie/services";
 // JSON route with schema validation
 export default route()
 	.post()
@@ -912,9 +995,10 @@ export default route()
 | `search`                      | POST   | Full-text search    |
 | `search/reindex/[collection]` | POST   | Reindex collection  |
 | `realtime`                    | POST   | SSE subscriptions   |
-| `storage/files/[...key]`      | GET    | Legacy file serving |
 | `health`                      | GET    | Health check        |
 
+File serving stays collection-scoped through QUESTPIE routes such as `/api/:collection/files/:key` or `/api/assets/files/:key`, so file reads remain behind collection access rules instead of a global storage namespace.
+
 ---
 
 ## 12. Services
@@ -922,8 +1006,7 @@ export default route()
 Services are **injectable singletons or request-scoped factories** available in `AppContext`.
 
 ```ts
-import { service } from "questpie";
-
+import { service } from "questpie/services";
 export const analyticsService = service()
 	.lifecycle("singleton") // created once at startup
 	.create(({ app }) => {
@@ -972,8 +1055,7 @@ async ({ db, session, services }) => {
 Background jobs for async processing — retries, scheduling, and queuing.
 
 ```ts
-import { job } from "questpie";
-
+import { job } from "questpie/services";
 export default job({
 	name: "sendWelcomeEmail",
 	schema: z.object({
@@ -1008,12 +1090,32 @@ await ctx.queue.sendWelcomeEmail.publish({
 
 The queue client exposes jobs as typed properties: `queue[jobName].publish(payload, options?)`. This gives you full type safety on the payload.
 
+### Recurring Jobs (Cron)
+
+Jobs accept a job-level `options.cron`; schedules are registered automatically when the queue worker starts (`app.queue.listen()`):
+
+```ts
+export default job({
+	name: "cleanupExpired",
+	schema: z.object({}),
+	options: { cron: "0 3 * * *" },
+	handler: async ({ collections }) => {
+		await collections.sessions.deleteMany({
+			where: { expiresAt: { lt: new Date() } },
+		});
+	},
+});
+```
+
+Programmatic control: `queue.jobName.schedule(payload, cron)` / `queue.jobName.unschedule()`. Use job cron for simple recurring tasks; reserve **workflow-level cron** (`@questpie/workflows`) for recurring processes that need steps, waits, or replay.
+
 ### Queue Adapters
 
-| Adapter                   | Use Case                                         |
-| ------------------------- | ------------------------------------------------ |
-| `pgBossAdapter()`         | PostgreSQL-based (default, great for most cases) |
-| `CloudflareQueuesAdapter` | Cloudflare Workers                               |
+| Adapter                     | Use Case                                         |
+| --------------------------- | ------------------------------------------------ |
+| `pgBossAdapter()`           | PostgreSQL-based (default, great for most cases) |
+| `bullMQAdapter()`           | Redis-based (BullMQ)                             |
+| `cloudflareQueuesAdapter()` | Cloudflare Workers Queues push consumers         |
 
 ---
 
@@ -1022,8 +1124,7 @@ The queue client exposes jobs as typed properties: `queue[jobName].publish(paylo
 Email templates define how emails look and what data they accept.
 
 ```tsx
-import { email } from "questpie";
-
+import { email } from "questpie/services";
 export default email({
 	name: "welcome",
 	schema: z.object({
@@ -1053,11 +1154,13 @@ await ctx.email.send("welcome", {
 
 ### Email Adapters
 
-| Adapter                       | Description                      |
-| ----------------------------- | -------------------------------- |
-| `ConsoleAdapter`              | Logs to console (dev)            |
-| `SmtpAdapter`                 | SMTP via Nodemailer              |
-| `createEtherealSmtpAdapter()` | Auto-generated test SMTP account |
+| Adapter                       | Import                       | Description                      |
+| ----------------------------- | ---------------------------- | -------------------------------- |
+| `ConsoleAdapter`              | `questpie/adapters/console`  | Logs to console (dev)            |
+| `SmtpAdapter`                 | `questpie/adapters/smtp`     | SMTP via Nodemailer              |
+| `resendAdapter()`             | `questpie/adapters/resend`   | Resend HTTP API (and compatible) |
+| `plunkAdapter()`              | `questpie/adapters/plunk`    | Plunk transactional HTTP API     |
+| `createEtherealSmtpAdapter()` | `questpie/adapters/smtp`     | Auto-generated test SMTP account |
 
 ---
 
@@ -1066,8 +1169,7 @@ await ctx.email.send("welcome", {
 ### Migrations
 
 ```ts
-import { migration } from "questpie";
-
+import { migration } from "questpie/migration";
 export default migration({
 	id: "0001_create_categories_table",
 	up: async ({ db }) => {
@@ -1087,8 +1189,7 @@ export default migration({
 ### Seeds
 
 ```ts
-import { seed } from "questpie";
-
+import { seed } from "questpie/services";
 export default seed({
 	id: "seed-default-categories",
 	category: "required", // "required" | "dev" | "test"
@@ -1177,14 +1278,41 @@ f.upload({
 ### Storage Adapters
 
 ```ts
+import { fs } from "files-sdk/fs";
+import { r2 } from "files-sdk/r2";
+import { s3 } from "files-sdk/s3";
+
 // Local filesystem (default)
 runtimeConfig({
-	storage: { location: "./uploads", basePath: "/api" },
+	storage: { adapter: fs({ root: "./uploads" }), basePath: "/api" },
 });
 
-// S3-compatible (R2, Minio, etc.)
+// S3-compatible (MinIO, Spaces, etc.)
 runtimeConfig({
-	storage: { driver: myS3Driver },
+	storage: {
+		adapter: s3({
+			bucket: process.env.S3_BUCKET!,
+			region: process.env.S3_REGION!,
+			credentials: {
+				accessKeyId: process.env.S3_ACCESS_KEY!,
+				secretAccessKey: process.env.S3_SECRET_KEY!,
+			},
+		}),
+		basePath: "/api",
+	},
+});
+
+// Cloudflare R2
+runtimeConfig({
+	storage: {
+		adapter: r2({
+			bucket: process.env.R2_BUCKET!,
+			accountId: process.env.R2_ACCOUNT_ID!,
+			accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+			secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+		}),
+		basePath: "/api",
+	},
 });
 
 // Auto-detected from env vars:
@@ -1238,6 +1366,8 @@ collection("pages").options({
 - `transitionStage({ id, stage: "published" })` → move between workflow stages
 - `beforeTransition` / `afterTransition` hooks
 
+For publishable pages with workflow enabled, workflow stage is the publication source. Public reads must pass `stage: "published"`. If public client/HTTP access is enabled, anonymous read access should require `input?.stage === "published"` so callers cannot omit `stage` and fetch the working draft. Preview/draft-mode reads may omit `stage` to show the working stage to authorized editors. Do not add duplicate `isPublished` guidance when workflow already controls publishing.
+
 ### API Usage
 
 ```ts
@@ -1308,33 +1438,76 @@ await ctx.queue.indexRecords.publish({ collection: "posts" });
 
 ## 19. Realtime
 
-Server-sent events for live data updates.
+Live queries over SSE. **Broadcasts are automatic** — every collection/global create/update/delete already writes a change event to the `questpie_realtime_log` outbox and notifies subscribers. Do NOT write `afterChange` hooks that "emit" realtime events; a custom emitter double-fires against the built-in broadcast hook.
 
 ### How It Works
 
-1. Every create/update/delete writes a change event to `questpie_realtime_log` (outbox pattern)
-2. An adapter (pg_notify or Redis Streams) notifies connected clients
-3. Clients subscribe via SSE to specific resources
+1. Every CRUD write appends a change event to the outbox; an adapter (pg_notify / Redis Streams) or 2s polling wakes subscribers
+2. The server **re-runs the subscribed query under the subscriber's auth** and pushes the full result as a `snapshot` — clients never receive raw change events (no `operation`/`recordId` on the client; snapshots are access-controlled)
+3. One SSE connection multiplexes all topics (`POST /realtime`)
+
+Snapshots are idempotent state, not diffs — filtered subscriptions may receive unchanged snapshots on update/delete (over-refresh by design). Always render from the snapshot.
 
 ### Client-Side Usage
 
 ```ts
-// With TanStack Query (automatic)
-const { data } = useQuery(qp.collections.posts.find({}, { realtime: true }));
+// React + TanStack Query — typed second arg, no casts needed
+const { data } = useQuery(
+	qp.collections.posts.find({ where: { event: eventId }, limit: 50 }, { realtime: true }),
+);
 
-// Manual subscription
-const unsub = client.realtime.subscribe(
-	{ resourceType: "collection", resource: "posts" },
-	(event) => {
-		console.log("Change:", event.operation, event.recordId);
-	},
+// Vanilla TS — live() is the live form of find(): same options in, same result type out
+const stop = client.collections.posts.live(
+	{ where: { event: eventId }, with: { author: true }, orderBy: { createdAt: "desc" } },
+	(snap) => render(snap.docs), // snap.docs[i].author is typed
+	{ onError: (e) => console.error(e) },
+);
+stop(); // unsubscribe
+
+// Async-iterable form (workers, agents, tests) — terminate via AbortSignal
+for await (const snap of client.collections.posts.liveIter(
+	{ where: { event: eventId } },
+	{ signal: controller.signal },
+)) {
+	render(snap.docs);
+}
+
+// Globals mirror get()
+client.globals.siteSettings.live(undefined, (settings) => applyTheme(settings));
+
+// Low-level escape hatch — topic objects, never channel strings; data is untyped
+client.realtime.subscribe(
+	{ resourceType: "collection", resource: "posts", where: { event: eventId } },
+	(data) => {}, // unknown — prefer the typed live() wrappers
 );
 ```
 
+Live options carry exactly what the wire protocol supports: `where`, `with`, `limit`, `offset`, `orderBy`, `locale` (no `columns`/`groupBy`/`search` — compile error).
+
+### Wire Protocol (stable contract)
+
+`POST <basePath>/realtime` body `{ topics: [{ id, resourceType: "collection" | "global", resource, where?, with?, limit?, offset?, orderBy?, locale? }] }` → SSE events:
+
+| Event      | Payload                  | Meaning                                                |
+| ---------- | ------------------------ | ------------------------------------------------------ |
+| `snapshot` | `{ topicId, seq, data }` | Full `find()`/`get()` result under subscriber's auth   |
+| `error`    | `{ topicId, message }`   | Topic-level failure (unknown resource, access denied)  |
+| `ping`     | `{ ts }`                 | Keep-alive (default every 8s)                          |
+
+Ignore unknown SSE event types (forward compat).
+
+### Keepalive (Bun)
+
+The stream pings every 8s by default (`realtime.keepAliveIntervalMs`). Bun's default `idleTimeout` is 10s — the default ping survives it, but set headroom explicitly in the server entry:
+
+```ts
+export default { port: 3000, idleTimeout: 30, fetch: server.fetch };
+```
+
 ### Realtime Adapters
 
 ```ts
-import { pgNotifyAdapter } from "questpie";
+import { pgNotifyAdapter } from "questpie/adapters/pg-notify";
 
 runtimeConfig({
 	realtime: {
@@ -1432,11 +1605,11 @@ interface AppContext {
 	globals: { [name]: GlobalAPI }; // typed CRUD for all globals
 	queue: QueueClient; // dispatch background jobs
 	email: MailerService; // send emails
-	storage: DriveManager; // file storage operations
+	storage: Files; // direct typed Files SDK storage operations
 	kv: KVService; // key-value store
 	logger: LoggerService; // structured logging
 	search: SearchService; // full-text search
-	realtime: RealtimeService; // publish realtime events
+	realtime: RealtimeService; // server-side change-event subscription (broadcasts are automatic)
 	t: (key, params?, locale?) => string; // i18n translator
 	services: Record<string, unknown>; // user-defined services
 }
@@ -1453,23 +1626,32 @@ interface AppContext {
 | Access rules     | Destructure: `({ session, data }) => boolean`                    |
 | Seeds            | `async ({ collections, log }) => { ... }`                        |
 | Services         | `create: ({ app }) => ...` (app instance only, not full context) |
+| Better Auth callbacks (`onLinkAccount`, `databaseHooks`, `sendMagicLink`, plugin hooks) | `getContext<App>()` — `/auth/*` is a raw route executed inside `runWithContext`, so the request scope is live there (see `references/auth.md`) |
 
 ### Getting Context Programmatically
 
 ```ts
-import { getContext, tryGetContext } from "questpie";
+import { getContext, tryGetContext } from "questpie/types";
+import type { App } from "#questpie"; // type-only — no runtime cycle
 
-const ctx = getContext(); // throws if outside a request scope
-const ctx = tryGetContext(); // returns null if outside scope
+const ctx = getContext<App>(); // typed app/session/extensions; throws outside a request scope
+const maybe = tryGetContext(); // returns null if outside scope
 
 // Create a fresh context manually:
-const ctx = await app.createContext({
+const fresh = await app.createContext({
 	session: null,
 	locale: "en",
 	accessMode: "system",
 });
 ```
 
+**Partial context overrides:** the second argument of every CRUD call merges with the ambient request scope (priority: explicit param → ALS scope → defaults). A bare `{ accessMode: "system" }` elevates **only** the mode — `session`, `db`, and `locale` inherit from the request automatically. The inverse works too: `{ accessMode: "user" }` inside system-scoped code re-enables access rules against the inherited session. Never re-thread session/locale by hand:
+
+```ts
+await app.collections.posts.find({}, { accessMode: "system" }); // mode elevated, request session/locale ride along
+await app.collections.posts.find({}, { accessMode: "user" }); // rules enforced for the inherited session
+```
+
 ---
 
 ## 22. Server-Side CRUD API
@@ -1505,9 +1687,10 @@ const post = await app.collections.posts.findOne({
 // WRITE
 .create(data)                      → T
 .updateById({ id, data })          → T
-.update({ where, data })           → T[]       (batch)
+.updateMany({ where, data })       → T[]       (batch; deprecated alias: update)
+.updateBatch({ updates })          → T[]       (per-record batch)
 .deleteById({ id })                → { success }
-.delete({ where })                 → { success, count }  (batch)
+.deleteMany({ where })             → { success, count }  (batch; deprecated alias: delete)
 .restoreById({ id })               → T          (soft-delete)
 
 // VERSIONING
@@ -1537,7 +1720,7 @@ const post = await app.collections.posts.findOne({
     author: true,
     tags: { columns: { name: true } },
   },
-  orderBy: { createdAt: "desc" },
+  orderBy: { createdAt: "desc" },             // or multi-field: [{ status: "desc" }, { createdAt: "desc" }]
   limit: 10,
   offset: 0,
   search: "keyword",                          // full-text ILIKE on title
@@ -1813,7 +1996,7 @@ The admin panel is a **server-driven React SPA**. The server declares what shoul
 
 ```ts
 // modules.ts
-import { adminModule } from "@questpie/admin/server";
+import { adminModule } from "@questpie/admin/modules/admin";
 export default [adminModule] as const;
 
 // config/admin.ts
@@ -2012,6 +2195,10 @@ collection("posts").preview({
 });
 ```
 
+Live Preview uses the existing admin `FormView`, Preview button, `LivePreviewMode`, and iframe. Do not introduce a separate visual-edit form API, a second default form view, or parallel preview API names. Preserve save, autosave, Cmd+S, history, workflow transitions, locks, and actions in the normal form lifecycle.
+
+Frontend visual editing needs `useCollectionPreview`, `PreviewProvider`, `PreviewField`, and usually `BlockRenderer`; load the `questpie-admin` skill for the full frontend preparation checklist.
+
 ### `.actions()` — Server Actions
 
 ```ts
@@ -2028,9 +2215,9 @@ collection("posts").actions(({ a, c, f }) => ({
 				destructive: false,
 			},
 			handler: async ({ record, collections }) => {
-				await collections.posts.updateById({
+				await collections.posts.transitionStage({
 					id: record.id,
-					data: { status: "published" },
+					stage: "published",
 				});
 				return { type: "success", toast: { message: "Published!" } };
 			},
@@ -2341,50 +2528,68 @@ export const { GET, POST, PUT, PATCH, DELETE } =
 	questpieNextRouteHandlers(questpieApp);
 ```
 
+### MCP Integration
+
+Use `@questpie/mcp` as a static module:
+
+```ts
+// modules.ts
+import mcpModule from "@questpie/mcp";
+
+export default [mcpModule] as const;
+```
+
+Configure it through plugin-discovered `config/mcp.ts`, not `mcpModule(options)`. It exposes generated CRUD tools, annotated JSON route tools, schema resources, and custom `mcp-tools/` definitions. HTTP MCP is always user mode and cannot be elevated to system mode; stdio defaults to trusted system mode unless explicitly lowered.
+
 ### Storage Adapters
 
-| Config                        | Driver                         |
-| ----------------------------- | ------------------------------ |
-| Default                       | `FSDriver` (local `./uploads`) |
-| `QUESTPIE_STORAGE_*` env vars | S3-compatible (auto-detected)  |
-| `{ driver: customDriver }`    | Any FlyDrive `DriverContract`  |
+| Config                              | Storage backend                  |
+| ----------------------------------- | -------------------------------- |
+| Default                             | Filesystem adapter (`./uploads`) |
+| `QUESTPIE_STORAGE_*` env vars       | S3-compatible (auto-detected)    |
+| `{ adapter: customAdapter }`        | Files SDK adapter instance       |
 
 ### Queue Adapters
 
-| Adapter                   | Description                          |
-| ------------------------- | ------------------------------------ |
-| `pgBossAdapter()`         | PostgreSQL-based job queue (pg-boss) |
-| `CloudflareQueuesAdapter` | Cloudflare Workers Queues            |
+| Adapter                     | Description                          |
+| --------------------------- | ------------------------------------ |
+| `pgBossAdapter()`           | PostgreSQL-based job queue (pg-boss) |
+| `bullMQAdapter()`           | Redis-based job queue (BullMQ)       |
+| `cloudflareQueuesAdapter()` | Cloudflare Workers Queues            |
 
 ### Search Adapters
 
-| Adapter                 | Description                       |
-| ----------------------- | --------------------------------- |
-| `PostgresSearchAdapter` | pg_trgm + full-text search        |
-| `PgVectorSearchAdapter` | Hybrid semantic search (pgvector) |
+| Adapter                          | Description                       |
+| -------------------------------- | --------------------------------- |
+| `createPostgresSearchAdapter()`  | pg_trgm + full-text search        |
+| `createPgVectorSearchAdapter()`  | Hybrid semantic search (pgvector + embedding provider — see `references/infrastructure-adapters.md`) |
 
 ### Realtime Adapters
 
-| Adapter                 | Description              |
-| ----------------------- | ------------------------ |
-| Default                 | Polling (2s interval)    |
-| `pgNotifyAdapter()`     | PostgreSQL LISTEN/NOTIFY |
-| `redisStreamsAdapter()` | Redis Streams            |
+| Adapter                       | Description                |
+| ----------------------------- | -------------------------- |
+| Default                       | Polling (2s interval)      |
+| `pgNotifyAdapter()`           | PostgreSQL LISTEN/NOTIFY   |
+| `redisStreamsAdapter()`       | Redis Streams              |
+| `cloudflareRealtimeAdapter()` | Cloudflare Durable Objects |
 
 ### KV Adapters
 
-| Adapter            | Description          |
-| ------------------ | -------------------- |
-| `MemoryKVAdapter`  | In-process (default) |
-| `IORedisKVAdapter` | Redis-backed         |
+| Adapter                 | Description           |
+| ----------------------- | --------------------- |
+| `MemoryKVAdapter`       | In-process (default)  |
+| `RedisKVAdapter`        | Redis-backed          |
+| `cloudflareKVAdapter()` | Cloudflare Workers KV |
 
 ### Email Adapters
 
-| Adapter                       | Description                 |
-| ----------------------------- | --------------------------- |
-| `ConsoleAdapter`              | Logs to console             |
-| `SmtpAdapter`                 | Nodemailer SMTP             |
-| `createEtherealSmtpAdapter()` | Auto-generated test account |
+| Adapter                       | Description                      |
+| ----------------------------- | -------------------------------- |
+| `ConsoleAdapter`              | Logs to console                  |
+| `SmtpAdapter`                 | Nodemailer SMTP                  |
+| `resendAdapter()`             | Resend HTTP API (and compatible) |
+| `plunkAdapter()`              | Plunk transactional HTTP API     |
+| `createEtherealSmtpAdapter()` | Auto-generated test account      |
 
 ### Logger
 
@@ -2612,7 +2817,7 @@ module()                 Packaging unit (groups related entities)
   ├── block()            Content builder block         ← admin plugin
   ├── migration()        DB schema change
   ├── seed()             DB seed data
-  ├── appConfig()        App-level config (locale, access, hooks)
+  ├── appConfig()        App-level config (locale, access, hooks, context)
   ├── authConfig()       Auth config (Better Auth options)
   └── adminConfig()      Admin config (sidebar, dashboard, branding)  ← admin plugin
 ```
@@ -2652,8 +2857,10 @@ module()                 Packaging unit (groups related entities)
 | Seed           | `seed({...})`                        | `questpie`                 | DB seed data                 |
 | Module         | `module({...})`                      | `questpie`                 | Packaging unit               |
 | Runtime Config | `runtimeConfig({...})`               | `questpie`                 | Infrastructure config        |
-| App Config     | `appConfig({...})`                   | `questpie`                 | Locale, access, hooks        |
+| App Config     | `appConfig({...})`                   | `questpie`                 | Locale, access, hooks, context |
 | Auth Config    | `authConfig({...})`                  | `questpie`                 | Better Auth options          |
+| Env            | `env({...})`                         | `questpie/env`             | Boot-validated typed env     |
+| Client Env     | `clientEnv({...})`                   | `questpie/env`             | Client-safe env definition   |
 | Admin Config   | `adminConfig({...})`                 | `#questpie/factories`      | Sidebar, dashboard, branding |
 | View           | `view(name, {kind, component})`      | `@questpie/admin/client`   | Admin view component         |
 | Widget         | `widget(name, {component})`          | `@questpie/admin/client`   | Dashboard widget             |