create-questpie 1.0.0 → 2.0.0

package/templates/tanstack-start/AGENTS.md

@@ -1,13 +1,13 @@
 # AGENTS.md
 
-Source-of-truth guidance for AI agents working in this QUESTPIE CMS project.
+Source-of-truth guidance for AI agents working in this QUESTPIE project.
 
 > **Docs for LLMs**: https://questpie.com/llms.txt (sitemap), https://questpie.com/llms-full.txt (full content)
 
 ## Project Overview
 
 - **Framework**: TanStack Start (React) + Vite + Nitro (Bun preset)
-- **CMS**: QUESTPIE — headless CMS framework with config-driven admin UI
+- **QUESTPIE**: QUESTPIE — application framework with config-driven admin UI
 - **Database**: PostgreSQL (via Drizzle ORM)
 - **Styling**: Tailwind CSS v4 + shadcn/ui components
 - **Auth**: Better Auth (email/password)
@@ -20,7 +20,7 @@ When you need more context about QUESTPIE APIs, consult these resources in order
 
 1. **LLMs full docs**: https://questpie.com/llms-full.txt — complete documentation in a single LLM-optimized file
 2. **Online docs**: https://questpie.com/docs — browsable documentation
-3. **Local API docs**: http://localhost:3000/api/cms/docs — Scalar UI (available when dev server is running)
+3. **Local API docs**: http://localhost:3000/api/docs — Scalar UI (available when dev server is running)
 
 Key documentation pages:
 
@@ -28,14 +28,14 @@ Key documentation pages:
 | -------------------------- | ---------------------------------------------------------------- |
 | Getting Started            | https://questpie.com/docs/getting-started                        |
 | Project Structure          | https://questpie.com/docs/getting-started/project-structure      |
-| Your First CMS             | https://questpie.com/docs/getting-started/your-first-cms         |
+| Your First QUESTPIE        | https://questpie.com/docs/getting-started/your-first-app         |
 | Architecture Principles    | https://questpie.com/docs/mentality                              |
 | Field Builder              | https://questpie.com/docs/server/field-builder                   |
 | Field Types Reference      | https://questpie.com/docs/server/field-types                     |
 | Collections                | https://questpie.com/docs/server/collections                     |
 | Globals                    | https://questpie.com/docs/server/globals                         |
 | Relations                  | https://questpie.com/docs/server/relations                       |
-| RPC (Server Functions)     | https://questpie.com/docs/server/rpc                             |
+| Routes                     | https://questpie.com/docs/backend/business-logic/routes          |
 | Hooks & Lifecycle          | https://questpie.com/docs/server/hooks-and-lifecycle             |
 | Access Control             | https://questpie.com/docs/server/access-control                  |
 | Reactive Fields            | https://questpie.com/docs/server/reactive-fields                 |
@@ -64,25 +64,31 @@ Key documentation pages:
 src/
   questpie/
     server/              ← WHAT: data contracts and behavior
-      builder.ts         ← Shared builder: qb = q.use(adminModule)
-      app.ts             ← Composition root (collections, globals, auth, build)
-      rpc.ts             ← RPC router instance: r = rpc()
-      sidebar.ts         ← Admin sidebar configuration
-      dashboard.ts       ← Admin dashboard configuration
-      collections/       ← One file per collection (*.collection.ts)
-      globals/           ← One file per global (*.global.ts)
-      functions/         ← RPC functions
-      jobs/              ← Background job definitions
-      blocks.ts          ← Block definitions (if using blocks)
+      questpie.config.ts ← App config: runtimeConfig({ db, app, ... })
+      modules.ts         ← Module dependencies (adminModule, openApiModule, etc.)
+      config/            ← Typed configuration files
+        auth.ts          ← authConfig({...}) — Better Auth options
+        app.ts           ← appConfig({ locale, access, hooks, context })
+        admin.ts         ← adminConfig({ sidebar, dashboard, branding, locale })
+        openapi.ts       ← openApiConfig({ info, scalar })
+      .generated/        ← Codegen output (app instance + App type)
+        index.ts
+      collections/       ← One file per collection (auto-discovered)
+      globals/           ← One file per global (auto-discovered)
+      routes/            ← Server routes via route() (auto-discovered)
+      jobs/              ← Background job definitions (auto-discovered)
+      blocks/            ← Block definitions (auto-discovered)
     admin/               ← HOW: UI rendering concerns
-      builder.ts         ← Client builder: qa<AppCMS>().use(adminModule)
-      hooks.ts           ← Typed hooks via createTypedHooks<AppCMS>()
+      admin.ts           ← Re-exports generated admin config
+      hooks.ts           ← Typed hooks via createTypedHooks<App>()
+      .generated/        ← Codegen output (admin client config)
+        client.ts
       blocks/            ← Block renderers (if using blocks)
   lib/
     env.ts               ← Type-safe env vars (@t3-oss/env-core + Zod)
-    cms-client.ts        ← CMS client instance
+    client.ts            ← client instance
   routes/
-    api/cms/$.ts         ← CMS catch-all handler (REST + OpenAPI + auth)
+    api/$.ts             ← QUESTPIE catch-all handler (REST + OpenAPI + auth)
   migrations/            ← Database migrations (generated by CLI)
 ```
 
@@ -90,28 +96,33 @@ src/
 
 ### Server-First Split
 
-| Directory          | Responsibility                    | Defines                            |
-| ------------------ | --------------------------------- | ---------------------------------- |
-| `questpie/server/` | **WHAT** — contracts and behavior | Schema, access, hooks, RPC, jobs   |
-| `questpie/admin/`  | **HOW** — rendering concerns      | Branding, locale, custom renderers |
-| `routes/`          | **Mounting** — HTTP wiring        | Route handlers, no business logic  |
+| Directory          | Responsibility                    | Defines                             |
+| ------------------ | --------------------------------- | ----------------------------------- |
+| `questpie/server/` | **WHAT** — contracts and behavior | Schema, access, hooks, routes, jobs |
+| `questpie/admin/`  | **HOW** — rendering concerns      | Branding, locale, custom renderers  |
+| `routes/`          | **Mounting** — HTTP wiring        | Route handlers, no business logic   |
 
 ### File Naming Conventions
 
-- Collections: `*.collection.ts` (e.g., `posts.collection.ts`)
-- Globals: `*.global.ts` (e.g., `site-settings.global.ts`)
-- RPC functions: `*.function.ts` or grouped in `functions/` directory
-- Background jobs: grouped in `jobs/` directory
+- Collections: `*.ts` in `collections/` (e.g., `posts.ts`) — named exports
+- Globals: `*.ts` in `globals/` (e.g., `site-settings.ts`) — named exports
+- Routes: `*.ts` in `routes/` (e.g., `get-stats.ts`) — default exports
+- Jobs: `*.ts` in `jobs/` (e.g., `send-email.ts`) — default exports
+- Blocks: `*.ts` in `blocks/` (e.g., `hero.ts`) — named exports
 
 ### Key Files
 
-- **`src/questpie/server/builder.ts`** — Creates the shared builder `qb = q.use(adminModule)` used by all collections/globals.
-- **`src/questpie/server/app.ts`** — Composition root. Registers collections, globals, sidebar, dashboard, auth, and calls `.build()`. Also exports `appRpc`, `AppCMS`, `AppRpc`.
-- **`src/questpie/server/rpc.ts`** — Creates the RPC builder `r = rpc()` used by all server functions.
-- **`src/questpie/admin/builder.ts`** — Creates the client builder `admin = qa<AppCMS>().use(adminModule)`.
+- **`src/questpie/server/questpie.config.ts`** — App config: `runtimeConfig({ db, app, ... })`.
+- **`src/questpie/server/modules.ts`** — Module dependencies: `export default [adminModule, openApiModule] as const`.
+- **`src/questpie/server/config/auth.ts`** — Auth config via `authConfig()` factory.
+- **`src/questpie/server/config/app.ts`** — App config (locale, access, hooks, context) via `appConfig()` factory.
+- **`src/questpie/server/config/admin.ts`** — Admin config (sidebar, dashboard, branding, locale) via `adminConfig()` factory.
+- **`src/questpie/server/config/openapi.ts`** — OpenAPI config via `openApiConfig()` factory.
+- **`src/questpie/server/.generated/index.ts`** — Codegen output. Exports typed `app` instance and `App` type. Run `bunx questpie generate` to regenerate.
+- **`src/questpie/admin/.generated/client.ts`** — Codegen output: pre-built admin client config. Run `bunx questpie generate` to regenerate.
 - **`src/lib/env.ts`** — Type-safe env variables via `@t3-oss/env-core`. Add new env vars here with Zod schemas.
 - **`questpie.config.ts`** — CLI config (migration directory, app reference).
-- **`src/routes/api/cms/$.ts`** — CMS API catch-all handler. Serves REST + OpenAPI docs at `/api/cms/docs`.
+- **`src/routes/api/$.ts`** — API catch-all handler. Serves REST + OpenAPI docs at `/api/docs`.
 
 ## How To Write Code
 
@@ -120,181 +131,170 @@ src/
 Keep the entire builder chain in one file — single source of truth per entity:
 
 ```ts
-// src/questpie/server/collections/posts.collection.ts
-import { qb } from "@/questpie/server/builder";
-
-export const posts = qb
-  .collection("posts")
-  .fields((f) => ({
-    title: f.text({ label: "Title", required: true }),
-    slug: f.slug({ label: "Slug", from: "title" }),
-    content: f.richText({ label: "Content" }),
-    published: f.boolean({ label: "Published", default: false }),
-    category: f.select({ label: "Category", options: ["news", "blog", "tutorial"] }),
-    author: f.relation({ label: "Author", to: "users" }),
-    image: f.upload({ label: "Cover Image" }),
-  }))
-  .title(({ f }) => f.title)
-  .admin(({ c }) => ({
-    label: "Posts",
-    icon: c.icon("ph:article"),
-  }))
-  .access({
-    read: true,
-    create: ({ session }) => !!session,
-    update: ({ session }) => !!session,
-    delete: ({ session }) => session?.user?.role === "admin",
-  })
-  .hooks({
-    beforeCreate: [async ({ data, ctx }) => { /* ... */ return data; }],
-  })
-  .list(({ v }) => v.table({}))
-  .form(({ v, f }) =>
-    v.form({
-      sidebar: { position: "right", fields: [f.slug, f.published, f.category] },
-      fields: [f.title, f.content, f.author, f.image],
-    })
-  );
+// src/questpie/server/collections/posts.ts
+import { collection } from "questpie";
+
+export const posts = collection("posts")
+	.fields(({ f }) => ({
+		title: f.text(255).label("Title").required(),
+		slug: f
+			.text(255)
+			.label("Slug")
+			.required()
+			.inputOptional()
+			.admin({
+				compute: {
+					handler: ({ data, prev }) => {
+						/* slugify title */
+					},
+					deps: ({ data }) => [data.title],
+					debounce: 300,
+				},
+			}),
+		content: f.richText().label("Content"),
+		published: f.boolean().label("Published").default(false),
+		category: f
+			.select()
+			.label("Category")
+			.options(["news", "blog", "tutorial"]),
+		author: f.relation().label("Author").to("users"),
+		image: f.upload().label("Cover Image"),
+	}))
+	.title(({ f }) => f.title)
+	.admin(({ c }) => ({
+		label: "Posts",
+		icon: c.icon("ph:article"),
+	}))
+	.access({
+		read: true,
+		create: ({ session }) => !!session,
+		update: ({ session }) => !!session,
+		delete: ({ session }) => session?.user?.role === "admin",
+	})
+	.hooks({
+		beforeCreate: [
+			async ({ data, ctx }) => {
+				/* ... */ return data;
+			},
+		],
+	})
+	.list(({ v }) => v.collectionTable({}))
+	.form(({ v, f }) =>
+		v.collectionForm({
+			sidebar: { position: "right", fields: [f.slug, f.published, f.category] },
+			fields: [f.title, f.content, f.author, f.image],
+		}),
+	);
 ```
 
-Then register it:
-1. Export from `src/questpie/server/collections/index.ts`
-2. Add to `.collections({ ..., posts })` in `app.ts`
-3. Add to sidebar in `sidebar.ts`
-4. Run `bun questpie migrate:create` to generate migration
+Then (preferred):
+
+1. Use `bun questpie add collection <name>` to scaffold files
+2. Codegen runs automatically
+3. Run `bun questpie migrate:create` to generate migration
+
+Manual workflow (if you create files yourself):
+
+1. Run `bunx questpie generate` to regenerate `.generated/index.ts`
+2. Run `bun questpie migrate:create` to generate migration
+
+Collections are auto-discovered by codegen — no manual registration needed.
 
 ### Available Field Types
 
-`text`, `number`, `boolean`, `date`, `dateTime`, `select`, `multiSelect`, `relation`, `upload`, `richText`, `json`, `slug`, `email`, `url`, `password`, `color`, `textarea`
+**Core:** `text`, `number`, `boolean`, `date`, `datetime`, `time`, `select`, `relation`, `upload`, `object`, `json`, `from`, `email`, `url`, `textarea`.
+**Admin module:** `richText`, `blocks` (provided by `@questpie/admin`)
 
 ### Creating a Global
 
 ```ts
-// src/questpie/server/globals/site-settings.global.ts
-import { qb } from "@/questpie/server/builder";
-
-export const siteSettings = qb
-  .global("site_settings")
-  .fields((f) => ({
-    siteName: f.text({ label: "Site Name", required: true }),
-    description: f.textarea({ label: "Description" }),
-    logo: f.upload({ label: "Logo" }),
-    maintenanceMode: f.boolean({ label: "Maintenance Mode", default: false }),
-  }))
-  .admin(({ c }) => ({ label: "Site Settings", icon: c.icon("ph:gear") }))
-  .form(({ v, f }) => v.form({
-    fields: [f.siteName, f.description, f.logo, f.maintenanceMode],
-  }));
+// src/questpie/server/globals/site-settings.ts
+import { global } from "questpie";
+
+export const siteSettings = global("site_settings")
+	.fields(({ f }) => ({
+		siteName: f.text(255).label("Site Name").required(),
+		description: f.textarea().label("Description"),
+		logo: f.upload().label("Logo"),
+		maintenanceMode: f.boolean().label("Maintenance Mode").default(false),
+	}))
+	.admin(({ c }) => ({ label: "Site Settings", icon: c.icon("ph:gear") }))
+	.form(({ v, f }) =>
+		v.globalForm({
+			fields: [f.siteName, f.description, f.logo, f.maintenanceMode],
+		}),
+	);
 ```
 
-Then register it:
-1. Export from `src/questpie/server/globals/index.ts`
-2. Add to `.globals({ ..., siteSettings })` in `app.ts`
-3. Add to sidebar in `sidebar.ts`
-4. Run `bun questpie migrate:create`
+Then (preferred):
 
-### Creating an RPC Function (End-to-End Type-Safe)
+1. Use `bun questpie add global <name>` to scaffold files
+2. Codegen runs automatically
+3. Run `bun questpie migrate:create`
 
-QUESTPIE provides standalone RPC — `cms` and `appRpc` are two independent instances, no circular dependency.
+Manual workflow (if you create files yourself):
 
-**How typing works:**
-```ts
-// rpc.ts — standalone RPC builder
-import { rpc } from "questpie";
-export const r = rpc();
-```
+1. Run `bunx questpie generate` to regenerate `.generated/index.ts`
+2. Run `bun questpie migrate:create`
 
-```ts
-// app.ts — imports r (runtime), exports cms and appRpc separately
-import { r } from "./rpc.js";
+Globals are auto-discovered by codegen — no manual registration needed.
 
-export const cms = qb.collections({...}).build({...});
-export const appRpc = r.router({ ...adminRpc, myFn });
+### Creating a Server Route (End-to-End Type-Safe)
 
-export type AppCMS = typeof cms;
-export type AppRpc = typeof appRpc;
-```
+Routes are defined as standalone files in `routes/` and auto-discovered by codegen.
 
-**Step 1 — Define a function:**
+**Step 1 — Define a route:**
 
 ```ts
-// src/questpie/server/functions/get-stats.function.ts
-import { r } from "@/questpie/server/rpc";
+// src/questpie/server/routes/get-stats.ts
+import { route } from "questpie";
 import { z } from "zod";
 
-export const getStats = r.fn({
-  schema: z.object({
-    period: z.enum(["day", "week", "month"]),
-  }),
-  handler: async ({ input, app }) => {
-    // input: { period: "day" | "week" | "month" } — typed from Zod schema
-    // app: fully typed CMS instance with autocomplete
-    const count = await app.api.collections.posts.count({});
-    return { totalPosts: count, period: input.period };
-  },
-});
+export default route()
+	.post()
+	.schema(
+		z.object({
+			period: z.enum(["day", "week", "month"]),
+		}),
+	)
+	.handler(async ({ input, collections }) => {
+		// input: typed from Zod schema; collections, db, session, etc. from AppContext
+		const count = await collections.posts.count({});
+		return { totalPosts: count, period: input.period };
+	});
 ```
 
-**Step 2 — Register in `app.ts`:**
-
-```ts
-import { getStats } from "./functions/get-stats.function.js";
+**Step 2 — Run codegen:**
 
-export const appRpc = r.router({
-  ...adminRpc,
-  getStats,
-});
+```bash
+bunx questpie generate
 ```
 
-**Step 3 — Call from client (fully typed):**
-
-```ts
-import { client } from "@/lib/cms-client";
-
-const result = await client.rpc.getStats({ period: "week" });
-// result: { totalPosts: number, period: string }
-```
+The route is auto-discovered and available at `/api/get-stats`.
 
 **With access control:**
 
 ```ts
-export const adminOnlyFn = r.fn({
-  access: ({ session }) => session?.user?.role === "admin",
-  schema: z.object({ ... }),
-  handler: async ({ input, app }) => { ... },
-});
+export default route()
+  .post()
+  .schema(z.object({ ... }))
+  .handler(async ({ input, session }) => {
+    if (session?.user?.role !== "admin") throw new Error("Forbidden");
+    return { ok: true };
+  });
 ```
 
 **With TanStack Query:**
 
 ```ts
-import { useQuery, useMutation } from "@tanstack/react-query";
+import { useQuery } from "@tanstack/react-query";
 
 const { data } = useQuery({
-  queryKey: ["stats", period],
-  queryFn: () => client.rpc.getStats({ period }),
-});
-
-const mutation = useMutation({
-  mutationFn: (input) => client.rpc.createSomething(input),
+	queryKey: ["stats", period],
+	queryFn: () => client.routes.getStats({ period }),
 });
 ```
 
-**Type flow:**
-
-```
-rpc()                                → r.fn() handlers get typed `app`
-  ↓
-r.fn({ schema, handler })           → RpcProcedureDefinition<TInput, TOutput>
-  ↓
-r.router({ myFn })                  → AppRpc type (preserves all function types)
-  ↓
-createClient<AppCMS, AppRpc>(...)    → client.rpc is fully typed
-  ↓
-client.rpc.myFn(input)              → Input: compile-time + runtime (Zod) validation
-                                     → Output: inferred from handler return type
-```
-
 ### Blocks (Page Builder)
 
 Blocks are content building units for page builders and rich content areas.
@@ -302,128 +302,80 @@ Blocks are content building units for page builders and rich content areas.
 **Simple block (no data fetching):**
 
 ```ts
-// src/questpie/server/blocks.ts
-import { qb } from "./builder";
-
-const heroBlock = qb
-  .block("hero")
-  .admin(({ c }) => ({
-    label: "Hero Section",
-    icon: c.icon("ph:image"),
-    category: { label: "Sections", icon: c.icon("ph:layout"), order: 1 },
-  }))
-  .fields((f) => ({
-    title: f.text({ label: "Title", required: true }),
-    subtitle: f.textarea({ label: "Subtitle" }),
-    backgroundImage: f.upload({ label: "Background Image" }),
-    ctaText: f.text({ label: "CTA Text" }),
-    ctaLink: f.text({ label: "CTA Link" }),
-  }))
-  .prefetch({ with: { backgroundImage: true } }); // expand upload to full URL
-
-export const blocks = { hero: heroBlock };
+// src/questpie/server/blocks/hero.ts
+import { block } from "#questpie/factories";
+
+export const heroBlock = block("hero")
+	.admin(({ c }) => ({
+		label: "Hero Section",
+		icon: c.icon("ph:image"),
+		category: { label: "Sections", icon: c.icon("ph:layout"), order: 1 },
+	}))
+	.fields(({ f }) => ({
+		title: f.text(255).label("Title").required(),
+		subtitle: f.textarea().label("Subtitle"),
+		backgroundImage: f.upload().label("Background Image"),
+		ctaText: f.text(255).label("CTA Text"),
+		ctaLink: f.text(255).label("CTA Link"),
+	}))
+	.prefetch({ with: { backgroundImage: true } }); // expand upload to full URL
 ```
 
 **Block with dynamic data fetching (prefetch):**
 
 ```ts
-const teamBlock = qb
-  .block("team")
-  .admin(({ c }) => ({
-    label: "Team",
-    icon: c.icon("ph:users"),
-    category: { label: "Sections", icon: c.icon("ph:layout"), order: 1 },
-  }))
-  .fields((f) => ({
-    title: f.text({ label: "Title" }),
-    limit: f.number({ label: "Number to Show", default: 4 }),
-  }))
-  .prefetch(async ({ values, ctx }) => {
-    const res = await ctx.app.api.collections.members.find({
-      limit: values.limit || 4,
-      where: { isActive: true },
-      with: { avatar: true },
-    });
-    return { members: res.docs };
-  });
+const teamBlock = block("team")
+	.admin(({ c }) => ({
+		label: "Team",
+		icon: c.icon("ph:users"),
+		category: { label: "Sections", icon: c.icon("ph:layout"), order: 1 },
+	}))
+	.fields(({ f }) => ({
+		title: f.text(255).label("Title"),
+		limit: f.number().label("Number to Show").default(4),
+	}))
+	.prefetch(async ({ values, ctx }) => {
+		const res = await ctx.collections.members.find({
+			limit: values.limit || 4,
+			where: { isActive: true },
+			with: { avatar: true },
+		});
+		return { members: res.docs };
+	});
 ```
 
-**Register blocks in `app.ts`:**
-
-```ts
-import { blocks } from "./blocks";
-
-export const cms = qb
-  .collections({ ... })
-  .blocks(blocks) // ← register blocks
-  .build({ ... });
-```
+Blocks in `blocks/` are auto-discovered by codegen. No manual registration needed.
 
 **Use blocks in a collection's richText field:**
 
 ```ts
-content: f.richText({
-  label: "Content",
-  blocks: [heroBlock, teamBlock],
-})
+content: f.richText().label("Content").blocks([heroBlock, teamBlock]);
 ```
 
-#### Blocks & Circular Dependencies (BaseCMS Pattern)
-
-When blocks use `.prefetch()` with functional handlers that need typed access to `ctx.app` (e.g., `ctx.app.api.collections.posts.find(...)`), you hit a circular dependency:
-
-- `app.ts` imports `blocks.ts` (to register blocks)
-- `blocks.ts` wants to import `AppCMS` from `app.ts` (for typed prefetch)
-- **Circular!**
+#### Blocks & Circular Dependencies
 
-**The workaround: split into `baseCms` and final `cms`:**
+Block prefetch handlers receive `ctx` with fully typed `collections` and `globals` via `AppContext` augmentation. Use `ctx.collections.*` directly — no app import needed:
 
 ```ts
-// app.ts
-import { blocks } from "./blocks";
-
-// Step 1: Build everything EXCEPT blocks
-export const baseCms = qb
-  .collections({ posts, pages })
-  .globals({ siteSettings })
-  .auth({ ... });
-
-// Step 2: Export the base type — blocks import THIS (not AppCMS)
-export type BaseCMS = (typeof baseCms)["$inferCms"];
-
-// Step 3: Add blocks and build
-export const cms = baseCms.blocks(blocks).build({ ... });
-
-export type AppCMS = typeof cms;
+// blocks/latest-posts.ts
+import { block } from "#questpie/factories";
+
+export const latestPostsBlock = block("latest-posts")
+	.fields(({ f }) => ({
+		count: f.number().label("Number of Posts").default(3),
+	}))
+	.prefetch(async ({ values, ctx }) => {
+		const res = await ctx.collections.posts.find({
+			limit: values.count || 3,
+			where: { published: true },
+		});
+		return { posts: res.docs };
+	});
 ```
 
-```ts
-// blocks.ts — imports BaseCMS (not AppCMS) to avoid circular dependency
-import { typedApp, type Where } from "questpie";
-import type { BaseCMS } from "./app";
-
-const latestPostsBlock = qb
-  .block("latest-posts")
-  .fields((f) => ({
-    count: f.number({ label: "Number of Posts", default: 3 }),
-  }))
-  .prefetch(async ({ values, ctx }) => {
-    // Use typedApp<BaseCMS> for typed access without circular import
-    const cms = typedApp<BaseCMS>(ctx.app);
-    const res = await cms.api.collections.posts.find({
-      limit: values.count || 3,
-      where: { published: true },
-      orderBy: { createdAt: "desc" },
-    });
-    return { posts: res.docs };
-  });
-```
+Do NOT import `app` from `#questpie` inside block files — these are imported BY `.generated/index.ts`, creating circular dependencies. Use the `ctx` parameters instead.
 
-**Key points:**
-- `BaseCMS` has the same collections/globals as `AppCMS` — blocks just aren't part of the type yet
-- `typedApp<BaseCMS>(ctx.app)` casts the untyped `ctx.app` to the typed CMS API
-- This is a known limitation; we're working on a more ergonomic solution
-- If your blocks only use declarative prefetch (`{ with: { field: true } }`), you don't need this pattern at all — it's only needed for functional prefetch that calls `ctx.app.api.*`
+If your blocks only use declarative prefetch (`{ with: { field: true } }`), you don't need a function at all.
 
 ### Reactive Fields
 
@@ -437,75 +389,81 @@ Fields support reactive behaviors in `meta.admin`:
 All reactive handlers run **server-side** with access to `ctx.db`, `ctx.user`, `ctx.req`.
 
 ```ts
-fields: (f) => ({
-  country: f.relation({ to: "countries", label: "Country" }),
-  city: f.relation({
-    to: "cities",
-    label: "City",
-    options: {
-      handler: async ({ data, search, ctx }) => {
-        const cities = await ctx.db.query.cities.findMany({
-          where: { countryId: data.country },
-        });
-        return { options: cities.map((c) => ({ value: c.id, label: c.name })) };
-      },
-      deps: ({ data }) => [data.country],
-    },
-  }),
-  status: f.select({
-    label: "Status",
-    options: ["draft", "published", "archived"],
-  }),
-  publishedAt: f.dateTime({
-    label: "Published At",
-    meta: {
-      admin: {
-        hidden: ({ data }: { data: Record<string, any> }) => data.status !== "published",
-      },
-    },
-  }),
-})
+fields: ({ f }) => ({
+	country: f.relation().to("countries").label("Country"),
+	city: f
+		.relation()
+		.to("cities")
+		.label("City")
+		.admin({
+			options: {
+				handler: async ({ data, search, ctx }) => {
+					const cities = await ctx.db.query.cities.findMany({
+						where: { countryId: data.country },
+					});
+					return {
+						options: cities.map((c) => ({ value: c.id, label: c.name })),
+					};
+				},
+				deps: ({ data }) => [data.country],
+			},
+		}),
+	status: f
+		.select()
+		.label("Status")
+		.options(["draft", "published", "archived"]),
+	publishedAt: f
+		.datetime()
+		.label("Published At")
+		.admin({
+			hidden: ({ data }) => data.status !== "published",
+		}),
+});
 ```
 
 ### Admin Configuration (Client-Side)
 
-```ts
-// src/questpie/admin/builder.ts
-import { adminModule, qa } from "@questpie/admin/client";
-import type { AppCMS } from "@/questpie/server/cms";
+The admin client config is auto-generated by codegen into `admin/.generated/client.ts`.
+No manual builder setup is needed. Run `bunx questpie generate` to regenerate.
 
-export const admin = qa<AppCMS>().use(adminModule);
+```ts
+// src/questpie/admin/admin.ts (re-export for convenience)
+export { default as admin } from "./.generated/client";
 ```
 
 ```ts
 // src/questpie/admin/hooks.ts
 import { createTypedHooks } from "@questpie/admin/client";
-import type { AppCMS } from "../server/cms";
+import type { App } from "#questpie";
 
 export const {
-  useCollectionList, useCollectionCount, useCollectionItem,
-  useCollectionCreate, useCollectionUpdate, useCollectionDelete,
-  useGlobal, useGlobalUpdate,
-} = createTypedHooks<AppCMS>();
+	useCollectionList,
+	useCollectionCount,
+	useCollectionItem,
+	useCollectionCreate,
+	useCollectionUpdate,
+	useCollectionDelete,
+	useGlobal,
+	useGlobalUpdate,
+} = createTypedHooks<App>();
 ```
 
-### CMS Route Handler
+### QUESTPIE Route Handler
 
 ```ts
-// src/routes/api/cms/$.ts
+// src/routes/api/$.ts
 import { createFetchHandler } from "questpie";
-import { withOpenApi } from "@questpie/openapi";
-import { appRpc, cms } from "~/questpie/server/cms";
+import { app } from "#questpie";
 
-const handler = withOpenApi(
-  createFetchHandler(cms, { basePath: "/api/cms", rpc: appRpc }),
-  { cms, rpc: appRpc, basePath: "/api/cms", info: { title: "My API", version: "1.0.0" } },
-);
+const handler = createFetchHandler(app, { basePath: "/api" });
 ```
 
+OpenAPI is registered as a module in `src/questpie/server/modules.ts` via `openApiModule()` — no wrapper needed in the route handler.
+
 ### Icons
 
 Use `@iconify/react` with Phosphor icon set:
+
 - Prefix: `ph:` (e.g., `ph:house`, `ph:article`, `ph:gear`)
 - Weight variants: `-bold`, `-fill`, `-duotone`, `-light`, `-thin`
 - Regular weight = no suffix (default)
@@ -515,13 +473,16 @@ Use `@iconify/react` with Phosphor icon set:
 ## Environment Variables
 
 Type-safe via `@t3-oss/env-core` in `src/lib/env.ts`. All env vars must be:
+
 1. Declared with Zod schema in `env.ts`
 2. Accessed via `env.VAR_NAME` (not `process.env.VAR_NAME`)
 
 Required:
+
 - `DATABASE_URL` — PostgreSQL connection string
 
 Optional (with defaults):
+
 - `APP_URL` — Application URL (default: `http://localhost:3000`)
 - `BETTER_AUTH_SECRET` — Auth secret key
 - `MAIL_ADAPTER` — `console` or `smtp`
@@ -553,11 +514,98 @@ Always use these exact versions — check `package.json` before upgrading:
 
 - **Schema rules in client code** — Validation, access control, and hooks belong on the server.
 - **Splitting a collection across files** — Keep the full `.collection().fields().admin().list().form()` chain in one file.
-- **Business logic in route handlers** — Routes only mount handlers. Logic goes in RPC functions, hooks, or jobs.
+- **Business logic in route handlers** — Mounting files should only mount handlers. Business logic goes in server routes, hooks, or jobs.
 - **Hardcoding view components** — Use the registry pattern for custom views.
 - **Using `process.env` directly** — Use the `env` object from `src/lib/env.ts`.
 - **Using Zod v3 API** — This project uses Zod v4. Use `z.object()` etc. from `zod` (v4).
 - **Using `asChild` prop** — This project uses `@base-ui/react`, not Radix. Use `render` prop instead.
 - **Using Radix UI or Lucide icons** — Use `@base-ui/react` and `@iconify/react` with `ph:` prefix.
 - **Adding UI config to database schema** — Admin UI config is UI-only, defined in builder chain.
-- **Importing `AppCMS` in `blocks.ts`** — Use `BaseCMS` pattern to avoid circular dependencies (see Blocks section).
+- **Importing `app` from `#questpie` in blocks/collections/hooks** — Files inside `collections/`, `globals/`, `routes/`, `hooks/`, `blocks/` are imported BY `.generated/index.ts`, so importing from it back creates circular dependencies. Use the `ctx` parameters instead.
+
+## Live Preview
+
+QUESTPIE supports live preview with a split-screen editor. The preview architecture uses a direct `postMessage` patch bus for instant feedback — NOT save-driven iframe reloads.
+
+### Key Principles
+
+- **Same-tab preview** = direct patch bus via `postMessage` (editor iframe and preview share the same browser tab)
+- **Save/autosave** = persistence only, NOT the live transport mechanism
+- **Realtime** = extension for detached/shared preview only (e.g., another browser tab or collaborator)
+- **Hybrid model**: local draft patches give instant response; server reconciles derived data (slugs, relations, computed fields)
+- **Preview wrappers must prevent accidental navigation** inside the iframe
+
+### Server Config
+
+Add `.preview()` to a collection to enable the split-screen editor:
+
+```ts
+// src/questpie/server/collections/pages.ts
+import { collection } from "questpie";
+
+export const pages = collection("pages")
+	.fields(({ f }) => ({
+		title: f.text(255).label("Title").required(),
+		slug: f.text(255).label("Slug").required(),
+		content: f.blocks().label("Content"),
+	}))
+	.preview({
+		url: ({ record }) => {
+			const slug = record.slug as string;
+			return slug === "home" ? "/?preview=true" : `/${slug}?preview=true`;
+		},
+		watch: ["title", "slug", "content"],
+		strategy: "hybrid", // "instant" | "server" | "hybrid"
+	});
+```
+
+| Strategy    | Behavior                                                                 |
+| ----------- | ------------------------------------------------------------------------ |
+| `"instant"` | Patches applied locally only — no server round-trip                      |
+| `"server"`  | Every change round-trips through the server before preview updates       |
+| `"hybrid"`  | Local patches for instant response + server reconcile for derived fields |
+
+### Frontend Integration
+
+Use `useQuestpiePreview` in your frontend page components to receive live patches:
+
+```tsx
+// src/routes/[slug].tsx
+import { useQuestpiePreview } from "@questpie/admin/client";
+
+function PageComponent({ initialData }) {
+	const router = useRouter();
+	const { data } = useQuestpiePreview({
+		initialData,
+		reconcile: () => router.invalidate(), // called on COMMIT — refetch server data
+	});
+
+	return (
+		<PreviewRoot>
+			<h1>
+				<PreviewField path="title">{data.title}</PreviewField>
+			</h1>
+			<PreviewBlock id="content">{/* block renderers */}</PreviewBlock>
+		</PreviewRoot>
+	);
+}
+```
+
+#### Protocol
+
+Each `postMessage` carries a structured envelope:
+
+| Field             | Description                            |
+| ----------------- | -------------------------------------- |
+| `sessionId`       | Unique preview session identifier      |
+| `seq`             | Monotonic sequence number              |
+| `timestamp`       | `Date.now()` at send time (number)     |
+| `protocolVersion` | Protocol version for forward compat    |
+| `patches`         | Array of field path + value patch ops  |
+
+### Anti-Patterns (Preview)
+
+- **Using `router.invalidate()` as the core live-preview mechanism** — this causes full data refetches and visible flicker. Use the patch bus instead.
+- **Tying preview freshness to save/autosave** — save is for persistence. Preview updates flow through `postMessage` patches.
+- **Using realtime transport for same-tab preview** — realtime (SSE/WebSocket) is for detached or shared preview sessions, not the default same-tab flow.
+- **Allowing navigation inside the preview iframe** — preview wrappers must intercept link clicks and route changes to prevent the iframe from navigating away.